This section lists SAFs that are common to multiple directives.
Table 7–109 Common SAFs
Server Application Functions |
Directives |
---|---|
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 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.
The following table describes parameters for the insert-filter function.
Table 7–110 insert-filter Parameters
Parameter |
Description |
---|---|
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. |
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 6 NSAPI Developer’s Guide
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.
stage fn="match-browser" browser="string" name="value" [name="value" ...]
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. |
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.
The query-handler function runs a CGI program instead of referencing the path requested.
This function is provided for backward compatibility only and is used mainly to support the obsolete ISINDEX tag. Use an HTML form instead.
The following table describes parameters for the query-handler function.
Table 7–112 query-handler Parameters
Parameter |
Description |
---|---|
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. |
Service query="*" fn="query-handler" path="/http/cgi/do-grep" Service query="*" fn="query-handler" path="/http/cgi/proc-info"
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.
The following table describes parameters for the redirect function.
Table 7–113 redirect Parameters
Parameter |
Description |
---|---|
(Optional) Specifies the prefix of the requested URI to match. If from is not specified, it defaults to "". |
|
(Optional) Specifies a complete URL to return to the client. If you use this parameter, do not use 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. |
|
(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 6 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. |
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"
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 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.
The following table describes parameters for the remove-filter function.
Table 7–114 remove-filter Parameters
Parameter |
Description |
---|---|
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. |
Input fn="remove-filter" filter="http-compression"
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.
The following table describes parameters for the restart function.
Table 7–115 restart Parameters
Parameter |
Description |
---|---|
(Optional) Wildcard pattern that specifies the path of requests that should be restarted. The default is to match all paths. |
|
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 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"
The send-error function sends an HTML file to the client in place of a specific HTTP response status. This allows the server to present a message describing the problem. The HTML page may contain images and links to the server's home page or other pages.
The following table describes parameters for the send-error function.
Table 7–116 send-error Parameters
Parameter |
Description |
---|---|
Specifies the absolute path of an HTML file to send to the client. If the file does not exist or is not accessible, the server returns a 404 or 403 error page. The file is sent as text/html regardless of its name or actual type. |
|
(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:
|
(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. |
Error fn="send-error" code="401" path="/sun/server7/docs/errors/401.html"
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.
stage fn="set-variable" [{insert|set|remove}-pblock="name=value" ...][name="value" ...]
The following table describes parameter values for the set-variable function.
Table 7–117 set-variable Parameters
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 6 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 6 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 6 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 6 NSAPI Developer’s Guide. |
url |
Redirect requests to a specified URL. |
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.