Chapter 5 Predefined SAFs in the obj.conf File

This chapter describes the standard directives and predefined Server Application Functions (SAFs) that are used in the obj.conf file to give instructions to the server.

This chapter describes functions that are part of the core functionality of Proxy Server. It does not include functions that are available only if additional components, such as server-parsed HTML, are enabled.

This chapter covers the following stages:

• Init Functions

• AuthTrans

• NameTrans

• PathCheck

• ObjectType

• Input

• Output

• Service

• AddLog

• Error

• Connect

• DNS

• Filter

• Route

Each SAF has its own arguments, which are passed to it by a directive in obj.conf. Every SAF is also passed additional arguments that contain information about the request (such as what resource was requested and what kind of client requested it), and any other server variables created or modified by SAFs called by previously invoked directives. Each SAF may examine, modify, or create server variables. Each SAF returns a result code that tells the server whether it succeeded, did nothing, or failed.

For an alphabetical list of predefined SAFs, see Appendix D, List of Predefined SAFs.

Server Application Functions (SAFs)

The following table lists the SAFs that can be used with each directive.

Bucket Parameter

The following performance buckets are predefined in Proxy Server:

• The default-bucket records statistics for the functions not associated with any user-defined or built-in bucket.

• The all-requests bucket records .perf statistics for all NSAPI SAFs, including SAFs in the default-bucket.

You can define additional performance buckets in the magnus.conf file. For more information, see the descriptions of the perf-init and define-perf-bucket functions.

You can measure the performance of any SAF in obj.conf by adding a bucket=bucket-name parameter to the function, for example, bucket=cache-bucket.

To list the performance statistics, use the service-dump Service function.

As an alternative, you can use the stats-xml Service function to generate performance statistics. Use of buckets is optional.

For more information about performance buckets, see Oracle iPlanet Web Proxy Server 4.0.14 Administration Guide.

Init Functions

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

Syntax

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

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

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

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

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

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

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

• icp-init - Initializes the ICP feature.

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

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

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

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

• init-uhome - Loads user home directory information.

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

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

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

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

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

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

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

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

• pool-init - Configures pooled memory allocation.

• register-http-method - Enables 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.

define-perf-bucket

Applicable in Init-class directives.

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

Parameters

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

Example

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

See Also

perf-init

flex-init

Applicable in Init-class directives.

The flex-init function opens the named log file to be used for flexible logging and establishes a record format for it. The log format is recorded in the first line of the log file. You cannot change the log format while the log file is in use by the server.

The flex-log function, which is applicable in AddLog-class directives, writes entries into the log file during the AddLog stage of the request-handling process.

The log file stays open until the server is shut down or restarted, at which time all logs are closed and reopened.

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

You may specify multiple log file names in the same flex-init function call. Use multiple AddLog directives with the flex-log function to log transactions to each log file.

The flex-init function may be called more than once. Each new log file name and format is added to the list of log files.

If you move, remove, or change the currently active log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup the currently active log file, rename the file and then restart the server. The server first looks for the log file by name, and if it doesn’t find that name, it creates a new file. The renamed original log file is left for you to use.

For information on rotating log files, see flex-rotate-init.

The flex-init function has three parameters: one that names the log file, one that specifies the format of each record in that file, and one that specifies the logging mode.

Parameters

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

Log Format

The flex-init function recognizes anything contained between percent signs (%) as the name portion of a name-value pair stored in a parameter block in the server. (The one exception to this rule is the %SYSDATE% component, which delivers the current system date.) %SYSDATE% is formatted using the time format %d/%b/%Y:%H:%M:%S plus the offset from GMT.

Any additional text is treated as literal text, so you can add to the line to make it more readable. Typical components of the formatting parameter are listed in the following flex-init. Components that contain spaces should be bounded by escaped quotation marks (\\”).

If no format parameter is specified for a log file, the common log format is used:

"%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \\"%Req->reqpb.clf-request%\\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"

You can now log cookies by logging the Req->headers.cookie.name component.

In the following table, the components that are enclosed in escaped double quotation marks (\\”) are the ones that could potentially resolve to values that contains spaces.

Examples

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

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

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

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

This example will record the following items:

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

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

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

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

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

• Content length

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

Init fn=flex-init extended="<install-root><instance-directory>
	/logs/extended" format.extended="%Ses->client.ip% - %Req->vars.auth-user
	% [%SYSDATE%]	\\"%Req->reqpb.clf-request%\\" %Req->srvhdrs.clf-status% 
	%Req->srvhdrs.content-length% %Req->headers.referer% 
	\\"%Req->headers.user-agent%\\" %Req->reqpb.method% 
	%Req->reqpb.uri% %Req->reqpb.query% %Req->reqpb.protocol%"

The third example shows how logging can be tuned to prevent request handling threads from making blocking calls when writing to log files Instead you can delegate these calls to the log flush thread.

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

Init fn=flex-init buffer-size=16384 num-buffers=2000 access="
	/<install-root><instance-directory>/logs/access" 
	format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] 
	\\"%Req->reqpb.clf-request%\\" %Req->srvhdrs.clf-status% 
	%Req->srvhdrs.content-length%"

See Also

flex-rotate-init

flex-rotate-init

Applicable in Init-class directives.

The flex-rotate-init function configures log rotation for all log files on the server, including error logs and the common-log, flex-log, and record-useragent AddLog SAFs. Call this function in the Init section of magnus.conf before calling flex-init. The flex-rotate-init function enables you to specify a time interval for rotating log files. At the specified time interval, the server moves the log file to a file whose name indicates the time of the move. The log functions in the AddLog stage in obj.conf then start logging entries in a new log file. The server does not need to be shut down while the log files are being rotated.

The server keeps all rotated log files so clean them up as necessary to free disk space.

By default, log rotation is disabled.

Parameters

The following table describes parameters for the flex-rotate-init function.

Example

This example enables log rotation, starting at midnight and occurring every hour.

Init fn=flex-rotate-init rotate-start=2400 rotate-interval=60

See Also

flex-init

host-dns-cache-init

Applicable in Init-class directives.

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

Parameters

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

Example

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

icp-init

Applicable in Init-class directives.

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

Syntax

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

Parameters

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

Example

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

init-clf

Applicable in Init-class directives.

The init-clf function opens the named log files to be used for common logging. The common-log function writes entries into the log files during the AddLog stage of the request-handling process. The log files stay open until the server is shut down, at which time the log files are closed or the server is restarted. 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.

Parameters

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

Examples

Init fn=init-clf access=/usr/netscape/server4/https-boots/logs/access
Init fn=init-clf templog=/tmp/mytemplog templog2=/tmp/mytemplog2

See Also

flex-rotate-init

init-filter-order

Applicable in Init-class directives.

The init-filter-order Init SAF can be used to control the position of specific filters within filter stacks. For example, init-filter-order can be used to ensure that a filter that converts outgoing XML to XHTML is inserted above a filter that converts outgoing XHTML to HTML.

Filters that appear higher in the filter stack are given an earlier opportunity to process outgoing data. Filters that appear lower in the filter stack are given an earlier opportunity to process incoming data.

Filter developers use the filter_create function to define the filter’s position in the filter stack. For example, filters that translate content from XML to HTML are placed higher in the filter stack than filters that compress data for transmission. init-filter-order can be used to override the position defined by the filter developer.

When two or more filters are defined to occupy the same position in the filter stack, filters that were inserted later will appear higher than filters that were inserted earlier. The order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf becomes important. For example, consider two filters, xhtml-to-html and xml-to-xhtml, which convert XHTML to HTML and XML to XHTML, respectively. Because both filters transform data from one format to another, they may be defined to occupy the same position in the filter stack. To transform XML documents to XHTML and then to HTML before sending the data to the client, Output fn="insert-filter" directives in obj.conf would appear in the following order:

Output fn="insert-filter" filter="xhtml-to-html"
Output fn="insert-filter" filter="xml-to-xhtml"

Administrators should use the order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf to control the position of filters in the filter stack. init-filter-order should only be used to address specific filter interoperability problems.

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

Parameters

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

Example

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

init-j2ee

This function is applicable only to the Administration Server in Init-class directives..

The init-j2ee function initializes the Java subsystem.

Parameters

This function requires a LateInit=yes parameter.

Example

Init fn="load-modules" shlib="install_dir/lib/libj2eeplugin.so" 
	funcs="init-j2ee,ntrans-j2ee,service-j2ee,error-j2ee" 
	shlib_flags="(global|now)"
Init fn="init-j2ee" LateInit=yes

init-proxy

Applicable in Init-class directives.

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

Syntax

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

Parameters

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

Example

Init fn=init-proxy
    timeout=120

init-uhome

Applicable in Init-class directives.

UNIX Only. The init-uhome function loads information about the system’s user home directories into internal hash tables. This process increases memory usage slightly, but improves performance for servers that have significant traffic to home directories.

Parameters

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

Examples

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

init-url-filter

Applicable in Init-class directives.

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

Parameters

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

Example

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

ip-dns-cache-init

Applicable in Init-class directives.

The ip-dns-cache-init function specifies that DNS lookups should be cached when DNS lookups are enabled. If DNS lookups are cached, then when the server gets a client’s host name information, it stores that information in the DNS cache. If the server requires information about the client in the future, the information is available in the DNS cache.

You may specify the size of the DNS cache and the time it takes before a cache entry becomes invalid. The DNS cache can contain 32 to 32768 entries. The default value is 1024 entries. Values for the time before a cache entry expires, specified in seconds can range from 1 second to 1 year. The default value is 1200 seconds (20 minutes).

Parameters

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

Example

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

load-modules

Applicable in Init-class directives.

The load-modules function loads a shared library or dynamic-link library (DLL) into the server code. Specified functions from the library can then be executed from any subsequent directives. Use this function to load new plug-ins or SAFs.

If you define your own SAFs, load them by using the load-modules function and specifying the shared library or DLL to load.

Parameters

The following table describes parameters for the load-modules function.

Examples

Init fn=load-modules shlib="C:/mysrvfns/corpfns.dll" funcs="moveit"
Init fn=load-modules shlib="/mysrvfns/corpfns.so" 
	funcs="myinit,myservice"Init fn=myinit

load-types

Applicable in Init-class directives.

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

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

Syntax

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

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

Parameters

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

Example

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

nt-console-init

Applicable in Init-class directives.

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

Parameters

The following table describes the parameter for the nt-console-init function.

Example

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

pa-init-parent-array

Applicable in Init-class directives.

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

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

Syntax

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

Parameters

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

Example

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

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

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

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

pa-init-proxy-array

Applicable in Init-class directives.

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

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

Syntax

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

Parameters

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

Example

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

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

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

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

perf-init

Applicable in Init-class directives.

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

Parameters

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

Example

Init fn=perf-init disable=false

See Also

define-perf-bucket

pool-init

Applicable in Init-class directives.

The pool-init function changes the default values of pooled memory settings. The size of the free block list may be changed or pooled memory may be entirely disabled.

Memory allocation pools enable the server to run significantly faster. If you are programming with the NSAPI, note that MALLOC, REALLOC, CALLOC, STRDUP, and FREE work slightly differently if pooled memory is disabled. If pooling is enabled, the server automatically cleans up all memory allocated by these routines when each request completes. In most cases, this process will improve performance and prevent memory leaks. If pooling is disabled, all memory is global and 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.

Parameters

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

Example

Init fn=pool-init disable=true

register-http-method

Applicable in Init-class directives.

This function enables you to extend the HTTP protocol by registering new HTTP methods. You do not need to register the default HTTP methods.

Upon accepting a connection, the server checks whether the method it received is registered. If the server does not recognize the method, it returns a “501 Method Not Implemented” error message.

Parameters

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

Example

The following example shows the use of register-http-method and a Service function for one of the methods.

Init fn="register-http-method" methods="MY_METHOD1,MY_METHOD2"
	Service fn="MyHandler" method="MY_METHOD1"

stats-init

Applicable in Init-class directives.

The stats-init function enables reporting of performance statistics in XML format. The report is generated by the stats-xml function in obj.conf.

Parameters

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

Example

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

suppress-request-headers

Applicable in Init-class and ObjectType-class directives.

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

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

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

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

Parameters

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

Example

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

thread-pool-init

Applicable in Init-class directives.

The thread-pool-init function creates a new pool of user threads. A pool must be declared before it is used. To specify that a plug-in should use the new pool, specify the pool parameter when loading the plug-in with the Init-class function load-modules.

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

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.

Example

Init fn=tune-cache
    byte-ranges=off

tune-proxy

Applicable in Init-class directives.

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

Syntax

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

Parameters

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

Example

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

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.

The following parameters apply only to junction mappings.

The following parameters apply only to junction definitions.

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:

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.

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:

AuthTrans

AuthTrans stands for Authorization Translation. AuthTrans directives give the server instructions for checking authorization before allowing a client to access resources. AuthTrans directives work in conjunction with PathCheck directives. The AuthTrans function checks whether the user name and password associated with the request are acceptable. However, this function does not allow or deny access to the request. Access is handled by the PathCheck function.

The server handles the authorization of client users in two steps:

• AuthTrans validates authorization information sent by the client in the Authorization header.

• PathCheck checks that the authorized user is allowed access to the requested resource.

The authorization process is split into two steps so that multiple authorization schemes can be easily incorporated. This scheme also provides the flexibility to have resources that record authorization information but do not require it.

AuthTrans functions get the user name and password from the headers associated with the request. When a client initially makes a request, the user name and password are unknown so the AuthTrans functions and PathCheck functions work together to reject the request, because they cannot validate the user name and password. When the client receives the rejection, its usual response is to present a dialog box asking for the user name and password to enter the appropriate realm. The client submits the request again, this time including the user name and password in the headers.

If more than one AuthTrans directive is present in obj.conf, each function is executed in order until one succeeds in authorizing the user.

The following AuthTrans-class functions are described in detail in this section:

• basic-auth calls a custom function to verify user name and password. Optionally determines the user’s group.

• basic-ncsa verifies user name and password against an NCSA-style or system DBM database. Optionally determines the user’s group.

• get-sslid retrieves a string that is unique to the current SSL session and stores it as the ssl-id variable in the Session->client parameter block.

• match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Proxy Server based upon the results by setting values for specified variables.

• proxy-auth translates authorization information provided through the basic proxy authorization scheme.

• set-variable enables you to change server settings based upon conditional information in a request, and to manipulate variables in parameter blocks by using specific commands.

basic-auth

Applicable in AuthTrans-class directives.

The basic-auth function calls a custom function to verify authorization information sent by the client. The Authorization header is sent as part of the basic server authorization scheme.

This function is usually used in conjunction with the PathCheck-class function require-auth.

Parameters

The following table describes the parameter for the basic-auth function.

Examples

In magnus.conf:

Init fn=load-modules shlib=/path/to/mycustomauth.so funcs=hardcoded_auth

         

In obj.conf:

AuthTrans fn=basic-auth auth-type=basic userfn=hardcoded_authPathCheck 
	fn=require-auth auth-type=basic realm="Marketing Plans"

See Also

require-auth

basic-ncsa

Applicable in AuthTrans-class directives.

The basic-ncsa function verifies authorization information sent by the client against a database. The Authorization header is sent as part of the basic server authorization scheme.

This function is usually used in conjunction with the PathCheck-class function require-auth.

Parameters

The following table describes the parameter for the basic-ncsa function.

Examples

AuthTrans fn=basic-ncsa auth-type=basic dbm=/sun/server61/userdb/rsPathCheck 
	fn=require-auth auth-type=basic realm="Marketing Plans"AuthTrans 
	fn=basic-ncsa auth-type=basic userfile=/sun/server61/.htpasswd 
	grpfile=/sun/server61/.grpfilePathCheck fn=require-auth auth-type=basic 
	realm="Marketing Plans"

See Also

require-auth

get-sslid

Applicable in AuthTrans-class directives.

This function is provided for backward compatibility only. The functionality of get-sslid has been incorporated into the standard processing of an SSL connection.

The get-sslid function retrieves a string that is unique to the current SSL session, and stores it as the ssl-id variable in the Session->client parameter block.

If the variable ssl-id is present when a CGI is invoked, it is passed to the CGI as the HTTPS_SESSIONID environment variable.

The get-sslid function has no parameters and always returns REQ_NOACTION. It has no effect if SSL is not enabled.

Parameters

The following table describes the parameter for the get-sslid function.

match-browser

Applicable in all stage directives.

The match-browser SAF matches specific strings in the User-Agent string supplied by the browser match-browser then modifies the behavior of Proxy Server based upon the results by setting values for specified variables.

Syntax

stage fn="match-browser" browser="string" name="value" [name="value" ...]

Parameters

The following table describes the parameter values for the match-browser function.

Example

The following AuthTrans directive instructs Proxy Server to when the browser’s User-Agent header contains the string Broken or broken:

• Not send the SSL3 and TLS close_notify packet (see set-variable).

• Not honor requests for HTTP Keep-Alive (see set-variable).

• Use the HTTP/1.0 protocol rather than HTTP/1.1 (see set-variable).

AuthTrans fn="match-browser" browser="*[Bb]roken*" ssl-unclean-shutdown="true" 
keep-alive="disabled" http-downgrade="1.0"

The following table describes the variables used in the example.

AuthTrans fn="match-browser" browser="*MSIE*" 
ssl-unclean-shutdown="true"

AuthTrans fn="match-browser" browser="*MSIE*" keep-alive="disabled"

See Also

set-variable

proxy-auth

Applicable in AuthTrans-class directives.

The proxy-auth function of the AuthTrans directive translates authorization information provided through the basic proxy authorization scheme. This scheme is similar to the HTTP authorization scheme but doesn’t interfere with it, so using proxy authorization doesn’t block the ability to authenticate to the remote server.

This function is usually used with the PathCheck fn=require-proxy-auth function.

Syntax

AuthTrans fn=proxy-auth auth-type=basic  dbm=full path name
AuthTrans fn=proxy-auth auth-type=basic userfile=full path name 
	grpfile=full path name

Parameters

The following table describes the parameter values for the proxy-auth function.

Example

A UNIX example:

AuthTrans fn=proxy-auth auth-type=basic  
	dbm=/usr/ns-home/proxy-EXAMPLE/userdb/rs
A Windows NT example:
AuthTrans fn=proxy-auth auth-type=basic userfile=\\netscape\\server
	\\proxy-EXAMPLE\\.htpasswd grpfile=\\netscape\\server
	\\proxy-EXAMPLE\\.grpfile

You can have a user-provided function perform authentication by passing the user-fn parameter to the proxy-auth function.

Syntax

AuthTrans fn=proxy-auth auth-type=basic    user-fn=your function     userdb=full path name

Parameters

The following table describes the parameter values for the user provided proxy-auth function.

set-variable

Applicable in all stage directives.

The set-variable function enables you to change server settings based upon conditional information in a request. It can also be used to manipulate variables in parameter blocks with the following commands:

• insert-pblock="name=value"

  Adds a new value to the specified pblock.

• set-pblock="name=value"

  Sets a new value in the specified pblock, replacing any existing values with the same name.

• remove-pblock="name"

  Removes all values with the given name from the specified pblock.

For more information about parameter blocks, see Oracle iPlanet Web Proxy Server 4.0.14 NSAPI Developer’s Guide.

Syntax

stage fn="set-variable" [{insert|set|remove}-pblock="name=value" ...][name="value" ...]

Parameters

The following table describes parameter values for the set-variable function.

Variables

The following table lists variables supported by the set-variable SAF.

Examples

• To deny HTTP keep-alive requests for a specific server class while still honoring keep-alive requests for the other classes, add this AuthTrans directive to the obj.conf for the server class, and set the variable keep-alive to disabled:

  AuthTrans fn="set-variable" keep-alive="disabled"

  To cause that same server class to use HTTP/1.0 while the rest of the server classes use HTTP/1.1, the AuthTrans directive would be:

  AuthTrans fn="set-variable" keep-alive="disabled" http-downgrade="true"

• To insert an HTTP header into each response, add a NameTrans directive to obj.conf, using the insert-pblock command and specifying srvhdrs as your Session/Request parameter block.

  For example, to insert the HTTP header P3P, you would add the following line to each request:

  NameTrans fn="set-variable" insert-srvhdrs="P3P"

• To terminate processing a request based upon certain URIs, use a <Client> tag to specify the URIs and an AuthTrans directive that sets the variable abort to true when a match is found. Your <Client> tag would be comparable to the following:

  <Client uri="*(system32|root.exe)*">AuthTrans fn="set-variable" abort="true"</Client>

See Also

match-browser

NameTrans

NameTrans stands for Name Translation. NameTrans directives translate virtual URLs to physical directories on your server. For example, the URL

http://www.test.com/some/file.html

could be translated to the full file system path

/usr/Sun/WebServer61/server1/docs/some/file.html

NameTrans directives should appear in the default object. If an object contains more than one NameTrans directive, the server executes each directive in order until one succeeds.

The following NameTrans-class functions are described in detail in this section

• assign-name tells the server to process directives in a named object.

• document-root translates a URL into a file system path by replacing the http://server-name/ part of the requested resource with the document root directory.

• home-page translates a request for the server’s root home page (/) to a specific file.

• map looks for a certain URL prefix in the URL that the client is requesting.

• match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Proxy Server based upon the results by setting values for specified variables.

• ntrans-j2ee determines whether a request maps to a -based web application context. Based on Java technology this function is applicable only to the Administration Server.

• pac-map maps proxy-relative URLs to local files that are delivered to clients who request configuration.

• pat-map maps proxy-relative URLs to local files that are delivered to proxies that request configuration.

• pfx2dir translates any URL beginning with a given prefix to a file system directory and optionally enables directives in an additional named object.

• redirect redirects the client to a different URL.

• regexp-map allows a regular expression map.

• reverse-map rewrites HTTP response headers when the proxy server is functioning as a reverse proxy.

• set-variable enables you to change server settings based upon conditional information in a request, and to manipulate variables in parameter blocks by using specific commands.

• strip-params removes embedded semicolon-delimited parameters from the path.

• um-ntrans identifies an inbound request as being related to a junction (or not).

• unix-home translates a URL to a specified directory within a user’s home directory.

assign-name

Applicable in NameTrans-class directives.

The assign-name function specifies the name of an object in obj.conf that matches the current request. The server then processes the directives in the named object in preference to the ones in the default object.

For example, consider the following directive in the default object:

NameTrans fn=assign-name name=personnel from=/personnel

Suppose the server receives a request for http://server-name/personnel. After processing this NameTrans directive, the server looks for an object named personnel in obj.conf, and continues by processing the directives in the personnel object.

The assign-name function always returns REQ_NOACTION.

Parameters

The following table describes the parameters for the assign-name function.

Example

# This NameTrans directive is in the default object.
	NameTrans fn=assign-name name=personnel from=/a/b/c/pers...
	<Object name=personnel>...additional directives..</Object>
NameTrans fn="assign-name" from="/perf" find-pathinfo-forward="" name="perf"
NameTrans fn="assign-name" from="/nsfc"  nostat="/nsfc" name="nsfc"

document-root

Applicable in NameTrans-class directives.

The document-root function specifies the root document directory for the server. If the physical path has not been set by a previous NameTrans function, the http://server-name/ part of the path is replaced by the physical path name for the document root.

When the server receives a request for http://server-name/somepath/somefile, the document-root function replaces http://server-name/ with the value of its root parameter. For example, if the document root directory is /usr/sun/webserver61/server1/docs, then when the server receives a request for http://server-name/a/b/file.html, the document-root function translates the path name for the requested resource to /usr/sun/webserver61/server1/docs/a/b/file.html.

This function always returns REQ_PROCEED. NameTrans directives listed after this response are never called, so be sure that the directive that invokes document-root is the last NameTrans directive.

You can declare only one root document directory. To specify additional document directories, use the pfx2dir function to set up additional path name translations.

Parameters

The following table describes parameters for the document-root function.

Examples

NameTrans fn=document-root root=/usr/sun/webserver61/server1/docsNameTrans 
	fn=document-root root=$docroot

         

See Also

pfx2dir

home-page

Applicable in NameTrans-class directives.

The home-page function specifies the home page for your server. This page is displayed whenever a client requests the server’s home page (/).

Parameters

The following table describes parameters for the home-page function.

Examples

NameTrans fn="home-page" path="/path/to/file.html"
NameTrans fn="home-page" path="/path/to/$id/file.html"

map

Applicable in NameTrans-class directives.

The map function looks for a certain URL prefix in the URL that the client is requesting. If map finds the prefix, it replaces the prefix with the mirror site prefix. Note that the trailing slashes in URL cause “Not Found” errors.

Syntax

NameTrans fn=map from="source site prefix" to="destination site prefix" name="named object"

Parameters

The following table describes parameters for the map function.

Example

# Map site http://home.netscape.com/ to mirror site http://mirror.com
NameTrans fn=map  from="http://home.netscape.com" to="http://mirror.com"

         

match-browser

See match-browser.

ntrans-j2ee

This function is applicable only to the Administration Server. It is applicable in NameTrans-class directives.

The ntrans-j2ee function determines whether a request maps to a Java web application context.

Parameters

The following table describes parameters for the ntrans-j2ee function.

Example

 NameTrans fn="ntrans-j2ee" name="j2ee"

See Also

service-j2ee, error-j2ee

pac-map

Applicable in NameTrans-class directives.

The pac-map function maps proxy-relative URLs to local files that are delivered to clients who request configuration.

Syntax

NameTrans fn=pac-map     from=URL    to=prefix    name=named object

Parameters

The following table describes parameters for the pac-map function.

Example

NameTrans fn=pac-map  from=http://proxy.mysite.com/pac  
	to=<install-root><instance-directory>pac/proxy.pac name=file

pat-map

Applicable in NameTrans-class directives.

The pat-map function maps proxy-relative URLs to local files that are delivered to proxies who request configuration.

Syntax

NameTrans fn=pat-map     from=URL    to=prefix    name=named object

Parameters

The following table describes parameters for the pat-map function.

Example

NameTrans fn=pat-map  from=http://proxy.mysite.com/pac  
	to=<install-root><instance-directory>pac/proxy.pac name=file

pfx2dir

Applicable in NameTrans-class directives.

The pfx2dir function replaces a directory prefix in the requested URL with a real directory name. It also optionally enables you to specify the name of an object that matches the current request. See the discussion of assign-name for details of using named objects.

Parameters

The following table describes parameters for the pfx2dir function.

Examples

In the first example, the URL http://server-name/cgi-bin/resource (such as http://x.y.z/cgi-bin/test.cgi) is translated to the physical path name /httpd/cgi-local/resource (such as /httpd/cgi-local/test.cgi), and the server also starts processing the directives in the object named cgi.

NameTrans fn=pfx2dir from=/cgi-bin dir=/httpd/cgi-local name=cgi

In the second example, the URL http://server-name/icons/resource (such as http://x.y.z/icons/happy/smiley.gif) is translated to the physical path name /users/nikki/images/resource (such as /users/nikki/images/smiley.gif).

NameTrans fn=pfx2dir from=/icons/happy dir=/users/nikki/images

         

The third example shows the use of the find-pathinfo-forward parameter. The URL http://server-name/cgi-bin/resource is translated to the physical path name /export/home/cgi-bin/resource.

NameTrans fn="pfx2dir" find-pathinfo-forward="" from="/cgi-bin" 
	dir="/export/home/cgi-bin" name="cgi"

redirect

Applicable in NameTrans-class directives.

The redirect function enables you to change URLs and send the updated URL to the client. When a client accesses your server with an old path, the server treats the request as a request for the new URL.

Parameters

The following table describes parameters for the redirect function.

Examples

In the first example, any request for http://server-name/string is translated to a request for http://tmpserver/string.

NameTrans fn=redirect from=/ url-prefix=http://tmpserver

         

In the second example, any request for http://server-name/toopopular/string is translated to a request for http://bigger/better/stronger/morepopular/string.

NameTrans fn=redirect from=/toopopular 
	url=http://bigger/better/stronger/morepopular

regexp-map

Applicable in NameTrans-class directives.

The regexp-map is similar to the map function. While the map function looks for an exact match of a URL prefix, regexp-map allows a regular expression match.

Parameters

The following table describes parameters for the regexp-map function.

reverse-map

Applicable in NameTrans-class directives.

The reverse-map function is used to rewrite HTTP response headers when the proxy server is functioning as a reverse proxy. reverse-map looks for the URL prefix specified by the from parameter in certain response headers. If the from prefix matches the beginning of the response header value, reverse-map replaces the matching portion with the to prefix.

Parameters

The following table describes parameters for the reverse-map function.

set-variable

See set-variable.

strip-params

Applicable in NameTrans-class directives.

The strip-params function removes embedded semicolon-delimited parameters from the path. For example, a URI of /dir1;param1/dir2 would become a path of /dir1/dir2. When used, the strip-params function should be the first NameTrans directive listed.

Parameters

The following table describes the parameter for the strip-params function.

Example

NameTrans fn=strip-params

um-ntrans

Applicable in NameTrans-class directives.

The um-ntrans function determines if an inbound request is related to a junction or not. It also rewrites inbound cookies, adds headers, and does any rewriting when necessary, before the request is sent to the back-end server.

If a request cannot be mapped to a junction, it is passed through without modification.

This directive must appear exactly once in obj.conf, typically inside the default object.

Example

Nametrans fn="um-ntrans"

unix-home

Applicable in NameTrans-class directives.

UNIX Only. The unix-home function translates user names typically of the form ~username into the user’s home directory on the server’s UNIX machine. You specify a URL prefix that signals user directories. Any request that begins with the prefix is translated to the user’s home directory.

You specify the list of users with either the /etc/passwd file or a file with a similar structure. Each line in the file should have this structure. Elements in the passwd file that are not needed are indicated with *:

username:*:*:groupid:*:homedir:*

If you want the server to scan the password file only once at startup, use the Init-class function init-uhome in magnus.conf.

Parameters

The following table describes the parameters for the unix-home function.

Examples

NameTrans fn=unix-home from=/~ subdir=public_html
NameTrans fn=unix-home from /~ pwfile=/mydir/passwd subdir=public_html

See Also

find-links

PathCheck

PathCheck directives check the local file system path that is returned after the NameTrans step. The path is checked for things such as CGI path information and for dangerous elements such as /./and /../ and //, and then any access restriction is applied.

If object contains more than one PathCheck directive, each of the functions is executed in order.

The following PathCheck-class functions are described in detail in this section:

• block-multipart-posts - Blocks all multipart form file uploads when configured without any parameters.

• check-acl - Checks an access control list for authorization.

• deny-existence - Indicates that a resource was not found.

• deny-service - Sends a “Proxy Denies Access” error when a client tries to access a specific path.

• find-index - Locates a default file when a directory is requested.

• find-links - Denies access to directories with certain file system links.

• find-pathinfo - Locates extra path info beyond the file name for the PATH_INFO CGI environment variable.

• get-client-cert - Gets the authenticated client certificate from the SSL3 session.

• load-config - Finds and loads extra configuration information from a file in the requested path.

• match-browser - Matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Proxy Server based upon the results by setting values for specified variables.

• nt-uri-clean - Denies access to requests with unsafe path names by sending not found error.

• ntcgicheck - Checks for a CGI file with a specified extension.

• require-auth - Denies access to unauthorized users or groups.

• require-proxy-auth - Makes sure that users are authenticated and triggers a password pop-up window.

• set-variable - Enables you to change server settings based upon conditional information in a request, and to manipulate variables in parameter blocks by using specific commands.

• set-virtual-index - Specifies a virtual index for a directory.

• ssl-check - Checks the secret keysize.

• ssl-logout - Invalidates the current SSL session in the server’s SSL session cache.

• unix-uri-clean - Denies access to requests with unsafe path names by sending not found error.

• url-check - Checks the validity of URL syntax.

• url-filter - Allows or denies URL patterns.

• user-agent-check - Restricts access to the proxy server based on the type and version of the client’s web browser.

block-multipart-posts

Applicable in PathCheck-class directives.

The block-multipart-posts function blocks all multipart form file uploads when configured without any parameters. This can also be used to block requests based on specific content type, user-agent, or HTTP method using content-type, user-agent and method parameters.

Parameters

The following table describes parameters for the block-multipart-posts function.

Example

PathCheck fn="block-multipart-posts" user-agent="Mozilla/.*" 
	method="(POST|PUT)"

check-acl

Applicable in PathCheck-class directives.

The check-acl function specifies an access control list (ACL) to use to check whether the client is allowed to access the requested resource. An access control list contains information about who is allowed to access a resource, and under what conditions access is allowed.

Regardless of the order of PathCheck directives in the object, check-acl functions are executed first. These functions cause user authentication to be performed, if required by the specified ACL, and will also update the access control state.

Parameters

The following table describes parameters for the check-acl function.

Example

PathCheck fn=check-acl acl="*HRonly*"

deny-existence

Applicable in PathCheck-class directives.

The deny-existence function sends a “not found” message when a client tries to access a specified path. The server sends “not found” instead of “forbidden,” so the user cannot tell if the path exists.

Parameters

The following table describes the parameters for the deny-existence function.

Examples

PathCheck fn=deny-existence path=/usr/sun/server61/docs/private
PathCheck fn=deny-existence bong-file=/svr/msg/go-away.html

deny-service

Applicable in PathCheck-class directives and Service-class directives.

The deny-service function sends a “Proxy Denies Access” error when a client tries to access a specific path. If this directive appears in a client region, the directive performs access control on the specified clients.

The proxy specifically denies clients instead of specifically allowing them access to documents. The default object is used when a client doesn’t match any client region in objects. Because the default object uses the deny-service function, no one is allowed access by default.

Syntax

PathCheck fn=deny-service path=.*someexpression.*

Parameters

The following table describes the parameter for the deny-service function.

Example

<Object ppath="http://sun/.*">
# Deny servicing proxy requests for fun GIFs
PathCheck fn=deny-service path=.*fun.*.gif
# Make sure nobody except Sun employees can use the object
# inside which this is placed.
<Client dns=*~.*.sun.com>
PathCheck fn=deny-service
</Client>
</Object>

find-compressed

Applicable in PathCheck-class directives.

The find-compressed function checks if a compressed version of the requested file is available. If the following conditions are met, find-compressed changes the path to point to the compressed file:

• A compressed version is available

• The compressed version is at least as recent as the noncompressed version

• The client supports compression

Not all clients support compression. The find-compressed function enables you to use a single URL for both the compressed and noncompressed versions of a file. The version of the file that is selected is based on the individual client's capabilities.

A compressed version of a file must have the same file name as the noncompressed version but with a .gz suffix. For example, the compressed version of a file named /httpd/docs/index.html would be named /httpd/docs/index.html.gz. To compress files, you can use the freely available gzip program.

Because compressed files are sent as is to the client, you should not compress files such as SHTML pages, CGI programs, or pages created with Java Server Pages^TM (JSP^TM) technology that need to be interpreted by the server. To compress the dynamic content generated by these types of files, use the http-compression filter.

The find-compressed function does nothing if the HTTP method is not GET or HEAD.

Parameters

The following table describes parameters for the find-compressed function.

Example

<Object name="default">NameTrans fn="assign-name" from="*.html" 
	name="find-compressed"...</Object><Object name="find-compressed">
	PathCheck fn="find-compressed"</Object>

See Also

http-compression

find-index

Applicable in PathCheck-class directives.

The find-index function investigates whether the requested path is a directory. If the path is directory, the function searches for an index file in the directory, and then changes the path to point to the index file. If no index file is found, the server generates a directory listing.

If the obj.conf file contains a NameTrans directive that calls home-page and the requested directory is the root directory, then the home page rather than the index page is returned to the client.

The find-index function does nothing if there is a query string, if the HTTP method is not GET, or if the path is that of a valid file.

Parameters

The following table describes parameters for the find-index function.

Example

PathCheck fn=find-index index-names=index.html,home.html

find-links

Applicable in PathCheck-class directives.

UNIX Only. The find-links function searches the current path for symbolic or hard links to other directories or file systems. If any are found, an error is returned. This function is normally used for directories that are not trusted such as user home directories. The function prevents someone from pointing to information that should not be made public.

Parameters

The following table describes parameters for the find-links function.

Examples

PathCheck fn=find-links disable=sh dir=/foreign-dir
PathCheck fn=find-links disable=so dir=public_html

See Also

unix-home

find-pathinfo

Applicable in PathCheck-class directives.

The find-pathinfo function finds any extra path information after the file name in the URL and stores it for use in the CGI environment variable PATH_INFO.

Parameters

The following table describes parameters for the find-pathinfo function.

Examples

PathCheck fn=find-pathinfo
PathCheck fn=find-pathinfo find-pathinfo-forward=""

get-client-cert

Applicable in PathCheck-class directives.

The get-client-cert function gets the authenticated client certificate from the SSL3 session. The function can apply to all HTTP methods, or only to those that match a specified pattern. The function only works when SSL is enabled on the server.

If the certificate is present or obtained from the SSL3 session, the function returns REQ_NOACTION, allowing the request to proceed. Otherwise, the function returns REQ_ABORTED and sets the protocol status to 403 FORBIDDEN, causing the request to fail and the client to be given the FORBIDDEN status.

Parameters

The following table describes parameters for the get-client-cert function.

Example

# Get the client certificate from the session. 
	If a certificate is not already associated with the session, request one.
 The request fails if the client does not present a valid certificate.
PathCheck fn="get-client-cert" dorequest="1"

load-config

Applicable in PathCheck-class directives.

The load-config function searches for configuration files in document directories and adds the file’s contents to the server’s existing configuration. These configuration files, also known as dynamic configuration files, specify additional access control information for the requested resource. Depending on the rules in the dynamic configuration files, the server determines whether to allow the client to access the requested resource.

Each directive that invokes load-config is associated with a base directory, which is either stated explicitly through the basedir parameter or derived from the root directory for the requested resource. The base directory determines two things:

• The topmost directory for which requests will invoke this call to the load-config function.

  For example, if the base directory is D:/sun/server1/docs/nikki/, then only requests for resources in this directory or its subdirectories and their subdirectories trigger the search for dynamic configuration files. A request for the resource D:/sun/server1/docs/somefile.html does not trigger the search in this case because the requested resource is in a parent directory of the base directory.

• The topmost directory in which the server looks for dynamic configuration files to apply to the requested resource.

  If the base directory is D:/sun/server1/docs/nikki/, the server starts its search for dynamic configuration files in this directory. It may or may not also search subdirectories (but never parent directories), depending on other factors.

When you enable dynamic configuration files through the Server Manager interface, the system writes additional objects with ppath parameters into the obj.conf file. If you manually add directives that invoke load-config to the default object rather than putting them in separate objects, the Server Manager interface might not reflect your changes.

If you manually add PathCheck directives that invoke load-config to the file obj.conf, put them in additional objects created with the <OBJECT> tag rather than putting them in the default object. Use the ppath attribute of the OBJECT tag to specify the partial path name for the resources to be affected by the access rules in the dynamic configuration file. The partial path name can be any path name that matches a pattern, which can include wildcard characters.

For example, the following <OBJECT> tag specifies that requests for resources in the directory D:/sun/proxy4/docs are subject to the access rules in the file my.nsconfig.

<Object ppath="D:/sun/server1/docs/*">PathCheck fn="load-config" 
	file="my.nsconfig" descend=1 basedir="D:/sun/server1/docs" </Object>

If the ppath resolves to a resource or directory that is higher in the directory tree or is in a different branch of the tree than the base directory, the load-config function is not invoked. The base directory specifies the highest-level directory for which requests will invoke the load-config function.

The load-config function returns REQ_PROCEED if configuration files were loaded, REQ_ABORTED on error, or REQ_NOACTION when no files are loaded.

Parameters

The following table describes parameters for the load-config function.

Examples

In this example, whenever the server receives a request for any resource containing the substring secret that resides in D:/Sun/WebServer61/server1/docs/nikki/ or a subdirectory it searches for a configuration file called checkaccess.nsconfig.

The server starts the search in the directory D:/Sun/WebServer61/server1/docs/nikki, and searches subdirectories too. It loads each instance of checkaccess.nsconfig and applies the access control rules contained in each instance to determine whether the client is allowed to access the requested resource.

<Object ppath="*secret*"> PathCheck fn="load-config" 
	file="checkaccess.nsconfig" basedir="D:/Sun/WebServer61/server1/docs/nikki" 
	descend="1" </Object>

match-browser

See match-browser.

nt-uri-clean

Applicable in PathCheck-class directives.

Windows Only. The nt-uri-clean function denies access to any resource whose physical path contains \\.\\, \\..\\ or \\\\ (these are potential security problems).

Parameters

The following table describes parameters for the nt-uri-clean function.

Example

PathCheck fn=nt-uri-clean

See Also

unix-uri-clean

ntcgicheck

Applicable in PathCheck-class directives.

Windows Only. The ntcgicheck function specifies the file name extension to be added to any file name that does not have an extension, or to be substituted for any file name that has the extension .cgi.

Parameters

The following table describes parameters for the ntcgicheck function.

Example

PathCheck fn=ntcgicheck extension=pl

See Also

send-wincgi, send-shellcgi

require-auth

Applicable in PathCheck-class directives.

The require-auth function allows access to resources only if the user or group is authorized. Before this function is called, an authorization function such as basic-auth must be called in an AuthTrans directive.

If a user was authorized in an AuthTrans directive and the auth-user parameter is provided, then the user’s name must match the auth-user wildcard value. Also, if the auth-group parameter is provided, the authorized user must belong to an authorized group, which must match the auth-user wildcard value.

Parameters

The following table describes parameters for the require-auth function.

Example

PathCheck fn=require-auth auth-type=basic realm="Marketing Plans" 
	auth-group=mktg auth-user=(jdoe|johnd|janed)

See Also

basic-auth, basic-ncsa

require-proxy-auth

Applicable in PathCheck-class directives.

The require-proxy-auth function is a PathCheck function that makes sure that users are authenticated and triggers a password pop-up window.

Syntax

PathCheck fn=require-proxy-auth auth-type=basic  realm=name 
auth-group=group    auth-users=name

Parameters

The following table describes parameters for the require-proxy-auth function.

Example

PathCheck fn=require-auth   auth-type=basic  realm="Marketing Plans"  
	auth-group=mktg  auth-users=(jdoe|johnd|janed)

set-variable

See set-variable.

set-virtual-index

Applicable in PathCheck-class directives.

The set-virtual-index function specifies a virtual index for a directory, which determines the URL forwarding. The index can refer to a LiveWire application, a servlet in its own namespace, a Sun ONE Application Server applogic, and so on.

REQ_NOACTION is returned if none of the URIs listed in the from parameter match the current URI. REQ_ABORTED is returned if the file specified by the virtual-index parameter is missing, or if the current URI cannot be found. REQ_RESTART is returned if the current URI matches any one of the URIs mentioned in the from parameter, or if no from parameter is specified.

Parameters

The following table describes parameters for the set-virtual-index function.

Example

# MyLWApp is a LiveWire applicationPathCheck fn=set-virtual-index 
	virtual-index=MyLWApp

ssl-check

Applicable in PathCheck-class directives.

If a restriction is selected that is not consistent with the current cipher settings under Security Preferences, this function displays a warning that ciphers with larger secret key sizes need to be enabled. This function is designed to be used together with a Client tag to limit access of certain directories to nonexportable browsers.

The function returns REQ_NOACTION if SSL is not enabled, or if the secret-keysize parameter is not specified. If the secret key size for the current session is less than the specified secret-keysize and the bong-file parameter is not specified, the function returns REQ_ABORTED with a status of PROTOCOL_FORBIDDEN. If the bong-file is specified, the function returns REQ_PROCEED, and the path variable is set to the bong file name. Also, when a key size restriction is not met, the SSL session cache entry for the current session is invalidated so that a full SSL handshake will occur the next time the same client connects to the server.

Requests that use ssl-check are not cacheable in the accelerator file cache if ssl-check returns a value other than REQ_NOACTION.

Parameters

The following table describes parameters for the ssl-check function.

ssl-logout

Applicable in PathCheck-class directives.

The ssl-logout function invalidates the current SSL session in the server’s SSL session cache. This function does not affect the current request, but the next time the client connects, a new SSL session will be created. If SSL is enabled, this function returns REQ_PROCEED after invalidating the session cache entry. If SSL is not enabled, the function returns REQ_NOACTION.

Parameters

The following table describes the parameter for the ssl-logout function.

unix-uri-clean

Applicable in PathCheck-class directives.

UNIX Only. The unix-uri-clean function denies access to any resource whose physical path contains /./, /../ or //, which are potential security problems.

Parameters

The following table describes the parameter for the unix-uri-clean function.

Example

PathCheck fn=unix-uri-clean

See Also

nt-uri-clean

url-check

Applicable in PathCheck-class directives.

The url-check function checks the validity of URL syntax.

url-filter

Applicable in PathCheck-class directives.

The url-filter can be used to allow or deny URL patterns. You can use either regular expressions of URL patterns or names of filter files of URLs as values for allow and deny parameters. The value names here refers to parameter names that were associated with filter files of URLs through init-url-filter SAF.

Parameters

The following table describes the parameter for the url-filter function.

Example

PathCheck fn="url-filter" allow="filt1" deny=".*://.*.iplanet.com/.*"

user-agent-check

Applicable in PathCheck-class directives.

The user-agent-check can be used to restrict access to the proxy server based on the type and version of the client’s web browser. A regular expression to match the user-agent header sent from the client is passed as a parameter to this function.

Parameters

The following table describes the parameter for the user-agent-check function.

Example

PathCheck fn = "user-agent-check" ua="Mozilla/.*"

ObjectType

ObjectType directives determine the MIME type of the file to send to the client in response to a request. MIME attributes currently sent are type, encoding, and language. The MIME type is sent to the client as the value of the Content-Type header.

ObjectType directives also set the type parameter, which is used by Service directives to determine how to process the request according to what kind of content is being requested.

If an object contains more than one ObjectType directive, all of the directives are applied in the order they appear. If a directive sets an attribute and later directives try to set that attribute to another value , the first setting is used and the subsequent settings are ignored.

The obj.conf file has an ObjectType directive that calls the type-by-extension function. This function instructs the server to look in the MIME types file to deduce the content type from the extension of the requested resource.

The following ObjectType-class functions are described in detail in this section:

• block-auth-cert instructs the proxy server not to forward the client’s SSL/TLS certificate to remote servers.

• block-cache-info instructs the proxy server not to forward information about local cache hits to remote servers.

• block-cipher instructs the proxy server to forward the name of the client’s SSL/TLS cipher suite to remote servers.

• block-ip instructs the proxy server not to forward the client’s IP address to remote servers.

• block-issuer-dn instructs the proxy server not to forward the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers.

• block-keysize instructs the proxy server not to forward the size of the client’s SSL/TLS key to remote servers.

• block-proxy-auth instructs the proxy server not to forward the client’s proxy authentication credentials.

• block-secret-keysize instructs the proxy server not to forward the size of the client’s SSL/TLS secret key to remote servers.

• block-ssl-id instructs the proxy server not to forward the client’s SSL/TLS session ID to remote servers.

• block-user-dn instructs the proxy server not to forward the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers.

• cache-disable disables cache.

• cache-enable tells the proxy that an object is cacheable, based on specific criteria.

• cache-setting sets parameters used for cache control.

• force-type sets the Content-Type header for the response to a specific type.

• forward-auth-cert instructs the proxy server to forward the client’s SSL/TLS certificate to remote servers.

• forward-cache-info instructs the proxy server to forward information about local cache hits to remote servers.

• forward-cipher instructs the proxy server to forward the name of the client’s SSL/TLS cipher suite to remote servers.

• forward-ip instructs the proxy server to forward the client’s IP address to remote servers.

• forward-issuer-dn instructs the proxy server to forward the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers.

• forward-keysize instructs the proxy server to forward the size of the client’s SSL/TLS key to remote servers.

• forward-proxy-auth instructs the proxy server to forward the client’s proxy authentication credentials

• forward-secret-keysize instructs the proxy server to forward the size of the client’s SSL/TLS secret key to remote servers.

• forward-ssl-id instructs the proxy server to forward the client’s SSL/TLS session ID to remote servers.

• forward-user-dn instructs the proxy server to forward the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers.

• http-client-config configures the proxy server’s HTTP client.

• java-ip-check allows clients to query the proxy server for the IP address used to reroute a resource.

• match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Proxy Server based upon the results by setting values for specified variables.

• set-basic-auth sets the HTTP basic authentication credentials used by the proxy server when it sends an HTTP request.

• set-default-type enables you to define a default charset, content-encoding, and content-language for the response being sent back to the client.

• set-variable enables you to change server settings based upon conditional information in a request, and to manipulate variables in parameter blocks by using specific commands.

• shtml-hacktype requests that .htm and .html files are parsed for server-parsed HTML commands.

• ssl-client-config configures options used when the proxy server connects to a remote server using SSL/TLS.

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

• type-by-exp sets the Content-Type header for the response based on the requested path.

• type-by-extension sets the Content-Type header for the response based on the file’s extension and the MIME types database.

block-auth-cert

Applicable in ObjectType-class directives.

The block-auth-cert function instructs the proxy server not to forward the client’s SSL/TLS certificate to remote servers.

Parameters

None.

block-cache-info

Applicable in ObjectType-class directives.

The block-cache-info function instructs the proxy server not to forward information about local cache hits to remote servers.

Parameters

None.

block-cipher

Applicable in ObjectType-class directives.

The block-cipher function instructs the proxy server to forward the name of the client’s SSL/TLS cipher suite to remote servers.

Parameters

None.

block-ip

Applicable in ObjectType-class directives.

The block-ip function instructs the proxy server not to forward the client’s IP address to remote servers.

Parameters

None.

block-issuer-dn

Applicable in ObjectType-class directives.

The block-issuer-dn function instructs the proxy server not to forward the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers.

Parameter

None.

block-keysize

Applicable in ObjectType-class directives.

The block-keysize function instructs the proxy server not to forward the size of the client’s SSL/TLS key to remote servers.

Parameters

None.

block-proxy-auth

Applicable in ObjectType-class directives.

The block-proxy-auth function instructs the proxy server not to forward the client’s proxy authentication credentials, that is, the client’s Proxy-authorization HTTP request header, to remote servers.

Parameter

None.

block-secret-keysize

Applicable in ObjectType-class directives.

The block-secret-keysize function instructs the proxy server not to forward the size of the client’s SSL/TLS secret key to remote servers.

Parameters

None.

block-ssl-id

Applicable in ObjectType-class directives.

The block-ssl-id function instructs the proxy server not to forward the client’s SSL/TLS session ID to remote servers.

Parameters

None.

block-user-dn

Applicable in ObjectType-class directives.

The block-user-dn function instructs the proxy server not to forward the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers.

Parameters

None.

cache-disable

Applicable in ObjectType-class directives.

The cache-disable function disables cache. It replaces the cache-enable function when cache is disabled through the administration interface.

Syntax

ObjectType fn=cache-disable

Parameters

None.

cache-enable

Applicable in ObjectType-class directives.

The cache_enable function tells the proxy that an object is cacheable, based on specific criteria. As an example, if the function appears in the object <Object ppath="http://.*">, then all the HTTP documents are considered cacheable, as long as other conditions for an object to be cacheable are met.

Syntax

ObjectType fn=cache-enable
     cache-auth=0|1
     query-maxlen=number
     min-size=number
     max-size=number    log-report=feature
     cache-local=0|1

Parameters

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

Example

The following example of cache-enable allows you to enable caching of objects matching the current resource. This function applies to normal, non-query, non-authenticated documents of any size. The proxy requires that the document carries either last-modified or expires headers or both, and that the content-type reported by the origin server is accurate.

ObjectType fn=cache-enable

The example below is like the first example, but it also caches documents that require user authentication, and it caches queries up to five characters long. The cache-auth=1 indicates that an up-to-date check is always required for documents that need user authentication. This function forces authentication again.

ObjectType fn=cache-enable
     cache-auth=1
     query-maxlen=5

The example below is also like the first example, except that it limits the size of cache files to a range of 2 Kbytes to 1 Mbytes.

ObjectType fn=cache-enable
     min-size=2
     max-size=1000

cache-setting

Applicable in ObjectType-class directives.

cache-setting is an ObjectType function that sets parameters used for cache control.

This function is used to explicitly cache or not cache a resource, create an object for that resource, and set the caching parameters for the object.

Syntax

ObjectType fn=cache-setting
     max-uncheck=seconds
     lm-factor=factor    connect-mode=always|fast-demo|never
     cover-errors=number

Parameters

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

Example

<Object ppath="http://.*">
ObjectType fn=cache-enable
ObjectType fn=cache-setting max-uncheck="7200"
ObjectType fn=cache-setting lm-factor="0.020"
ObjectType fn=cache-setting connect-mode="fast-demo"
ObjectType fn=cache-setting cover-errors="3600"
Service fn=proxy-retrieve
</Object>

# Force check every time
ObjectType fn=cache-setting max-uncheck=0
# Check every 30 minutes, or sooner if changed less than
# 6 hours ago (factor 0.1; last change 1 hour ago would
# give 6-minute maximum check interval).
ObjectType fn=cache-setting max-uncheck=1800 lm-factor=0.1

force-type

Applicable in ObjectType-class directives.

The force-type function assigns a type to requests that do not already have a MIME type. This function is used to specify a default object type.

Make sure that the directive that calls this function comes last in the list of ObjectType directives, so that all other ObjectType directives have a chance to set the MIME type first. If an object contains more than one ObjectType directive all of the directives are applied in the order they appear. If a directive sets an attribute and later directives try to set that attribute to a different value, the first setting is used and the subsequent settings are ignored.

Parameters

The following table describes the parameter for the force-type function.

Example

ObjectType fn=force-type type=text/plain
ObjectType fn=force-type lang=en_US

See Also

type-by-extension, type-by-exp

forward-auth-cert

Applicable in ObjectType-class directives.

The forward-auth-cert function instructs the proxy server to forward the client’s SSL/TLS certificate to remote servers.

Parameters

The following table describes the parameter for the forward-auth-cert function.

forward-cache-info

Applicable in ObjectType-class directives.

The forward-cache-info function instructs the proxy server to forward information about local cache hits to remote servers.

Parameter

The following table describes the parameter for the forward-cache-info function.

forward-cipher

Applicable in ObjectType-class directives.

The forward-cipher function instructs the proxy server to forward the name of the client’s SSL/TLS cipher suite to remote servers.

Parameters

The following table describes the parameter for the forward-cipher function.

forward-ip

Applicable in ObjectType-class directives.

The forward-ip function instructs the proxy server to forward the client’s IP address to remote servers.

Parameters

The following table describes the parameter for the forward-ip function.

forward-issuer-dn

Applicable in ObjectType-class directives.

The forward-issuer-dn function instructs the proxy server to forward the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers.

Parameters

The following table describes the parameter for the forward-issuer-dn function.

forward-keysize

Applicable in ObjectType-class directives.

The forward-keysize function instructs the proxy server to forward the size of the client’s SSL/TLS key to remote servers.

Parameters

The following table describes the parameter for the forward-keysize function.

forward-proxy-auth

Applicable in ObjectType-class directives.

The forward-proxy-auth instructs the proxy server to forward the client’s proxy authentication credentials, that is, the client’s Proxy-authorization HTTP request header, to remote servers.

Parameters

None.

forward-secret-keysize

Applicable in ObjectType-class directives.

The forward-secret-keysize function instructs the proxy server to forward the size of the client’s SSL/TLS secret key to remote servers.

Parameters

The following table describes the parameter for the forward-secret-keysize function.

forward-ssl-id

Applicable in ObjectType-class directives.

The forward-ssl-id function instructs the proxy server to forward the client’s SSL/TLS session ID to remote servers.

Parameter

The following table describes the parameter for the forward-ssl-id function.

forward-user-dn

Applicable in ObjectType-class directives.

The forward-user-dn function instructs the proxy server to forward the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers.

Parameters

The following table describes the parameter for the forward-user-dn function.

http-client-config

Applicable in ObjectType-class directives.

The http-client-config function configures the proxy server’s HTTP client.

Parameters

The following table describes the parameter for the http-client-config function.

java-ip-check

Applicable in ObjectType-class directives.

The java-ip-check function enables clients to query the proxy server for the IP address used to reroute a resource. Because DNS spoofing often occurs with Java applets, this feature enables clients to see the true IP address of the origin server. When this feature is enabled, the proxy server attaches a header containing the IP address that was used for connecting to the destination origin server.

Syntax

ObjectType fn=java-ip-check
    status=on|off

Parameters

The following table describes the parameter for the java-ip-check function.

match-browser

See match-browser.

set-basic-auth

Applicable in ObjectType-class directives.

The set-basic-auth function sets the HTTP basic authentication credentials used by the proxy server when it sends an HTTP request. set-basic-auth can be used to authenticate to a remote origin server or proxy server.

Parameters

The following table describes the parameter for the set-basic-auth function.