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.
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:
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:
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:
When the requested URL translates to a directory that does not contain an index file or home page.
If no index file or home page has been specified.
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.
The following table describes the cindex-init parameters.
Table 5–1 cindex-init Parameters
Parameter |
Description |
---|---|
(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. |
|
(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. |
|
(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. |
|
(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. |
|
(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. |
|
(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. |
Init fn="cindex-init" widths="50,1,1,0" Init fn="cindex-init" ignore="*private*" Init fn="cindex-init" widths="22,0,0,50"
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 3 Performance Tuning, Sizing, and Scaling Guide.
The following table describes the define-perf-bucket parameters.
Table 5–2 define-perf-bucket Parameters
Parameter |
Description |
---|---|
The name of the bucket, for example, cgi-bucket |
|
The description of what the bucket measures, for example, CGI Stats |
Init fn="define-perf-bucket" name="cgi-bucket" description="CGI Stats"
The init-dav function performs initialization tasks to load the WebDAV plug-in. This function is applicable in Init-class directives.
Init fn="load-modules" shlib="libdavplugin.so" funcs="init-dav,ntrans-dav,service-dav" Init fn="init-dav"
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.
The load-module function that creates the filters should be called before init-filter-order attempts to order them.
The following table describes the init-filter-order parameter.
Table 5–3 init-filter-order Parameter
Parameter |
Description |
---|---|
A comma-separated list of filters in the order they should appear within a filter stack, listed from highest to lowest |
Init fn="init-filter-order" filters="xml-to-xhtml,xhtml-to-html,http-compression"
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.
The following table describes the init-request-limits parameter.
Table 5–4 init-request-limits Parameter
Parameter |
Description |
---|---|
(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. |
Init fn="init-request-limits" timeout="120"
(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.
The following table describes the init-uhome parameter.
Table 5–5 init-uhome Parameter
Parameter |
Description |
---|---|
(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. |
Init fn="init-uhome" Init fn="init-uhome" pwfile="/etc/passwd-http"
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.
The following table describes the load-modules parameters.
Table 5–6 load-modules Parameters
Parameter |
Description |
---|---|
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. |
|
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. |
|
(Optional) Specifies the threading model to use:
The default is yes. |
|
The name of a custom thread pool as specified in thread-pool-init. For more information, see thread-pool-init. |
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"
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.
The following table describes the pool-init function parameters.
Table 5–7 pool-init Parameters
Parameter |
Description |
---|---|
(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. |
|
(Optional) The size (in bytes) of the memory blocks allocated by the internal pooled memory allocator. The default value is 32768. |
Init fn="pool-init" disable="true"
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.
The following table describes the register-http-method parameters.
Table 5–8 register-http-method Parameters
Parameter |
Description |
---|---|
A comma-separated list of the methods you are registering |
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"
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.
The following table describes the thread-pool-init parameters.
Table 5–9 thread-pool-init Parameters
Parameter |
Description |
---|---|
The name of the thread pool. |
|
The maximum number of threads in the pool. |
|
The minimum number of threads in the pool. |
|
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. |
|
Stack size of each thread in the native (kernel) thread pool. |
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"
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:
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 |
---|---|
Superseded by the server.xml dns-cache element. For more information, see dns-cache. |
|
Superseded by the server.xml access-log element. For more information, see access-log. |
|
Superseded by the server.xml event and log elements. For more information, see event and log. |
|
Superseded by the server.xml cgi element. For more information, see cgi. |
|
Superseded by the server.xml access-log element. For more information, see access-log. |
|
Superseded by the server.xml log element. For more information, see log. |
|
Superseded by the server.xml stats element. For more information, see stats. |
|
Superseded by the server.xml stats element. For more information, see stats. |