Sun Java System Web Server 6.1 SP12 Administrator's Configuration File Reference

Chapter 3 Syntax and Use of magnus.conf

When the Sun JavaTM System 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 Java System 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 Java System Web Server 6.1.

The categories are:


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 Functions

The Init functions load and initialize server modules and plug-ins, and initialize log files. For more information about these functions, see the Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide.

Server Information

This 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 – 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 Unix 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 Issues

This 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 Lookup

This 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, JSP, Servlet, 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.

Threads, Processes, and Connections

In Sun Java System 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:

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 Java System Web Server 6.1 SP12 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 Java System 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 (Windows), 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 1048576 for the 64–bit server.

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 Java System 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 Java System Web Server 6.1 Performance Tuning, Sizing, and Scaling Guide.

Default

1

PostThreadsEarly

If this directive is set to 1 (on), the server checks whether the minimum number of threads are available at a listen socket, after accepting a connection but before sending a response to the request. Use this directive, when the server handles request that take a long time, such as those that perform long database connections. By default, this directive is set to 0 (off) and as a result, the server checks whether the minimum number of threads are available at a listen socket, only after sending a response to the request.

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 Java System Web Server 6.1 SP12 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

off

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 Pools

This 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 Java System 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.

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

CGI

This 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 plug-in 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 Collection

This 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 Appendix C, 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

2

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

ACL

This 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 Java System Web Server when you make changes to the LDAP entries. For example, if this value is set to 120 seconds, the Sun Java System 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

Security

This section lists the directives in magnus.conf that affect server access and security issues for Sun Java System 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).


Note –

When you create a secure listen socket through the Server Manager, security is automatically turned on globally in magnus.conf. When you create a secure listen socket manually in server.xml, security must be turned on by editing magnus.conf.


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 Encoding

This section lists directives that control chunked encoding. For more information, see the Sun Java System Web Server 6.1 SP12 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. While AcceptTimeout determines how long the server waits for an individual packet, the ChunkedRequestTimeout determines how long the server will wait for all packets in total when reassembling a chunked request entity body. As a result, ChunkedRequestTimeout should typically be greater than or equal to AcceptTimeout.

Syntax

ChunkedRequestTimeout seconds

The seconds value is the number of seconds.

Default

The default value is 60 (1 minute).

Miscellaneous Directives

This 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 directive

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 Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide.

Deprecated Directives

The following directives have been deprecated in Sun Java System Web Server 6.1:

Summary of Init Functions and Directives in magnus.conf

Purpose

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 tableInit Functions, functions are in bold to distinguish them from parameters.

Directives have the following syntax:

directive value

See Also

Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide

Init Functions

The following table lists the Init functions available in the magnus.conf file:

Table 3–1 magnus.conf Init Functions

Function/Parameter  

Allowed Values  

Default Value  

Description  

cindex-init

   

Changes the default characteristics for fancy indexing. 

opts

s

(None) 

(optional) is a string of letters specifying the options to activate. Currently there is only one possible option: 

  • s tells the server to scan each HTML file in the directory being indexed for the contents of the HTML <TITLE> tag to display in the description field. The <TITLE> tag must be within the first 255 characters of the file.

widths

Comma separated numbers of characters 

Minimums required to display column titles 

(optional) Specifies the width for each of the four columns in the indexing display: name, last-modified date, size, and description respectively. 

The final three values can each be set to 0 to turn the display for that column off. The name column cannot be turned off. 

timezone

GMT or local

local

(optional, iPlanet Web Server 4.x only) Indicates whether the last-modified time is shown in local time or in Greenwich Mean Time.

format

Format for the UNIX function strftime()

%d-%b-%Y %H:%M

(optional, iPlanet Web Server 4.x only) Determines the format of the last modified date display.

ignore

Wildcard pattern 

.*

(optional) Specifies a wildcard pattern for file names the server should ignore while indexing. File names starting with a period (.) are always ignored. 

icon-uri

 

/mc-icons/

(optional) Specifies the URI prefix the index-common function uses when generating URLs for file icons (.gif files). If icon-uri is different from the default, the pfx2dir function in the NameTrans directive must be changed so that the server can find these icons.

define-perf-bucket

   

Creates a performance bucket, which you can use to measure the performance of SAFs in obj.conf (see the Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide). This function works only if the perf-init function is enabled.

name

   

A name for the bucket, for example cgi-bucket.

description

   

A description of what the bucket measures, for example CGI Stats.

dns-cache-init

   

Configures DNS caching. 

cache-size

32 to 32768 (32K)

1024

(optional) Specifies how many entries are contained in the cache. 

expire

1 to 31536000 seconds (1 year)

1200 seconds (20 minutes)

(optional) specifies how long (in seconds) it takes for a cache entry to expire. 

flex-init

   

Initializes the flexible logging system. 

logFileName

A path or file name 

 

The full path to the log file or a file name relative to the server’s logs directory. In this example, the log file name is access and the path is /logdir/access:

access="/logdir/access"

format.logFileName

   

Specifies the format of each log entry in the log file. See the Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide for more information.

buffer-size

Number of bytes 

8192

Specifies the size of the global log buffer. 

buffers-per-file

The lower bound is 1. There always needs to be at least one buffer per file. 

The upper bound is dictated by the number of buffers that exist. The upper bound on the number of buffers that exist can be defined by the num-buffers parameter. 

Determined by the server 

Specifies the number of buffers for a given log file 

num-buffers

 

1000

Specifies the maximum number of logging buffers to use. 

%duration%

   

This flex-log format variable, records the time in microseconds, spent by the server in processing requests. Statistics must be enabled for the server instance before %duration% is used. See Sun Java System Web Server 6.1 SP12 Administrator’s Guide for information on enabling statistics. For more information on log file formats, see Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide and Sun Java System Web Server 6.1 SP12 Administrator’s Guide.

flex-rotate-init

   

Enables rotation for logs. 

rotate-start

A 4-digit string indicating the time in 24-hour format 

 

Indicates the time to start rotation. For example, 0900 indicates 9 am while 1800 indicates 9 pm. 

rotate-interval

Number of minutes 

 

Indicates the number of minutes to elapse between each log rotation. 

rotate-access

yes, no

yes

(optional) determines whether common-log, flex-log, and record-useragent logs are rotated. For more information, see the Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide.

rotate-error

yes, no

yes

(optional) determines whether error logs are rotated. 

rotate-callback

A path 

 

(optional) specifies the file name of a user-supplied program to execute following log file rotation. The program is passed the post-rotation name of the rotated log file as its parameter. 

init-cgi

   

Changes the default settings for CGI programs. 

timeout

Number of seconds 

300

(optional) specifies how many seconds the server waits for CGI output before terminating the script. 

cgistub-path

 

 

(optional) specifies the path to the CGI stub binary. If not specified, iPlanet Web Server looks in the following directories, in the following order, relative to the server instance’s config directory: ../private/Cgistub, then ../../bin/https/bin/Cgistub.

For information about installing an suid Cgistub, see the Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide.

env-variable

   

(optional) specifies the name and value for an environment variable that the server places into the environment for the CGI. 

init-clf

   

Initializes the Common Log subsystem. 

logFileName

A path or file name 

 

Specifies either the full path to the log file or a file name relative to the server’s logs directory.

init-uhome

   

Loads user home directory information. 

pwfile

   

(optional) specifies the full file system path to a file other than /etc/passwd. If not provided, the default UNIX path (/etc/passwd) is used.

load-modules

   

Loads shared libraries into the server. 

shlib

   

Specifies either the full path to the shared library or dynamic link library or a file name relative to the server configuration directory. 

funcs

A comma separated list with no spaces 

 

A list of the names of the functions in the shared library or dynamic link library to be made available for use by other Init or Service directives. The dash (-) character may be used in place of the underscore (_) character in function names.

NativeThread

yes, no

yes

(optional) specifies which threading model to use. no causes the routines in the library to use user-level threading. yes enables kernel-level threading.

pool

 

 

The name of a custom thread pool, as specified in thread-pool-init.

nt-console-init

   

Enables the NT console, which is the command-line shell that displays standard output and error streams. 

stderr

console

 

Directs error messages to the NT console. 

stdout

console

 

Directs output to the NT console. 

perf-init

   

Enables system performance measurement via performance buckets. 

disable

true, false

true

Disables the function when true.

pool-init

   

Configures pooled memory allocation. 

block-size

   

(optional) size (in bytes) of the memory blocks allocated by the internal pooled memory allocator. Default value is 32768.

free-size

1048576 bytes or less

 

(optional) maximum size in bytes of free block list. 

disable

true, false

false

(optional) flag to disable the use of pooled memory if true.

register-http-method

   

Lets you extend the HTTP protocol by registering new HTTP methods. 

methods

A comma separated list 

 

Names of the methods you are registering. 

stats-init

   

Enables reporting of performance statistics in XML format. 

profiling

yes, no

no

Enables NSAPI performance profiling using buckets. This can also be enabled through perf-init.

update-interval

1 or greater

5

The period in seconds between statistics updates within the server. 

virtual-servers

1 or greater

1000

The maximum number of virtual servers for which statistics are tracked. This number should be set higher than the number of virtual servers configured. 

thread-pool-init

   

Configures an additional thread pool. 

name

   

Name of the thread pool. 

maxthreads

   

Maximum number of threads in the pool.You can use only five threads at a time in the FastTrack edition of iPlanet Web Server. 

minthreads

   

Minimum number of threads in the pool. 

queueSize

Number of bytes 

 

Size of the queue for the pool. 

stackSize

Number of bytes 

 

Stack size of each thread in the native (kernel) thread pool. 

Directives

The following table lists

Table 3–2 magnus.conf Directives

Directive  

Allowed Values  

Default Value  

Description  

AcceptTimeout

Any number of seconds 

30 for servers that don't use hardware encryption devices and 300 for those that do

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. 

ACLCacheLifetime

Any number of seconds 

120

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.

ACLUserCacheSize

 

200

Determines the number of users in the User Cache. 

ACLGroupCacheSize

 

4

Determines how many group IDs can be cached for a single UID/cache entry. 

AsyncDNS

on, off

off

Specifies whether asynchronous DNS is allowed. 

CGIExpirationTimeout

Any number of seconds 

300 (5 minutes) recommended

Specifies the maximum time in seconds that CGI processes are allowed to run before being killed. 

CGIStubIdleTimeout

Any number of seconds 

30

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.

CGIWaitPid

on, off

on

(UNIX only) makes the action for the SIGCHLD signal the system default action for the signal. Makes the SHTML engine wait explicitly on its exec cmd child processes. 

ChildRestartCallback

on, off, yes, no, true, false

no

Forces the callback of NSAPI functions that were registered using the daemon_atrestart function when the server is restarting or shutting down.

ChunkedRequestBufferSize

Any number of bytes 

8192

Determines the default buffer size for “un-chunking” request data. 

ChunkedRequestTimeout

Any number of seconds 

60 (1 minute).

Determines the default timeout for “un-chunking” request data. 

ConnQueueSize

Any number of connections (including 0) 

4096

Specifies the number of outstanding (yet to be serviced) connections that the web server can have. 

This setting can have performance implications. For more information, see the Sun Java System Web Server 6.1 SP12 Performance Tuning, Sizing, and Scaling Guide.

DefaultLanguage

en (English),fr (French),de (German),ja (Japanese)

en

Specifies the default language for the server. The default language is used for both the client responses and administration. 

DNS

on, off

on

Specifies whether the server performs DNS lookups on clients that access the server. 

ErrorLogDateFormat

See the manual page for the C library function strftime

%d/%b/%Y:%H:%M:%S

The date format for the error log. 

ExtraPath

A path 

(none) 

Appends the specified directory name to the PATH environment variable. This is used for configuring Java on Windows NT. There is no default value; you must specify a value.

Favicon

On / Off

on

Provides the web server administrator the ability to disable or change the icon which appears in the web address book or favorites list on Internet Explorer browsers (so, favicon translates as favorite icon).

HeaderBufferSize

Any number of bytes 

8192 (8 KB)

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.

HTTPVersion

m.n; m is the major version number and n the minor version number

1.1

The current HTTP version used by the server. 

KeepAliveQueryMaxSleepTime

 

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. 

This directive specifies an upper limit to the time slept (in milliseconds) after polling keep-alive connections for further requests. 

KeepAliveQueryMeanTime

 

100 is appropriate for almost all installations.

Note that CPU usage will increase with lower KeepAliveQueryMeanTime values. 

This directive specifies the desired keep-alive latency in milliseconds. 

KeepAliveThreads

Any number of threads 

1

Specifies 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. 

KeepAliveTimeout

300 seconds maximum

30

Determines the maximum time that the server holds open an HTTP Keep-Alive connection or a persistent connection between the client and the server. 

KernelThreads

0 (off), 1 (on)

0 (off)

If on, ensures that the server uses only kernel-level threads, not user-level threads. If off, uses only user-level threads. 

ListenQ

Ranges are platform-specific 

4096 (AIX), 200 (NT), 128 (all others)

Defines the number of incoming connections for a server socket. 

LogFlushInterval

Any number of seconds 

30

Determines the log flush interval, in seconds, of the log flush thread. 

MaxCGIStubs

Any number of CGI stubs 

10

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. 

MaxKeepAliveConnections

0 - 1048576 (for 64–bit server)

25616

Specifies the maximum number of Keep-Alive and persistent connections that the server can have open simultaneously. 

MaxProcs

Any number of processes1 

1

(UNIX only) Specifies the maximum number of processes that the server can have running simultaneously. 

MaxRqHeaders

1 - 512

64

Specifies the maximum number of header lines in a request. 

MinCGIStubs

Any number less than MaxCGIStubs 

2

Controls the number of processes that are started by default. 

NativePoolMaxThreads

Any number of threads 

1285

Determines the maximum number of threads in the native (kernel) thread pool. 

NativePoolMinThreads

Any number of threads 

1

Determines the minimum number of threads in the native (kernel) thread pool. 

NativePoolQueueSize

Any nonnegative number 

0

Determines the number of threads that can wait in the queue for the thread pool. 

NativePoolStackSize

Any nonnegative number 

0

Determines the stack size of each thread in the native (kernel) thread pool. 

PidLog

A valid path to a file 

(none) 

Specifies a file in which to record the process ID (pid) of the base server process. 

PostThreadsEarly

1 (on), 0 (off)

0 (off) 

If on, checks whether the minimum number of threads are available at a socket after accepting a connection but before sending the response to the request. 

RcvBufSize

Range is platform-specific 

0 (uses platform-specific default)

Controls the size of the receive buffer at the server’s sockets. 

RqThrottle

Any number of requests (including 0) 

51216

Specifies the maximum number of simultaneous request processing threads that the server can handle simultaneously per socket. 

This setting can have performance implications. For more information, see the Sun Java System Web Server 6.1 SP12 Performance Tuning, Sizing, and Scaling Guide.

RqThrottleMin

Any number less than RqThrottle

484

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).

Security

on, off

off

Globally enables or disables SSL by making certificates available to the server instance. Must be on for virtual servers to use SSL.

SndBufSize

Range is platform-specific 

0 (uses platform-specific default)

Controls the size of the send buffer at the server’s sockets. 

SSL3SessionTimeout

5 - 86400

86400 (24 hours).

The number of seconds until a cached SSL3 session becomes invalid. 

SSLCacheEntries

A non-negative integer 

10000 (used if 0 is specified)

Specifies the number of SSL sessions that can be cached. There is no upper limit. 

SSLClientAuthDataLimit

Number of Bytes 

1048576 (1MB)

Specifies the maximum amount of application data that is buffered during the client certificate handshake phase. 

SSLClientAuthTimeout

Any number of seconds 

60

Specifies the number of seconds after which the client certificate handshake phase times out. 

SSLSessionTimeout

5 - 100

100

Specifies the number of seconds until a cached SSL2 session becomes invalid. 

StackSize

Number of Bytes 

The most favorable machine- specific stack size. 

Determines the maximum stack size for each request handling thread. 

StrictHttpHeaders

on, off

off

If on, rejects connections that include inappropriately duplicated headers.

TempDir

A path 

/tmp (UNIX)

TEMP (environment variable for Windows NT)

Specifies the directory the server uses for its temporary files. On UNIX, this directory should be owned by, and writable by, the user the server runs as. 

TempDirSecurity

on, off

on

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.

TerminateTimeout

Any number of seconds 

30

Specifies the time in seconds that the server waits for all existing connections to terminate before it shuts down. 

ThreadIncrement

Any number of threads 

10

The number of additional or new request processing threads created to handle an increase in the load on the server. 

Umask

A standard UNIX umask value 

(none) 

UNIX only: Specifies the umask value used by the NSAPI functions System_fopenWA() and System_fopenRW() to open files in different modes.

UseNativePoll

1 (on), 0 (off)

1 (on)

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).

UseOutputStreamSize

Any number of bytes 

8192 (8 KB)

Determines the default output stream buffer size for the net_read and netbuf_grab NSAPI functions.

User

A login name, 8 characters or less 

(none) 

(Windows NT) specifies the user account the server runs with, allowing you to restrict or enable system features for the server. 

(UNIX) 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.

WincgiTimeout

Any number of seconds 

60

WinCGI processes that take longer than this value are terminated when this timeout expires.