Chapter 2
SAFs in the magnus.conf File

When 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=functionparam1="value1" ...paramN="valueN"

Directives have the following syntax:

directivevalue

The following Init-class functions and their parameters are described in detail in this chapter:

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

The following table describes parameters for the cindex-init function.

Table 2-1 cindex-init parameters

Parameter

Description

opts

(Optional) 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 nonzero) 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 nonzero value for a column that is less than the length of its title, the width defaults to the minimum required to display the title.

timezone

(Optional) 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) 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

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 (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-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

The following table describes parameters for the dns-cache-init function.

Table 2-3 dns-cache-init parameters

Parameter

Description

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

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.

For more information about flex-log, see information about predefined SAFs in the obj.conf file in the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference.

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

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 Initfn="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.

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.

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:

You can now log cookies by logging the Req->headers.cookie.namecomponent.

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 2-5 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 variablein Req->vars

%Req->vars.varname%

Virtual server ID

%vsid%

Duration

%duration%

Records the time in microseconds the server spent handling the request. Statistics must be enabled for the server instance before %duration% can be used. For information about enabling statistics, see the Sun ONE Web Server 6.1 Administrator's Guide.

Examples

The first example below initializes flexible logging into the file /usr/sun/webserver61/server1/https-servername/logs/access.

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 LogFlushIntervalmagnus.conf directive to 4 seconds (see "SAFs in the magnus.conf File") frees the request-handling threads to quickly write the log data.

See Also

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

See Also

init-cgi

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 fn=init-cgi LD_LIBRARY_PATH=/usr/lib;/usr/local/lib

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

Example

Example

Init fn=init-cgi LD_LIBRARY_PATH=/usr/lib;/usr/local/lib

init-filter-order

Applicable 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_createfunction 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-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

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

Init fn=init-uhome

Init fn=init-uhome pwfile=/etc/passwd-http

load-modules

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

Example

See Also

pool-init

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

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

stats-init

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-initInit SAF. The default is no, which results in slightly better server performance.

Example

thread-pool-init

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