Common SAFs across Multiple Directives

                                                                                                                                                                                                                                                                                                                                      Back to [Book]     [Topic]

Common SAFs across Multiple Directives

This section lists SAFs that are common to multiple directives.

Table 7-109 Common SAFs

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

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, see Creating Custom Filters in Sun Java System Web Server NSAPI Developer's Guide

See Also

• sed-request
• sed-response

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

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.

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

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

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

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

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

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

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.
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 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 Creating Custom Server Application Functions in Sun Java System Web Server 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, see Creating Custom Server Application Functions in Sun Java System Web Server 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.

See Also

match-browser