Init

The Init functions load and initialize server modules and plugins, 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.

• 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 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 tells 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 via performance buckets.

• pool-init configures pooled memory allocation.

• register-http-method lets 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 allows you to tune the performance of your proxy server’s cache.

• tune-proxy allows 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, which 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 (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. 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.

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.

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.

Examples

The first example below initializes flexible logging into the file <Install_Root><Instance_Directory>/logs/access.

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

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

It is advisable that the first six elements of any log always be in exactly this format, because a number of log analyzers expect that as output.

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

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.

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

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

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.

Example

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

init-j2ee

This is applicable to only the Administration Server.

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

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

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 tells it how to map filename extensions to MIME types. MIME types are essential for network navigation software like Netscape Navigator to tell the difference between file types. For example, they are used to tell an HTML file from a GIF file. 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 file mime.types from the configuration directory (the same directory as 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 parameters 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 parameters 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 parameters for the pa-init-parent-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-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 parameters 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 via performance buckets.

Parameters

The following table describes parameters 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 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).

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.

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.

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.

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 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. It accepts one or more hdr parameters through which you can specify multiple headers you want to suppress.

For example, you might want to prevent the from and Cookie headers from going out because it reveals the user’s credentials.

Parameters

The following table describes parameters 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 tell a plugin to use the new pool, specify the pool parameter when loading the plugin with the Init-class function load-modules.

One reason to create a custom thread pool would be if a plugin 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 plugins.

On Windows, the default native pool is always being used and 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 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 allows 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 allows 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: