Sun Java System Web Server 6.1 SP11 NSAPI Programmer's Guide

Chapter 2 SAFs in the magnus.conf File

When the Sun Java System Web Server starts up, it looks in a file called magnus.conf in the server-id/config directory to establish a set of global variable settings that affect the server’s behavior and configuration. Sun Java System Web Server executes all 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.


Init SAFs

This section the Init SAFs that can be specified in magnus.conf in Sun Java System Web Server 6.1. For information about the other, non-SAF directives in magnus.conf, see the Sun Java System Web Server 6.1 SP11 Administrator’s Configuration File Reference.

The Init directives initialize the server (for example they load and initialize additional modules and plug-ins, 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

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 Sun Java System Web Server 6.1 SP11 Administrator’s Configuration File Reference).

For more information about performance buckets, see the Sun Java System Web Server 6.1 SP11 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

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

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 Java System Web Server 6.1 SP11 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).

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 flex-init

%duration%

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

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 3, Creating Custom SAFs for more information about parameter blocks, and Chapter 7, NSAPI Function Reference.)

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 flex-init. 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 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%

Cipher name 

%Ses->client.cipher%

Size in bits of cipher key 

%Ses->client.keysize%

Size in bits of private key 

%Ses->client.secret-keysize%

DN for certificate issuer 

%Ses->client.issuer_dn%

DN for certificate user 

%Ses->client.user_dn%

SSL session identifier 

%Ses->client.ssl-id%

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 Sun Java System Web Server 6.1 SP11 Administrator’s Guide.

Examples

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

Init fn=flex-init 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%"

This will record the following items:

Init fn=flex-init extended="/usr/sun/webserver61/server1/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 2, SAFs in the magnus.conf File

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

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


Init fn=flex-rotate-init rotate-start=2400 rotate-interval=60

See Also

flex-init

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

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 Java System 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 Java System 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 a suid Cgistub, see the Sun Java System Web Server 6.1 SP11 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).

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

flex-rotate-init

init-dav

Applicable in Init-class directives.

The init-dav function performs initialization tasks to load the WebDAV plug-in.

Parameters

This function requires a LateInit=yes parameter.

Example


Init fn="load-modules" shlib="/s1ws6.1/lib/libdavplug-in.so"
funcs="init-dav,ntrans-dav,service-dav"
shlib_flags="(global|now)"
 Init fn="init-dav" LateInit=yes

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_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 fn="init-filter-order" filters="xml-to-xhtml,xhtml-to-html,http-compression"

init-j2ee

Applicable 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/libj2eeplug-in.so" 
funcs="init-j2ee,ntrans-j2ee,service-j2ee,error-j2ee" shlib_flags="(global|now)"
Init fn="init-j2ee" LateInit=yes

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 plug-ins 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-init

Applicable 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


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


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

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.


Init fn="register-http-method" methods="MY_METHOD1,MY_METHOD2"
Service fn="MyHandler" method="MY_METHOD1"

stats-init

Applicable 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


Init fn="stats-init" update-interval="5" virtual-servers="2000" profiling="yes"

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 plug-in to use the new pool, specify the pool parameter when loading the plug-in with the Init-class function load-modules.

One reason to create a custom thread pool would be if a plug-in 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, the default native pool is always being used and Sun Java System Web Server uses fibers (user-scheduled threads) for initial request processing. Using custom additional pools on Windows introduces no additional overhead.

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

load-modules