Sun ONE Web Server 6.1 NSAPI Programmer's Guide |
Chapter 2
SAFs in the magnus.conf FileWhen the Sun ONE Web Server starts up, it looks in a file called magnus.conf in the server-id/config directory to establish a set of global variable settings that affect the server’s behavior and configuration. Sun ONE Web Server executes all of 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 Init SAFs that can be specified in magnus.conf in Sun ONE Web Server 6.1. For information about the other, non-SAF directives in magnus.conf, see the Sun ONE Web Server 6.1 Administrator's Configuration File Reference.
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.
Syntax
Init functions have the following syntax:
Init fn=function param1="value1" ...paramN="valueN"
Directives have the following syntax:
directive value
The following Init-class functions and their parameters are described in detail in this chapter:
- cindex-init changes the default characteristics for fancy indexing.
- define-perf-bucket creates a performance bucket.
- dns-cache-init configures DNS caching.
- flex-init initializes the flexible logging system.
- flex-rotate-init enables rotation for flexible logs.
- init-cgi changes the default settings for CGI programs.
- init-clf initializes the Common Log subsystem.
- init-dav initializes the WebDAV subsystem.
- init-filter-order controls the position of specific filters within filter stacks.
- init-j2ee initializes the Java subsystem.
- init-uhome loads user home directory information.
- load-modules loads shared libraries into the server.
- nt-console-init enables the Windows console, which is the command-line shell that displays standard output and error streams.
- perf-init enables system performance measurement via performance buckets.
- pool-init configures pooled memory allocation.
- register-http-method lets you extend the HTTP protocol by registering new HTTP methods.
- stats-init enables reporting of performance statistics in XML format.
- thread-pool-init configures an additional thread pool.
cindex-initApplicable 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
The following table describes parameters for the cindex-init function.
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
define-perf-bucketApplicable 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 (for more information about predefined SAFs that are used in obj.conf, see the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference).
For more information about performance buckets, see the Sun ONE Web Server 6.1 Performance Tuning, Sizing, and Scaling Guide.
Parameters
The following table describes parameters for the define-perf-bucket function.
Table 2-2 define-perf-bucket parameters
Parameter
Description
name
Name for the bucket (for example, cgi-bucket).
description
Description of what the bucket measures (for example, CGI Stats).
Example
See Also
dns-cache-initApplicable 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
The following table describes parameters for the dns-cache-init function.
Example
flex-initApplicable 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 (applicable in AddLog-class directives) 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).
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
The following table describes parameters for the flex-init function.
Table 2-4 flex-init parameters
Parameter
Description
logFileName
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 (applicable in AddLog-class directives).
buffer-size
Specifies the size of the global log buffer. The default is 8192. See the third flex-init example below.
buffers-per-file
Specifies the number of buffers for a given log file. The default value is determined by the server.
Access log entries can be logged in strict chronological order by using a single buffer per log file. To accomplish this, add buffers-per-file="1" to the Init fn="flex-log-init" line in magnus.conf. This ensures that requests are logged in chronological order. Note that this approach will result in decreased performance when the server is under heavy load.
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.
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 "Creating Custom SAFs" for more information about parameter blocks, and "NSAPI Function Reference" for functions that 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 the following table Table 2-5. 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.
Examples
The first example below initializes flexible logging into the file /usr/sun/webserver61/server1/https-servername/logs/access.
This will record the following items:
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 /usr/sun/webserver61/server1/https-servername/logs/extended.
Init fn=flex-init extended="/usr/sun/webserver61/server1/https-servername/logs/exten ded" 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 "SAFs in the magnus.conf File") frees the request-handling threads to quickly write the log data.
Init fn=flex-init buffer-size=16384 num-buffers=2000 access="/usr/sun/webserver61/server1/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-initApplicable 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 disk space.
By default, log rotation is disabled.
Parameters
The following table describes parameters for the flex-rotate-init function.
Table 2-6 flex-rotate-init parameters
Parameter
Description
rotate-start
Indicates the time to start rotation. This value is a four-digit string indicating the time in 24-hour format. For example, 0900 indicates 9 a.m., while 1800 indicates 9 p.m.
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 (AddLog SAFs). 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.
See Also
init-cgiApplicable 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
The following table describes parameters for the init-cgi function.
Table 2-7 init-cgi parameters
Parameter
Description
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, Sun ONE 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 that 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 Sun ONE 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 Sun ONE Web Server 6.1 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-clfApplicable 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
The following table describes parameters for the init-clf function.
Table 2-8 init-clf parameters
Parameter
Description
logFileName
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 (applicable in AddLog-class directives).
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
init-davApplicable in Init-class directives.
The init-dav function performs initialization tasks to load the WebDAV plugin.
Parameters
This function requires a LateInit=yes parameter.
Example
Init fn="load-modules" shlib="/s1ws6.1/lib/libdavplugin.so"
funcs="init-dav,ntrans-dav,service-dav"
shlib_flags="(global|now)"
Init fn="init-dav" LateInit=yes
Example
init-filter-orderApplicable in Init-class directives.
The init-filter-order Init SAF can be used to control the position of specific filters within filter stacks. For example, init-filter-order can be used to ensure that a filter that converts outgoing XML to XHTML is inserted above a filter that converts outgoing XHTML to HTML.
Filters that appear higher in the filter stack are given an earlier opportunity to process outgoing data, and filters that appear lower in the filter stack are given an earlier opportunity to process incoming data.
The appropriate position of a specific filter within the filter stack is defined by the filter developer. For example, filters that translate content from XML to HTML are placed higher in the filter stack than filters that compress data for transmission. Filter developers use the filter_create function to define the filter's position in the filter stack. init-filter-order can be used to override the position defined by the filter developer.
When two or more filters are defined to occupy the same position in the filter stack, filters that were inserted later will appear higher than filters that were inserted earlier. That is, the order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf becomes important. For example, consider two filters, xhtml-to-html and xml-to-xhtml, which convert XHTML to HTML and XML to XHTML, respectively. Since both filters transform data from one format to another, they may be defined to occupy the same position in the filter stack. To transform XML documents to XHTML and then to HTML before sending the data to the client, Output fn="insert-filter" directives in obj.conf would appear in the following order:
Output fn="insert-filter" filter="xhtml-to-html"
Output fn="insert-filter" filter="xml-to-xhtml"
In general, administrators should use the order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf to control the position of filters in the filter stack. init-filter-order should only be used to address specific filter interoperability problems.
Note
The load-module SAFs that create the filters should be called before init-filter-order attempts to order them.
Parameters
The following table describes parameters for the init-filter-order function.
Table 2-9 init-filter-order parameters
Parameter
Description
filters
Comma-separated list of filters in the order they should appear within a filter stack, listed from highest to lowest.
Example
init-j2eeApplicable in Init-class directives.
The init-j2ee function initializes the Java subsystem.
Parameters
This function requires a LateInit=yes parameter.
Example
Init fn="load-modules" shlib="install_dir/lib/libj2eeplugin.so" funcs="init-j2ee,ntrans-j2ee,service-j2ee,error-j2ee" shlib_flags="(global|now)"
Init fn="init-j2ee" LateInit=yes
init-uhomeApplicable 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
The following table describes parameters for the init-uhome function.
Table 2-10 init-uhome parameters
Parameter
Description
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
load-modulesApplicable in Init-class directives.
The load-modules function loads a shared library or dynamic-link library (DLL) 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 SAFs, you get the server to load them by using the load-modules function and specifying the shared library or DLL to load.
Parameters
The following table describes parameters for the load-modules function.
Table 2-11 load-modules parameters
Parameter
Description
shlib
Specifies either the full path to the shared library or DLL, or a file name relative to the server configuration directory.
funcs
Comma-separated list of the names of the functions in the shared library or DLL 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
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-initApplicable in Init-class directives.
The nt-console-init function enables the Windows console, which is the command-line shell that displays standard output and error streams.
Parameters
The following table describes parameters for the nt-console-init function.
Table 2-12 nt-console-init parameters
Parameter
Description
stderr
Directs error messages to the Windows console. The required and only value is console.
stdout
Directs output to the Windows console. The required and only value is console.
Example
perf-initApplicable in Init-class directives.
The perf-init function enables system performance measurement via performance buckets.
For more information about performance buckets, see the Sun ONE Web Server 6.1 Performance Tuning, Sizing, and Scaling Guide.
Parameters
The following table describes parameters for the perf-init function.
Table 2-13 perf-init parameters
Parameter
Description
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
See Also
pool-initApplicable 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
The following table describes parameters for the pool-init function.
Table 2-14 pool-init parameters
Parameter
Description
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
register-http-methodApplicable 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 if the method it received is known to it. If the server does not recognize the method, it returns a “501 Method Not Implemented” error message.
Parameters
The following table describes parameters for the register-http-method function.
Table 2-15 register-http-method parameters
Parameter
Description
methods
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-initApplicable in Init-class directives.
The stats-init function enables reporting of performance statistics in XML format. The actual report is generated by the stats-xml function in obj.conf.
Parameters
The following table describes parameters for the stats-init function.
Table 2-16 stats-init parameters
Parameter
Description
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
thread-pool-initApplicable in Init-class directives.
The thread-pool-init function creates a new pool of user threads. A pool must be declared before it is 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 plugins.
On Windows, the default native pool is always being used and Sun ONE Web Server uses fibers (user-scheduled threads) for initial request processing. Using custom additional pools on Windows introduces no additional overhead.
In addition, native thread pool parameters can be added to the magnus.conf file for convenience. For more information, see “Native Thread Pools” in the chapter “Syntax and Use of magnus.conf” in the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference.
Parameters
The following table describes parameters for the thread-pool-init function.
Table 2-17 thread-pool-init parameters
Parameter
Description
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 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