set-variable (Sun Java System Web Server 7.0 Administrator's Configuration File Reference)

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

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–116 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–117 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 1, Creating Custom Server Application Functions, in Sun Java System Web Server 7.0 Update 1 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 1 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 1, Creating Custom Server Application Functions, in Sun Java System Web Server 7.0 Update 1 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 1, Creating Custom Server Application Functions, in Sun Java System Web Server 7.0 Update 1 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.

set-variable

Syntax

Parameters

Variables

Examples

See Also