Common SAFs across Multiple Directives

                                                                                                                                                                                                                                                                                                                                      *Back to [[Book|Administrator's Configuration File Reference#cfr]]     [[Topic|Administrator's Configuration File Reference#chap7]]*
h2. Common SAFs across Multiple Directives

This section lists SAFs that are common to multiple directives.

Table 7-109 Common SAFs
||Server Application Functions ||Directives ||
|[#{{insert-filter}}] |* [{{Input}}|Input]
* [{{Output}}|Output] |
|[#{{match-browser}}] |* [{{AuthTrans}}|AuthTrans]
* [{{NameTrans}}|NameTrans]
* [{{PathCheck}}|PathCheck]
* [{{ObjectType}}|ObjectType]
* [{{Input}}|Input]
* [{{Output}}|Output]
* [{{Route}}|Route]
* [{{Service}}|Service]
* [{{AddLog}}|Addlog]
* [{{Error}}|Error] |
|[#{{query-handler}}] |* [{{Service}}|Service]
* [{{Error}}|Error] |
|[#{{redirect}}] |* [{{NameTrans}}|NameTrans]
* [{{Output}}|Output]
* [{{Error}}|Error] |
|[#{{remove-filter}}] |* [{{Input}}|Input]
* [{{Output}}|Output]
* [{{Service}}|Service]
* [{{Error}}|Error] |
|[#{{restart}}] |* [{{NameTrans}}|NameTrans] |
|[#{{send-error}}] |* [{{Service}}|Service]
* [{{Error}}|Error] |
|[#{{set-variable}}] |* [{{AuthTrans}}|AuthTrans]
* [{{NameTrans}}|NameTrans]
* [{{PathCheck}}|PathCheck]
* [{{ObjectType}}|ObjectType]
* [{{Input}}|Input]
* [{{Output}}|Output]
* [{{Route}}|Route]
* [{{Service}}|Service]
* [{{AddLog}}|AddLog]
* [{{Error}}|Error] |

h3. {{insert-filter}} {anchor:saf1}

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.

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

h4. 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}}|Input] and [{{Output}}|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|The bucket Parameter#b1]. |

h4. Example
{code}
Input fn="insert-filter" filter="http-decompression"
{code}

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}}|Input] and [{{Output}}|Output]. For more information, see Creating Custom Filters in [Sun Java System Web Server NSAPI Developer's Guide|NSAPI Developer's Guide#Creating Custom Filters]

h4. See Also
* [{{sed-request}}|Input#inp1]
* [{{sed-response}}|Output#out3]

h3. {{match-browser}} {anchor:saf2}

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.

h4. Syntax

_stage_ {{fn="match-browser" browser=}}_"string"_ _name="value"_ [ _name="value"_ {{...}}]

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

h4. Example
{code}
AuthTrans fn="match-browser"
browser="*[Bb]roken*"
ssl-unclean-shutdown="true"
keep-alive="disabled"
http-downgrade="1.0"
{code}

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

h4. See Also

[#{{set-variable}}]

h3. {{query-handler}} {anchor:saf3}

The {{query-handler}} function runs a CGI program instead of referencing the path requested.

{info:title=Note -}This function is provided for backward compatibility only and is used mainly to support the obsolete {{ISINDEX}} tag. Use an HTML form instead.
{info}

h4. 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}}|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}}|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}}|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}}|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}}|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}}|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}}|Service]. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
Service query="*" fn="query-handler" path="/http/cgi/do-grep"

Service query="*" fn="query-handler" path="/http/cgi/proc-info"
{code}

h3. {{redirect}} {anchor:saf4}

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

h4. 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 NSAPI Developer's Guide|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|The bucket Parameter#b1].

h4. Example

In the first example, any request for {{http://}}_server-name_{{/}}_whatever_ is translated to a request for {{http://tmpserver/}}_whatever_.
{code}
NameTrans fn="redirect" from="/" url-prefix="http://tmpserver/"
{code}

In the second example, any request for {{http://}}_server-name_{{/toopopular/}}_whatever_ is translated to a request for {{http://bigger/better/stronger/morepopular/}}.
{code}
NameTrans fn="redirect" from="/toopopular"
url="http://bigger/better/stronger/morepopular"
{code}

h4. See Also

[#{{restart}}]

h3. {{remove-filter}} {anchor:saf5}

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.

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

h4. 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}}|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}}|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}}|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}}|Service]. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
Input fn="remove-filter" filter="http-compression"
{code}

h3. {{restart}} {anchor:saf6}

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.

h4. 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|The bucket Parameter#b1]. |

h4. Example

The following {{obj.conf}} code causes the server to service requests for {{/index.html}} as though they were requests for {{/index.jsp}}:
{code}
NameTrans fn="restart" from="/index.html" uri="/index.jsp"
{code}

h3. {{send-error}} {anchor:saf7}

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.

h4. 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}}|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}}|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}}|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}}|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}}|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}}|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}}|Service]. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
Error fn="send-error" code="401" path="/sun/server7/docs/errors/401.html"
{code}

h3. {{set-variable}} {anchor:saf8}

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.

h4. Syntax

_stage_ {{fn="set-variable"}} {{[ insert|set|remove-}}_pblock_{{=}}_"name=value_" {{...]}}[ _name="value"_ {{...}}]

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

h4. 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 Creating Custom Server Application Functions in [Sun Java System Web Server NSAPI Developer's Guide|NSAPI Developer's Guide#Creating Custom Server Application Functions]. |
|{{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:
{code}
<Client code="302">
Output fn="set-variable" error="301 Moved Permanently"
noaction="true"
</Client>
{code}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 NSAPI Developer's Guide|NSAPI Developer's Guide]. |
|{{find-pathinfo-forward}} |Path information after the file name in a URI. See [{{find-pathinfo}}|PathCheck#path8]. |
|{{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}}|NameTrans#name1]. |
|{{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 Creating Custom Server Application Functions in [Sun Java System Web Server NSAPI Developer's Guide|NSAPI Developer's Guide#Creating Custom Server Application Functions]. |
|{{nostat}} |Causes the server _not_ to perform the {{stat()}} function for a URL when possible. See also [{{assign-name}}|NameTrans#name1]. |
|{{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.

h4. 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}}:
{code}
AuthTrans fn="set-variable" keep-alive="disabled"
{code}
* 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:
{code}
AuthTrans fn="set-variable" keep-alive="disabled" http-downgrade="true"
{code}
* 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:
{code}
NameTrans fn="set-variable" insert-srvhdrs="P3P"
{code}
* 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:
{code}
&lt;Client uri="*(system32|root.exe)*">
AuthTrans fn="set-variable" abort="true"
&lt;/Client>
{code}
* To use predefined variables so that the server rewrites redirects to host _badname_ as redirects to host _goodname_:
{code}
<If $srvhdrs{'location'} =~ "^(http|https)://badname/(.*)$"
Output fn="set-variable" $srvhdrs{'location'}="$1://goodname/$2"
</If>
{code}
* To set a {{$variable}} value at request time:
{code}
<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"
{code}
\\
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.

h4. See Also

[#{{match-browser}}]