Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference

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

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.

Table 5–2 define-perf-bucket Parameters

Parameter  

Description  

name

Name for the bucket (for example, cgi-bucket)

description

Description of what the bucket measures (for example, CGI Stats)

Example

Init fn=define-perf-bucketname=cgi-bucketdescription=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.


Note –

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.

Table 5–3 flex-init Parameters

Parameter  

Description  

logFileName

The name of the parameter is the name of the log file. The value of the parameter specifies either the full path to the log file or a file name relative to the server’s logs directory. For example:

access="/usr/netscape/server4/https-servername/logs/access"mylogfile = "log1"

The log file name is a parameter to the flex-log function, which is applicable in AddLog-class directives.

buffer-size

Specifies the size of the global log buffer. The default is 8192.

buffers-per-file

Specifies the number of buffers for a given log file. The default value is determined by the server. 

Access log entries can be logged in strict chronological order by using a single buffer per log file. Add buffers-per-file="1" to the Init fn="flex-log-init" line in magnus.conf. This setting ensures that requests are logged in chronological order. This approach results in decreased performance when the server is under heavy load.

format.logFileName

Specifies the format of each log entry in the log file. 

For information about the format, see the “More on Log Format” section below. 

no-format-str.access

Specifies whether to include the format string in the log file. You can choose yes or no.

If you are using the Proxy Server's log analyzer, you should include a format string. If you are using a third-party analyzer, you may not want to include a format string in your log file. 

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.

Table 5–4 Typical Components of flex-init Formatting

Flex-log Option  

Component  

Client host name (unless iponly is specified in flex-log or DNS name is not available) or IP address

%Ses->client.ip%

Client DNS name 

%Ses->client.dns%

System date 

%SYSDATE%

Status 

%Req->srvhdrs.clf-status%

Response content length 

%Req->srvhdrs.content-length%

Response content type 

%Req->srvhdrs.content-type%

Referer header 

\\"%Req->headers.referer%\\"

User-agent header 

\\"%Req->headers.user-agent%\\"

HTTP method 

%Req->reqpb.method%

HTTP URI 

%Req->reqpb.uri%

HTTP query string 

%Req->reqpb.query%

HTTP protocol version 

%Req->reqpb.protocol%

DNS Time 

%Req->vars.xfer-time-dns%

Time required for Proxy to complete a DNS lookup and to attempt to connect to the server. 

Connect Wait Time 

%Req->vars.xfer-time-cwait%

Time required for Proxy to establish a TCP/IP connection to the server and send a request. 

Full Wait Time 

%Req->vars.xfer-time-fwait%

Time that elapses between the moment the proxy establishes a connection to a server and the moment that it receives its last packet of response. 

Initial Wait Time 

%Req->vars.xfer-time-iwait%

Time for Proxy to receive the first packet of response from the server after the proxy sends its request. 

Accept header 

%Req->headers.accept%

Date header 

%Req->headers.date%

If-Modified-Since header 

%Req->headers.if-modified-since%

Authorization header 

%Req->headers.authorization%

Any header value 

%Req->headers.headername%

Name of authorized user 

%Req->vars.auth-user%

Value of a cookie 

%Req->headers.cookie.name%

Value of any variable in Req->vars

%Req->vars.varname%

Duration 

%duration%

Time in microseconds that the server spent handling the request. Statistics must be enabled for the server instance before %duration% can be used. For information about enabling statistics, see the Oracle iPlanet Web Proxy Server 4.0.14 Administration Guide.

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:

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.


Note –

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.

Table 5–5 flex-rotate-init Parameters

Parameter  

Description  

rotate-start

Indicates the time to start rotation. This value is a four-digit string indicating the time in 24-hour format. For example, 0900 indicates 9 a.m., while 1800 indicates 9 p.m. 

rotate-interval

Indicates the number of minutes to elapse between each log rotation. 

rotate-access

(Optional) Determines whether common-log, flex-log, and record-useragent logs are rotated (AddLog SAFs). Values are yes (the default), and no.

rotate-error

(Optional) Determines whether error logs are rotated. Values are yes (the default), and no.

rotate-callback

(Optional) Specifies the file name of a user-supplied program to execute following log file rotation. The program is passed the post-rotation name of the rotated log file as its parameter. 

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.

Table 5–6 host-dns-cache-init parameters

Parameter  

Description  

cache-size

(Optional) Specifies how many entries are contained in the cache. Acceptable values are 32 to 32768. The default value is 1024.

expire

(Optional) Specifies how long in seconds before a cache entry should expire. Acceptable values are 1 to 31536000 (1 year). The default value is 1200 seconds (20 minutes).

negative-dns-cache

Enables or disables the caching of invalid host names. The default value is yes.

Example

Init fn=host-dns-cache-initcache-size=2140expire=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.

Table 5–7 icp-init parameters

Parameter  

Description  

config_file

The name of the ICP configuration file. 

status

Specifies whether ICP is enabled or disabled. 

Possible values are: 

  • on means that ICP is enabled.

  • off means that ICP is disabled.

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. If the server is restarted the log files are closed and reopened.


Note –

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



Note –

If this function is called more than once, 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.

Table 5–8 init-clf Parameters

Parameter  

Description  

logFileName

The name of the parameter is the name of the log file. The value of the parameter specifies either the full path to the log file or a file name relative to the server’s logs directory. For example:Ini

access="/usr/netscape/server4/https-servername/logs/access"mylogfile = "log1"

The log file name is a parameter to the common-log function, which is applicable in AddLog-class directives.

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.

Table 5–9 init-filter-order Parameters

Parameter  

Description  

filters

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

Table 5–10 init-proxy Parameters

Parameter  

Description  

timeout

The number of seconds of delay allowed between consecutive network packets received from the remote server. If the delay exceeds the timeout, the connection is dropped. The default is 120 seconds (2 minutes). This value is not the maximum time allowed for an entire transaction, but the delay between the packets. For example, the entire transaction can last 15 minutes, as long as at least one packet of data is received before each timeout period. 

timeout-2

(timeout after interrupt) 

The timeout after interrupt value indicates how much time the Proxy Server has to continue writing a cache file after a client has aborted the transaction. In other words, if the Proxy Server has almost finished caching a document and the client aborts the connection, the server can continue caching the document until it reaches the timeout after interrupt value. 

The highest recommended timeout after interrupt value is 5 minutes. The default value is 15 seconds. 

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.

Table 5–11 init-uhome parameters

Parameter  

Description  

pwfile

(Optional) Specifies the full file system path to a file other than /etc/passwd. If file name is not provided, the default UNIX path (/etc/passwd) is used.

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.

Table 5–12 ip-dns-cache-init Parameters

Parameter  

Description  

cache-size

(Optional) Specifies how many entries are contained in the cache. Acceptable values are 32 to 32768. The default value is 1024.

expire

(Optional) Specifies the remaining time in seconds before a cache entry expires. Acceptable values are 1 to 31536000 (1 year); the default is 1200 seconds (20 minutes).

Example

Init fn=ip-dns-cache-initcache-size=2140expire=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.

Table 5–13 load-modules Parameters

Parameter  

Description  

shlib

Specifies either the full path to the shared library or DLL, or a file name relative to the server configuration directory. 

funcs

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

Name of a custom thread pool, as specified in 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

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

Table 5–14 load-types Parameters

Parameter  

Description  

mime-types

Specifies either the full path to the global MIME types file or a filename relative to the server configuration directory. The proxy server comes with a default file called mime.types.

local-types

Optional parameter to a file with the same format as the global MIME types file. This parameter is used to maintain types that are applicable only to your server. 

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.

Table 5–15 nt-console-init Parameters

Parameter  

Description  

stderr

Directs error messages to the Windows console. The required and only value is console.

stdout

Directs output to the Windows console. The required and only value is console.

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.


Note –

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.

Table 5–16 pa-init-parent-array Parameters

Parameter  

Description  

set-status-fn

Specifies the function that sets the status for the member. 

poll

Indicates whether the array member should poll for a PAT file. 

  • yes means that the member should poll for the PAT file. A member should only poll for a PAT file if it is not the master proxy. The master proxy has a local copy of the PAT file, and therefore does not need to poll for it.

  • no means that the member should not poll for the PAT file. A member should not poll for the PAT file if it is the master proxy.

file

The full path name of the PAT file. 

pollhost

The host name of the proxy to be polled for the PAT file. Specify this parameter only if the poll parameter is set to yes, meaning that the member is not the master proxy.

pollport

The port number on the poll host that should be contacted when polling for the PAT file. Specify this parameter only if the poll parameter is set to yes, meaning that the member is not the master proxy.

pollhdrs

The full path name of the file that contains any special headers that must be sent with the HTTP request for the PAT file. This parameter is optional and should be specified only if the poll parameter is set to yes, meaning that the member is not the master proxy.

pollurl

The URL of the PAT file to be polled for. Specify this parameter only if the poll parameter is set to yes, meaning that the member is not the master proxy.

status

Specifies whether the parent array member is on or off.

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.


Note –

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.

Table 5–17 pa-init-proxy-array Parameters

Parameter  

Description  

set-status-fn

Specifies the function that sets the status for the member. 

poll

Indicates whether the array member should poll for a PAT file. 

  • yes means that the member should poll for the PAT file. A member should only poll for a PAT file if it is not the master proxy. The master proxy has a local copy of the PAT file, and therefore does not need to poll for it.

  • no means that the member should not poll for the PAT file. A member should not poll for the PAT file if it is the master proxy.

file

The full path name of the PAT file. 

pollhost

The host name of the proxy to be polled for the PAT file. Specify this parameter only if the poll parameter is set to yes, meaning that the member is not the master proxy.

pollport

The port number on the poll host that should be contacted when polling for the PAT file. Specify this parameter only specify if the poll parameter is set to yes, meaning that the member is not the master proxy.

pollhdrs

The full path name of the file that contains any special headers that must be sent with the HTTP request for the PAT file. This parameter is optional and should only be specified if the poll parameter is set to yes, meaning that the member is not the master proxy.

pollurl

The URL of the PAT file to be polled for. Specify this parameter only if the poll parameter is set to yes, meaning that the member is not the master proxy.

status

Specifies whether the parent array member is on or off.

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.

Table 5–18 perf-init parameters

Parameter  

Description  

disable

Flag to disable the use of system performance measurement via performance buckets. Should have a value of true or false. Default value is true.

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 no clean-up is required.

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


Note –

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.

Table 5–19 pool-init Parameters

Parameter  

Description  

free-size

(Optional) Maximum size in bytes of free block list. Can not be greater than 1048576. 

disable

(Optional) Flag to disable the use of pooled memory. Must have a value of true or false. Default value is false.

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.

Table 5–20 register-http-method Parameters

Parameter  

Description  

methods

Comma-separated list of the names of the methods you are registering. 

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.

Table 5–21 stats-init parameters

Parameter  

Description  

update-interval

Period in seconds between statistics updates within the server. Set higher for better performance, or lower for more frequent updates. The minimum value is 1. The default value is 5.

profiling

Enables NSAPI performance profiling using buckets if set to yes. This profiling can also be enabled through the perf-init Init SAF. The default is no, which results in slightly better server performance.

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.

Table 5–22 suppress-request-headers Parameters

Parameter  

Description  

hdr 

Name of the HTTP request header to be suppressed. 

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 can create a custom thread pool if a plug-in is not thread-aware. 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. 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.

Table 5–23 thread-pool-init Parameters

Parameter  

Description  

name

Name of the thread pool. 

maxthreads

Maximum number of threads in the pool. 

minthreads

Minimum number of threads in the pool. 

queueSize

Size of the queue for the pool. If all threads in the pool are busy, further request-handling threads that require 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 tries to access/denied the queue is therefore, the request is turned down, and 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" 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. Do not change the default settings unless directed to do so by Technical Support personnel.

Syntax

Init fn=tune-cache
    byte-ranges

Parameters

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

Table 5–24 tune-cache Parameters

Parameter  

Description  

byte-ranges

Determines whether the proxy is allowed to generate byte-range responses from the cache. By default, this feature is disabled. 

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.

Table 5–25 tune-cache parameters

Parameter  

Description  

ftp-listing-width

Increasing the width of FTP listings allows longer file names and thus reduces file name truncation. The default width is 80 characters. 

Example


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

um-define-junction

Applicable in Init-class directive.

The um-define-junction function defines a URL Mapping or junction which will be enforced by the URL Mapping layer.

Junction definitions take two forms: junction definitions and junction mappings. A junction definition defines the overall settings for a junction. A junction mapping defines additional URL mappings that also apply to a given junction definition. They inherit all settings of the parent junction's definition, but they allow other URL mappings that are appropriate to a given junction to be associated with it. This becomes important for cookie management, as cookies from one junction will not be passed to another one.

Syntax

Init fn="um-define-junction"

Parameters

The following table describe parameters for the um-define-junction function.

The following parameters apply to both junction definitions and junction mappings.

Table 5–26 um-define-junction parameters

Parameter 

Description 

jct-name

The name of the junction. In the case of junction definitions, this name must be unique. In the case of junction mappings, this must be the name of an existing junction. 

fe-uri-prefix

The front-end URI prefix that is to be associated with this junction definition or mapping. It must begin and end with a '/' character. 

be-url-prefix

The back-end URL prefix that is to be associated with this junction definition or mapping. This is the back-end URL that will connect to the back-end application server. It must be of the form http[s]://*/*. 

The following parameters apply only to junction mappings.

Table 5–27 Junction mapping parameters

Parameter 

Description 

junction-mapping

If this is set to yes, then this definition is taken to be a junction mapping.  

The following parameters apply only to junction definitions.

Table 5–28 Junction definition parameters

Parameter 

Description 

parser-config

Specifies the parser configuration used for this junction. If not specified, the default parser configuration (the first parser configuration listed in obj.conf) is used.

passthru-cookies

Specifies a comma-separated list of cookie names is passed through to the junction without translation. This parameter is a junction-specific version of the global-passthru-cookies parameter of the load-modules function.

has-javascript

If set to yes, then JavaScript rewriting is enabled for all JavaScript content. Otherwise, JavaScript is passed without rewriting.

onload-handler

If set to yes, then a special bit of code is inserted into each request to this junction, which will set a cookie specifying the name of the junction. This cookie's name is defined in the jct-cookie-name of the load-modules function. By default, the cookie's name is um_jct.

base-tag-handler

If set to yes, then <base> tags receives special handling. Use care when combining this parameter with has-javascript, as the parser may mistake a static string value for a relative URL. Default value is no.

rewrite-events

If set to no, then event attributes within HTML tags are not rewritten. Default value is yes. This parameter operates independently of has-javascript, but is only relevant if has-javascript is set to no.

redirect-without-trailing-slash

If set to yes, then requests that match fe-uri-prefix without the trailing slash is immediately redirected to fe-uri-prefix with the trailing slash.

add-headers

Specifies a static list of headers to be added to all requests within this junction.  

lookup-equiv-hosts

Equivalent host are strings that appear in the host part of a URL, which also represent the back-end server. By default, a new junction adds the back-end server's IP addresses to this list. Setting this option to 'no' prevents this behavior. 

add-equiv-hosts

Specifies a comma-delimited list of additional host names (and/or IP addresses) that are considered to be equivalent to this junction's host name. The host part of be-url-prefix is implicit, and does not need to be added. 

output-buffer-size

Enables (or disables) output buffering. The proxy server employs HTTP chunking to send data to the client when it does not know the size of the content to be sent. Because the URL Mapping layer can send data in many small chunks, this can create a lot of CPU overhead on the proxy server machine. To alleviate this, URL Mapping offers its own output buffering so that data is sent to the client in fewer, larger chunks. To enable this, set output-buffer-size to a nonzero value.

references-other-jcts

If set to yes, the other junctions are searched when trying to rewrite URLs for this junction. Use care when employing this option, as searching other junctions can be time-consuming in a configuration that contains many junctions. 

use-template

If set to yes, and name is not set, then requests that match this junction is also assigned an object name that matches the junction's name. This allows additional directives to be executed only for this junction. 

name

If set, then this overrides the object name for this junction. It implies use-template=yes.

Example

Junction definition:


Init fn="um-define-junction" jct-name="myJunction" fe-uri-prefix="/myj/"
 be-url-prefix="http://appserver.company.com/someApplication/"

Junction mapping:


Init fn="um-define-junction" jct-name="myJunction" 
fe-uri-prefix="/someApplication/cgi-bin/" 
be-url-prefix="http://appserver.company.com/someApplication/cgi-bin" 
junction-mapping="yes"

um-init

Applicable in Init-class directives.

This parameter is mandatory. It must appear only once in the obj.conf file and before other URL Mapping-related directives.

Parameters

The following describes parameters for the um-init function:

Table 5–29 um-init parameters

Parameter  

Description  

global-passthru-cookies

Specifies a comma-delimited list of cookies that is always passed through to the back-end applications. If a cookie's name is followed by a '|' character, then the cookie's name is changed to the name following the '|' character. 

jct-cookie-name

Sets the name of the cookie that stores the last-used back-end URL's name. By default, this parameter is set to um_jct.

jct-cookie-prefix

When cookies are set by applications within defined URL mappings, their names are prefixed by this string, followed by the name of the URL Mapping, followed by a '_' character. This setting tells the URL Mapping which cookies to pass to the back-end server on a given request. 

jct-cookie-domain

If specified, the URL Mapping cookie (specified in jct-cookie-name) is set in this domain. Otherwise, the domain for the cookie is not set. You do not have to use this parameter.

default-output-buffer-size

Sets the default output buffer size for URL Mappings that does not explicitly set output-buffer-size (See output-buffer-size in Table 5–28). If not specified, then output buffering is disabled by default.

Example


Init fn=um-init

um-load-parser-config

Applicable in Init-class directive.

Parser configurations are text files that contain the names of tag attributes and tag events whose URLs are to be rewritten. It also contains strings that are considered to be illegal in URLs.

Each line of the parser configuration starts with either a tag name, or the string **illegal.

If the line starts with a tag name, the rest of the line is a space-separated list of attribute names that will be searched for URLs.

If the tag name is prefixed with a '*' character, then the rest of the line is a space-separated list of the event names that will be searched for URLs.

If an attribute or event name is prefixed with a '*' character, then the URL Mapping feature always attempts to rewrite URLs within that attribute or event as absolute URLs. Otherwise, the URLs are rewritten in the same form that they were specified (relative, server-relative, or absolute).

If the first word of the line is the string **illegal, then the rest of the line contains a space-separated list of strings that, if they are contained within a URL, are considered to be illegal. If a URL containing any of these strings is encountered, then the URL is replaced with the string ***ILLEGAL_URL***.

All strings in this file are case-insensitive. Any lines that begin with a '#' character are considered to be comments, and are ignored. Blank lines are ignored.

Syntax

Init fn="um-load-parser-config"

Parameters

The following table describes parameters in the um-load-parser-config function.

Table 5–30 um-load-parser-config parameters

Parameter 

Description 

file

Specifies the location of the parser configuration file. 

config-name

Specifies the name that is associated with this parser configuration. This setting is only necessary if you have multiple parser configurations in your obj.conf. If not specified, the configuration is assigned a name equal to the value of the file.

Example


Init fn="um-load-parser-config" file="/opt/SUNWproxy/proxy-server1/conf/proxy.cfg"

Summary of Init Functions

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

Table 5–31 Init Functions

Function/Parameter  

Allowed Values  

Default Value  

Description  

define-perf-bucket

   

Creates a performance bucket. You can use this parameter to measure the performance of SAFs in obj.conf. This function only works if the perf-init function is enabled.

name

   

A name for the bucket, for example, cgi-bucket.

description

   

A description of what the bucket measures, for example, CGI Stats.

dns-cache-init

   

Configures DNS caching. 

cache-size

32 to 32768 (32K)

1024

(optional) Specifies how many entries are contained in the cache. 

expire

1 to 31536000 seconds (1 year)

1200 seconds (20 minutes)

(optional) Specifies how long in seconds before a cache entry expires. 

flex-init

   

Initializes the flexible logging system. 

logFileName

A path or file name 

 

The full path to the log file or a file name relative to the server’s logs directory. In this example, the log file name is access and the path is /logdir/access:

access="/logdir/access"

format.logFileName

   

Specifies the format of each log entry in the log file. 

relaxed.logFileName

true, on, yes, or 1;false, off, no, or 0

 

Turns on relaxed logging, which skips logging components that normally block static page acceleration if static page acceleration is enabled. 

buffer-size

Number of bytes 

8192

Specifies the size of the global log buffer. 

buffers-per-file

The lower bound is 1. Files must contain at least one buffer. 

The upper bound is dictated by the number of buffers that exist. The upper bound on the number of buffers that exist can be defined by the num-buffers parameter.

Determined by the server 

Specifies the number of buffers for a given log file. 

num-buffers

 

1000

Specifies the maximum number of logging buffers to use. 

thread-buffer-size

Number of bytes 

8192 (8 KB)

Specifies the size of the per thread log buffer. 

flex-rotate-init

   

Enables rotation for logs. 

rotate-start

A 4-digit string indicating the time in 24-hour format 

 

Indicates the time to start rotation. For example, 0900 indicates 9 a.m. while 1800 indicates 9 p.m. 

rotate-interval

Number of minutes 

 

Indicates the number of minutes to elapse between each log rotation. 

rotate-access

yes, no

yes

(optional) Determines whether common-log, flex-log, and record-useragent logs are rotated. For more information, see the Oracle iPlanet Web Proxy Server 4.0.14 NSAPI Developer’s Guide.

rotate-error

yes, no

yes

(optional) Determines whether error logs are rotated. 

rotate-callback

A path 

 

(optional) Specifies the file name of a user-supplied program to execute after following log file rotation. The program passes the post-rotation name of the rotated log file as its parameter. 

init-cgi

   

Changes the default settings for CGI programs. 

timeout

Number of seconds 

300

(optional) specifies how many seconds the server waits for CGI output before terminating the script. 

cgistub-path

   

(optional) Specifies the path to the CGI stub binary. If not specified, iPlanet Web Server looks in the following directories, in the following order, relative to the server instance’s config directory: ../private/Cgistub, then ../../bin/https/bin/Cgistub.

For information about installing an suid Cgistub, see the Oracle iPlanet Web Proxy Server 4.0.14 NSAPI Developer’s Guide.

env-variable

   

(optional) Specifies the name and value for an environment variable that the server places into the environment for the CGI. 

init-clf

   

Initializes the Common Log subsystem. 

logFileName

A path or file name 

 

Specifies either the full path to the log file or a file name relative to the server’s logs directory.

init-uhome

   

Loads user home directory information. 

pwfile

   

(optional) Specifies the full file system path to a file other than /etc/passwd. If not provided, the default UNIX path (/etc/passwd) is used.

load-modules

   

Loads shared libraries into the server. 

shlib

   

Specifies either the full path to the shared library or dynamic link library, or specifies a file name relative to the server configuration directory. 

funcs

A comma separated list with no spaces 

 

A list of the names of the functions in the shared library or dynamic link library to be made available for use by other Init or Service directives. The dash (-) character can be used in place of the underscore (_) character in function names.

NativeThread

yes, no

yes

(optional) Specifies which threading model to use. no causes the routines in the library to use user-level threading. yes enables kernel-level threading.

pool

 

 

The name of a custom thread pool, as specified in thread-pool-init.

nt-console-init

   

Enables the NT console, which is the command-line shell that displays standard output and error streams. 

stderr

console

 

Directs error messages to the NT console. 

stdout

console

 

Directs output to the NT console. 

perf-init

   

Enables system performance measurement via performance buckets. 

disable

true, false

true

Disables the function when true.

pool-init

   

Configures pooled memory allocation. 

free-size

1048576 bytes or less

 

(optional) Maximum size in bytes of free block list. 

disable

true, false

false

(optional) Flag to disable the use of pooled memory if true.

register-http-method

   

Enables you to extend the HTTP protocol by registering new HTTP methods. 

methods

A comma-separated list 

 

Names of the methods you are registering. 

stats-init

   

Enables reporting of performance statistics in XML format. 

profiling

yes, no

no

Enables NSAPI performance profiling using buckets. This setting can also be enabled through perf-init.

update-interval

1 or greater

5

The period in seconds between statistics updates within the server. 

virtual-servers

1 or greater

1000

The maximum number of virtual servers for which statistics are tracked. This number should be set higher than the number of virtual servers configured. 

thread-pool-init

   

Configures an additional thread pool. 

name

   

Name of the thread pool. 

maxthreads

   

Maximum number of threads in the pool. 

minthreads

   

Minimum number of threads in the pool. 

queueSize

Number of bytes 

 

Size of the queue for the pool. 

stackSize

Number of bytes 

 

Stack size of each thread in the native (kernel) thread pool. 

tune-cache

   

Enables you to tune the performance of your proxy server's cache. 

byte-ranges

   

Determines whether the proxy can generate byte-range responses from the cache. 

tune-proxy

   

Enables you to tune the performance of your proxy server. Do not change the default settings. 

ftp-listing-width

 

80 characters 

Increasing the width of FTP listings allows longer file names and thus reduces file name truncation.  

um-define-junction

   

Defines a URL Mapping that will be enforced by the "URL Mapping" layer. 

jct-name

   

The name of the junction. 

fe-uri-prefix

   

The front-end URI prefix that is associated with this junction definition or mapping. 

be-url-prefix

   

The back-end URL prefix that is associated with this junction definition or mapping.  

junction-mapping

 

yes

A junction mapping. 

parser-config

   

Specifies the parser configuration that is used for this junction. 

passthru-cookies

   

Specifies a comma-separated list of cookie names that is passed through to the junction without translation.  

has-javascript

 

yes

Enables JavaScript rewriting for all JavaScript content. 

onload-handler

 

um_jct

Inserts special bit of code into each request to this junction. 

base-tag-handler

 

no

<base> tags receive special handling

rewrite-events

 

yes

Rewrite event attributes within HTML tags 

redirect-without-trailing-slash

   

Requests that match fe-uri-prefix without the trailing slash are immediately redirected to fe-uri-prefix with the trailing slash.

add-headers

   

Specifies a static list of headers to be added to all requests within this junction.  

lookup-equiv-hosts

 

no

Prevent a new junction from adding the back-end server's IP addresses to this list. 

add-equiv-hosts

   

Specifies a comma-delimited list of additional host names (and/or IP addresses) that are considered to be equivalent to this junction's host name. 

output-buffer-size

   

Enables (or disables) output buffering. To enable this, set output-buffer-size to a nonzero value.

references-other-jcts

   

Searches other junctions while trying to rewrite URLs for this junction. 

use-template

   

Assigns an object name (which matches the junction's name) to requests that match this junction. 

name

   

Overrides the object name for this junction. 

um-init

   

Initializes the URL Mapping module.  

global-passthru-cookies

   

Specifies a comma-delimited list of cookies that are always passed through to the back-end applications.  

jct-cookie-name

 

um_jct

Sets the name of the cookie that stores the last-used back-end URL's name. 

jct-cookie-prefix

   

Informs the URL Mapping layer which cookies to pass to the back-end server on a given request. 

jct-cookie-domain

   

Sets the URL Mapping cookie in specified domain. 

default-output-buffer-size

   

Sets the default output buffer size for URL Mappings that do not explicitly set output-buffer-size. 

um-load-parser-config

   

Loads a parser configuration into memory.  

file

   

Specifies the location of the parser configuration file. 

config-name

   

Specifies the name associated with this parser configuration.