Init Functions

The Init functions load and initialize server modules and plug-ins, and initialize log files.

Syntax

Init fn=function-name [parm1=value1]...[parmN=valueN]

function-name identifies the server initialization function to call. These functions shouldn’t be called more than once.

parm=value pairs are values for function-specific parameters. The number of parameters depends on the function you use. The order of the parameters doesn’t matter. The functions of the Init directive listed here are described in detail in the following sections that follow.

• define-perf-bucket - Creates a performance bucket.

• flex-init - Initializes the flex-log flexible access logging feature

• flex-rotate-init - Enables rotation for flexible logs.

• host-dns-cache-init - Caches host names of the origin servers.

• icp-init - Initializes the ICP feature.

• init-clf - Initializes the Common Log File subsystem.

• init-filter-order - Controls the position of specific filters within filter stacks.

• init-j2ee - Initializes the Java subsystem. This function is applicable only to the Administration Server.

• init-proxy - Initializes the networking code used by the proxy.

• init-uhome - Loads user home directory information.

• init-url-filter - Specifies one or more filter files of URLs. A filter file is a file that contains a list of URLs.

• ip-dns-cache-init - Configures DNS caching.

• load-modules - Instructs the server to load functions from a shared object file.

• load-types - Maps file extensions to MIME types.

• nt-console-init - Enables the Windows console, which is the command-line shell that displays standard output and error streams.

• pa-init-parent-array - Initializes a parent array member and specifies information about the PAT file for the parent array of which it is a member.

• pa-init-proxy-array - Initializes a proxy array member and specifies information about the PAT file for the array of which it is a member.

• perf-init - Enables system performance measurement through performance buckets.

• pool-init - Configures pooled memory allocation.

• register-http-method - Enables to you extend the HTTP protocol by registering new HTTP methods.

• stats-init - Enables reporting of performance statistics in XML format.

• suppress-request-headers - Configures the proxy server to remove outgoing headers from the request.

• thread-pool-init - Configures an additional thread pool.

• tune-cache - Enables you to tune the performance of your proxy server’s cache.

• tune-proxy - Enables you to tune the performance of your proxy server.You should not change the default settings.

define-perf-bucket

Applicable in Init-class directives.

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

Parameters

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

Example

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

See Also

perf-init

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, which is 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.

If the server has AddLog-stage directives that call flex-log, the flexible log file must be initialized by flex-init during server initialization.

You may specify multiple log file names in the same flex-init function call. 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 is 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, rename the file and then restart the server. The server first looks for the log file by name, and if it doesn’t find that name, it creates a new file. 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.

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 flex-init. Components that contain spaces should be bounded by escaped quotation marks (\\”).

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 quotation marks (\\”) are the ones that could potentially resolve to values that contains spaces.

Examples

The first example below initializes flexible logging into the file <install-root><instance-directory>/logs/access.

This example shows the default format, which corresponds to the Common Log Format (CLF).

The first six elements of any log should always be in this format, because a number of log analyzers expect matching output.

Init fn="flex-init" access="$accesslog" format.access="%Ses->client.ip% 
	- %Req->vars.auth-user% [%SYSDATE%] ’%Req->reqpb.clf-request%’ 
	%Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"

This example will record the following items:

• IP or host name, followed by the three characters “ - ”

• User name, followed by the two characters “ [”

• System date, followed by the two characters “] ”

• Full HTTP request in quotes, followed by a single space

• HTTP result status in quotes, followed by a single space

• Content length

The second example initializes flexible logging into the file <install-root><instance-directory>/logs/extended.

Init fn=flex-init extended="<install-root><instance-directory>
	/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 you can delegate these calls to the log flush thread.

Doubling the default size of the buffer-size and num-buffers parameters and lowering the value of the LogFlushInterval directive in magnus.conf to 4 seconds frees the request-handling threads to quickly write the log data.

Init fn=flex-init buffer-size=16384 num-buffers=2000 access="
	/<install-root><instance-directory>/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 enables 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 the move. 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.

The server keeps all rotated log files so 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.

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

host-dns-cache-init

Applicable in Init-class directives.

The host-dns-cache-init function is used to cache host names of the origin servers. If DNS lookup are caches, then when the server gets a request from the client servers, it caches the server’s host name information.

Parameters

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

Example

Init fn=“host-dns-cache-init” cache-size=“2140” expire=“600”

icp-init

Applicable in Init-class directives.

The icp-init function enables and initializes ICP. ICP (Internet Cache Protocol) is an object location protocol that enables caches to communicate with one another. Caches can use ICP to send queries and replies about the existence of cached URLs and about the best locations from which to retrieve those URLs.

Syntax

Init fn=icp-init
    config_file=file name    status=on|off

Parameters

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

Example

Init fn=icp-init
    config_file=icp.conf
    status=on

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 the server is restarted, at which time the log files are closed and reopened.

If the server has an AddLog-stage directive that calls common-log, common log files must be initialized by init-clf during initialization.

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, rename the file and for UNIX, send the -HUP signal. Then restart the server. The server first looks for the log file by name. If the server does not find the file, 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 the parameters for the init-clf function.

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-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. Filters that appear lower in the filter stack are given an earlier opportunity to process incoming data.

Filter developers use the filter_create function to define the filter’s position in the filter stack. For example, filters that translate content from XML to HTML are placed higher in the filter stack than filters that compress data for transmission. 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. 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. Because 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"

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.

The load-module SAFs that create the filters should be called before init-filter-order attempts to order them.

Parameters

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

Example

Init fn="init-filter-order" filters="xml-to-xhtml,xhtml-to-html,
	http-compression"

init-j2ee

This function is applicable only to the Administration Server 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/libj2eeplugin.so" 
	funcs="init-j2ee,ntrans-j2ee,service-j2ee,error-j2ee" 
	shlib_flags="(global|now)"
Init fn="init-j2ee" LateInit=yes

init-proxy

Applicable in Init-class directives.

The init-proxy function initializes the Proxy Server’ s internal settings. This function is called during the initialization of the Proxy Server, but it should also be specified in the obj.conf to ensure that the values are initialized properly.

Syntax

Init fn=init-proxy
    timeout=<seconds>
 timeout-2=seconds

Parameters

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

Example

Init fn=init-proxy
    timeout=120

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 process increases memory usage slightly, but improves performance for servers that have significant traffic to home directories.

Parameters

The following table describes the parameter for the init-uhome function.

Examples

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

init-url-filter

Applicable in Init-class directives.

The init-url-filter function specifies one or more filter files of URLs. A filter file is a file that contains a list of URLs.

Parameters

You can pass one or more parameters to this SAF and associate each parameter to a filter file of URLs. These parameter names may be used later in url-filter SAF to either allow or deny these filter files of URLs.

Example

PathCheck fn="init-url-filter" filt1="/path/to/filter/file1" 
	filt2="/path/to/filter/file2" filt3="/path/to/filter/file3" etc...

ip-dns-cache-init

Applicable in Init-class directives.

The ip-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 requires 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 before a cache entry expires, 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 ip-dns-cache-init function.

Example

Init fn=“ip-dns-cache-init” cache-size=“2140” expire=“600”

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

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

load-types

Applicable in Init-class directives.

The load-types function scans a file that provide map filename extensions to MIME types. MIME types are essential to enable network navigation software to distinguish between file types. See Chapter 6, MIME Types for more information.

Calling this function is crucial if you use Web Proxy Server Manager online forms or the FTP proxying capability.

Syntax

Init fn=load-types
    mime-types="mime.types"

This function loads the MIME type the mime.types file from the configuration directory, that contains the same directory magnus.conf and obj.conf. This function call is mandatory and in practice is always as shown in the syntax.

Parameters

The following table describes the parameter for the load-types function.

Example

Init fn=load-types mime-types=mime.types
Init fn=load-types mime-types=/tp/mime.types \\
    local-types=local.types

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 the parameter for the nt-console-init function.

Example

Init fn="nt-console-init" stdout=console stderr=console

pa-init-parent-array

Applicable in Init-class directives.

The pa-init-parent-array function initializes a parent array member and specifies information about the PAT file for the parent array of which it is a member.

The load modules directive should come before the pa-init-proxy-array function in the obj.conf file.

Syntax

Init fn=pa-init-parent-array    set-status-fn=pa-set-member-status
    poll="yes|no"
    file="absolute filename"
    pollhost="host name"
    pollport="port number"
    pollhdrs="absolute filename"
    pollurl="url"
    status="on|off"

Parameters

The following table describes the parameter for the pa-init-parent-array function.

Example

The following example indicates that the member should not poll for the PAT file. This example would apply to a master proxy.

Init fn=pa-init-parent-array    poll="no"
    file="c:/netscape/server/bin/proxy/pa1.pat"

The following example specifies that the member should poll for a PAT file. This member is not the master proxy.

Init fn=pa-init-parent-array    poll="yes"    
	file="c:/netscape/server/bin/proxy/pa2.pat"    
	pollhost="proxy1"    pollport="8080"    
	pollhdrs="c:/netscape/server/proxy-name/parray/pa2.hdr"    
	status="on" set-status-fn=set-member-status   pollurl="/pat"

pa-init-proxy-array

Applicable in Init-class directives.

The pa-init-proxy-array function initializes a proxy array member and specifies information about the PAT file for the array of which it is a member.

The load modules directive should come before the pa-init-proxy-array function in the obj.conf file.

Syntax

Init fn=pa-init-proxy-array    set-status-fn=pa-set-member-status
    poll="yes|no"
    file="absolute filename"
    pollhost="host name"
    pollport="port number"
    pollhdrs="absolute filename"
    pollurl="url"
    status="on|off"

Parameters

The following table describes the parameter for the pa-init-proxy-array function.

Example

The following example tells the member not to poll for the PAT file. This example would apply to a master proxy.

Init fn=pa-init-proxy-array    poll="no"
    file="c:/netscape/server/bin/proxy/pa1.pat"

The following example specifies that the member should poll for a PAT file. This member is not the master proxy.

Init fn=pa-init-proxy-array    poll="yes"    
	file="c:/netscape/server/bin/proxy/pa2.pat"    
	pollhost="proxy1"    pollport="8080"    
	pollhdrs="c:/netscape/server/proxy-name/parray/pa2.hdr"    
	status="on" set-status-fn=set-member-status  pollurl="/pat"

perf-init

Applicable in Init-class directives.

The perf-init function enables system performance measurement through performance buckets.

Parameters

The following table describes the parameter for the perf-init function.

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 enable 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 process will improve performance and prevent memory leaks. If pooling is disabled, all memory is global and is required no clean-up.

For persistent memory allocation, add the prefix PERM_ to the name of each routine (PERM_MALLOC, PERM_REALLOC, PERM_CALLOC, PERM_STRDUP, and PERM_FREE).

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. Because Init-class functions are run before processing any requests, their memory is allocated globally.

Parameters

The following table describes the parameter for the pool-init function.

Example

Init fn=pool-init disable=true

register-http-method

Applicable in Init-class directives.

This function enables you to 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 whether the method it received is registered. If the server does not recognize the method, it returns a “501 Method Not Implemented” error message.

Parameters

The following table describes the parameter for the register-http-method function.

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 report is generated by the stats-xml function in obj.conf.

Parameters

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

Example

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

suppress-request-headers

Applicable in Init-class and ObjectType-class directives.

If you specify this function at the Init stage, it applies to the entire proxy for all the requests.

If you specify this function at the ObjectType stage, you can control suppressing outgoing headers functionality for different objects in the obj.conf file.

The suppress-request-headers function configures the proxy server to remove outgoing headers from the request. This function accepts one or more hdr parameters through which you can specify multiple headers that you want to suppress.

For example, you might want to prevent the from and Cookie headers from being sent because the information reveals the user’s credentials.

Parameters

The following table describes the parameter for the suppress-request-headers function.

Example

Init fn="suppress-request-headers" hdr="from" hdr="Cookie"

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

You might want to create a custom thread pool if a plug-in is not thread-aware. In this 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, because all threads are OS-level threads. Using native pools on UNIX might introduce a small performance overhead because the pools require an additional context switch. However, the pool 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. Sun Java System Web Proxy 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.

Parameters

The following table describes the Parameters for the thread-pool-init function.

Example

Init fn=thread-pool-init name="my-custom-pool" maxthreads=5 minthreads=1 
	queuesize=200Init fn=load-modules shlib="C:/mydir/myplugin.dll" 
	funcs="tracker" pool="my-custom-pool"

See Also

load-modules

tune-cache

Applicable in Init-class directives.

The tune-cache function enables you to tune the performance of your proxy server’s cache. You should not change the default settings unless directed to do so by Sun Technical Support.

Syntax

Init fn=tune-cache
    byte-ranges

Parameters

The following table describes the parameter for the tune-cache function.

Example

Init fn=tune-cache
    byte-ranges=off

tune-proxy

Applicable in Init-class directives.

The tune-proxy function enables you to tune the performance of your proxy server.You should not change the default settings.

Syntax

Init fn=tune-proxy
    ftp-listing-width=number

Parameters

The following table describes the parameter for the tune-proxy function.

Example

Init fn=tune-proxy
    ftp-listing-width=80

Summary of Init Functions

The following table lists the Init functions available in the obj.conf file: