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

Common SAFs

This section lists SAFs that are common to multiple directives.

Table 7–109 Common SAFs


Server Application Functions	Directives
insert-filter	Input Output
match-browser	AuthTrans NameTrans PathCheck ObjectType Input Output Route Service AddLog Error
query-handler	Service Error
redirect	NameTrans Output Error
remove-filter	Input Output Service Error
restart	NameTrans
send-error	Service Error
set-variable	AuthTrans NameTrans PathCheck ObjectType Input Output Route Service AddLog Error

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

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:

Not send the SSL3 and TLS close_notify packet
Not honor requests for HTTP Keep-Alive
Use the HTTP/1.0 protocol rather than HTTP/1.1

For more information on the variables used in this example, such as ssl-unclean-shutdown, see 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 2 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"

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:

insert-pblock="name=value"

Adds a new value to the specified pblock.
set-pblock="name=value"

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

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

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 2 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 2 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 2 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 – 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 2 NSAPI Developer’s Guide.
`url`	Redirect requests to a specified URL.

Examples

To deny HTTP keep-alive requests for a specific server class (while still honoring keep-alive requests for the other classes), add this AuthTrans directive to the obj.conf for the server class, and set the variable keep-alive to disabled:
```
AuthTrans fn="set-variable" keep-alive="disabled"
```
To set the same server class to use HTTP/1.0 while the rest of the server classes use HTTP/1.1, the AuthTrans directive is:
```
AuthTrans fn="set-variable" keep-alive="disabled" http-downgrade="true"
```
To insert an HTTP header into each response, add a NameTrans directive to obj.conf using the insert-pblock command and specify srvhdrs as your Session or Request parameter block.

For example, to insert the HTTP header P3P, add the following line to each request:
```
NameTrans fn="set-variable" insert-srvhdrs="P3P"
```
To terminate processing a request based on certain URIs, use a Client tag to specify the URIs and an AuthTrans directive that sets the variable abort to true when there is a match. Your Client tag would be as follows:
```
<Client uri="*(system32|root.exe)*">
AuthTrans fn="set-variable" abort="true"
</Client>
```

To use predefined variables so that the server rewrites redirects to host badname as redirects to host goodname:

<If $srvhdrs{'location'} =~ "^(http|https)://badname/(.*)$"
Output fn="set-variable" $srvhdrs{'location'}="$1://goodname/$2"
</If>

To set a $variable value at request time:
```
<If "$time_hour:$time_min" < "8:30" || "$time_hour:$time_min" > "17:00">
AuthTrans fn="set-variable" $docroot="/var/www/docs/closed"
</If>
...
NameTrans fn="document-root" root="$docroot"
```
Regardless of whether the $docroot variable has been defined in server.xml, its value is set to /var/www/docs/closed when the server is accessed after 5:00 p.m. and before 8:00 a.m. local time.

Common SAFs

insert-filter

Returns

Parameters

Example

See Also

match-browser

Syntax

Parameters

Example

See Also

query-handler

Parameters

Example

redirect

Parameters

Example

See Also

remove-filter

Returns

Parameters

Example

restart

Parameters

Example

send-error

Parameters

Example

set-variable

Syntax

Parameters

Variables

Examples

See Also