Chapter 7
Syntax and Use of 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. iPlanet Web Server executes all the directives defined in magnus.conf.
Except for the Init SAFs, the directives in magnus.conf specify a variable and a value, for example:
|
ServerID https-boots.mcom.com
#ServerRoot d:/netscape/server4/https-boots.mcom.com
|
|
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 iPlanet Web Server 6.0.
The categories are:
For an alphabetical list of directives, see Appendix H "Alphabetical List of Directives in magnus.conf."
Init SAFs
The Init directives initialize the server, for example they load and initialize additional modules and plugins, and initialize log files.
The Init directives are SAFs, like obj.conf directives, and have SAF syntax rather than the simpler variable value syntax of other magnus.conf directives. They are located in magnus.conf because, like other magnus.conf directives, they are executed only once at server startup.
Each Init directive has an optional LateInit parameter. For the Unix platform, if LateInit is set to yes, the function is executed by the child process after it is forked from the parent. If LateInit is set to no or is not provided, the function is executed by the parent process before the fork. When the server is started up by user root but runs as another user, any activities that must be performed as the user root (such as writing to a root-owned file) must be done before the fork. Functions that create threads, with the exception of thread-pool-init, should execute after the fork (that is, the relevant Init directive should have LateInit=yes set).
For all platforms, any function that requires access to a fully parsed configuration should have LateInit=yes set on its Init directive.
Upon failure, Init-class functions return REQ_ABORTED. The server logs the error according to the instructions in the Error directives in obj.conf, and terminates. Any other result code is considered a success.
The following Init-class functions are described in detail in this section:
cindex-init
Applicable in Init-class directives.
The function cindex-init sets the default settings for common indexing. Common indexing (also known as fancy indexing) is performed by the Service function index-common. Indexing occurs when the requested URL translates to a directory that does not contain an index file or home page, or no index file or home page has been specified.
In common (fancy) indexing, the directory list shows the name, last modified date, size and description for each indexed file or directory.
Parameters:
|
opts
|
(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. This option is off by default.
The search for <TITLE> is not case-sensitive.
|
|
widths
|
(optional) specifies the width for each column in the indexing display. The string is a comma-separated list of numbers that specify the column widths in characters for name, last-modified date, size, and description respectively.
The default values for the widths parameter are 22,18,8,33.
The final three values (corresponding to last-modified date, size, and description respectively) can each be set to 0 to turn the display for that column off. The name column cannot be turned off. The minimum size of a column (if the value is non-zero) is specified by the length of its title -- for example, the minimum size of the Date column is 5 (the length of "Date" plus one space). If you set a non-zero value for a column which is less than the length of its title, the width defaults to the minimum required to display the title.
|
|
timezone
|
(optional) This indicates whether the last-modified time is shown in local time or in Greenwich Mean Time. The values are GMT or local. The default is local.
|
|
format
|
(optional) This parameter determines the format of the last modified date display. It uses the format specification for the UNIX function strftime().
The default is %d-%b-%Y %H:%M.
|
|
ignore
|
(optional) specifies a wildcard pattern for file names the server should ignore while indexing. File names starting with a period (.) are always ignored. The default is to only ignore file names starting with a period (.).
|
|
icon-uri
|
(optional) specifies the URI prefix the index-common function uses when generating URLs for file icons (.gif files). By default, it is /mc-icons/. 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.
|
Example:
|
|
Init fn=cindex-init widths=50,1,1,0
|
|
Init fn=cindex-init ignore=*private*
|
|
Init fn=cindex-init widths=22,0,0,50
|
|
See Also
index-common, find-index, home-page
define-perf-bucket
Applicable in Init-class directives.
The define-perf-bucket function creates a performance bucket, which you can use to measure the performance of SAFs in obj.conf see "The bucket Parameter" and the service-dump function). This function works only if the perf-init function is enabled.
For more information about performance buckets, see the Performance Tuning, Sizing, and Scaling Guide for iPlanet Web Server.
Parameters
|
name
|
A name for the bucket, for example cgi-bucket.
|
|
description
|
A description of what the bucket measures, for example CGI Stats.
|
Example:
|
|
Init fn="define-perf-bucket" name="cgi-bucket" description="CGI Stats"
|
|
See Also
perf-init
dns-cache-init
Applicable in Init-class directives.
The dns-cache-init function specifies that DNS lookups should be cached when DNS lookups are enabled. If DNS lookups are cached, then when the server gets a client's host name information, it stores that information in the DNS cache. If the server needs information about the client in the future, the information is available in the DNS cache.
You may specify the size of the DNS cache and the time it takes before a cache entry becomes invalid. The DNS cache can contain 32 to 32768 entries; the default value is 1024 entries. Values for the time it takes for a cache entry to expire (specified in seconds) can range from 1 second to 1 year; the default value is 1200 seconds (20 minutes).
Parameters
|
cache-size
|
(optional) specifies how many entries are contained in the cache. Acceptable values are 32 to 32768; the default value is 1024.
|
|
expire
|
(optional) specifies how long (in seconds) it takes for a cache entry to expire. Acceptable values are 1 to 31536000 (1 year); the default is 1200 seconds (20 minutes).
|
Example:
|
|
Init fn="dns-cache-init" cache-size="2140" expire="600"
|
|
flex-init
Applicable in Init-class directives.
The flex-init function opens the named log file to be used for flexible logging and establishes a record format for it. The log format is recorded in the first line of the log file. You cannot change the log format while the log file is in use by the server.
The flex-log function writes entries into the log file during the AddLog stage of the request handling process.
The log file stays open until the server is shut down or restarted (at which time all logs are closed and reopened).
|
Note
|
If the server has AddLog stage directives that call flex-log, the flexible log file must be initialized by flex-init during server initialization.
|
You may specify multiple log file names in the same flex-init function call. Then use multiple AddLog directives with the flex-log function to log transactions to each log file.
The flex-init function may be called more than once. Each new log file name and format will be added to the list of log files.
If you move, remove, or change the currently active log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup the currently active log file, you need to rename the file and then restart the server. The server first looks for the log file by name, and if it doesn't find it, creates a new one (the renamed original log file is left for you to use).
For information on rotating log files, see flex-rotate-init.
The flex-init function has three parameters: one that names the log file, one that specifies the format of each record in that file, and one that specifies the logging mode.
Parameters
|
logFileName
|
The name of the parameter is the name of the log file. The value of the parameter specifies either the full path to the log file or a file name relative to the server's logs directory. For example:
access="/usr/netscape/server4/https-servername/logs/access"
mylogfile = "log1"
You will use the log file name later, as a parameter to the flex-log function.
|
|
format.logFileName
|
specifies the format of each log entry in the log file.
For information about the format, see the "More on Log Format" section below.
|
|
buffer-size
|
Specifies the size of the global log buffer. The default is 8192. See the third flex-init example below.
|
|
num-buffers
|
Specifies the maximum number of logging buffers to use. The default is 1000. See the third flex-init example below.
|
More on Log Format
The flex-init function recognizes anything contained between percent signs (%) as the name portion of a name-value pair stored in a parameter block in the server. (The one exception to this rule is the %SYSDATE% component which delivers the current system date.) %SYSDATE% is formatted using the time format %d/%b/%Y:%H:%M:%S plus the offset from GMT.
(See Chapter 4 "Creating Custom SAFs" for more information about parameter blocks and Chapter 5 "NSAPI Function Reference," for functions to manipulate pblocks.)
Any additional text is treated as literal text, so you can add to the line to make it more readable. Typical components of the formatting parameter are listed in Table 7-1. Certain components might contain spaces, so they should be bounded by escaped quotes (\").
If no format parameter is specified for a log file, the common log format is used:
"%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%]
\"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status%
%Req->srvhdrs.content-length%"
You can now log cookies by logging the Req->headers.cookie.name component.
In the following table, the components that are enclosed in escaped double quotes (\") are the ones that could potentially resolve to values that have white spaces.
Table 7-1 Typical components of flex-init formatting
|
Flex-log option
|
Component
|
|
Client Host name (unless iponly is specified in flex-log or DNS name is not available) or IP address
|
%Ses->client.ip%
|
|
Client DNS name
|
%Ses->client.dns%
|
|
System date
|
%SYSDATE%
|
|
Full HTTP request line
|
\"%Req->reqpb.clf-request%\"
|
|
Status
|
%Req->srvhdrs.clf-status%
|
|
Response content length
|
%Req->srvhdrs.content-length%
|
|
Response content type
|
%Req->srvhdrs.content-type%
|
|
Referer header
|
\"%Req->headers.referer%\"
|
|
User-agent header
|
\"%Req->headers.user-agent%\"
|
|
HTTP Method
|
%Req->reqpb.method%
|
|
HTTP URI
|
%Req->reqpb.uri%
|
|
HTTP query string
|
%Req->reqpb.query%
|
|
HTTP protocol version
|
%Req->reqpb.protocol%
|
|
Accept header
|
%Req->headers.accept%
|
|
Date header
|
%Req->headers.date%
|
|
If-Modified-Since header
|
%Req->headers.if-modified-since%
|
|
Authorization header
|
%Req->headers.authorization%
|
|
Any header value
|
%Req->headers.headername%
|
|
Name of authorized user
|
%Req->vars.auth-user%
|
|
Value of a cookie
|
%Req->headers.cookie.name%
|
|
Value of any variable
in Req->vars
|
%Req->vars.varname%
|
|
Virtual Server ID
|
%vsid%
|
Examples
The first example below initializes flexible logging into the file /usr/netscape/server4/https-servername/logs/access.
|
|
Init fn=flex-init access="/usr/netscape/server4/https-servername/logs/access" format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"
|
|
This will record the following items
|
ip or hostname, followed by the three characters " - "
the user name, followed by the two characters " ["
the system date, followed by the two characters "] "
the full HTTP request in quotes, followed by a single space
the HTTP result status in quotes, followed by a single space
the content length
|
|
This is the default format, which corresponds to the Common Log Format (CLF).
It is advisable that the first six elements of any log always be in exactly this format, because a number of log analyzers expect that as output.
The second example initializes flexible logging into the file /user/netscape/server4/https-servername/logs/extended.
|
|
Init fn=flex-init extended="/usr/netscape/server4/https-servername/logs/extended" format.extended="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length% %Req->headers.referer% \"%Req->headers.user-agent%\" %Req->reqpb.method% %Req->reqpb.uri% %Req->reqpb.query% %Req->reqpb.protocol%"
|
|
The third example shows how logging can be tuned to prevent request handling threads from making blocking calls when writing to log files, instead delegating these calls to the log flush thread.
Doubling the size of the buffer-size and num-buffers parameters from their defaults and lowering the value of the LogFlushInterval magnus.conf directive to 4 seconds (see Chapter 7 "Syntax and Use of magnus.conf") frees the request handling threads to quickly write the log data.
|
|
Init fn=flex-init buffer-size=16384 num-buffers=2000 access="/usr/netscape/server4/https-servername/logs/access" format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"
|
|
See Also
flex-rotate-init, flex-log
flex-rotate-init
Applicable in Init-class directives.
The flex-rotate-init function configures log rotation for all log files on the server, including error logs and the common-log, flex-log, and record-useragent AddLog SAFs. Call this function in the Init section of magnus.conf before calling flex-init. The flex-rotate-init function allows you to specify a time interval for rotating log files. At the specified time interval, the server moves the log file to a file whose name indicates the time of moving. The log functions in the AddLog stage in obj.conf then start logging entries in a new log file. The server does not need to be shut down while the log files are being rotated.
|
Note
|
The server keeps all rotated log files forever, so you will need to clean them up as necessary to free up disk space.
|
By default, log rotation is disabled.
Parameters
|
rotate-start
|
Indicates the time to start rotation. This value is a 4 digit string indicating the time in 24 hour format, for example, 0900 indicates 9 am while 1800 indicates 9 pm.
|
|
rotate-interval
|
Indicates the number of minutes to elapse between each log rotation.
|
|
rotate-access
|
(optional) determines whether common-log, flex-log, and record-useragent logs are rotated. Values are yes (the default) and no.
|
|
rotate-error
|
(optional) determines whether error logs are rotated. Values are yes (the default) and no.
|
|
rotate-callback
|
(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.
|
Example
This example enables log rotation, starting at midnight and occurring every hour.
|
|
Init fn=flex-rotate-init rotate-start=2400 rotate-interval=60
|
|
See Also
flex-init, common-log, flex-log, record-useragent
init-cgi
Applicable in Init-class directives.
The init-cgi function performs certain initialization tasks for CGI execution. Two options are provided: timeout of the execution of the CGI script, and establishment of environment variables.
Parameters
|
timeout
|
(optional) specifies how many seconds the server waits for CGI output. If the CGI script has not delivered any output in that many seconds, the server terminates the script. The default is 300 seconds.
|
|
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.
Use the first directory to house an suid Cgistub (that is, a Cgistub owned by root which has the set-user-ID-on-exec bit set). Use the second directory to house a non-suid Cgistub. The second directory is the location used by iPlanet Web Server 4.x servers.
If present, the ../private directory must be owned by the server user and have permissions d??x------. This prevents other users (for example, users with shell accounts or CGI access) from using Cgistub to set their uid.
For information about installing an suid Cgistub, see the iPlanet Web Server 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. You can set any number of environment variables in a single init-cgi function.
|
Example
|
|
Init fn=init-cgi LD_LIBRARY_PATH=/usr/lib;/usr/local/lib
|
|
See Also
send-cgi, send-wincgi, send-shellcgi
init-clf
Applicable in Init-class directives.
The init-clf function opens the named log files to be used for common logging. The common-log function writes entries into the log files during the AddLog stage of the request handling process. The log files stay open until the server is shut down (at which time the log files are closed) or restarted (at which time the log files are closed and reopened).
|
Note
|
If the server has an AddLog stage directive that calls common-log, common log files must be initialized by init-clf during initialization.
|
|
Note
|
This function should only be called once. If it is called again, the new call will replace log file names from all previous calls.
|
If you move, remove, or change the log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup a log file, you need to rename the file (and for Unix, send the -HUP signal) and then restart the server. The server first looks for the log file by name, and if it doesn't find it, creates a new one (the renamed original log file is left for you to use).
For information on rotating log files, see flex-rotate-init.
Parameters
|
logFileName
|
The name of the parameter is the name of the log file. The value of the parameter specifies either the full path to the log file or a file name relative to the server's logs directory. For example:
access="/usr/netscape/server4/https-servername/logs/access"
mylogfile = "log1"
You will use the log file name later, as a parameter to the common-log function.
|
Examples
|
|
Init fn=init-clf access=/usr/netscape/server4/https-boots/logs/access
|
|
Init fn=init-clf templog=/tmp/mytemplog templog2=/tmp/mytemplog2
|
|
See Also
common-log, record-useragent, flex-rotate-init
init-uhome
Applicable in Init-class directives.
Unix Only. The init-uhome function loads information about the system's user home directories into internal hash tables. This increases memory usage slightly, but improves performance for servers that have a lot of traffic to home directories.
Parameters
|
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.
|
Examples
|
|
Init fn=init-uhome
|
|
Init fn=init-uhome pwfile=/etc/passwd-http
|
|
See Also
unix-home, find-links
load-modules
Applicable in Init-class directives.
The load-modules function loads a shared library or Dynamic Link Library into the server code. Specified functions from the library can then be executed from any subsequent directives. Use this function to load new plugins or SAFs.
If you define your own Server Application Functions, you get the server to load them by using the load-modules function and specifying the shared library or dll to load.
Parameters
|
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
|
is a comma separated list of the names of the functions in the shared library or dynamic link library to be made available for use by other Init directives or by Service directives in obj.conf. The list should not contain any spaces. The dash (-) character may be used in place of the underscore (_) character in function names.
|
|
NativeThread
|
(optional) specifies which threading model to use.
no causes the routines in the library to use user-level threading.
yes enables kernel-level threading. The default is yes.
|
|
pool
|
the name of a custom thread pool, as specified in thread-pool-init.
|
Examples
|
|
Init fn=load-modules shlib="C:/mysrvfns/corpfns.dll" funcs="moveit"
|
|
Init fn=load-modules shlib="/mysrvfns/corpfns.so" funcs="myinit,myservice"
Init fn=myinit
|
|
nt-console-init
Applicable in Init-class directives.
The nt-console-init function enables the NT console, which is the command-line shell that displays standard output and error streams.
Parameters
|
stderr
|
Directs error messages to the NT console. The required and only value is console.
|
|
stdout
|
Directs output to the NT console. The required and only value is console.
|
Example
|
|
Init fn="nt-console-init" stdout=console stderr=console
|
|
perf-init
Applicable in Init-class directives.
The perf-init function enables system performance measurement via performance buckets.
For more information about performance buckets, see the Performance Tuning, Sizing, and Scaling Guide for iPlanet Web Server.
Parameters
|
disable
|
flag to disable the use of system performance measurement via performance buckets. Should have a value of true or false. Default value is true.
|
Example
|
|
Init fn=perf-init disable=false
|
|
See Also
define-perf-bucket
pool-init
Applicable in Init-class directives.
The pool-init function changes the default values of pooled memory settings. The size of the free block list may be changed or pooled memory may be entirely disabled.
Memory allocation pools allow the server to run significantly faster. If you are programming with the NSAPI, note that MALLOC, REALLOC, CALLOC, STRDUP, and FREE work slightly differently if pooled memory is disabled. If pooling is enabled, the server automatically cleans up all memory allocated by these routines when each request completes. In most cases, this will improve performance and prevent memory leaks. If pooling is disabled, all memory is global and there is no clean-up.
If you want persistent memory allocation, add the prefix PERM_ to the name of each routine (PERM_MALLOC, PERM_REALLOC, PERM_CALLOC, PERM_STRDUP, and PERM_FREE).
|
Note
|
Any memory you allocate from Init-class functions will be allocated as persistent memory, even if you use MALLOC. The server cleans up only the memory that is allocated while processing a request, and because Init-class functions are run before processing any requests, their memory is allocated globally.
|
Parameters
|
free-size
|
(optional) maximum size in bytes of free block list. May not be greater than 1048576.
|
|
disable
|
(optional) flag to disable the use of pooled memory. Should have a value of true or false. Default value is false.
|
Example
|
|
Init fn=pool-init disable=true
|
|
register-http-method
Applicable in Init-class directives.
This function lets you extend the HTTP protocol by registering new HTTP methods. (You do not need to register the default HTTP methods.)
Upon accepting a connection, the server checks to see if the method that it received is known to it. If the server does not recognize the method, it returns a "501 Method Not Implemented" error message.
Parameters
|
methods
|
is a comma separated list of the names of the methods you are registering.
|
Example
The following example shows the use of register-http-method and a Service function for one of the methods.
|
|
Init fn="register-http-method" methods="MY_METHOD1,MY_METHOD2"
Service fn="MyHandler" method="MY_METHOD1"
|
|
stats-init
Applicable in Init-class directives.
This function enables reporting of performance statistics in XML format. The actual report is generated by the stats-xml function in obj.conf.
Parameters
|
update-interval
|
period in seconds between statistics updates within the server. Set higher for better performance, lower for more frequent updates. The minimum value is 1; the default is 5.
|
|
virtual-servers
|
maximum number of virtual servers for which statistics are tracked. This number should be set higher than the number of virtual servers configured. Smaller numbers result in lower memory usage. The minimum value is 1; the default is 1000.
|
|
profiling
|
enables NSAPI performance profiling using buckets if set to yes. This can also be enabled through the perf-init Init SAF. The default is no, which results in slightly better server performance.
|
Example
|
Init fn="stats-init" update-interval="5" virtual-servers="2000"
profiling="yes"
|
|
See also
stats-xml
thread-pool-init
Applicable in Init-class directives.
This function creates a new pool of user threads. A pool must be declared before it's used. To tell a plugin to use the new pool, specify the pool parameter when loading the plugin with the Init-class function load-modules.
One reason to create a custom thread pool would be if a plugin is not thread-aware, in which case you can set the maximum number of threads in the pool to 1.
The older parameter NativeThread=yes always engages one default native pool, called NativePool.
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 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.
In addition, native thread pool parameters can be added to the magnus.conf file for convenience. For more information, see "Native Thread Pools" in Chapter 7 "Syntax and Use of magnus.conf."
Parameters
|
name
|
name of the thread pool.
|
|
maxthreads
|
maximum number of threads in the pool.
|
|
minthreads
|
minimum number of threads in the pool.
|
|
queueSize
|
size of the queue for the pool. If all the threads in the pool are busy, further request-handling threads that want to get a thread from the pool will wait in the pool queue. The number of request-handling threads that can wait in the queue is limited by the queue size. If the queue is full, the next request-handling thread that comes to the queue is turned away, with the result that the request is turned down, but the request-handling thread remains free to handle another request instead of becoming locked up in the queue.
|
|
stackSize
|
stack size of each thread in the native (kernel) thread pool.
|
Example
|
|
Init fn=thread-pool-init name="my-custom-pool" maxthreads=5 minthreads=1 queuesize=200
Init fn=load-modules shlib="C:/mydir/myplugin.dll" funcs="tracker" pool="my-custom-pool"
|
|
See also
load-modules
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 NT. There is no default value; you must specify a value.
Syntax
ExtraPath path
MtaHost
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.
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
ServerConfigurationFile
Specifies the location of the virtual server configuration file.
Syntax
ServerConfigurationFile path
Default
ServerConfigurationFile server_root/server_id/config/server.xml
ServerID
Specifies the server ID, such as https-boots.mcom.com.
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
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 NT)
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 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.
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 Issues
This section lists the directives in magnus.conf related to language issues. The directives are:
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.
DefaultCharSet
For an international version of the server, this directive specifies the default character set for the server. The default character set is used for both the client responses and administration.
Default
The default is iso-8859-1.
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 lookup. The directives are:
AsyncDNS
Specifies whether asynchronous DNS is allowed. The DNS directive must be set to on for this directive to take effect. The value is either on or off. If DNS is enabled, enabling asynchronous DNS improves server performance.
Default
The default is off.
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 server.
Syntax
DNS [on|off]
Default
DNS host name resolution is on as a default.
Example
DNS on
Threads, Processes and Connections
In iPlanet Web Server 6.0, 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.
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.
Default
The default value is 5000.
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).
IOTimeout
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
IOTimeout seconds
Default
30 seconds for servers that don't use hardware encryption devices and 300 seconds for those that do.
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
iPlanet 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 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 (NT), 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
256
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 iPlanet Web Server 6.0, there is always a primordial process in addition to the number of active processes specified by this setting.
There is additional discussion of this and other server configuration and performance tuning issues in the Performance Tuning, Sizing, and Scaling Guide for iPlanet Web Server.
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.
There is additional discussion of this and other server configuration and performance tuning issues in the Performance Tuning, Sizing, and Scaling Guide for iPlanet Web Server.
Default
128
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).
Default
48
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 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 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.
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
128
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 NT 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 Collection
This section lists the directives in magnus.conf that affect error logging and the collection of server statistics. They are:
ErrorLog
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.
Syntax
ErrorLog logfile
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.
Examples
Windows NT:
ErrorLog C:\Netscape\ns-home\Logs\Errors
Unix:
ErrorLog /var/ns-server/logs/errors
ErrorLog SYSLOG
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 D "Time Formats."
Default
%d/%b/%Y:%H:%M:%S
LogFlushInterval
This directive determines the log flush interval, in seconds, of the log flush thread.
Default
30
LogVerbose
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.
Default
off
LogVsId
This directive determines whether or not virtual server IDs are displayed in the error log. You should enable LogVsId when multiple virtual servers share the same log file.
Default
off
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 iPlanet Web Server when you make changes to the LDAP entries. For example, if this value is set to 120 seconds, the iPlanet Web Server might be out of sync with the LDAP server for as long as two minutes. If your LDAP is 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 iPlanet 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.
|
For more information about enabling SSL for individual virtual servers, see Chapter 8 "Virtual Server Configuration Files."
Syntax
Security [on|off]
Default
off
Example
Security off
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 "Buffered Streams."
These directives have equivalent Service SAF parameters in obj.conf. The obj.conf parameters override these directives. For more information, see "Service Stage."
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 zero in the obj.conf file to disable output stream buffering. For the magnus.conf file, setting UseOutputStreamSize to zero 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
This section lists miscellaneous other 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
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 0 to 32.
Default
32
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."