Sun Java System Web Server 7.0 Update 5 Administrator's Configuration File Reference

Chapter 7 Predefined SAFs and Filters in obj.conf

This chapter describes the predefined Server Application Functions (SAFs) and filters that are used in the obj.conf file. For details about the syntax and use of the obj.conf file, see Chapter 6, Syntax and Use of obj.conf.

Each SAF has its own parameters which are passed to it by an obj.conf directive. SAFs may examine, modify, or create server variables. Each SAF returns a result code that indicates whether it succeeded, did nothing, or failed.

The SAFs in this chapter are grouped by the type of directive that calls them. For an alphabetical list of predefined SAFs and server configuration elements, see Appendix G, Alphabetical List of Server Configuration Elements and Predefined SAFs.

This chapter contains the following sections:

The bucket Parameter

The bucket parameter is common to all SAFs. 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". The bucket statistics are displayed by the perfdump utility, which can be set up through the Admin Console, CLI, or through the service-dump SAF. For more information, see service-dump.

The following performance buckets are predefined:

For more information on performance buckets, see Using Performance Buckets in Sun Java System Web Server 7.0 Update 5 Performance Tuning, Sizing, and Scaling Guide.

AuthTrans

The Authtrans directive instructs the server to check for authorization before allowing a client to access resources. For more information, see AuthTrans.

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

In addition, the following common SAFs are valid for the AuthTrans directive:

basic-auth

The basic-auth function verifies the authorization information sent by the client. The Authorization header is sent as part of the basic server authorization scheme. This function is usually used with the PathCheck-class function require-auth.

Parameters

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

Table 7–1 basic-auth Parameters

Parameter 

Description 

auth-type

Specifies the type of authorization to be used. The values can be basic, digest, or ssl. The default value is basic.

userdb

(Optional) Specifies the full path and file name of the database to be used for user verification. This parameter will be passed to the user function. 

userfn

Name of the user custom function to verify authorization. This function must have been previously loaded with load-modules. It has the same interface as all of the SAFs, but it is called with the user name (user), password (pw), user database (userdb), and group database (groupdb), if supplied, in the pb parameter.

This function checks the name and password using the database and returns REQ_NOACTION if they are not valid. It returns REQ_PROCEED if the name and password are valid. The basic-auth function will then add auth-type, auth-user (user), auth-db (userdb), and auth-password (pw, Windows only) to the rq->vars pblock. For more information on custom functions, see Chapter 2, Creating Custom Server Application Functions, in Sun Java System Web Server 7.0 Update 5 NSAPI Developer’s Guide.

groupdb

(Optional) Specifies the full path and file name of the user database. This parameter will be passed to the group function. 

groupfn

(Optional) Name of the group custom function that must have been previously loaded with load-modules. It has the same interface as all of the SAFs, but it is called with the user name (user), password (pw), user database (userdb), and group database (groupdb) in the pb parameter.

This parameter also has access to the auth-type, auth-user (user), auth-db (userdb), and auth-password (pw, Windows only) parameters in the rq->vars pblock. The group function determines the group to which the user belongs using the group database, add it to rq->vars as auth-group, and return REQ_PROCEED if found. It returns REQ_NOACTION if the user’s group is not found.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

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_auth"
PathCheck fn="require-auth" auth-type="basic" realm="Marketing Plans"

See Also

require-auth

basic-ncsa

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 with the PathCheck-class function require-auth.

Parameters

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

Table 7–2 basic-ncsa Parameters

Parameter  

Description 

auth-type

Specifies the type of authorization to be used. The values can be basic, digest, or ssl. The default value is basic.

dbm

(Optional) Specifies the full path and base file name of the user database in the native format of the server. The native format is a system DBM file, which is a hashed file format allowing instantaneous access to billions of users. If you use this parameter, do not use the userfile parameter.

userfile

(Optional) Specifies the full path name of the user database in the NCSA-style HTTPD user file format. This format consists of lines using the format name:password, where password is encrypted. If you use this parameter, do not use dbm.

grpfile

(Optional) Specifies the NCSA-style HTTPD group file to be used. Each line of a group file consists of group:user1 user2 ... userN where each user name is separated by spaces.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

AuthTrans fn="basic-ncsa" auth-type="basic" dbm="/sun/server7/userdb/rs"
PathCheck fn="require-auth" auth-type="basic" realm="Marketing Plans"
AuthTrans fn="basic-ncsa" auth-type="basic" userfile="/sun/server7/.htpasswd" 
     grpfile="/sun/server7/.grpfile"
PathCheck fn="require-auth" auth-type="basic" realm="Marketing Plans"

See Also

require-auth

get-sslid

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.


Note –

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


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 parameter for the get-sslid function.

Table 7–3 get-sslid Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

qos-handler

The qos-handler function examines the current quality of service (QOS) statistics for a virtual server, logs the statistics, and enforces the QOS parameters by returning an error. This function must be the first AuthTrans function configured in the default object.

Parameters

The following table describes parameter for the qos-handler function.

Table 7–4 qos-handler Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

AuthTrans fn="qos-handler"

See Also

qos-error

NameTrans

The NameTrans directive translates virtual URLs to physical directories on your server. The NameTrans directive must appear in the default object. For more information, see NameTrans.

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

In addition, the following common SAFs are also valid for the NameTrans directive:

assign-name

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, if you have the following directive in the default object:

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

Assume that 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 parameters for the assign-name function.

Table 7–5 assign-name Parameters

Parameter 

Description  

from

(Optional) Wildcard pattern that specifies the path to be affected. If you do not specify the from parameter, all paths are affected.

name

Specifies an additional named object in obj.conf whose directives will be applied to this request.

find-pathinfo-forward

(Optional) Instructs the server to look for the PATHINFO forward in the path right after the ntrans-base, instead of backward from the end of path as the server function assign-name does by default.

The find-pathinfo-forward parameter is ignored if the ntrans-base parameter is not set in rq->vars. By default, ntrans-base is set.

This feature can improve performance for certain URLs by reducing the number of statistics performed. 

nostat

(Optional) Prevents the server from performing a stat on a specified URL. 

The effect of nostat="virtual-path" in the NameTrans function assign-name is that the server assumes that a stat on the specified virtual-path will fail. Therefore, use nostat only when the path of the virtual-path does not exist on the system. For example, use nostat for NSAPI plug-in URLs to improve performance by avoiding unnecessary stats on those URLs.

When the default PathCheck server functions are used, the server does not stat for the paths /ntrans-base/virtual-path and /ntrans-base/virtual-path/* if ntrans-base is set (the default condition). It does not stat for the URLs /virtual-path and /virtual-path/* if ntrans-base is not set.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

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

The document-root function specifies the root document directory for the server. If the physical path is not 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/webserver7/https-server/docs, 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/webserver7/https-server/docs/a/b/file.html.

You can also specify a document root in the virtual-server element of server.xml. For more information, see virtual-server.

This function always returns REQ_PROCEED.

NameTrans directives listed after this directive will never be called. Ensure that the directive that invokes document-root is the last NameTrans directive.

There can be only one root document directory. To specify additional document directories, use the pfx2dir function.

Parameters

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

Table 7–6 document-root Parameters

Parameter 

Description 

root

File system path to the server’s root document directory. 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

NameTrans fn="document-root" root="/usr/sun/webserver7/https-server/docs"

NameTrans fn="document-root" root="$docroot"

See Also

pfx2dir

home-page

The home-page function specifies the home page for your server.

Parameters

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

Table 7–7 home-page Parameters

Parameter 

Description 

path

Path and name of the home page file. If path starts with a slash (/), it is assumed to be the full path to a file.

If path is a relative path, this function sets the server’s path variable and returns REQ_PROCEED.

If path is a relative path, it is appended to the URI, and the function returns REQ_NOACTION. It then continues on to the other NameTrans directives.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

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

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

map

The map function maps a request URI to a URL on another server, allowing you to specify that a request should be serviced by another server. To load balance a given URI across multiple servers, use the map function in conjunction with the set-origin-server function. The map function looks for a certain prefix in the URI that the client is requesting. If map finds the prefix, it replaces the prefix with the mirror site prefix.

Parameters

The following table describes parameters for the map function.

Table 7–8 map Parameters

Parameter 

Description 

from

The URI prefix to map. The prefix should not contain trailing slashes.  

to

The URL prefix to which the request should be mapped. The prefix should not contain trailing slashes. 

name

(Optional) Specifies an additional named object in obj.conf. The directives of the named object will be applied to this request.

rewrite-host

(Optional) Indicates whether the Host HTTP request header is rewritten to match the host specified by the to parameter. In a reverse proxy configuration where the proxy server and origin server service the same set of virtual servers, you can specify rewrite-host="false". The default is true, indicating that the Host HTTP request header is rewritten.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

# Map everything under /docs to http://docs.sun.com/app/docs
NameTrans fn="map" from="/docs" to="http://docs.sun.com/app/docs"

See Also

set-origin-server

ntrans-dav

The ntrans-dav function determines whether a request should be handled by the WebDAV subsystem. If the request should be handled by the WebDAV subsystem, the function adds a dav object to the pipeline.

Parameters

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

Table 7–9 ntrans-dav Parameters

Parameter 

Description 

name

Specifies an additional named object in obj.conf whose directives will be applied to this request.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

NameTrans fn="ntrans-dav" name="dav"

See Also

ntrans-j2ee

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.

Table 7–10 ntrans-j2ee Parameters

Parameter 

Description 

name

Named object in obj.conf whose directives are applied to requests made to Java web applications.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

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

See Also

pfx2dir

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

Parameters

The following table describes parameters for the pfx2dir function.

Table 7–11 pfx2dir Parameters

Parameter  

Description 

from

URI prefix to convert. It should not have a trailing slash (/). 

dir

Local file system directory path to which the prefix is converted. It should not have a trailing slash (/). 

name

(Optional) Specifies an additional named object in obj.conf whose directives will be applied to this request.

find-pathinfo-forward

(Optional) Instructs the to server look for the PATHINFO forward in the path after ntrans-base, instead of backward from the end of path as the server function find-pathinfo does by default.

The find-pathinfo-forward parameter is ignored if the ntrans-base parameter is not set in rq->vars when the server function find-pathinfo is called. By default, ntrans-base is set.

This feature can improve performance for certain URLs by reducing the number of stats performed in the server function find-pathinfo.

On Windows, you can use this feature to exclude the PATHINFO from the server URL normalization process (by changing `\' to `/') when the PathCheck server function find-pathinfo is used. Some double-byte characters have hexadecimal values that might be parsed as URL separator characters such as `\' or ~. Using the find-pathinfo-forward parameter can sometimes prevent incorrect parsing of URLs containing double-byte characters.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

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"

See Also

reverse-map

The reverse-map function rewrites the HTTP response headers when the 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.

Table 7–12 reverse-map Parameters

Parameter  

Description  

from

URL prefix to be rewritten. 

to

URL prefix that will be substituted in place of the from prefix.

rewrite-location

(Optional) Indicates whether the location HTTP response header should be rewritten. The default is true, indicating that the location header is rewritten.

rewrite-content-location

(Optional) Indicates whether the Content-Location HTTP response header should be rewritten. The default is true, indicating that the Content-Location header is rewritten.

rewrite-headername

(Optional) Indicates whether the headername HTTP response header should be rewritten, where headername is a user-defined header name. With the exception of the Location and Content-Location headers, the default is false, indicating that the headername header is not rewritten.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

NameTrans fn="reverse-map" from="http://docs.sun.com/app/docs" to="/docs"

See Also

map

rewrite

The rewrite function allows flexible mappings between URIs and file system paths.

Parameters

The following table describes parameters for the rewrite function.

Table 7–13 rewrite Parameters

Parameter 

Description 

from

(Optional) Wildcard pattern that specifies the path of requests that should be rewritten. The default is to match all paths. 

root

(Optional) File system path to the effective root document directory. 

name

(Optional) Name of an object in obj.conf whose directives will be applied to this request.

path

(Optional) Rewritten partial path. If non-empty, the path must begin with a slash (/). 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

The following obj.conf code maps requests for the URI /~user/index.html to the file system path /home/user/public_html/index.html:

<If $path =~ "^/~([^/]+)(|/.*)$">
NameTrans fn="rewrite"
          root="/home/$1/public_html"
          path="$2"
</If>

See Also

restart

strip-params

The strip-params function removes the 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 parameters for the strip-params function.

Table 7–14 strip-params Parameters

Parameter  

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

NameTrans fn="strip-params"

unix-home

(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 required 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 parameters for the unix-home function.

Table 7–15 unix-home Parameters

Parameter 

Description 

subdir

Subdirectory within the user’s home directory that contains the web documents of users. 

pwfile

(Optional) Full path and file name of the password file if it is different from /etc/passwd.

name

(Optional) Specifies an additional named object whose directives will be applied to this request. 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

NameTrans fn="unix-home" from="/~" subdir="public_html"

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

See Also

find-links

PathCheck

The PathCheck directive checks the local file system path that is returned after the NameTrans step to verify that the client is allowed to access the specified resource. For more information, see PathCheck.

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

In addition, the following common SAFs are valid for the PathCheck directive:

check-acl

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 ACL contains information about who is or is not 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. They perform user authentication if required by the specified ACL, and also update the access control state. Because the server caches the ACLs returned by the check-acl function, do not use check-acl inside a Client, If, ElseIf, or Else container.

Parameters

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

Table 7–16 check-acl Parameters

Parameter 

Description 

acl

Name of an access control list. 

path

(Optional) Wildcard pattern that specifies the path for which the ACL should be applied. 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

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

check-request-limits

The check-request-limits function monitors incoming requests matching a given attribute (for example, client IP address) and computes an average requests per second on a configurable time interval. When requests that match the monitored attribute exceed a threshold that you configure, subsequent matching requests are not serviced until the request rate drops. Use this function to detect possible denial-of-service attacks.

You must specify either max-rps or max-connections, otherwise check-request-limits does nothing. If you do not enter an attribute or attributes to monitor, the function monitors all requests.

By default, the function keeps entries on requests for 300 seconds (five minutes) before purging them. To adjust this time, use the init-request-limits SAF in magnus.conf. For more information, see init-request-limits.

Parameters

The following table describes parameters for the check-request-limits function.

Table 7–17 check-request-limits Parameters

Parameter 

Description 

max-rps

(Optional) Threshold for matching requests per second. If this threshold is exceeded subsequent connections matching the criteria are not serviced. Because an acceptable threshold value can vary widely between sites, there is no default value for this parameter.  

max-connections

(Optional) Maximum number of concurrent matching connections. If the server receives a request that matches the criteria while the number of matching requests currently being processed meets or exceeds this number, the request is denied.  

Note that this number is the current requests at any time, and is independent of the interval. parameter. As soon as the number of concurrent requests falls below this limit, new matching requests are processed.

Because an acceptable value can vary widely between sites, there is no default value for this parameter. 

interval

(Optional) In seconds, the time interval during which average requests per second is computed. The max-rps limit is not applied until the next request rate computation. Because potential attackers can have unlimited requests serviced during this interval, balance the length of this interval against the performance cost of recomputing the maximum requests per second. The default is 30 seconds.

continue

(Optional) Determines what condition must be met in order for a blocked request type to become available again for servicing.  

Valid values are:

  • silence – Refused requests must fall to zero in a subsequent interval for service to resume.

  • threshold – Refused requests must fall below the max-rps value for service to resume.

The default value is threshold.

error

(Optional) The HTTP status code to use for blocked requests. The default value is 503 (the Service Unavailable error).

monitor

(Optional) A request attribute to monitor. Request rates are tracked in a bucket named by the value of this parameter. If the monitor parameter is not specified, the matching requests are tracked in an unnamed (anonymous) bucket. Note that these buckets are different from the buckets you specify with the standard obj.conf bucket parameter.

Although the value of the monitor parameter can be a fixed string, it is most useful when you use predefined variables, for example, monitor="$ip". You can also specify multiple variables, separated by a colon. For example, monitor="$ip:$uri". For a list of predefined variables, see Predefined Variables.

 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

The following example limits a client IP to a maximum request rate of 10 requests per second in the default interval of 30 seconds:

PathCheck fn="check-request-limit" monitor="$ip" max-rps="10"

The following example limits a client IP to a maximum request rate of 10 requests per second when accessing any Perl CGIs. Other types of requests are unlimited:

<If path = "*.pl">
PathCheck fn="check-request-limits" monitor="$ip" max-rps="10"
</If>

For more information on using the If tag, see If, ElseIf, and Else.

The following example limits requests globally for Perl CGIs to 10 requests per second. No specific monitor parameter is specified:

<If path = "*.pl">
PathCheck fn="check-request-limits" max-rps="10"
</If>

The following example limits a client IP from generating more than 10 Perl CGI requests per second, or 5 JSP requests per second. To track the Perl and JSP totals separately, the specified monitor parameters contain both a fixed string identifier and the client IP variable:

<If path = "*.pl">
PathCheck fn="check-request-limits" max-rps="10" monitor="perl:$ip"
</If>
<If path = "*.jsp">
PathCheck fn="check-request-limits" max-rps="5" monitor="jsp:$ip"
</If>

The following example limits any one client IP to no more than 5 connections at a given time:

PathCheck fn="check-request-limits" max-connections="2" monitor="$ip"

deny-existence

The deny-existence function sends a 404 Not Found message when a client tries to access a specified path.

Parameters

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

Table 7–18 deny-existence Parameters

Parameter 

Description 

path

(Optional) Wildcard pattern of the file system path to hide. If the path does not match, the function does nothing and returns REQ_NOACTION. If the path is not provided, it is assumed to match.

bong-file

(Optional) Specifies a file to send rather than responding with the 404 Not Found message. The value is a full file system path.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

PathCheck fn="deny-existence" path="/usr/sun/server7/docs/private"

PathCheck fn="deny-existence" bong-file="/svr/msg/go-away.html"

find-compressed

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:

Parameters

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

Table 7–19 find-compressed Parameters

Parameter 

Description 

check-age

(Optional) Specifies whether to check if the compressed version is older than the non-compressed version. The values can be yes or no.

  • If set to yes, the compressed version will not be selected if it is older than the non-compressed version.

  • If set to no, the compressed version is always selected, even if it is older than the non-compressed version.

By default, the value is set to yes.

vary

(Optional) Specifies whether to insert a Vary: Accept-Encoding header. The values can be yes or no.

  • If set to yes, a Vary: Accept-Encoding header is always inserted when a compressed version of a file is selected.

  • If set to no, a Vary: Accept-Encoding header is never inserted.

By default, the value is set to yes.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

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

The find-index function investigates whether the requested path is a directory. If yes, the function searches for an index file in the directory, and then changes the path to point to the index file. If an index file is not found, the server generates a directory listing. If the obj.conf file has a NameTrans directive that calls home-page and the requested directory is the root directory, the server returns the home page to the client instead of the index page.

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.

Table 7–20 find-index Parameters

Parameter  

Description  

index-names

Comma-separated list of index file names to look for. Use spaces only if they are part of a file name. Do not include spaces before or after the commas. This list is case-sensitive if the file system is case-sensitive. 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

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

See Also

find-index-j2ee

The find-index-j2ee function implements welcome-file-list processing for requests that map to directories in a Java web application. When configuring the server to host Servlet or JSP-technology-based web applications, position the find-index-j2ee SAF above the find-index SAF in obj.conf. This position ensures that web.xml welcome-file-list ordering takes precedence over the default index file order configured for the find-index SAF.

Parameters

The following table describes parameter for the find-index-j2ee function.

Table 7–21 find-index-j2ee Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

PathCheck fn="find-index-j2ee"

See Also

find-links

(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). It prevents someone from pointing to information that should not be made public.

Parameters

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

Table 7–22 find-links Parameters

Parameter 

Description 

disable

Character string of links to disable: 

  • h indicates hard link

  • s indicates soft link

  • o allows symbolic links only if the target of the link is owned by the user that the server runs as

dir

(Optional) Directory to begin checking. If you specify an absolute path, any request to that path and its subdirectories is checked for symbolic links. If you specify a partial path, any request containing that partial path is checked for symbolic links. For example, if you use /user/ and a request comes in for some/user/directory, then that directory is checked for symbolic links. If you do not specify a dir, all directories are checked.

checkFileExistence

(Optional) Checks linked file for existence and aborts the request with the 403 Forbidden error if the check fails. Controls whether the server checks if the target of the link exists. If set to Y, the server aborts the request with a 403 Forbidden error if the target of a link does not exist. The default is N, meaning the server does not check whether the target exists.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

PathCheck fn="find-links" disable="sh" dir="/foreign-dir"

PathCheck fn="find-links" disable="so" dir="public_html"

See Also

unix-home

find-pathinfo

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.

Table 7–23 find-pathinfo Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

PathCheck fn="find-pathinfo"

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

get-client-cert

The get-client-cert function gets the authenticated client certificate from the SSL3 session. It can apply to all HTTP methods, or only to those that match a specified pattern. It 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 and allows the request to proceed. Otherwise, it returns REQ_ABORTED and sets the protocol status to 403 forbidden, causing the request to fail.

Parameters

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

Table 7–24 get-client-cert Parameters

Parameter 

Description 

dorequest

(Optional) Controls whether to actually get the certificate, or just test for its presence. 

  • 1 tells the function to redo the SSL3 handshake to get a client certificate, if the server does not already have the client certificate. This typically causes the client to present a dialog box to the user to select a client certificate. The server might already have the client certificate if it was requested on the initial handshake, or if a cached SSL session has been resumed.

  • 0 tells the function not to redo the SSL3 handshake if the server does not already have the client certificate.

    If a certificate is obtained from the client and verified successfully by the server, the ASCII base 64 encoding of the DER-encoded X.509 certificate is placed in the parameter auth-cert in the Request->vars pblock, and the function returns REQ_PROCEED, allowing the request to proceed.

The default value is 0.

require

(Optional) Controls whether failure to get a client certificate will abort the HTTP request. 

  • 1 tells the function to abort the HTTP request if the client certificate is not present after dorequest is handled. In this case, the HTTP status is set to PROTOCOL_FORBIDDEN, and the function returns REQ_ABORTED.

  • 0 tells the function to return REQ_NOACTION if the client certificate is not present after dorequest is handled.

The default value is 1.

method

(Optional) Specifies a wildcard pattern for the HTTP methods for which the function will be applied. If method is absent, the function is applied to all requests.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

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"

nt-uri-clean

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

Table 7–25 nt-uri-clean Parameters

Parameter 

Description 

tildeok

(Optional) If present, allows tilde (~) characters in URIs. This is a potential security risk on the Windows platform, where longfi~1.htm might reference longfilename.htm but does not go through the proper ACL checking. If present, “//” sequences are allowed.

dotdirok

(Optional) If present, /./ sequences are allowed.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

PathCheck fn="nt-uri-clean"

See Also

unix-uri-clean

ntcgicheck

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

Table 7–26 ntcgicheck Parameters

Parameter  

Description  

extension

The replacement file extension. 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

PathCheck fn="ntcgicheck" extension="pl"

See Also

pcheck-dav

The pcheck-dav function inserts a DAV-specific service function as the first service function, if the following are true:

During the Service stage, this inserted service function restarts the request if necessary; otherwise, REQ_NOACTION is returned.

Parameters

The following table describes parameters for the pcheck-dav function.

Table 7–27 pcheck-dav Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

require-auth

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 the AuthTrans directive.

If a user is authorized in the AuthTrans directive and the auth-user parameter is provided, the name of the user must match with 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.

Table 7–28 require-auth Parameters

Parameter  

Description  

path

(Optional) Wildcard local file system path on which this function should operate. If no path is provided, the function applies to all paths. 

auth-type

Type of HTTP authorization used. Currently, basic is the only authorization type defined.

realm

String sent to the browser indicating the secure area (or realm) for which user name and password are requested. 

auth-user

(Optional) Specifies a wildcard list of users who are allowed access. If this parameter is not provided, any user authorized by the authorization function is given access. 

auth-group

(Optional) Specifies a wildcard list of groups that are allowed access. 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

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

See Also

set-virtual-index

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 Java System Application Server, 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 is not found. REQ_RESTART is returned if the current URI matches any one of the URIs mentioned in the from parameter, or if the from parameter is not specified.

Parameters

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

Table 7–29 set-virtual-index Parameters

Parameter  

Description  

virtual-index

URI of the content generator that acts as an index for the URI that the user enters. 

from

(Optional) Comma-separated list of URIs for which this virtual-index is applicable. If from is not specified, the virtual-index always applies.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

# MyLWApp is a LiveWire application
PathCheck fn="set-virtual-index" virtual-index="MyLWApp"

ssl-check

The ssl-check function is used along with a Client tag to limit access of certain directories to non-exportable browsers. If a restriction is selected that is not consistent with the current cipher settings, this function displays a warning that ciphers with larger secret keysizes must be enabled.

The function returns REQ_NOACTION if SSL is not enabled, or if the secret-keysize parameter is not specified. If the secret keysize 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 keysize 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 something other than REQ_NOACTION.

Parameters

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

Table 7–30 ssl-check Parameters

Parameter  

Description  

secret-keysize

(Optional) Minimum number of bits required in the secret key. 

bong-file

(Optional) Name of a file (not a URI) to be served if the restriction is not met. 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

ssl-logout

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

Parameters

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

Table 7–31 ssl-logout Parameter

Parameter  

Description  

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

unix-uri-clean

(UNIX only) The unix-uri-clean function denies access to any resource whose physical path contains /./ or /../ or // (these are potential security problems).

Parameters

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

Table 7–32 unix-uri-clean Parameters

Parameter  

Description  

dotdirok

If present, /./ sequences are allowed.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

PathCheck fn="unix-uri-clean"

See Also

nt-uri-clean

ObjectType

The ObjectType directives determine the MIME type of the file that has to be sent to the client in response to a request. For more information, see ObjectType.

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

In addition, the following common SAFs are valid for the ObjectType directive:

block-auth-cert

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

Parameters

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

Table 7–33 block-auth-cert Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-auth-cert"

See Also

forward-auth-cert

block-cache-info

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

Parameters

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

Table 7–34 block-cache-info Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-cache-info"

See Also

forward-cache-info

block-cipher

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

Parameters

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

Table 7–35 block-cipher Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-cipher"

See Also

forward-cipher

block-ip

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

Parameters

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

Table 7–36 block-ip Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-ip"

See Also

forward-ip

block-issuer-dn

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

Parameters

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

Table 7–37 block-issuer-dn Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-auth-cert"

See Also

forward-issuer-dn

block-jroute

The block-jroute function instructs the server not to forward information about request routing to remote servers using the proprietary Proxy-jroute format.

Parameters

The following table describes parameter for the block-jroute function.

Table 7–38 block-jroute Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-jroute"

See Also

forward-jroute

block-keysize

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

Parameters

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

Table 7–39 block-keysize Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-keysize"

See Also

forward-keysize

block-proxy-agent

The block-proxy-agent function instructs the server not to forward its version information to remote servers.

Parameters

The following table describes parameter for the block-proxy-agent function.

Table 7–40 block-proxy-agent Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-proxy-agent"

See Also

forward-proxy-agent

block-proxy-auth

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

Parameter

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

Table 7–41 block-proxy-auth Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-proxy-auth"

See Also

forward-proxy-auth

block-secret-keysize

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

Parameters

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

Table 7–42 block-secret-keysize Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-secret-keysize"

See Also

forward-secret-keysize

block-ssl-id

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

Parameters

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

Table 7–43 block-ssl-id Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-ssl-id"

See Also

forward-ssl-id

block-user-dn

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

Parameters

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

Table 7–44 block-user-dn Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-user-dn"

See Also

forward-user-dn

block-via

The block-via function instructs the server not to forward information about request routing to remote servers using the HTTP/1.1 Via format.

Parameters

The following table describes parameter for the block-via function.

Table 7–45 block-via Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="block-via"

See Also

forward-via

force-type

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.

Ensure 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. If a directive sets an attribute and later directives try to set that attribute to something else, the first setting is used and the subsequent settings are ignored.

Parameters

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

Table 7–46 force-type Parameters

Parameter  

Description  

type

(Optional) Type assigned to a matching request (the Content-Type header).

enc

(Optional) Encoding assigned to a matching request (the Content-Encoding header).

lang

(Optional) Language assigned to a matching request (the Content-Language header).

charset

(Optional) Character set for the magnus-charset parameter in rq->srvhdrs. If a browser sends the Accept-Charset header or its User-Agent is Mozilla/1.1 or newer, then append “; charset=charset” to Content-Type, where charset is the value of the magnus-charset parameter in rq->srvhdrs.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="force-type" type="text/plain"

ObjectType fn="force-type" lang="en_US"

See Also

forward-auth-cert

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

Parameters

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

Table 7–47 forward-auth-cert Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate the client’s DER-encoded SSL/TLS certificate in Base 64 encoding. The default value is Proxy-auth-cert.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

block-auth-cert

forward-cache-info

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

Parameter

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

Table 7–48 forward-cache-info Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate information about local cache hits. The default value is Cache-info.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

block-cache-info

forward-cipher

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

Parameters

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

Table 7–49 forward-cipher Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate the name of the client’s SSL/TLS cipher suite. The default value is Proxy-cipher.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

block-cipher

forward-ip

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

Parameters

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

Table 7–50 forward-ip Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate the client’s IP address. The default value is Client-ip.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

block-ip

forward-issuer-dn

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

Parameters

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

Table 7–51 forward-issuer-dn Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate the distinguished name of the issuer of the client’s SSL/TLS certificate. The default value is Proxy-issuer-dn.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

block-issuer-dn

forward-jroute

The forward-jroute function instructs the server to forward information about request routing using the proprietary Proxy-jroute format. The Proxy-jroute header field is used by the set-origin-server function and some Servlet containers to implement session stickiness.

Parameters

The following table describes parameters for the forward-jroute function.

Table 7–52 forward-jroute Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate the request routing information. The default value is Proxy-jrout.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

forward-keysize

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

Parameters

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

Table 7–53 forward-keysize Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate the size of the client’s SSL/TLS key. The default value is Proxy-keysize.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

block-keysize

forward-proxy-agent

The forward-proxy-agent function instructs the server to forward its version information to remote servers.

Parameters

The following table describes parameters for the forward-proxy-agent function.

Table 7–54 forward-proxy-agent Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate server version. The default value is Proxy-agent.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

forward-proxy-auth

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

Parameters

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

Table 7–55 forward-proxy-auth Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="forward-proxy-auth"

See Also

block-proxy-auth

forward-secret-keysize

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

Parameters

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

Table 7–56 forward-secret-keysize Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate the size of the client’s SSL/TLS secret key. The default value is Proxy-secret-keysize.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

block-secret-keysize

forward-ssl-id

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

Parameter

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

Table 7–57 forward-ssl-id Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate the client’s SSL/TLS session ID. The default value is Proxy-ssl-id.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

block-ssl-id

forward-user-dn

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

Parameters

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

Table 7–58 forward-user-dn Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate the distinguished name of the subject of the client’s SSL/TLS certificate. The default value is Proxy-user-dn.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

block-user-dn

forward-via

The forward-via function instructs the server to forward information about request routing to remote servers using the HTTP/1.1 Via format. The HTTP/1.1 Via header field records the proxy servers and protocol versions that were involved in routing a request.

Parameters

The following table describes parameters for the forward-via function.

Table 7–59 forward-via Parameters

Parameter  

Description  

hdr

(Optional) Name of the HTTP request header used to communicate routing information. The default value is Via.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

block-via

http-client-config

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

Parameters

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

Table 7–60 http-client-config Parameters

Parameter 

Description 

keep-alive

(Optional) Indicates whether the HTTP client should attempt to use persistent connections. The default value is true.

keep-alive-timeout

(Optional) The maximum number of seconds to keep a persistent connection open. The default value is 29.

always-use-keep-alive

(Optional) Indicates whether the HTTP client can reuse existing persistent connections for all types of requests. The default value is false indicating that persistent connections will not be reused for non-GET requests or for requests with a body.

protocol

(Optional) HTTP protocol version string. By default, the HTTP client uses either HTTP/1.0 or HTTP/1.1 based on the contents of the HTTP request. In general, you should not use the protocol parameter unless you encounter specific protocol interoperability problems.

proxy-agent

(Optional) Value of the proxy-agent HTTP request header. The default is a string that contains the web server product name and version.  

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="http-client-config" keep-alive="false"

set-basic-auth

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

Parameters

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

Table 7–61 set-basic-auth Parameters

Parameter 

Description 

user

Name of the user to authenticate. 

password

Password of the user to authenticate. 

hdr

(Optional) Name of the HTTP request header used to communicate the credentials. 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="set-basic-auth"
           user="admin"
           password="secret"
           hdr="proxy-authorization"

See Also

set-cache-control

The set-cache-control function allows you to specify the HTTP caching policy for the response being sent back to the client.

Parameters

The following table describes parameters for the set-cache-control function.

Table 7–62 set-cache-control Parameters

Parameter 

Description 

control

HTTP cache control directives. Separate multiple directives by commas. 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

The following table describes some of the useful cache control directives defined by the HTTP/1.1 protocol.

Table 7–63 Cache Control Directives

Directive 

Description 

public

The response may be cached by any cache. 

private

The response must not be cached by a shared cache (for example, a proxy server). 

no-cache

Clients must ask the server for updated content on each access. 

max-age=n

The response should not be cached for more than n seconds.

Example

ObjectType fn="set-cache-control" control="private,max-age=60"

set-cookie

The set-cookie function allows you to set a cookie in the response being sent back to the client.

Parameters

The following table describes parameters for the set-cookie function.

Table 7–64 set-cookie Parameters

Parameter 

Description 

name

Name of the cookie. 

value

(Optional) Value of the cookie. The default value is null.

path

(Optional) Base URI to which the cookie applies. The default value is / (slash).

domain

(Optional) The domain name of servers to which the cookie must be sent. If no domain is specified, web browsers send the cookie only to the server that sets the cookie. 

max-age

(Optional) Maximum time (in seconds) after which the cookie expires. If max-age is not specified, web browsers delete the cookie when the user closes the web browser.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

<If not defined $cookie{'FIRSTVISITTIME'}>
ObjectType fn="set-cookie"
           name="FIRSTVISITTIME"
           value="$time"
           max-age="31536000"
</If>

set-default-type

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

If the charset, content-encoding, and content-language are not set for a response, then just before the headers are sent the defaults defined by set-default-type are used. By placing this function in different objects in obj.conf, you can define different defaults for different parts of the document tree.

Parameters

The following table describes parameters for the set-default-type function.

Table 7–65 set-default-type Parameters

Parameter  

Description  

enc

(Optional) Encoding assigned to a matching request (the Content-Encoding header).

lang

(Optional) Language assigned to a matching request (the Content-Language header).

charset

(Optional) Character set for the magnus-charset parameter in rq->srvhdrs. If a browser sends the Accept-Charset header or its User-Agent is Mozilla/1.1 or newer, then append “; charset=charset” to Content-Type, where charset is the value of the magnus-charset parameter in rq->srvhdrs.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="set-default-type" charset="iso_8859-1"

shtml-hacktype

The shtml-hacktype function changes the Content-Type of any .htm or .html file to magnus-internal/parsed-html and returns REQ_PROCEED. This provides backward compatibility with server-side includes for files with .htm or .html extensions. The function may also check the execute bit for the file on UNIX systems. The use of this function is not recommended.

Parameters

The following table describes parameters for the shtml-hacktype function.

Table 7–66 shtml-hacktype Parameters

Parameter  

Description  

exec-hack

(Optional, UNIX only) Instructs the function to change the Content-Type only if the execute bit is enabled. The value of the parameter is not important, but the parameter should be provided. The value can be true.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="shtml-hacktyp"e exec-hack="true"

ssl-client-config

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

Parameter

The following table describes parameters for the ssl-client-config function.

Table 7–67 ssl-client-config Parameters

Parameter  

Description  

client-cert-nickname

(Optional) Nickname of the client certificate to present to the remote server. The default is not to present a client certificate. 

validate-server-cert

(Optional) Boolean that indicates whether the server validates the certificate presented by the remote server. The default value is true, indicating that remote servers must present valid certificates that were issued by a trusted certificate authority.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="ssl-client-config" validate-server-cert="false"

See Also

type-by-exp

The type-by-exp function matches the current path with a wildcard expression. If they match, the type parameter information is applied to the file. This is the same as type-by-extension, except that you use wildcard patterns for the files or directories specified in the URLs.

Parameters

The following table describes parameters for the type-by-exp function.

Table 7–68 type-by-exp Parameters

Parameter  

Description  

exp

Wildcard pattern of paths for which this function is applied. 

type

(Optional) Type assigned to a matching request (the Content-Type header).

enc

(Optional) Encoding assigned to a matching request (the Content-Encoding header).

lang

(Optional) Language assigned to a matching request (the Content-Language header).

charset

(Optional) The character set for the magnus-charset parameter in rq->srvhdrs. If a browser sends the Accept-Charset header or its User-Agent is Mozilla/1.1 or newer, then append “; charset=charset” to Content-Type, where charset is the value of the magnus-charset parameter in rq->srvhdrs.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="type-by-exp" exp="*.test" type="application/html"

See Also

type-by-extension

The type-by-extension function instructs the server to look in a table of MIME type mappings to find the MIME type of the requested resource. The MIME type is added to the Content-Type header that is sent back to the client.

The table of MIME type mappings is created by a mime-file element in the server.xml file, which loads a MIME types file or list and creates the mappings.

For example, the following two lines are part of a MIME types file:

type=text/html    exts=htm,html
type=text/plain    exts=txt

If the extension of the requested resource is htm or html, the type-by-extension file sets the type to text/html. If the extension is .txt, the function sets the type to text/plain.

Parameters

The following table describes parameters for the type-by-extension function.

Table 7–69 type-by-extension Parameters

Parameter  

Description  

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="type-by-extension"

See Also

type-j2ee

The type-j2ee function sets the Content-Type for requests that map to resources in a Java web application. When configuring the server to host Servlet or JSP-based web applications, type-j2ee must be the first ObjectType SAF in obj.conf. This is to ensure that web.xml MIME type mappings take precedence over the default MIME type mappings.

Parameters

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

Table 7–70 type-j2ee Parameter

Parameter 

Description 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

ObjectType fn="type-j2ee"

See Also

Input

The Input directives allow you to select filters that will process incoming request data read by the Service stage. For more information, see Input.

The following Input-class filter is described in detail in this section:

In addition, the following common SAFs are valid for the Input directive:

Every Input directive has the following optional parameters.

Table 7–71 Input Directive's Optional Parameters

Optional Parameters 

Description 

type

(Optional) Specifies a wildcard pattern of MIME types for which this function will be executed. 

method

(Optional) Specifies a wildcard pattern of HTTP methods for which this function will be executed. Common HTTP methods are GET, HEAD, and POST.

query

(Optional) Specifies a wildcard pattern of query strings for which this function will be executed. 

sed-request

The sed-request filter applies the sed edit commands to an incoming request entity body, for example, an uploaded file or submitted form.

Parameters

The following table shows the sed-request parameters:

Table 7–72 sed-request Parameters

Parameter 

Description 

sed

Specifies a sed command script. When multiple sed parameters are provided, the sed edit commands are evaluated in the order they appear.

Example

The following obj.conf code instructs sed-request to encode any (<) and (>) characters posted in an HTML form:

Input fn="insert-filter"
      method="POST"
      filter="sed-request"
      sed="s/</\\&lt;/g"
      sed="s/%3c/\\&lt;/g"
      sed="s/%3C/\\&lt;/g"
      sed="s/>/\\&gt;/g"
      sed="s/%3e/\\&gt;/g"
      sed="s/%3E/\\&gt;/g"

Because POST bodies are usually URL-encoded, it is important to check for URL-encoded forms when editing POST bodies. %3C is the URL-encoded form of (<) and %3E is the URI-encoded form of (>).

See Also

Output

The Output stage allows you to select filters that will process outgoing data. For more information, see Output.

Every Output directive has the following optional parameters:

Table 7–73 Output Directive's Optional Parameters

Optional Parameters 

Description 

type

(Optional) Specifies a wildcard pattern of MIME types for which this function will be executed. 

method

(Optional) Specifies a wildcard pattern of HTTP methods for which this function will be executed. Common HTTP methods are GET, HEAD, and POST.

query

(Optional) Specifies a wildcard pattern of query strings for which this function will be executed. 

The following Output-class filters are described in detail in this section:

In addition, the following common SAFs are valid for the Output directive:

compress-file

For dynamic compression of static files, compress-file SAF along with find-compressed SAF is used in Web Server 7.0 Update 5.

When a request is sent to the URI for the first time, the compress-file function creates a compressed file in the specified subdirectory, provided the file size is between min-size and max-size.

If check-age parameter is set to true, the compress-file function checks if the available compressed file version is as recent as the non-compressed file version. If not, it recreates a compressed file.

The find-compressed function checks if the compressed version of the requested file is available. It changes the path and directs to the compressed file under the following conditions:

The following table describes parameter for the compress-file filter.

Table 7–74 compress-file Parameter

Parameter 

Description 

subdir

(Optional) A directory name, relative to the directory in which the original non-compressed file is located. To overwrite a pre-compressed, compressed file lying in docroot, set the subdir to period (.). The default value is period (.), that is, current directory.

check-age

(Optional) Specifies whether to check if the compressed version is older than the non-compressed version. The values can be true or false. The default value is true.  

vary

(Optional) The values can be true or false. The default value is true.  

compression-level

(Optional) Controls the compression level used by the compression library. The values are from 1 to 9. A value of 1 results in the best speed. A value of 9 results in the best compression. The default value is 6.  

min-size

(Optional) The values are from 0 to INT_MAX. The default value is 256. 

max-size

Optional) The values are from min-size to INT_MAX. The default value is 1048576 

Example

<Objectname="default">
NameTrans fn="assign-name" from="*.html" name="find-compressed"
...
Service method=(GET|HEAD|POST) type=*~magnus-internal/* fn=compress-file
subdir=".compressed-files"
Service method=(GET|HEAD|POST) type=*~magnus-internal/* fn=send-file
...
</Object>

<Objectname="find-compressed">
PathCheck fn="find-compressed"
</Object>

See Also

http-compression

The http-compression filter compresses outgoing content. If the client does not support compression, or the outgoing content is already compressed, http-compression performs no action.

Unlike the find-compressed SAF, the http-compression filter can compress dynamic content such as the output from SHTML pages, CGI programs, or JSPs. However, for reasons of efficiency, the find-compressed SAF is better for static content such as non-parsed HTML files. For more information, see find-compressed.

Parameters

The following table describes parameter for the http-compression filter.

Table 7–75 http-compression Parameter

Parameter 

Description 

vary

Controls whether the filter inserts a Vary: Accept-encoding header. If vary is absent, the default value is yes. yes tells the filter to insert a Vary: Accept-encoding header when it compresses content. no tells the filter to never insert a Vary: Accept-encoding header.

fragment-size

Size in bytes of the memory fragment used by the compression library to control how much to compress at a time. The default value is 8096. 

compression-level

Controls the compression level used by the compression library. Valid values are from 1 to 9. A value of 1 results in the best speed. A value of 9 results in the best compression. The default value is 6. 

window-size

Controls an internal parameter of the compression library. Valid values are from 9 to 15. Higher values result in better compression at the expense of memory usage. The default value is 15. 

memory-level

Controls how much memory is used by the compression library. Valid values are from 1 to 9. A value of 1 uses the minimum amount of memory but is slow. A value of 9 uses the maximum amount of memory for optimal speed. The default value is 8. 

Example

Output fn="insert-filter"
          type="text/*"
          filter="http-compression"
          vary="on"
          compression-level="9"

In this example, type="text/*" restricts compression to documents that have a MIME type of text/* (for example, text/ascii, text/css, text/html, and so on).

Alternatively, you can specifically exclude browsers that do handle compressed content well by using the Client tag as follows:

<Client match="none"\
 browser="*MSIE [1-3]*"\
 browser="*MSIE [1-5]*Mac*"\
 browser="Mozilla/[1-4]*Nav*">
Output fn="insert-filter" filter="http-compression" type="text/*"
</Client>

This example restricts compression to browsers that are not any of the following:

Internet Explorer on Windows earlier than version 4 may request compressed data at times, but does not correctly support it. Internet Explorer on Macintosh earlier than version 6 does the same. Netscape Communicator version 4.x requests compression, but only correctly handles compressed HTML. It does not correctly handle linked CSS or JavaScriptTM from the compressed HTML, so administrators often simply prevent their servers from sending any compressed content to that browser (or earlier).

For more information about the Client tag, see Client.

sed-response

The sed-response filter applies sed edit commands to an outgoing response entity body, for example, an HTML file or output from a Servlet.

Parameter

The following table describes parameter for the sed-response filter

Table 7–76 sed-response Parameter

Parameter 

Description 

sed

Specifies a sed command script. When multiple sed parameters are provided, the sed edit commands are evaluated in the order they appear.

Example

The following obj.conf code instructs sed-response to rewrite any occurrence of http://127.0.0.1/ in an HTML response to http://server.example.com/:

Output fn="insert-filter"
       type="text/html"
       filter="sed-response"
       sed="s|http://127.0.0.1/|http://server.example.com/|g"

See Also

Route

The Route directive specifies information as to where the Web Server should route requests. For more information, see Route.

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

In addition, the following common SAFs are valid for the Route directive:

set-origin-server

The set-origin-server function distributes the load across a set of homogeneous HTTP origin servers.

Parameters

The following table describes parameters for the set-origin-server function.

Table 7–77 set-origin-server Parameters

Parameter 

Description 

server

URL of the origin server. If multiple server parameters are given, the server distributes the load among the specified origin servers. 

sticky-cookie

(Optional) Name of a cookie that, when present in a response, will cause subsequent requests to stick to that origin server. The default value is JSESSIONID.

sticky-param

(Optional) Name of a URI parameter to inspect for route information. When the URI parameter is present in a request URI and its value contains a colon (:) followed by a route ID, the request will stick to the origin server identified by that route ID. The default value is jsessionid.

route-hdr

(Optional) Name of the HTTP request header used to communicate route IDs to origin servers. set-origin-server associates each origin server named by a server parameter with a unique route ID. Origin servers may encode this route ID in the URI parameter named by the sticky-param parameter to cause subsequent requests to stick to them. The default value is Proxy-jroute.

route-cookie

(Optional) Name of the cookie generated by the server when it encounters a sticky-cookie in a response. The route-cookie parameter stores a route ID that enables the server to direct subsequent requests back to the same origin server. The default value is JROUTE.

rewrite-host

(Optional) Indicates whether the host HTTP request header is rewritten to match the host specified by the server parameter. The default value is false indicating that the host header is not rewritten.

rewrite-location

(Optional) Indicates whether the Location HTTP response header that matches the server parameter should be rewritten. The default value is true, indicating that the matching Location headers are rewritten.

rewrite-content-location

(Optional) Indicates whether the Content-Location HTTP response header that matches the server parameter should be rewritten. The default value is true, indicating that the matching Content-Location headers are rewritten.

rewrite-headername

(Optional) Indicates whether the headername HTTP response headers that match the server parameter should be rewritten, where headername is a user-defined header name. headername is in lowercase. With the exception of the Location and Content-Location headers, the default value is false, indicating that the headername header is not rewritten.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Route fn="set-origin-server"
      server="http://appserver1:8000"
      server="http://appserver2:8000"

See Also

set-proxy-server

The set-proxy-server function directs the server to retrieve the current resource from a particular proxy server.

Parameters

The following table describes parameters for the set-proxy-server function.

Table 7–78 set-proxy-server Parameters

Parameter 

Description 

server

URL of the remote proxy server. If multiple server parameters are given, the server distributes load among the specified remote servers.  

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Route fn="set-proxy-server"
      server="http://webcache1.eng.sun.com:8080"
      server="http://webcache2.eng.sun.com:8080"

See Also

set-origin-server

Service

The Service directives send the response data to the client. For more information, see Service.

Every Service directive has the following optional parameters to determine whether the function is executed. All optional parameters must match the current request for the function to be executed.

Table 7–79 Service Directive's Optional Parameters

Optional Parameters 

Description 

type

Specifies a wildcard pattern of MIME types for which this function will be executed. The magnus-internal/* MIME types are used only to select a Service function to execute.

method

Specifies a wildcard pattern of HTTP methods for which this function will be executed. Common HTTP methods are GET, HEAD, and POST.

query

Specifies a wildcard pattern of query strings for which this function will be executed. 

UseOutputStreamSize

Determines the default output stream buffer size (in bytes), for data sent to the client. If this parameter is not specified, the default is 8192 bytes.


Note –

Set this parameter to zero (0) to disable output stream buffering.


flushTimer

Determines the maximum number of milliseconds between write operations in which buffering is enabled. If the interval between subsequent write operations is greater than the flushTimer value for an application, further buffering is disabled. This is necessary for monitoring the status of CGI applications that run continuously and generate periodic status update reports. If this parameter is not specified, the default is 3000 milliseconds.

ChunkedRequestBufferSize

Determines the default buffer size, in bytes, for un-chunking request data. If this parameter is not specified, the default is 8192 bytes.

ChunkedRequestTimeout

Determines the default timeout, in seconds, for un-chunking request data. If this parameter is not specified, the default is 60 seconds.

If there is more than one Service-class function, the first one matching the optional wildcard parameters (type, method, and query) are executed.

The UseOutputStreamSize, ChunkedRequestBufferSize, and ChunkedRequestTimeout parameters also have equivalent magnus.conf directives. The obj.conf parameters override the magnus.conf directives.

By default, the server sends the requested file to the client by calling the send-file function. The directive that sets the default is:

Service method="(GET|HEAD)" type="*~magnus-internal/*" fn="send-file"

This directive usually comes last in the set of Service-class directives to give all other Service directives a chance to be invoked. This directive is invoked if the method of the request is GET, HEAD, or POST, and the type does not start with magnus-internal/. Note here that the pattern *~ means “does not match.” For a list of characters that can be used in patterns, see Appendix B, Using Wildcard Patterns.

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

In addition, the following common SAFs are valid for the Service directive:

add-footer

The add-footer function appends a footer to an HTML file that is sent to the client. The footer is specified either as a file name or a URI, thus the footer can be dynamically generated. To specify static text as a footer, use the append-trailer function.

Parameters

The following table describes parameters for the add-footer function.

Table 7–80 add-footer Parameters

Parameter 

Description 

file

(Optional) Path name to the file containing the footer. Specify either file or uri.

By default, the path name is relative. If the path name is absolute, set the NSIntAbsFilePath parameter to yes.

uri

(Optional) URI pointing to the resource containing the footer. The value can be file or uri.

NSIntAbsFilePath

(Optional) If the file parameter is specified, the NSIntAbsFilePath parameter determines whether the file name is absolute or relative. The default is relative. Set the value to yes to indicate an absolute file path.

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service type="text/html" method="GET" fn="add-footer" file="footers/footer1.html"

Service type="text/html" method="GET" fn="add-footer" 
     file="D:/sun/webserver7/https-server/footers/footer1.html" 
     NSIntAbsFilePath="yes"

See Also

add-header

The add-header function prepends a header to an HTML file that is sent to the client. The header is specified either as a file name or a URI and hence the header can be dynamically generated.

Parameters

The following table describes parameters for the add-header function.

Table 7–81 add-header Parameters

Parameter 

Description  

file

(Optional) Path name to the file containing the header. The value can be file or uri.

By default, the path name is relative. If the path name is absolute, set the NSIntAbsFilePath parameter as yes.

uri

(Optional) URI pointing to the resource containing the header. The value can be file or uri.

NSIntAbsFilePath

(Optional) If the file parameter is specified, the NSIntAbsFilePath parameter determines whether the file name is absolute or relative. The default is relative. Set the value to yes to indicate an absolute file path.

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service type="text/html" method="GET" fn="add-header" file="headers/header1.html"

Service type="text/html" method="GET" fn="add-footer" 
     file="D:/sun/webserver7/https-server/headers/header1.html" 
     NSIntAbsFilePath="yes"

See Also

append-trailer

The append-trailer function sends an HTML file and appends text to it. This is typically used for author information and copyright text. The date when the file was last modified can be inserted.

Returns

Returns REQ_ABORTED if a required parameter is missing, if there is extra path information after the file name in the URL, or if the file cannot be opened for read-only access.

Parameters

The following table describes parameters for the append-trailer function.

Table 7–82 append-trailer Parameters

Parameter  

Description  

trailer

Text to append to HTML documents. The string is unescaped with util_uri_unescape before being sent. The text can contain HTML tags, and can be up to 512 characters long after unescaping and inserting the date.

If you use the string :LASTMOD: which is replaced by the date the file was last modified, you must also specify a time format with timefmt.

timefmt

(Optional) Time format string for :LASTMOD:. If timefmt is not provided, :LASTMOD: will not be replaced with the time.

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service type="text/html" method="GET" fn="append-trailer" 
     trailer="<hr><img src=/logo.gif> Copyright 1999"

# Add a trailer with the date in the format: MM/DD/YY 
Service type="text/html" method="GET" fn="append-trailer" 
     timefmt="%D" trailer="<HR>File last updated on: :LASTMOD:"

See Also

delete-file

The delete-file function deletes a file when the client sends a request whose method is DELETE. It deletes the file indicated by the URL if the user is authorized and the server has the needed file system privileges.

When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes delete-file when the request method is DELETE.

Parameters

The following table describes parameters for the delete-file function.

Table 7–83 delete-file Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service method="DELETE" fn="delete-file"

imagemap

The imagemap function responds to requests for imagemaps. Imagemaps are images that are divided into multiple areas and each have an associated URL. The information about which URL is associated with which area is stored in a mapping file.

Parameters

The following table describes parameters for the imagemap function.

Table 7–84 imagemap Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service type="magnus-internal/imagemap" method="(GET|HEAD)" fn="imagemap"

index-common

The index-common function generates a fancy (or common) list of files in the requested directory. The list is sorted alphabetically. Files beginning with a period (.) are not displayed. Each item appears as an HTML link. This function displays more information than index-simple, including the size, last modified date, and an icon for each file. It may also include a header and readme file in the listing.

The Init-class function cindex-init in magnus.conf specifies the format for the index list, including where to look for the images. If obj.conf contains a call to index-common in the Service stage, magnus.conf must initialize fancy (or common) indexing by invoking cindex-init during the Init stage.

Indexing occurs when the requested resource is a directory that does not contain an index file or a home page, or no index file or home page has been specified by the functions find-index or home-page.

The icons displayed are .gif files dependent on the Content-Type of the file, as listed in the following table:

Table 7–85 Content-Type Icons

Content-Type  

Icon 

"text/*"

text.gif

"image/*"

image.gif

"audio/*"

sound.gif

"video/*"

movie.gif

"application/octet-stream"

binary.gif

Directory 

menu.gif

All others 

unknown.gif

Parameters

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

Table 7–86 index-common Parameters

Parameter  

Description  

header

(Optional) Path (relative to the directory being indexed) and name of a file (HTML or plain text) that is included at the beginning of the directory listing to introduce the contents of the directory. The file is first tried with .html added to the end. If found, it is incorporated near the top of the directory list as HTML. If the file is not found, it is tried without the .html and incorporated as pre-formatted plain text (bracketed by <PRE> and </PRE>).

readme

(Optional) Path (relative to the directory being indexed) and name of a file (HTML or plain text) to append to the directory listing. This file might give more information about the contents of the directory, indicate copyrights, authors, or other information. The file is first tried with .html added to the end. If found, it is incorporated at the bottom of the directory list as HTML. If the file is not found, it is tried without the .html and incorporated as pre-formatted plain text (enclosed within the PRE tag).

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service type="magnus-internal/directory" method="(GET|HEAD)" 
fn="index-common" header="hdr" readme="rdme.txt"

See Also

index-simple

The index-simple function generates a simple index of the files in the requested directory. It scans a directory and returns an HTML page to the browser displaying a list of the files and directories in the directory. The list is sorted alphabetically. Files beginning with a period (.) are not displayed. Each item appears as an HTML link.

Indexing occurs when the requested resource is a directory that does not contain either an index file or a home page, or no index file or home page has been specified by the functions find-index or home-page.

Parameters

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

Table 7–87 index-simple Parameters

Parameter 

Description 

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service type="magnus-internal/directory" fn="index-simple"

See Also

key-toosmall

The key-toosmall function returns a message to the client specifying that the secret key size for SSL communications is too small. This function is designed to be used together with a Client tag to limit access of certain directories to non-exportable browsers.


Note –

This function is provided for backward compatibility only and was deprecated in iPlanetTM Web Server 4.x. It is replaced by the PathCheck-class SAF ssl-check.


Parameters

The following table describes parameters for the key-toosmall function.

Table 7–88 key-toosmall Parameters

Parameter 

Description 

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

<Object ppath=/mydocs/secret/*>
Service fn="key-toosmall"
</Object>

See Also

ssl-check

list-dir

The list-dir function returns a sequence of text lines to the client in response to a request whose method is INDEX. The format of the returned lines is:

name type size mimetype

where:

When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that calls list-dir for requests whose method is INDEX.

Parameters

The following table describes parameters for the list-dir function.

Table 7–89 list-dir Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service method="INDEX" fn="list-dir"

make-dir

The make-dir function creates a directory when the client sends a request whose method is MKDIR. The function fails if the server can not write to that directory.

When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes make-dir when the request method is MKDIR.

Parameters

The following table describes parameters for the make-dir function.

Table 7–90 make-dir Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service method="MKDIR" fn="make-dir"

proxy-retrieve

The proxy-retrieve function retrieves a document from a remote server and returns it to the client. This function also enables you to configure the server to allow or block arbitrary methods. This function only works on the HTTP protocol.

Parameters

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

Table 7–91 proxy-retrieve Parameters

Parameter 

Description 

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

# Normal proxy retrieve
Service fn="proxy-retrieve"
# Proxy retrieve with POST method disabled
Service fn="proxy-retrieve"
     method="(POST)"

See Also

remove-dir

The remove-dir function removes a directory when the client sends a request whose method is RMDIR. The directory must be empty (have no files in it). The function will fail if the directory is not empty or if the server does not have the privileges to remove the directory.

When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes remove-dir when the request method is RMDIR.

Parameters

The following table describes parameters for the remove-dir function.

Table 7–92 remove-dir Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service fn="remove-dir" method="RMDIR"

rename-file

The rename-file function renames a file when the client sends a request with a New-URL header whose method is MOVE. It renames the file indicated by the URL to New-URL within the same directory if the user is authorized and the server has the required file system privileges.

When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes rename-file when the request method is MOVE.

Parameters

The following table describes parameters for the rename-file function.

Table 7–93 rename-file Parameters

Parameter 

Description 

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service fn="rename-file" method="MOVE"

send-cgi

The send-cgi function sets up the CGI environment variables, runs a file as a CGI program in a new process, and sends the results to the client.

There are three ways to change the timing used to flush the CGI buffer:

Parameters

The following table describes parameters for the send-cgi function.

Table 7–94 send-cgi Parameters

Parameter 

Description 

user

(UNIX only) Specifies the name of the user to execute CGI programs. 

group

(UNIX only) Specifies the name of the group to execute CGI programs. 

chroot

(UNIX only) Specifies the directory to chroot to before execution begins.

dir

(UNIX only) Specifies the directory to chdir to after chroot, but before execution begins.

rlimit_as

(UNIX only) Specifies the maximum CGI program address space (in bytes). You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, both the limits are set to this value. 

rlimit_core

(UNIX only) Specifies the maximum CGI program core file size. A value of 0 disables writing cores. You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, both the limits are set to this value.

rlimit_nofile

(UNIX only) Specifies the maximum number of file descriptors for the CGI program. You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, both the limits are set to this value. 

nice

(UNIX only) Accepts an increment that determines the CGI program's priority relative to the server. Typically, the server is run with a nice value of 0 and the nice increment would be from 0 (the CGI program runs at same priority as server) to 19 (the CGI program runs at much lower priority than server). Do not increase the priority of the CGI program above that of the server by specifying a nice increment of -1.

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

The following example uses variables defined in the server.xml file for the send-cgi parameters. For more information about defining variables, see Variables.

<Object name="default">
...
NameTrans fn="pfx2dir" from="/cgi-bin" dir="/home/foo.com/public_html/cgi-bin" name="cgi"
...
</Object>

<Object name="cgi">
ObjectType fn="force-type" type="magnus-internal/cgi" 
Service fn="send-cgi" user="$user" group="$group" dir="$dir" chroot="$chroot" nice="$nice"
</Object>

send-file

The send-file function sends the contents of the requested file to the client. It provides the Content-Type, Content-Length, and Last-Modified headers.

Most requests are handled by this function using the following directive (which usually comes last in the list of Service-class directives in the default object, so that it acts as a default):

Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" 
fn="send-file"

This directive is invoked if the method of the request is GET, HEAD, or POST, and the type does not start with magnus-internal/. Note that the pattern *~ means “does not match”.

Parameters

The following table describes parameters for the send-file function.

Table 7–95 send-file Parameters

Parameter  

Description  

nocache

(Optional) Prevents the server from caching responses to static file requests. For example, you can specify that files in a particular directory are not to be cached, which is useful for directories where the files change frequently. 

The value you assign to this parameter is ignored. 

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service type="*~magnus-internal/*" method="(GET|HEAD)" fn="send-file"

In the following example, the server does not cache static files from /export/somedir/ when requested by the URL prefix /myurl.

<Object name=default>
...
NameTrans fn="pfx2dir" from="/myurl" dir="/export/mydir", name="myname"
...
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
...
</Object>
<Object name="myname">
Service method="(GET|HEAD") type="*~magnus-internal/*" fn="send-file" nocache=""
</Object>

send-range

When the client requests a portion of a document by specifying HTTP byte ranges, the send-range function returns that portion.

Parameters

The following table describes parameters for the send-range function.

Table 7–96 send-range Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service fn="send-range" 

send-shellcgi

(Windows only) The send-shellcgi function runs a file as a shell CGI program and sends the results to the client. Shell CGI is a server configuration that lets you run CGI applications using the file associations set in Windows.

Parameters

The following table describes parameters for the send-shellcgi function.

Table 7–97 send-shellcgi Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service fn="send-shellcgi"

Service type="magnus-internal/cgi" fn="send-shellcgi"

send-wincgi

(Windows only) The send-wincgi function runs a file as a Windows CGI program and sends the results to the client.

Parameters

The following table describes parameters for the send-wincgi function.

Table 7–98 send-wincgi Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service fn="send-wincgi"

Service type="magnus-internal/cgi" fn="send-wincgi"

service-dav

The service-dav function services a request to a WebDAV-enabled URI. In response to a request for a WebDAV resource, the service-dav function services the static content and restarts the request with the sourceuri for dynamic content. The sourceuri is identified by the magnus-internal setting. If no sourceuri is defined for dynamic content, an HTTP error message is returned.

Requests to WebDAV resources are authenticated and authorized by the AuthTrans and PathCheck NSAPI stages, respectively. By default, all access to sourceuri is restricted by the PathCheck entry in the dav object.

OPTIONS on a WebDAV-enabled URI are always handled by the service-dav directive of the default object. Therefore, the OPTIONS method is not included in the service-dav directive of the dav object.

In response to an OPTIONS request to a WebDAV-enabled URI (or sourceuri), the service-dav function in the default object adds the necessary DAV headers and returns control to the core server, which then services the request.

For more information on access control for WebDAV resources, see Chapter 10, Web Publishing With WebDAV, in Sun Java System Web Server 7.0 Update 5 Administrator’s Guide.

Parameters

The following table describes parameters for the service-dav function.

Table 7–99 service-dav Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

<Object name="default">
.... 
Service method="(OPTIONS|PUT|DELETE|COPY|MOVE|PROPFIND|PROPPATCH|LOCK|UNLOCK|MKCOL)"
     fn="service-dav"
</Object>

See Also

service-dump

The service-dump function creates a performance report based on collected performance bucket data. To read the report, point the browser to:

http://server_id:portURI

For example:

http://sun.com:80/.perf

Parameters

The following table describes parameters for the service-dump function.

Table 7–100 service-dump Parameters

Parameter 

Description 

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

<Object name="default">
<If uri = "/.perf">
Service fn="service-dump"
</If>
...
</Object>

See Also

stats-xml

service-j2ee

The service-j2ee function services requests made to Java web applications.

Parameters

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

Table 7–101 service-j2ee Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

<Object name="default">
NameTrans fn="ntrans-j2ee" name="j2ee"
...
</Object>

<Object name="j2ee">
Service fn="service-j2ee"
</Object>

See Also

service-trace

The service-trace function services TRACE requests. TRACE requests are used to diagnose problems with web proxy servers located between a web client and web server.

Parameters

The following table describes parameters for the service-trace function.

Table 7–102 service-trace Parameters

Parameter  

Description 

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

<Object name="default">
...
Service method="TRACE" fn="service-trace"
...
</Object>

shtml-send

The shtml-send function parses an HTML document, scanning for embedded commands. These commands may provide information from the server, include the contents of other files, or execute a CGI program.

See Chapter 2, Server-Parsed HTML Tags, in Sun Java System Web Server 7.0 Update 5 Developer’s Guide for server-parsed HTML commands.

Parameters

The following table describes parameters for the shtml-send function.

Table 7–103 shtml-send Parameters

Parameter  

Description  

ShtmlMaxDepth

Maximum depth of include nesting allowed. The default value is 10.

addCgiInitVars

(UNIX only) If present and set to yes, adds the environment variables defined in the init-cgi SAF to the environment of any command executed through the SHTML exec tag. The default is no.

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service type="magnus-internal/shtml-send" method="(GET|HEAD)" fn="shtml-send"

stats-xml

The stats-xml function creates a performance report in XML format. If performance buckets are defined, this performance report includes them.

The report is generated at:

http://server_id:portURI

For example:

http://sun.com:80/stats-xml

For more information about tuning the server using the stats-xml information, see Sun Java System Web Server 7.0 Update 5 Performance Tuning, Sizing, and Scaling Guide.

Parameters

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

Table 7–104 stats-xml Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

<Object name="default">
<If uri = "/stats-xml/*">
Service fn="stats-xml"
</If>
...
</Object>

See Also

service-dump

upload-file

The upload-file function uploads and saves a new file when the client sends a request whose method is PUT, if the user is authorized, and the server has the needed file system privileges.

When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes upload-file when the request method is PUT.

Parameters

The following table describes parameters for the upload-file function.

Table 7–105 upload-file Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service fn="upload-file"

AddLog

The AddLog directives are executed to record information about the transaction. For more information, see AddLog.

The following AddLog-class function is described in detail in this section:

In addition, the following common SAFs are valid for the AddLog directive:

flex-log

The flex-log function records request-specific data in a flexible log format. It can also record requests in the common log format. There is a log analyzer, flexanlg, in the /bin directory for Web Server. There are also a number of free statistics generators for the common log format.

Specify the log format using the format subelement of the access-log element in server.xml. For more information, see access-log. For more information on the log format, see Appendix C, Using the Custom Log File Format.

Parameters

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

Table 7–106 flex-log Parameters

Parameter 

Description 

name

(Optional) Specifies the name of a log file. The name must previously been defined by an access-log element in server.xml. If no name is given, the entry is recorded in the default log file.

iponly

(Optional) Instructs the server to log the IP address of the remote client rather than looking up and logging the DNS name. This improves performance if DNS is turned off. The value of iponly has no significance, as long as it exists; you may use iponly=1.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

# Log all accesses to the default log file
AddLog fn="flex-log"
# Log accesses from outside our subnet (198.93.5.*) to 
# nonlocallog
<Client ip="*~198.93.5.*">
AddLog fn="flex-log" name="nonlocallog"
</Client>

Error

If a SAF results in an error, the server stops executing all other directives and immediately starts executing the Error directives. For more information, see Error.

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

In addition, the following common SAFs are valid for the Error directive:

error-j2ee

The error-j2ee function handles errors that occur during execution of web applications deployed to the Web Server individually or as part of full Java EE applications.

Parameters

The following table describes the parameter for the error-j2ee function.

Table 7–107 error-j2ee Parameter

Parameter  

Description  

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

See Also

qos-error

The qos-error function returns an error page stating the quality of service that caused the error, and the value of the QOS statistic.

Parameters

The following table describes parameters for the qos-error function.

Table 7–108 qos-error Parameters

Parameter  

Description  

code

(Optional) Three-digit number representing the HTTP response status code, such as 401 or 407. The recommended value is 503.

This can be any HTTP response status code or reason phrase according to the HTTP specification. 

A list of common HTTP response status codes and reason strings is as follows:

  • 401 Unauthorized

  • 403 Forbidden

  • 404 Not Found

  • 500 Server Error

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Error fn="qos-error" code="503"

See Also

qos-handler

Common SAFs

This section lists SAFs that are common to multiple directives.

Table 7–109 Common SAFs

Server Application Functions 

Directives 

insert-filter

match-browser

query-handler

redirect

remove-filter

restart

send-error

set-variable

insert-filter

The insert-filter SAF is used to add a filter to the filter stack to process incoming (client to server) data. The order of Input fn="insert-filter" and Output fn="insert-filter" directives is important.

Returns

Returns REQ_PROCEED if the specified filter was inserted successfully or REQ_NOACTION if the specified filter was not inserted because it was not required. Any other return value indicates an error.

Parameters

The following table describes parameters for the insert-filter function.

Table 7–110 insert-filter Parameters

Parameter 

Description 

filter

Specifies the name of the filter to insert. For more information about predefined filters, see Input and Output.

type

(Optional) Common to all Input-class and Output-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed.

method

(Optional) Common to all Input-class and Output-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. Common HTTP methods are GET, HEAD, and POST.

query

(Optional) Common to all Input-class and Output-class functions. Specifies a wildcard pattern of query strings for which this function will be executed.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Input fn="insert-filter" filter="http-decompression"

The above directive instructs the insert-filter function to add a custom filter, that is, http-decompression to the filter stack. The http-decompression filter will decompress the incoming HTTP request data, before it goes to the service stage. For more information about predefined filters, see Input and Output. For more information, Chapter 3, Creating Custom Filters, in Sun Java System Web Server 7.0 Update 5 NSAPI Developer’s Guide

See Also

match-browser

The match-browser function matches specific strings in the User-Agent string supplied by the browser. It then modifies the behavior of Sun Java System Web Server based on the results by setting values for specified variables. This function is applicable in all directives.

Syntax

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

Parameters

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

Table 7–111 match-browser Parameters

Value 

Description 

stage

Stage directive used in obj.conf processing. The match-browser function is applicable in all stage directives.

string

Wildcard pattern to compare with the User-Agent header (for example, "*Mozilla*").

name

Variable to be changed. The match-browser function indirectly invokes the set-variable function.

value

New value for the specified variable. 

Example

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

If a browser's User-Agent header contains the string Broken or broken, the above AuthTrans directive instructs the server to do the following:

For more information on the variables used in this example, such as ssl-unclean-shutdown, see set-variable.

See Also

set-variable

query-handler

The query-handler function runs a CGI program instead of referencing the path requested.


Note –

This function is provided for backward compatibility only and is used mainly to support the obsolete ISINDEX tag. Use an HTML form instead.


Parameters

The following table describes parameters for the query-handler function.

Table 7–112 query-handler Parameters

Parameter  

Description  

path

Full path and file name of the CGI program to run. 

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Service query="*" fn="query-handler" path="/http/cgi/do-grep"

Service query="*" fn="query-handler" path="/http/cgi/proc-info"

redirect

The redirect function lets you 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.

The redirect function inspects the URL to which the client will be redirected. If the URL matches the URL the client has requested (same scheme, hostname, port, and path), this function does not perform the redirect and instead returns REQ_NOACTION.

Parameters

The following table describes parameters for the redirect function.

Table 7–113 redirect Parameters

Parameter 

Description 

from

(Optional) Specifies the prefix of the requested URI to match. If from is not specified, it defaults to "".

url

(Optional) Specifies a complete URL to return to the client. If you use this parameter, do not use url-prefix.

url-prefix

(Optional) The new URL prefix to return to the client. The from prefix is replaced by this URL prefix. If you use this parameter, do not use url.

escape

(Optional) Indicates whether the value of the url or url-prefix parameter needs to be escaped. The default is yes, indicating that the server will escape the value. The value no indicates that the URL or URL prefix value has already been escaped. An example of an escaped value is one where any % characters have been replaced with %25 and any spaces have been replaced with %20.

For more information about escaping URIs, see the description of util_uri_escape, in the Sun Java System Web Server 7.0 Update 5 NSAPI Developer’s Guide.

status

(Optional) Customizes the HTTP status code. If status is not specified, it defaults to 302.

type

(Optional) Common to all Output-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed.

method

(Optional) Common to all Output-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. Common HTTP methods are GET, HEAD, and POST.

query

(Optional) Common to all Output-class functions. Specifies a wildcard pattern of query strings for which this function will be executed.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

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

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

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

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

See Also

restart

remove-filter

The remove-filter SAF is used to remove a filter from the filter stack. If the filter is inserted multiple times, only the topmost instance is removed. In general, it is not necessary to remove filters with remove-filter, as they are removed automatically at the end of a request.

Returns

Returns REQ_PROCEED if the specified filter was removed successfully, or REQ_NOACTION if the specified filter was not part of the filter stack. Any other return value indicates an error.

Parameters

The following table describes parameters for the remove-filter function.

Table 7–114 remove-filter Parameters

Parameter  

Description  

filter

Specifies the name of the filter to remove. 

type

(Optional) Common to all Input-class, Output-class, and Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. The magnus-internal/* MIME types are used only to select a Service function to execute.

method

(Optional) Common to all Input-class, Output-class, and Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. Common HTTP methods are GET, HEAD, and POST.

query

(Optional) Common to all Input-class, Output-class, and Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Input fn="remove-filter" filter="http-compression"

restart

The restart function allows URL rewriting within the server without sending an HTTP redirect to the client. The restart function replaces the uri and query values in rq->reqpb with the URI and query string specified by the uri parameter and restarts the request by returning REQ_RESTART.

If the uri parameter contains a ? character, the value following ? is used as the query string. Otherwise, the restarted request will not have a query string. Because the new request URI will be passed through the AuthTrans and NameTrans stages again, avoid creating infinite loops.

Parameters

The following table describes parameters for the restart function.

Table 7–115 restart Parameters

Parameter 

Description 

from

(Optional) Wildcard pattern that specifies the path of requests that should be restarted. The default is to match all paths. 

uri

URI and query string to use for the restarted request. 

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

The following obj.conf code causes the server to service requests for /index.html as though they were requests for /index.jsp:

NameTrans fn="restart" from="/index.html" uri="/index.jsp"

send-error

The send-error function sends an HTML file to the client in place of a specific HTTP response status. The HTML page may contain images and links to the server home page or other pages.

Parameters

The following table describes parameters for the send-error function.

Table 7–116 send-error Parameters

Parameter 

Description 

path

Specifies the full file system path of an HTML file to send to the client. The file is sent as text/html regardless of its name or actual type. If the file does not exist, the server sends a simple default error page.

reason

(Optional) Text of one of the reason strings (such as “Unauthorized” or “Forbidden”). The string is not case-sensitive. 

code

(Optional) Three-digit number representing the HTTP response status code, such as 401 or 407. 

This can be any HTTP response status code or reason phrase according to the HTTP specification. 

The following is a list of common HTTP response status codes and reason strings:  

  • 401 Unauthorized

  • 403 Forbidden

  • 404 Not Found

  • 500 Server Error

uri

(Optional) URI of the resource to send to the client. The URI can specify any resource on the server, including HTML files, SHTML pages, CGI programs, JSPs, and Servlets. If the specified resource does not exist, the HTML file specified by the path parameter is sent instead.

type

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of MIME types for which this function will be executed. For more information, see Service.

method

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of HTTP methods for which this function will be executed. For more information, see Service.

query

(Optional) Common to all Service-class functions. Specifies a wildcard pattern of query strings for which this function will be executed. For more information, see Service.

UseOutputStreamSize

(Optional) Common to all Service-class functions. Determines the default output stream buffer size (in bytes), for data sent to the client. For more information, see Service.

flushTimer

(Optional) Common to all Service-class functions. Determines the maximum number of milliseconds between write operations in which buffering is enabled. For more information, see Service.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions. Determines the default buffer size, in bytes, for un-chunking request data. For more information, see Service.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions. Determines the default timeout, in seconds, for un-chunking request data. For more information, see Service.

bucket

(Optional) Common to all obj.conf functions. Adds a bucket to monitor performance. For more information, see The bucket Parameter.

Example

Error fn="send-error" code="401" path="/sun/server7/docs/errors/401.html"

set-variable

The set-variable function enables you to change server settings based upon conditional information in a request. This function is applicable in all directives.

It can also be used to manipulate variables in parameter blocks with the following commands:

The set-variable function recognizes many predefined variables as parameters. Additionally, when a set-variable parameter name begins with $ but is not the name of a predefined variable, the parameter and its value are stored in the rq->vars pblock. This functionality allows you to define or override the $variable values at the request time.

set-variable accepts both the $variable and ${variable} forms, but the name of the parameter stored in the rq->vars pblock is always in the $variable form.

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.

Table 7–117 set-variable Parameters

Value 

Description 

pblock

Specifies one of the following session or request parameter block names: 

  • client: Contains the IP address of the client machine and the DNS name of the remote machine.

  • vars: Contains the server's working variables, which includes anything not specifically found in the reqpb, headers, or srvhdrs pblocks. The contents of this pblock differ, depending on the specific request and the type of SAF.

  • reqpb: Contains elements of the HTTP request, which includes the HTTP method such as GET or POST, the URI, the protocol (generally HTTP/1.0), and the query string. This pblock does not change during the request-response process.

  • headers: Contains all the request headers (such as User-Agent, If-Modified-Since, and so on) received from the client in the HTTP request. This pblock does not change during the request-response process.

  • srvhdrs: Contains the response headers (such as Server, Date, Content-Type, Content-length, and so on) that are to be sent to the client in the HTTP response.

name

The variable to set. 

value

The string assigned to the variable specified by name.

Variables

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

Table 7–118 Supported Variables

Variable 

Description  

abort

A value of true indicates that the result code should be set to REQ_ABORTED. Setting the result code to REQ_ABORTED will abort the current request and send an error to the browser. For information about result codes, see Chapter 2, Creating Custom Server Application Functions, in Sun Java System Web Server 7.0 Update 5 NSAPI Developer’s Guide.

error

Sets the HTTP status code and exits the request by returning REQ_ABORTED. To set the HTTP status code without exiting the request, use the set-variable error parameter along with the noaction parameter. To rewrite an HTTP status code, use a Client tag to match the original status code and an Output directive to set the new status code.

For example, the following code will rewrite all 302 Moved Temporarily responses to 301 Moved Permanently responses:

<Client code="302">
Output fn="set-variable" error="301 Moved Permanently"
     noaction="true"
</Client>

Sets the error code to be returned in the event of an aborted browser request. 

escape

A Boolean value signifying whether a URL should be escaped using util_uri_escape. For information about util_uri_escape, see Sun Java System Web Server 7.0 Update 5 NSAPI Developer’s Guide.

find-pathinfo-forward

Path information after the file name in a URI. See find-pathinfo.

http-downgrade

HTTP version number (for example, 1.0). 

http-upgrade

HTTP version number (for example, 1.0). 

keep-alive

A Boolean value that establishes whether a keep-alive request from a browser will be honored. 

name

Specifies an additional named object in the obj.conf file whose directives will be applied to this request. See also assign-name.

noaction

A value of true indicates the result code should be set to REQ_NOACTION. For AuthTrans, NameTrans, Service, and Error stage SAFs, setting the result code to REQ_NOACTION indicates that subsequent SAFs in that stage should be allowed to execute. For information about result codes, see Chapter 2, Creating Custom Server Application Functions, in Sun Java System Web Server 7.0 Update 5 NSAPI Developer’s Guide.

nostat

Causes the server not to perform the stat() function for a URL when possible. See also assign-name.

senthdrs

A Boolean value that indicates whether HTTP response headers have been sent to the client. 

ssl-unclean-shutdown

A Boolean value that can be used to alter the way SSL3 connections are closed.  


Caution – Caution –

As this violates the SSL3 RFCs, you should only use this with great caution if you know that you are experiencing problems with SSL3 shutdowns.


stop

A value of true indicates the result code should be set to REQ_PROCEED. For AuthTrans, NameTrans, Service, and Error stage SAFs, setting the result code to REQ_PROCEED indicates that no further SAFs in that stage should be allowed to execute. For information about result codes, Chapter 2, Creating Custom Server Application Functions, in Sun Java System Web Server 7.0 Update 5 NSAPI Developer’s Guide.

url

Redirect requests to a specified URL. 

Examples

See Also

match-browser

FastCGI Plug-in SAFs

FastCGI plug-in provides the following Server Application Functions (SAFs):

The various parameters and "error-reason" strings for the FastCGI SAFs are described in the Sun Java System Administrator's Guide.