| Previous Contents Index Next |
| iPlanet Web Server, Enterprise Edition NSAPI Programmer's Guide |
Appendix B Variables in magnus.conf
When the iPlanet Web Server starts up, it looks in a file called magnus.conf in the server-id/config directory to establish a set of global variable settings that affect the server's behavior and configuration.Each directive in magnus.conf specifies a variable and a value, for example:
ServerID https-boots.mcom.com
ServerName boots.mcom.com
Address 123.45.67.89The order of the directives is not important.
This appendix lists the global settings that can be specified in magnus.conf in Enterprise Server 3.x and iPlanet Web Server 4.x.
Server Information
For an alphabetical list of directives, see Appendix I "Alphabetical List of Directives in magnus.conf."Threads, Processes and Connections
Note In iPlanet Web Server 4.x, much of the functionality of the file cache is controlled by a new configuration file called nsfc.conf. For information about nsfc.conf, see the tuning chapter in the iPlanet Web Server Administrator's Guide.
Server Information
This sub-section lists the directives in magnus.conf that specify information about the server. They are:
If a server has multiple IP addresses and you want it listen for requests only at a specific IP address, set the value of this directive.
This directive determines the number of CPU processors that the server uses. By default, the server uses all the CPU processors. You only need to set this directive if you want the server to use less than the available processors.
Specifies the name of the SMTP mail server used by the server's agents. This value must be specified before reports can be sent to a mailing address.
The Port directive determines which TCP port the server listens to. There should be only one Port directive in magnus.conf.
Unix: If you choose a port number less than 1024, the server must be started as root.
Note: The port you choose can affect how users configure their navigators. Users must specify the port number when accessing the server if the port number is anything other than 80 (unsecured servers) or 443 (secured servers).
number is a whole number between 0 and 65535.
Default
If no port is specified, the server assumes 80.
Specifies the server ID, such as https-boots.mcom.com.
The ServerName directive tells the server what to put in the host name section of any URLs it sends to the client. This affects URLs the server automatically generates; it doesn't affect the URLs for directories and files stored in the server. This name is what all clients use to access the server; they need to combine this name with the port number if the port number is anything other than 80.
This name should be the alias name if your server uses an alias. You can't have more than one ServerName directive in magnus.conf.
host is a fully qualified domain name such as myhost.netscape.com.
Default
If ServerName isn't in magnus.conf, the server attempts to derive a host name through system calls. If they don't return a qualified domain name (for example, it gets myhost instead of myhost.netscape.com), the server won't start, and you'll get a message telling you to manually set this value.
Examples
ServerName server.netscape.comServerName www.server.anycompany.com
Specifies the server root. This directive is set during installation and is commented out. Unlike other directives, the server expects this directive to start with #. Do not change this directive. If you do, the Server Manager may not function properly.
Example
#ServerRoot d:/netscape/server4/https-boots.mcom.com
Windows NT: The User directive specifies the user account the server runs with. By using a specific user account (other than LocalSystem), you can restrict or enable system features for the server. For example, you can use a user account that can mount files from another machine.
Unix: The User directive specifies the Unix user account for the server. If the server is started by the superuser or root user, the server binds to the Port you specify and then switches its user ID to the user account specified with the User directive. This directive is ignored if the server isn't started as root. The user account you specify should have read permission to the server's root and subdirectories. The user account should have write access to the logs directory and execute permissions to any CGI programs. The user account should not have write access to the configuration files. This ensures that in the unlikely event that someone compromises the server, they won't be able to change configuration files and gain broader access to your machine. Although you can use the nobody user, it isn't recommended.1
name is the 8-character (or less) login name for the user account.
Default
If there is no User directive, the server runs with the user account it was started with.
The value of this directive is the name of a file that specifies virtual servers. Each line in this file contains an IP, docroot pair.
Object Configuration File
This subsection lists the directives in magnus.conf that provide information about the object configuration file that instructs the server how to handle requests. These directives are:
LoadObjects
The LoadObjects directive specifies one or more object configuration files to use on startup, most notably obj.conf, which contains instructions that tell the server how to handle requests from clients.
Note: Although you can have more than one object configuration file, the Server Manager interface works on only one file and assumes that it is the file obj.conf in the config directory in the server root directory. If you use the Server Manger interface, don't put the obj.conf file in any other directory and don't rename it.
The filename is either the full path name or a relative path name.
Unix: When the server starts executing, relative path names are resolved from the directory specified with the -d command lien flag. If no -d flag was given, the server looks in the current directory.
Default
There is no default. Make sure that your magnus.conf loads the obj.conf object, otherwise your server will not be able to process requests from clients.LoadObjects /var/ns-server/admin/config/local-objs.conf
The RootObject directive tells the server which object loaded from an object file is the server default. The default object is expected to have all the name translation directives for the server; any server behavior that is configured in the default object affects the entire server.
If you specify an object that doesn't exist, the server doesn't report an error until a client tries to retrieve a document. The Server Manager assumes the default to be the object named default. Don't deviate from this convention if you use (or plan to use) the Server Manager.
The name is the name of an object defined in one of the object files loaded with a LoadObjects directive.
Default
There is no default; that is, if you specify RootObject, you must specify a name with it.
Language Issues
This section lists the directives in magnus.conf related to language issues. The directives are:
AcceptLanguage
This directive determines whether or not the server parses the Accept-Language header sent by the client to indicate which languages the client accepts. If the value is on, the server parses this header and sends an appropriate language version based on which language the client can accept. You should set this value to on only if the server supports multiple languages.
When this directive is set to on, the accelerator cache is disabled since it does not use AcceptLanguage in its cache keys.
Default
The default value is off.
For an international version of the server, this directive specifies the language for the Server Manager. Values en (English), fr (French), de (German) or ja (Japanese).
For an international version of the server, this directive specifies the language for client messages (such as File Not Found). Values en (English), fr (French), de (German) or ja (Japanese).
For an international version of the server, this directive specifies the default language for the server. The default language is used for both the client responses and administration. Values en (English), fr (French), de (German) or ja (Japanese).
DNS Lookup
This section lists the directives in magnus.conf that affect DNS lookup. The directives are:
AsyncDNS
Specifies whether asynchronous DNS is allowed. The value is either on or off. If DNS is enabled, enabling asynchronous DNS improves server performance.
The DNS directive specifies whether the server performs DNS lookups on clients that access the server. When a client connects to your server, the server knows the client's IP address but not its host name (for example, it knows the client as 198.95.251.30, rather than its host name www.a.com). The server will resolve the client's IP address into a host name for operations like access control, CGI, error reporting, and access logging.
If your server responds to many requests per day, you might want (or need) to stop host name resolution; doing so can reduce the load on the DNS or NIS server.
Default
DNS host name resolution is on as a default.
Threads, Processes and Connections
This subsection lists the directives in magnus.conf that affect the number and timeout of threads, processes, and connections. They are:
BlockingListenSockets
Also see the section "Native Thread Pools" for new directives in iPlanet Web Server 4.x for controlling the pool of native kernel threads.
This directive determines whether or not the server's sockets listen in blocking mode. Do not use this directive with SSL.
This directive determines the maximum time that the server holds open an HTTP Keep-Alive connection or a persistent connection between the client and the server. The Keep-Alive feature for earlier versions of the server allows the client/server connection to stay open while the server processes the client request. For Enterprise Server 3.0+, the default connection is a persistent connection that remains open until the server closes it or the connection has been open for longer than the time allowed by KeepAliveTimeout.
Default
The default value is 30 seconds. The maximum value is 300 seconds (5 minutes).
iPlanet Web Server can support both kernel-level and user-level threads whenever the operating system supports kernel-level threads. Usually, the standard debugger and compiler are intended for use with kernel-level threads. By setting KernelThreads to on, you ensure that the server uses only kernel-level threads, not user-level threads.
Defines the number of incoming connections for a server socket.
Specifies the maximum number of Keep-Alive and persistent connections that the server can have open simultaneously.
New in iPlanet Web Server 4.0.
Specifies the maximum number of processes that the server can have running simultaneously. If you don't include MaxProcs in your magnus.conf file, the server defaults to running a single process.
There is additional discussion of this and other server configuration and performance tuning issues in the "Configuring the Server for Performance" chapter in the iPlanet Web Server Administrator's Guide.
If this directive is set to on, the server checks the whether the minimum number of threads are available at a socket (as specified by RqThrottleMinPerSocket) after accepting a connection but before sending the response to the request. Use this directive when the server will be handling requests that take a long time to handle, such as those that do long database connections.
Controls the size of the receive buffer at the server's sockets.
Specifies the maximum number of simultaneous requests that the server can handle simultaneously per socket. Each request runs in its own thread.
There is additional discussion of this and other server configuration and performance tuning issues in the "Configuring the Server for Performance" chapter in the iPlanet Web Server Administrator's Guide.
Specifies the approximate minimum number of threads that wait at each socket for requests to come in.
Controls the size of the send buffer at the server's sockets.
Determines the maximum stack size for each request handling thread.
New in iPlanet Web Server 4.1.
Controls strict HTTP header checking. If strict HTTP header checking is on, the server rejects connections that include inappropriately duplicated headers.
Syntax
StrictHttpHeaders [on|off]
Default
Strict HTTP header checking is off by default.
Specifies the time that the server waits for all existing connections to terminate before it shuts down.
Native Thread Pools
New in iPlanet Web Server 4.0.This section lists the directives for controlling the size of the native kernel thread pool. These directives are all new in iPlanet Web Server 4.x. In previous versions of the server, you could control the native thread pool by setting the system variables NSCP_POOL_STACKSIZE, NSCP_POOL_THREADMAX, and NSCP_POOL_WORKQUEUEMAX.
If you have set these values as environment variables and also in magnus.conf, the environment variable values will take precedence.
The native pool on Unix is normally not engaged, as all threads are OS-level threads. Using native pools on Unix may introduce a small performance overhead as they'll require an additional context switch; however, they can be used to localize the jvm.stickyAttach effect or for other purposes, such as resource control and management or to emulate single-threaded behavior for plug-ins (by setting maxThreads=1).
On Windows NT, the default native pool is always being used and iPlanet Web Server uses fibers (user-scheduled threads) for initial request processing. Using custom additional pools on Windows NT introduces no additional overhead.
NativePoolStackSize
New in iPlanet Web Server 4.0.
Determines the stack size of each thread in the native (kernel) thread pool.
New in iPlanet Web Server 4.0.
Determines the maximum number of threads in the native (kernel) thread pool.
New in iPlanet Web Server 4.0.
Determines the minimum number of threads in the native (kernel) thread pool.
New in iPlanet Web Server 4.0.
Determines the number of threads that can wait in the queue for the thread pool. If all threads in the pool are busy, then the next request-handling thread that needs to use a thread in the native pool must wait in the queue. If the queue is full, the next request-handling thread that tries to get in the queue is rejected, with the result that it returns a busy response to the client. It is then free to handle another incoming request instead of being tied up waiting in the queue.
CGI
This section lists the directives in magnus.conf that affect requests for CGI programs. The directives are:
CGIExpirationTimeout
New in iPlanet Web Server 4.0.
This directive specifies the maximum time in seconds that CGI processes are allowed to run before being killed.
The value of CGIExpirationTimeout should not be set too low - 5 minutes would be a good value for most interactive CGIs; but if you have CGIs that are expected to take longer without misbehaving, then you should set it to the maximum duration you expect a CGI program to run normally.
Note that on Windows NT platforms init-cgi time-out does not work, so you must use CGIExpirationTimeout.
For UNIX platforms, when CGIWaitPid is set to on, the action for the SIGCHLD signal is the system default action for the signal. If a NSAPI plugin fork/execs a child process, it should call waitpid with its child process pid when CGIWaitPid is enabled to avoid leaving "defunct" processes when its child process terminates. When CGIWaitPid is enabled, the SHTML engine waits explicitly on its exec cmd child processes. Note that this directive has no effect on CGI.
Error Logging and Statistic Collection
This section lists the directives in magnus.conf that affect error logging and the collection of server statistics. They are:
DaemonStats (Unix Only)
This directive specifies whether or not the server collects some daemon statistics. The value is on or off. If the value is off, SNMP statistic collection will not work.
The ErrorLog directive specifies the directory where the server logs its errors. If errors are reported to a file, then the file and directory in which the log is kept must be writable by whatever user account the server runs as.
Unix: You can also use the syslog facility.
The logfile can be either a full path or file name.
On Unix systems, it can be the keyword SYSLOG (it must be in all capital letters).
Default
There is no default error log.ErrorLog C:\Netscape\ns-home\Logs\Errors
ErrorLog /var/ns-server/logs/errors
New in iPlanet Web Server 4.1.
This directive determines the log flush interval, in seconds, of the log flush thread.
This directive determines whether verbose logging occurs or not. If the value is on, the server logs all server messages including those that are not logged by default (such as WAI initialization messages).
PidLog specifies a file in which to record the process ID (pid) of the base server process. Some of the server support programs assume that this log is in the server root, in logs/pid.
To shut down your server, kill the base server process listed in the pid log file by using a -TERM signal. To tell your server to reread its configuration files and reopen its log files, use kill with the -HUP signal.
If the PidLog file isn't writable by the user account that the server uses, the server does not log its process ID anywhere. The server won't start if it can't log the process ID.
The file is the full path name and file name where the process ID is stored.
Examples
PidLog /var/ns-server/logs/pid
ACL
This section lists the directives in magnus.conf relevant to access control lists (ACLs).
ACLFile
The ACLFile directive specifies an ACL (Access Control List) definition file—a text file that normally resides in the httpacl directory. Multiple ACLFile directives can appear in the magnus.conf file. The server reads all the ACL definitions in all the specified ACL definition files when it starts up. Each ACL file must have a unique name.
Usually the value of ACLFile is generated.https-servername.acl, and it resides in the httpacl directory of the server installation directory.
The name is the name of an ACL definition file.
Example
ACLFile d:/netscape/server4/httpacl/generated.https-boots.mcom.com.acl
Security
This section lists the directives in magnus.conf that affect server access and security issues for iPlanet Web Server. They are:
CERTDefaultNickname
The CERTDefaultNickname directive is the nickname of the server certificate in the certificate database.
Syntax
CERTDefaultNickname nameThe name is the nickname of the server certificate in the certificate database.
Default
There is no default. You must specify a name.
The Chroot directive lets the Unix system administrator place the server under a constraint such that it has access only to files in a given directory, termed the "Chroot directory". This is useful if the server's security is ever compromised. For example, if an intruder somehow obtains shell access on the server machine, the intruder could only affect a very limited set of files on the server machine.
The server must be started as the superuser to use the Chroot directive. CGI programs must be linked statically, and any binaries (perl or /bin/sh) must be copied to the Chroot directory.
The user public information directory feature isn't available unless a copy of /etc/passwd is kept in the Chroot directory and all of the users home directories are exactly mirrored within the Chroot directory.
A server using Chroot can't be restarted with the -HUP signal.
Logs and server configuration files should be kept outside the Chroot directory.
IMPORTANT
All paths in magnus.conf must be absolute; paths in obj.conf must be relative to the Chroot directory.The directory is the full path name to the directory used as the server's root directory.
Default
There is no default. You must specify a directory.
The Ciphers directive specifies the ciphers enabled for your server.
Syntax
Ciphers +rc4 +rc4export -rc2 -rc2export +idea +des +desede3A + means the cipher is active, and a - means the cipher is inactive.
Valid ciphers are rc4, rc4export, rc2, rc2export, idea, des, desede3. Any cipher with export as port of its name is not stronger than 40 bits.
The Security directive tells the server whether encryption (Secure Sockets Layer version 2 or version 3 or both) is enabled or disabled.
If Security is set to on, and both SSL2 and SSL3 are enabled, then the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption.
Default
By default, security is off.
Specifies the number of SSL sessions that can be cached. There is no upper limit.
If the number is 0, the default value, which is 10000, is used.
The SSLClientAuth directive causes SSL3 client authentication on all requests.
on directs that SSL3 client authentication be performed on every request, independent of ACL-based access control.
The SSLSessionTimeout directive controls SSL2 session caching.
Syntax
SSLSessionTimeout secondsThe seconds value is the number of seconds until a cached SSL2 session becomes invalid. The default value is 100. If the SSLSessionTimeout directive is specified, the value of seconds is silently constrained to be between 5 and 100 seconds.
The SSL2 directive tells the server whether Secure Sockets Layer, version 2 encryption is enabled or disabled. The Security directive dominates the SSL2 directive; if SSL2 encryption is enabled but the Security directive is set to off, then it is as though SSL2 were disabled.
Default
By default, security is off.
The SSL3 directive tells the server whether Secure Sockets Layer, version 3 security is enabled or disabled. The Security directive dominates the SSL3 directive; if SSL3 security is enabled but the Security directive is set to off, then it is as though SSL3 were disabled.
Default
By default, security is off.
The SSL3Ciphers directive specifies the SSL3 ciphers enabled for your server.
Syntax
SSL3Ciphers +rsa_rc4_128_md5 -rsa3des_sha +rsa_des_sha +rsa_rc4_40_md5 -rsa_rc2_40_md5 -rsa_null_md5A + means the cipher is active, and a - means the cipher is inactive.
Valid ciphers are rsa_rc4_128_md5, rsa3des_sha, rsa_des_sha, rsa_rc4_40_md5, rsa_rc2_40_md5, and rsa_null_md5. Any cipher with 40 as part of its name is 40 bits.
The SSL3SessionTimeout directive controls SSL3 session caching.
Syntax
SSL3SessionTimeout secondsThe seconds value is the number of seconds until a cached SSL3 session becomes invalid. The default value is 86400 (24 hours). If the SSL3SessionTimeout directive is specified, the value of seconds is silently constrained to be between 5 and 86400 seconds.
Chunked Encoding
This section lists directives that control chunked encoding. For more information, see "Buffered Streams."
UseOutputStreamSize
New in iPlanet Web Server 4.1.
The UseOutputStreamSize directive determines the default output stream buffer size for the net_read and netbuf_grab NSAPI functions.
Syntax
UseOutputStreamSize sizeThe size value is the number of bytes. The default value is 8192.
New in iPlanet Web Server 4.1.
If the interval between subsequent write operations is greater than the flushTimer value for an application, further buffering is disabled. This is necessary for status monitoring CGI applications that run continuously and generate periodic status update reports.
Syntax
flushTimer millisecondsThe milliseconds value is the maximum number of milliseconds between write operations in which buffering is enabled. The default value is 3000 (3 seconds).
New in iPlanet Web Server 4.1.
The ChunkedRequestBufferSize directive determines the default buffer size for "un-chunking" request data.
Syntax
ChunkedRequestBufferSize sizeThe size value is the number of bytes. The default value is 8192.
New in iPlanet Web Server 4.1.
The ChunkedRequestTimeout directive determines the default timeout for "un-chunking" request data.
Syntax
ChunkedRequestTimeout secondsThe seconds value is the number of seconds. The default value is 60 (1 minute).
Miscellaneous
This section lists miscellaneous other directives in magnus.conf.
Umask (UNIX only)
This directive specifies the umask value used by the NSAPI functions System_fopenWA() and System_fopenRW() to open files in different modes. Valid values for this directive are standard UNIX umask values.
For more information on these functions, see system_fopenWA and system_fopenRW in Chapter 5 "NSAPI Function Reference."
Previous Contents Index Next
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated November 20, 2000