Init SAFs

                                                                                                                                                                                                                                                                                                                                      *Back to [[Book|Administrator's Configuration File Reference#cfr]]     [[Topic|Administrator's Configuration File Reference#chap5]]*
h2. {{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}}]
* [#{{define-perf-bucket}}]
* [#{{init-dav}}]
* [#{{init-filter-order}}]
* [#{{init-request-limits}}]
* [#{{init-uhome}}]
* [#{{load-modules}}]
* [#{{pool-init}}]
* [#{{register-http-method}}]
* [#{{thread-pool-init}}]

h3. {{cindex-init}} {anchor:magi51}

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.

h4. 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|Administrator's Configuration File Reference#appB]. |
|{{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. |

h4. Example
{code}
Init fn="cindex-init" widths="50,1,1,0"
Init fn="cindex-init" ignore="*private*"
Init fn="cindex-init" widths="22,0,0,50"
{code}

h3. {{define-perf-bucket}} {anchor:magi52}

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

h4. Example
{code}
Init fn="define-perf-bucket" name="cgi-bucket" description="CGI Stats"
{code}

h3. {{init-dav}} {anchor:magi53}

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

h4. Example
{code}
Init fn="load-modules"
shlib="libdavplugin.so"
funcs="init-dav,ntrans-dav,service-dav"
Init fn="init-dav"
{code}

h3. {{init-filter-order}} {anchor:magi54}

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:
{code}
Output fn="insert-filter" filter="xhtml-to-html"
Output fn="insert-filter" filter="xml-to-xhtml"
{code}

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.

{info:title=Note - }The {{load-module}} function that creates the filters should be called before {{init-filter-order}} attempts to order them.
{info}

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

h4. Example
{code}
Init fn="init-filter-order" filters="xml-to-xhtml,xhtml-to-html,http-compression"
{code}

h3. {{init-request-limits}} {anchor:magi55}

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. {{init-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}}|PathCheck#path2]. The default is 300 seconds (five minutes). This function is applicable in {{Init}}-class directives.

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

h4. Example
{code}
Init fn="init-request-limits" timeout="120"
{code}

h3. {{init-uhome}} {anchor:magi56}

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

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

h4. Example
{code}
Init fn="init-uhome"
Init fn="init-uhome" pwfile="/etc/passwd-http"
{code}

h3. {{load-modules}} {anchor:magi57}

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.

h4. 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}}]. |

h4. Examples
{code}
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"
{code}

h3. {{pool-init}} {anchor:magi58}

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.

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

h4. Example
{code}
Init fn="pool-init" disable="true"
{code}

h3. {{register-http-method}} {anchor:magi59}

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.

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

h4. Example

The following example shows the use of {{register-http-method}}:
{code}
Init fn="register-http-method" methods="MY_METHOD1,MY_METHOD2"
{code}

The methods can be called from a {{Service}} function in {{obj.conf}}, for example:
{code}
Service fn="MyHandler" method="MY_METHOD1"
{code}

h3. {{thread-pool-init}} {anchor:magi510}

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|Administrator's Configuration File Reference#chap4].

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

h4. Example
{code}
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"
{code}