Sun ONE Web Server 6.1 Administrator's Configuration File Reference |
Chapter 3
Syntax and Use of magnus.confWhen the Sun ONE 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. Sun ONE Web Server executes all the directives defined in magnus.conf. The order of the directives is not important.
Note
When you edit the magnus.conf file, you must restart the server for the changes to take effect.
This chapter lists the global settings that can be specified in magnus.conf in Sun ONE Web Server 6.1.
The categories are:
For an alphabetical list of directives, see Alphabetical List of Server Configuration Elements.
For a list of magnus.conf directives deprecated in Sun ONE Web Server 6.1, see Deprecated Directives.
Note
Much of the functionality of the file cache is controlled by a configuration file called nsfc.conf. For information about nsfc.conf, see nsfc.conf.
Init FunctionsThe Init functions load and initialize server modules and plugins, and initialize log files. For more information about these functions, see the Sun ONE Web Server NSAPI Programmer’s Guide.
Server InformationThis sub-section lists the directives in magnus.conf that specify information about the server. They are:
ExtraPath
Appends the specified directory name to the PATH environment variable. This is used for configuring Java on Windows. There is no default value; you must specify a value.
Syntax
ExtraPath path
TempDir
Specifies the directory on the local volume that the server uses for its temporary files. On UNIX, this directory must be owned by, and writable by, the user the server runs as. See also the directives User and TempDirSecurity.
Syntax
TempDir path
Default
/tmp (UNIX)
TEMP (environment variable for Windows)
TempDirSecurity
Determines whether the server checks if the TempDir directory is secure. On UNIX, specifying TempDirSecurity off allows the server to use /tmp as a temporary directory.
Caution
Specifying TempDirSecurity off or using /tmp as a temporary directory on UNIX is highly discouraged. Using /tmp as a temporary directory opens a number of potential security risks.
Syntax
TempDirSecurity [on|off]
Default
on
User
Windows: 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.
Syntax
User name
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.
Examples
User http
User server
User nobody
Language IssuesThis section lists the directives in magnus.conf related to language issues. The following directive is supported:
DefaultLanguage
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 are en (English), fr (French), de (German) or ja (Japanese).
Default
The default is en.
DNS LookupThis section lists the directives in magnus.conf that affect DNS (Domain Name System) lookup. The directives are:
AsyncDNS
Specifies whether asynchronous DNS is allowed. This directive is ignored. Even if the value is set to on, the server does not perform asynchronous DNS lookups.
DNS
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 (Network Information System) server.
Syntax
DNS [on|off]
Default
DNS host name resolution is on as a default.
Example
DNS on
Threads, Processes, and ConnectionsIn Sun ONE Web Server 6.1, acceptor threads on a listen socket accept connections and put them onto a connection queue. Session threads then pick up connections from the queue and service the requests. The session threads post more session threads if required at the end of the request. The policy for adding new threads is based on the connection queue state:
- Each time a new connection is returned, the number of connections waiting in the queue (the backlog of connections) is compared to the number of session threads already created. If it is greater than the number of threads, more threads are scheduled to be added the next time a request completes.
- The previous backlog is tracked, so that if it is seen to be increasing over time, and if the increase is greater than the ThreadIncrement value, and the number of session threads minus the backlog is less than the ThreadIncrement value, then another ThreadIncrement number of threads are scheduled to be added.
- The process of adding new session threads is strictly limited by the RqThrottle value.
- To avoid creating too many threads when the backlog increases suddenly (such as the startup of benchmark loads), the decision whether more threads are needed is made only once every 16 or 32 times a connection is made based on how many session threads already exist.
This subsection lists the directives in magnus.conf that affect the number and timeout of threads, processes, and connections. They are:
Also see the section "Native Thread Pools"” for directives for controlling the pool of native kernel threads.
For more information about performance tuning, see the Sun ONE Web Server 6.1 Performance Tuning, Sizing, and Scaling Guide.
AcceptTimeout
Specifies the number of seconds the server waits for data to arrive from the client. If data does not arrive before the timeout expires then the connection is closed. By setting it to less than the default 30 seconds, you can free up threads sooner. However, you may also disconnect users with slower connections.
Syntax
AcceptTimeout seconds
Default
30 seconds for servers that don't use hardware encryption devices and 300 seconds for those that do.
ConnQueueSize
Specifies the number of outstanding (yet to be serviced) connections that the web server can have. It is recommended that this value always be greater than the operating system limit for the maximum number of open file descriptors per process.
This setting can have performance implications. For more information, see the Sun ONE Web Server 6.1 Performance Tuning, Sizing, and Scaling Guide.
Default
The default value is 4096.
HeaderBufferSize
The size (in bytes) of the buffer used by each of the request processing threads for reading the request data from the client. The maximum number of request processing threads is controlled by the RqThrottle setting.
Default
The default value is 8192 (8 KB).
KeepAliveQueryMaxSleepTime
This directive specifies an upper limit to the time slept (in milliseconds) after polling keep-alive connections for further requests.
Default
The default is 100.
On lightly loaded systems that primarily service keep-alive connections, you can lower this number to enhance performance. However doing so can increase CPU usage.
KeepAliveQueryMeanTime
This directive specifies the desired keep-alive latency in milliseconds.
Default
The default value of 100 is appropriate for almost all installations.
Note that CPU usage will increase with lower KeepAliveQueryMeanTime values.
KeepAliveThreads
This directive determines the number of threads in the keep-alive subsystem. It is recommended that this number be a small multiple of the number of processors on the system (for example, a 2 CPU system should have 2 or 4 keep alive threads). The maximum number of keep-alive connections allowed (MaxKeepAliveConnections) should also be taken into consideration when choosing a value for this setting.
Default
1
KeepAliveTimeout
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. 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.
The timeout countdown starts when the connection is handed over to the keep-alive subsystem. If there is no activity on the connection when the timeout expires, the connection is closed.
Default
The default value is 30 seconds. The maximum value is 300 seconds (5 minutes).
KernelThreads
Sun ONE Web Server can support both kernel-level and user-level threads whenever the operating system supports kernel-level threads. Local threads are scheduled by NSPR (Netscape Portable Runtime) within the process, whereas kernel threads are scheduled by the host operating system. Usually, the standard debugger and compiler are intended for use with kernel-level threads. By setting KernelThreads to 1 (on), you ensure that the server uses only kernel-level threads, not user-level threads. By setting KernelThreads to 0 (off), you ensure that the server uses only user-level threads, which may improve performance.
Default
The default is 0 (off).
ListenQ
Specifies the maximum number of pending connections on a listen socket. Connections that time out on a listen socket whose backlog queue is full will fail.
Default
The default value is platform-specific: 4096 (AIX), 200 (), 128 (all others).
MaxKeepAliveConnections
Specifies the maximum number of Keep-Alive and persistent connections that the server can have open simultaneously. Values range from 0 to 32768.
Default
MaxProcs (UNIX Only)
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.
One process per processor is recommended if you are running in multi-process mode. In Sun ONE Web Server 6.1, there is always a primordial process in addition to the number of active processes specified by this setting.
Additional discussion of this and other server configuration and performance tuning issues can be found in the Sun ONE Web Server 6.1 Performance Tuning, Sizing, and Scaling Guide.
Default
1
PostThreadsEarly
If this directive is set to 1 (on), the server checks the whether the minimum number of threads are available at a listen socket 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.
Default
0 (off)
RcvBufSize
Specifies the size (in bytes) of the receive buffer used by sockets. Allowed values are determined by the operating system.
Default
The default value is determined by the operating system. Typical defaults are 4096 (4K), 8192 (8K).
RqThrottle
Specifies the maximum number of request processing threads that the server can handle simultaneously. Each request runs in its own thread.
This setting can have performance implications. For more information, see the Sun ONE Web Server 6.1 Performance Tuning, Sizing, and Scaling Guide.
RqThrottleMin
Specifies the number of request processing threads that are created when the server is started. As the load on the server increases, more request processing threads are created (up to a maximum of RqThrottle threads).
SndBufSize
Specifies the size (in bytes) of the send buffer used by sockets.
Default
The default value is determined by the operating system. Typical defaults are 4096 (4K), 8192 (8K).
StackSize
Determines the maximum stack size for each request handling thread.
Default
The most favorable machine-specific stack size.
StrictHttpHeaders
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
on
TerminateTimeout
Specifies the time that the server waits for all existing connections to terminate before it shuts down.
Default
30 seconds
ThreadIncrement
The number of additional or new request processing threads created to handle an increase in the load on the server, for example when the number of pending connections (in the request processing queue) exceeds the number of idle request processing threads.
When a server starts up, it creates RqThrottleMin number of request processing threads. As the load increases, it creates ThreadIncrement additional request processing threads until RqThrottle request processing threads have been created.
Default
The default value is 10.
UseNativePoll (UNIX only)
Uses a platform-specific poll interface when set to 1(on). Uses the NSPR poll interface in the KeepAlive subsystem when set to 0 (off).
Default
1 (on)
Native Thread PoolsThis section lists the directives for controlling the size of the native kernel thread pool. You can also 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.
On Windows, the default native pool is always being used and Sun ONE Web Server uses fibers (user-scheduled threads) for initial request processing. Using custom additional pools on Windows introduces no additional overhead.
The directives are:
NativePoolStackSize
Determines the stack size of each thread in the native (kernel) thread pool.
Default
0
NativePoolMaxThreads
Determines the maximum number of threads in the native (kernel) thread pool.
Default
NativePoolMinThreads
Determines the minimum number of threads in the native (kernel) thread pool.
Default
1
NativePoolQueueSize
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.
Default
0
CGIThis section lists the directives in magnus.conf that affect requests for CGI programs. The directives are:
CGIExpirationTimeout
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 — 300 seconds (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. A value of 0 disables CGI expiration, which means that there is no time limit for CGI processes.
Note that on Windows platforms init-cgi time-out does not work, so you must use CGIExpirationTimeout.
Default
0
CGIStubIdleTimeout
This directive causes the server to kill any CGIStub processes that have been idle for the number of seconds set by this directive. Once the number of processes is at MinCGIStubs, the server does not kill any more processes.
Default
30
CGIWaitPid (UNIX Only)
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.
Default
on
MaxCGIStubs
Controls the maximum number of CGIStub processes the server can spawn. This is the maximum concurrent CGIStub processes in execution, not the maximum number of pending requests. The default value should be adequate for most systems. Setting this too high may actually reduce throughput.
Default
10
MinCGIStubs
Controls the number of processes that are started by default. The first CGIStub process is not started until a CGI program has been accessed. Note that if you have an init-cgi directive in the magnus.conf file, the minimum number of CGIStub processes are spawned at startup. The value must be less than the MaxCGIStubs value.
Default
2
WincgiTimeout
WinCGI processes that take longer than this value are terminated when this timeout (in seconds) expires.
Default
60
Error Logging and Statistic CollectionThis section lists the directives in magnus.conf that affect error logging and the collection of server statistics. They are:
ErrorLogDateFormat
The ErrorLogDateFormat directive specifies the date format that the server logs use.
Syntax
ErrorLogDateFormat format
The format can be any format valid for the C library function strftime. See Time Formats.
Default
%d/%b/%Y:%H:%M:%S
LogFlushInterval
This directive determines the log flush interval, in seconds, of the log flush thread for the access log.
Default
30
PidLog
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.
Syntax
PidLog file
The file is the full path name and file name where the process ID is stored.
Default
There is no default.
Examples
PidLog /var/ns-server/logs/pid
PidLog /tmp/ns-server.pid
ACLThis section lists the directives in magnus.conf relevant to access control lists (ACLs). They are:
ACLCacheLifetime
ACLCacheLifetime determines the number of seconds before cache entries expire. Each time an entry in the cache is referenced, its age is calculated and checked against ACLCacheLifetime. The entry is not used if its age is greater than or equal to the ACLCacheLifetime. If this value is set to 0, the cache is turned off.
If you use a large number for this value, you may need to restart the Sun ONE Web Server when you make changes to the LDAP entries. For example, if this value is set to 120 seconds, the Sun ONE Web Server might be out of sync with the LDAP server for as long as two minutes. If your LDAP entries are not likely to change often, use a large number.
Default
120
ACLUserCacheSize
ACLUserCacheSize determines the number of users in the User Cache.
Default
200
ACLGroupCacheSize
ACLGroupCacheSize determines how many group IDs can be cached for a single UID/cache entry.
Default
4
SecurityThis section lists the directives in magnus.conf that affect server access and security issues for Sun ONE Web Server. They are:
Security
The Security directive globally enables or disables SSL by making certificates available to the server instance. It must be on for virtual servers to use SSL. If enabled, the user is prompted for the administrator password (in order to access certificates, and so on).
Syntax
Security [on|off]
Default
off
Example
Security off
ServerString
Allows the administrator to change the string sent with the Server HTTP header.
Syntax
ServerString string
string is the new string to send as the header. All characters, including quotes, will be sent. The string none, will cause the header to not be sent at all.
Example
ServerString My Own Server/1.0
ServerString none
SSLCacheEntries
Specifies the number of SSL sessions that can be cached. There is no upper limit.
Syntax
SSLCacheEntries number
If the number is 0, the default value, which is 10000, is used.
SSLClientAuthDataLimit
Specifies the maximum amount of application data, in bytes, that is buffered during the client certificate handshake phase.
Default
The default value is 1048576 (1 MB).
SSLClientAuthTimeout
Specifies the number of seconds after which the client certificate handshake phase times out.
Default
60
SSLSessionTimeout
The SSLSessionTimeout directive controls SSL2 session caching.
Syntax
SSLSessionTimeout seconds
The seconds value is the number of seconds until a cached SSL2 session becomes invalid. If the SSLSessionTimeout directive is specified, the value of seconds is silently constrained to be between 5 and 100 seconds.
Default
The default value is 100.
SSL3SessionTimeout
The SSL3SessionTimeout directive controls SSL3 session caching.
Syntax
SSL3SessionTimeout seconds
The 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 EncodingThis section lists directives that control chunked encoding. For more information, see the Sun ONE Web Server 6.1 NSAPI Programmer’s Guide
These directives have equivalent Service SAF parameters in obj.conf. The obj.conf parameters override these directives. For more information, see the Sun ONE Web Server 6.1 NSAPI Programmer’s Guide.
UseOutputStreamSize
The UseOutputStreamSize directive determines the default output stream buffer size for the net_read and netbuf_grab NSAPI functions.
Note
The UseOutputStreamSize parameter can be set to 0 in the obj.conf file to disable output stream buffering. For the magnus.conf file, setting UseOutputStreamSize to 0 has no effect.
Syntax
UseOutputStreamSize size
The size value is the number of bytes.
Default
The default value is 8192 (8 KB).
ChunkedRequestBufferSize
The ChunkedRequestBufferSize directive determines the default buffer size for “un-chunking” request data.
Syntax
ChunkedRequestBufferSize size
The size value is the number of bytes.
Default
The default value is 8192.
ChunkedRequestTimeout
The ChunkedRequestTimeout directive determines the default timeout for “un-chunking” request data.
Syntax
ChunkedRequestTimeout seconds
The seconds value is the number of seconds.
Default
The default value is 60 (1 minute).
Miscellaneous DirectivesThis section lists the following miscellaneous directives in magnus.conf:
Note
Directives noted with boolean values have the following equivalent values: on/yes/true and off/no/false.
ChildRestartCallback
This directive forces the callback of NSAPI functions that were registered using the daemon_atrestart function when the server is restarting or shutting down. Values are on, off, yes, no, true, or false.
Default
no
Favicon
To turn off the internal favicon.ico support, add the following line to magnus.conf:
Favicon off
HTTPVersion
The current HTTP version used by the server in the form m.n, where m is the major version number and n the minor version number.
Default
The default value is 1.1.
MaxRqHeaders
Specifies the maximum number of header lines in a request. Values range from 1 to 512.
Default
64
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 the Sun ONE Web Server 6.1 NSAPI Programmer’s Guide.
Deprecated DirectivesThe following directives have been deprecated in Sun ONE Web Server 6.1:
AdminLanguage
For an international version of the server, this directive specifies the language for the Server Manager. Values are en (English), fr (French), de (German) or ja (Japanese).
Default
The default is en.
ClientLanguage
For an international version of the server, this directive specifies the language for client messages (such as File Not Found). Values are en (English), fr (French), de (German) or ja (Japanese).
Default
The default is en.
NetsiteRoot
Specifies the absolute pathname to the top-level directory under which server instances can be found. This directive is used by the Administration Server. There is no default value; you must specify a value.
Syntax
NetsiteRoot path
ServerID
Specifies the server ID, such as https-boots.mcom.com.
ServerName
Specifies the server name.
ServerRoot
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.
Syntax
#ServerRoot path
Example
#ServerRoot d:/netscape/server4/https-boots.mcom.com
Summary of Init Functions and Directives in magnus.confPurpose
Contains global variable settings that affect server functioning. This file is read only at server start-up.
Location
server_root/https-admserv/config
server_root/https-admserv/conf_bk
server_root/https-server_id/config
server_root/https-server_id/conf_bk
Syntax
Init functions have the following syntax:
Init fn=function param1="value1" ...paramN="valueN"
In the following tableTable 3-1, functions are in bold to distinguish them from parameters.
Directives have the following syntax:
directive value
See Also
Sun ONE Web Server 6.1 NSAPI Programmer’s Guide
Init Functions
The following table lists the Init functions available in the magnus.conf file:
Directives
The following table lists