The Init functions load and initialize server modules and plug-ins, and initialize log files.
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 you to 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.
um-define-junction - Defines a URL Mapping that will be enforced by the "URL Mapping" layer.
um-init - Initializes the URL Mapping module.
um-load-parser-config - Loads a parser configuration into memory.
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.
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 of what the bucket measures (for example, CGI Stats) |
Init fn=“define-perf-bucket” name=“cgi-bucket” description=“CGI Stats”
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.
The following table describes parameters for the flex-init function.
Table 5–3 flex-init Parameters
Parameter |
Description |
---|---|
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. |
|
Specifies the size of the global log buffer. The default is 8192. |
|
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. |
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. |
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%" |
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.
The following table describes parameters for the flex-rotate-init function.
Table 5–5 flex-rotate-init Parameters
Parameter |
Description |
---|---|
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. |
|
Indicates the number of minutes to elapse between each log rotation. |
|
(Optional) Determines whether common-log, flex-log, and record-useragent logs are rotated (AddLog SAFs). Values are yes (the default), and no. |
|
(Optional) Determines whether error logs are rotated. Values are yes (the default), and no. |
|
(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. |
This example enables log rotation, starting at midnight and occurring every hour.
Init fn=flex-rotate-init rotate-start=2400 rotate-interval=60 |
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.
The following table describes parameters for the dns-cache-init function.
Table 5–6 host-dns-cache-init parameters
Parameter |
Description |
---|---|
(Optional) Specifies how many entries are contained in the cache. Acceptable values are 32 to 32768. The default value is 1024. |
|
(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. |
Init fn=“host-dns-cache-init” cache-size=“2140” expire=“600”
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.
Init fn=icp-init config_file=file name status=on|off
The following table describes parameters for the icp-init function.
Table 5–7 icp-init parameters
Init fn=icp-init config_file=icp.conf status=on |
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.
If the server has an AddLog-stage directive that calls common-log, common log files must be initialized by init-clf during initialization.
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.
The following table describes the parameters for the init-clf function.
Table 5–8 init-clf Parameters
Parameter |
Description |
---|---|
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. |
Init fn=init-clf access=/usr/netscape/server4/https-boots/logs/access Init fn=init-clf templog=/tmp/mytemplog templog2=/tmp/mytemplog2 |
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.
The following table describes the parameter for the init-filter-order function.
Table 5–9 init-filter-order Parameters
Parameter |
Description |
---|---|
Comma-separated list of filters in the order they should appear within a filter stack, listed from highest to lowest. |
Init fn="init-filter-order" filters="xml-to-xhtml,xhtml-to-html, http-compression" |
This function is applicable only to the Administration Server in Init-class directives..
The init-j2ee function initializes the Java subsystem.
This function requires a LateInit=yes parameter.
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 |
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.
Init fn=init-proxy timeout=<seconds> timeout-2=seconds
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. |
Init fn=init-proxy timeout=120 |
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.
The following table describes the parameter for the init-uhome function.
Table 5–11 init-uhome parameters
Parameter |
Description |
---|---|
(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. |
Init fn=init-uhome Init fn=init-uhome pwfile=/etc/passwd-http |
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.
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.
PathCheck fn="init-url-filter" filt1="/path/to/filter/file1" filt2="/path/to/filter/file2" filt3="/path/to/filter/file3" etc... |
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).
The following table describes parameters for the ip-dns-cache-init function.
Table 5–12 ip-dns-cache-init Parameters
Parameter |
Description |
---|---|
(Optional) Specifies how many entries are contained in the cache. Acceptable values are 32 to 32768. The default value is 1024. |
|
(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). |
Init fn=“ip-dns-cache-init” cache-size=“2140” expire=“600”
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.
The following table describes parameters for the load-modules function.
Table 5–13 load-modules Parameters
Parameter |
Description |
---|---|
Specifies either the full path to the shared library or DLL, or a file name relative to the server configuration directory. |
|
Comma-separated list of the names of the functions in the shared library or DLL to be made available for use by other Init directives or by Service directives in obj.conf. The list should not contain any spaces. The dash (-) character may be used in place of the underscore (_) character in function names. |
|
(Optional) Specifies 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. |
|
Name of a custom thread pool, as specified in thread-pool-init. |
Init fn=load-modules shlib="C:/mysrvfns/corpfns.dll" funcs="moveit" Init fn=load-modules shlib="/mysrvfns/corpfns.so" funcs="myinit,myservice"Init fn=myinit |
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.
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.
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. |
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
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.
The following table describes the parameter for the nt-console-init function.
Table 5–15 nt-console-init Parameters
Parameter |
Description |
---|---|
Directs error messages to the Windows console. The required and only value is console. |
|
Directs output to the Windows console. The required and only value is console. |
Init fn="nt-console-init" stdout=console stderr=console |
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.
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"
The following table describes the parameter for the pa-init-parent-array function.
Table 5–16 pa-init-parent-array Parameters
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"
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.
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"
The following table describes the parameter for the pa-init-proxy-array function.
Table 5–17 pa-init-proxy-array Parameters
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"
Applicable in Init-class directives.
The perf-init function enables system performance measurement through performance buckets.
The following table describes the parameter for the perf-init function.
Table 5–18 perf-init parameters
Parameter |
Description |
---|---|
Flag to disable the use of system performance measurement via performance buckets. Should have a value of true or false. Default value is true. |
Init fn=perf-init disable=false |
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).
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.
The following table describes the parameter for the pool-init function.
Table 5–19 pool-init Parameters
Parameter |
Description |
---|---|
(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. |
Init fn=pool-init disable=true |
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.
The following table describes the parameter for the register-http-method function.
Table 5–20 register-http-method Parameters
Parameter |
Description |
---|---|
Comma-separated list of the names of the methods you are registering. |
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" |
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.
The following table describes parameters for the stats-init function.
Table 5–21 stats-init parameters
Parameter |
Description |
---|---|
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. |
|
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. |
Init fn="stats-init" update-interval="5" virtual-servers="2000" profiling="yes" |
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.
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. |
Init fn="suppress-request-headers" hdr="from" hdr="Cookie" |
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.
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. |
Maximum number of threads in the pool. |
|
Minimum number of threads in the pool. |
|
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. |
|
Stack size of each thread in the native (kernel) thread pool. |
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" |
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.
Init fn=tune-cache byte-ranges
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. |
Init fn=tune-cache byte-ranges=off |
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.
Init fn=tune-proxy ftp-listing-width=number
The following table describes the parameter for the tune-proxy function.
Table 5–25 tune-cache parameters
Parameter |
Description |
---|---|
Increasing the width of FTP listings allows longer file names and thus reduces file name truncation. The default width is 80 characters. |
Init fn=tune-proxy ftp-listing-width=80 |
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.
Init fn="um-define-junction"
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. |
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" |
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.
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. |
Init fn=um-init |
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.
Init fn="um-load-parser-config"
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. |
Init fn="um-load-parser-config" file="/opt/SUNWproxy/proxy-server1/conf/proxy.cfg" |
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 |
---|---|---|---|
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. |
|||
A name for the bucket, for example, cgi-bucket. |
|||
A description of what the bucket measures, for example, CGI Stats. |
|||
Configures DNS caching. |
|||
32 to 32768 (32K) |
1024 |
(optional) Specifies how many entries are contained in the cache. |
|
1 to 31536000 seconds (1 year) |
1200 seconds (20 minutes) |
(optional) Specifies how long in seconds before a cache entry expires. |
|
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" |
|
Specifies the format of each log entry in the log file. |
|||
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. |
||
Number of bytes |
8192 |
Specifies the size of the global log buffer. |
|
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. |
|
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. |
Enables rotation for logs. |
|||
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. |
||
Number of minutes |
|
Indicates the number of minutes to elapse between each log rotation. |
|
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. |
|
yes, no |
yes |
(optional) Determines whether error logs are rotated. |
|
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. |
||
Changes the default settings for CGI programs. |
|||
Number of seconds |
300 |
(optional) specifies how many seconds the server waits for CGI output before terminating the script. |
|
(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. |
||
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. |
|
Loads user home directory information. |
|||
(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. |
|||
Loads shared libraries into the server. |
|||
Specifies either the full path to the shared library or dynamic link library, or specifies a file name relative to the server configuration directory. |
|||
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. |
||
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. |
|
|
The name of a custom thread pool, as specified in thread-pool-init. |
||
Enables the NT console, which is the command-line shell that displays standard output and error streams. |
|||
console |
Directs error messages to the NT console. |
||
console |
Directs output to the NT console. |
||
Enables system performance measurement via performance buckets. |
|||
disable |
true, false |
true |
Disables the function when true. |
Configures pooled memory allocation. |
|||
1048576 bytes or less |
(optional) Maximum size in bytes of free block list. |
||
true, false |
false |
(optional) Flag to disable the use of pooled memory if true. |
|
Enables you to extend the HTTP protocol by registering new HTTP methods. |
|||
methods |
A comma-separated list |
Names of the methods you are registering. |
|
Enables reporting of performance statistics in XML format. |
|||
yes, no |
no |
Enables NSAPI performance profiling using buckets. This setting can also be enabled through perf-init. |
|
1 or greater |
5 |
The period in seconds between statistics updates within the server. |
|
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. |
|
Configures an additional thread pool. |
|||
Name of the thread pool. |
|||
Maximum number of threads in the pool. |
|||
Minimum number of threads in the pool. |
|||
Number of bytes |
Size of the queue for the pool. |
||
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. |