Sun Java System Web Server 7.0 Update 4 Administrator's Configuration File Reference

Chapter 5 Predefined SAFs in magnus.conf

This chapter lists the Init Server Application Functions (SAF) that you can specify in magnus.conf. Init SAFs load and initialize server modules and NSAPI plug-ins.


Note –

When you edit the magnus.conf file, you must restart the server for the changes to take effect.


The following topics are described in detail in this chapter:

Init SAFs

The Init directives are executed only once at server startup. Each Init directive has an fn parameter that specifies which Init SAF to invoke.

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. For the Windows platform, LateInit functions are executed later than functions that do not have the LateInit parameter.

When the server is started by a root user but runs as another user, perform all activities that must be performed as the user root (such as writing to a root-owned file) before the fork. Functions that create threads, with the exception of thread-pool-init, should be executed after the fork, that is, the relevant Init directive should have LateInit=yes set.

This section describes the following SAFs:

cindex-init

The cindex-init function sets the default settings for common indexing. Common indexing (also known as fancy indexing) is performed by the Service function index-common. Indexing occurs:

This function is applicable in Init-class directives. In common (fancy) indexing, the directory list shows the name, last modified date, size, and description of each indexed file or directory.

Parameters

The following table describes the cindex-init parameters.

Table 5–1 cindex-init Parameters

Parameter 

Description 

opts

(Optional) String of letters specifying the options to activate. Currently there is only one possible option: 

s instructs the server to scan each HTML file in the directory that is being indexed for the contents of the HTML TITLE tag. 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 of 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 value for the widths parameter is 22, 18, 8, and 33.

The final three values (corresponding to last-modified date, size, and description) can each be set to 0 to turn off the display for that column. 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 the date plus one space). If you set a non-zero 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) Determines 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) Determines the format of the last modified date. 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 that the server should ignore while indexing. By default, file names starting with a period (.) are always ignored. For more information, see Appendix B, Using Wildcard Patterns.

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

The define-perf-bucket function creates a performance bucket, which you can use to measure the performance of SAFs in obj.conf.

This function is applicable in Init-class directives. For more information about performance buckets, see Sun Java System Web Server 7.0 Update 4 Performance Tuning, Sizing, and Scaling Guide.

Parameters

The following table describes the define-perf-bucket parameters.

Table 5–2 define-perf-bucket Parameters

Parameter 

Description 

name

The name of the bucket, for example, cgi-bucket

description

The description of what the bucket measures, for example, CGI Stats

Example

Init fn="define-perf-bucket" name="cgi-bucket" description="CGI Stats"

init-dav

The init-dav function performs initialization tasks to load the WebDAV plug-in. This function is applicable in Init-class directives.

Example

Init fn="load-modules"
     shlib="libdavplugin.so"
     funcs="init-dav,ntrans-dav,service-dav"
Init fn="init-dav"

init-filter-order

The init-filter-order function controls the position of specific filters within the filter stacks. For example, you can use init-filter-order to ensure that a filter that converts outgoing XML to XHTML is inserted above a filter that converts outgoing XHTML to HTML.

This function is applicable in Init-class directives.

Filters that appear higher in the filter stack are given the first opportunity to process outgoing data, and filters that appear lower in the filter stack are given the first 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. You can use init-filter-order 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. As both these 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 should appear in the following order:

Output fn="insert-filter" filter="xhtml-to-html"
Output fn="insert-filter" filter="xml-to-xhtml"

In general, you 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 function that creates the filters should be called before init-filter-order attempts to order them.


Parameters

The following table describes the init-filter-order parameter.

Table 5–3 init-filter-order Parameter

Parameter 

Description 

filters

A 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-request-limits

The init-request-limits function works with the obj.conf function check-request-limits to monitor incoming requests with a given attribute. check-request-limits maintains a table of monitored values. intit-request-limits purges existing entries in that table according to the timeout. This function is not required unless you want to override the default value for the purge timeout in check-request-limits. For more information, see check-request-limits. The default is 300 seconds (five minutes). This function is applicable in Init-class directives.

Parameters

The following table describes the init-request-limits parameter.

Table 5–4 init-request-limits Parameter

Parameter 

Description 

timeout

(Optional) Sets the time in seconds after which to purge entries tracked by check-request-limits. The default is 300 seconds (five minutes).

An optimal value for timeout depends not only on your performance and memory requirements but also on the check-request-limits rules you are using. When using rules containing, for example, monitor="$ip" on a busy public web site, new buckets are created and kept for every client IP accessing the server. Because this setting potentially creates a very large number of buckets, the expiration should be short enough that unused entries are purged in a reasonable time.

However, to avoid removing and re-creating buckets for the same client, do not set a timeout that is shorter than the typical or expected client session.

If you do not use any dynamic bucket names (that is, if all monitored values and bucket are fixed strings instead of variables, or you never specify monitor or bucket parameters at all) there are only a fixed number of buckets. In that case, you can disable expiration entirely by setting the timeout to zero.

Example

Init fn="init-request-limits" timeout="120"

init-uhome

(UNIX only) The init-uhome function loads information about the system’s user home directories into internal hash tables. This function slightly increases memory usage, but improves performance for servers that have a lot of traffic to home directories.

This function is applicable in Init-class directives.

Parameters

The following table describes the init-uhome parameter.

Table 5–5 init-uhome Parameter

Parameter 

Description 

pwfile

(Optional) Specifies the full file system path to a file other than /etc/passwd. If you do not specify this parameter, the default UNIX path (/etc/passwd) is used.

Example

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

load-modules

The load-modules function loads a shared library or dynamic-link library (DLL) into the server. Specified functions from the library can then be executed from any subsequent directives. Use this function to load new plug-ins or SAFs.

This function is applicable in Init-class directives.

If you define your own SAFs, load them by using the load-modules function and specify the shared library or DLL to load.

Parameters

The following table describes the load-modules parameters.

Table 5–6 load-modules Parameters

Parameter 

Description 

shlib

Specifies either the full path to the shared library or DLL, the name of a file that can be found in the operating system's library path, the name of a file that can be found in the server's plugins directory, or a file name relative to the server's config directory.

funcs

A 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 the 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. For more information, see 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"

pool-init

The pool-init function changes the default values of pooled memory settings. You can change the size of the free block list, or disable pooled memory entirely.

This function is applicable in Init-class directives.

Parameters

The following table describes the pool-init function parameters.

Table 5–7 pool-init Parameters

Parameter 

Description 

disable

(Optional) The flag to disable the internal pooled memory allocator. Disabling the internal pooled memory allocator is useful when debugging plug-ins. The default value is false.

block-size

(Optional) The size (in bytes) of the memory blocks allocated by the internal pooled memory allocator. The default value is 32768.

Example

Init fn="pool-init" disable="true"

register-http-method

The register-http-method function enables you to extend the HTTP protocol by registering new HTTP methods. This function is applicable in Init-class directives.

While 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 the register-http-method parameters.

Table 5–8 register-http-method Parameters

Parameter 

Description 

methods

A comma-separated list of the methods you are registering 

Example

The following example shows the use of register-http-method:

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

The methods can be called from a Service function in obj.conf, for example:

Service fn="MyHandler" method="MY_METHOD1"

thread-pool-init

The thread-pool-init function creates a new pool of user threads. A pool must be declared before it is used. For a plug-in to use the new pool, specify the pool parameter when loading the plug-in with the Init-class function load-modules. For more information, see load-modules.

This function is applicable in Init-class directives.

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 kernel-level threads. In addition, native thread pool parameters can be added to the magnus.conf file for convenience. For more information, see Chapter 4, Syntax and Use of magnus.conf.

Parameters

The following table describes the thread-pool-init parameters.

Table 5–9 thread-pool-init Parameters

Parameter 

Description 

name

The name of the thread pool. 

maxthreads

The maximum number of threads in the pool. 

minthreads

The minimum number of threads in the pool. 

queueSize

The size of the pool queue. If all threads in the pool are busy, further request-handling threads that need to get a thread from the pool 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"
     minthreads="1" maxthreads="5" queuesize="200"
Init fn="load-modules" shlib="myplugin.dll" funcs="tracker"
     pool="my-custom-pool"

Common SAFs

You can call some SAFs from Init in magnus.conf as well as from ObjectType directives in obj.conf. These SAFs are documented in Chapter 7, Predefined SAFs and Filters in obj.conf, as referenced below:

Deprecated Init SAFs

The following magnus.conf Init SAFs are deprecated for Sun Java System Web Server 7.0.

Table 5–10 List of Deprecated Init SAFs

Directive 

Description 

dns-cache-init

Superseded by the server.xml dns-cache element. For more information, see dns-cache.

flex-init

Superseded by the server.xml access-log element. For more information, see access-log.

flex-rotate-init

Superseded by the server.xml event and log elements. For more information, see event and log.

init-cgi

Superseded by the server.xml cgi element. For more information, see cgi.

init-clf

Superseded by the server.xml access-log element. For more information, see access-log.

nt-console-init

Superseded by the server.xml log element. For more information, see log.

perf-init

Superseded by the server.xml stats element. For more information, see stats.

stats-init

Superseded by the server.xml stats element. For more information, see stats.