Oracle® Traffic Director Configuration File Reference 11g Release 1 (11.1.1.7) Part Number E21038-03 |
|
|
PDF · Mobi · ePub |
This chapter describes the predefined server application functions (SAFs) and filters that are used in the obj.conf
file. For details about the syntax and use of the obj.conf
file, see Chapter 4, "Syntax and Use of obj.conf".
Each SAF has its own parameters that are passed to it by an obj.conf
directive. SAFs can examine, modify, or create server variables. Each SAF returns a result code that indicates whether it has succeeded, did nothing, or has failed.
The SAFs in this chapter are grouped by the type of directive that calls them. For an alphabetical list of predefined SAFs and server configuration elements, see Appendix D, "Alphabetical List of Server Configuration Elements and Predefined SAFs".
This chapter includes the following topics:
The bucket
parameter is common to all SAFs. You can measure the performance of any SAF in the obj.conf
file by adding a bucket=
bucket-name parameter to the function, for example, bucket="cache-bucket"
. The bucket statistics are displayed by the perfdump
utility, which can be set up through the Administrator Console, CLI, or through the service-dump
SAF.
The following performance buckets are predefined:
The Authtrans
directive instructs Oracle Traffic Director to check for authorization before allowing a client to access resources. For more information, see Section 4.4.1, "AuthTrans".
The following AuthTrans
-class functions are described in detail in this section:
In addition, the following common SAFs are valid for the AuthTrans
directive:
The get-sslid
function retrieves a string that is unique to the current SSL session and stores it as the ssl-id
variable in the Session->client
parameter block.
Note:
This function is provided for backward compatibility. The functionality of get-sslid
was incorporated into the standard processing of an SSL connection.
If the variable ssl-id
is present when a CGI is invoked, it is passed to the CGI as the HTTPS_SESSIONID
environment variable. The get-sslid
function has no parameters and always returns REQ_NOACTION
. It has no effect if SSL is not enabled.
The qos-handler
function examines the current quality of service (QoS) statistics for a virtual server, logs the statistics, and enforces the QoS parameters by returning an error. This function must be the first AuthTrans
function configured in the default
object.
AuthTrans fn= "qos-handler"
See Also:
The webapp-firewall
function controls the enabling and disabling of the rule engine. If this function is present in a virtual server specific obj.conf, it indicates that the rule engine is enabled for that particular virtual server.
The webapp-firewall
function is not configured by default and hence, the rule engine is not enabled. If the rule engine is not enabled, neither the directives nor the rules within the configuration files, specified by webapp-firewall-ruleset
element, are applied.
Note:
If the directive SecRuleEngine
is specified within the configuration file(s) specified by the webapp-firewall-ruleset
element, then it will be ignored. However, this condition is not applicable if SecRuleEngine
is set to DetectionOnly
mode.
If there are other SAFs that could return REQ_PROCEED
, then the SAF webapp-firewall
must be on top of the list. If this is not the case, the execution of webapp-firewall
might get skipped.
For information about various web application firewall use cases, see the appendix, Web Application Firewall Examples and Use Cases in the Oracle Traffic Director Administrator's Guide.
Table 5-1 describes parameters for the webapp-firewall
function. These parameters take precedence over the equivalent settings specified within the webapp-firewall-ruleset
element.
Table 5-1 webapp-firewall Parameters
Parameter | Equivalent setting within webapp-firewall-ruleset | Description |
---|---|---|
DetectionOnly |
(optional) Indicates if the rule engine should enforce the rules or not. This is equivalent to setting The value If this parameter is not specified and if |
|
|
(Optional) Indicates whether request bodies will be processed by web application firewall. When the |
|
|
|
(Optional) Indicates whether response bodies are buffered and processed by web application firewall. When response body processing is enabled, the server will buffer the entire response body in memory, up to the limit defined by the |
The NameTrans
directive translates virtual URLs to physical directories on your server. The NameTrans
directive must appear in the default
object. For more information, see Section 4.4.2, "NameTrans".
The following NameTrans
-class functions are described in detail in this section:
In addition, the following common SAFs are also valid for the NameTrans
directive:
The assign-name
function specifies the name of an object in the obj.conf
file that matches the current request. Oracle Traffic Director then processes the directives in the named object in preference to the ones in the default object.
For example, if you have the following directive in the default
object:
NameTrans fn="assign-name" name="personnel" from="/personnel"
Assume that Oracle Traffic Director receives a request for http://
server-name/personnel
. After processing this NameTrans
directive, Oracle Traffic Director searches for an object named personnel
in the obj.conf
file and continues by processing the directives in the personnel
object.
The assign-name
function returns REQ_NOACTION
.
Table 5-2 describes parameters for the assign-name
function.
Table 5-2 assign-name Parameters
# This NameTrans directive is in the default object. NameTrans fn="assign-name" name="proxy-cache" from="/.proxycache" ... <Object name="proxy-cache"> ...additional directives.. </Object>
The map
function maps a request URI to a URL on another server, enabling you to specify that a request should be serviced by another server. To load balance a given URI across multiple servers, use the map
function in conjunction with the set-origin-server
function. The map
function looks for a certain prefix in the URI that the client is requesting. If map
finds the prefix, it replaces the prefix with the mirror site prefix.
Table 5-3 describes the parameters for the map
function.
Parameter | Description |
---|---|
|
The URI prefix to map. The prefix must not contain trailing slashes. |
|
The URL prefix to which the request should be mapped. The prefix must not contain trailing slashes. The |
|
(Optional) Specifies an additional named object in the |
(Optional) Indicates if the |
NameTrans fn="map" from="/" name="reverse-proxy" to="/"
See Also:
The reverse-map
function rewrites the HTTP response headers when Oracle Traffic Director is functioning as a reverse proxy. reverse-map
looks for the URL prefix specified by the from
parameter in certain response headers. If the from
prefix matches the beginning of the response header value, reverse-map
replaces the matching portion with the to
prefix.
Table 5-4 describes the parameters for the reverse-map
function.
Table 5-4 reverse-map Parameters
Parameter | Description |
---|---|
|
URL prefix to be rewritten. |
|
URL prefix that will be substituted in place of the |
(Optional) Indicates whether the |
|
(Optional) Indicates whether the |
|
(Optional) Indicates whether the headername HTTP response header should be rewritten, where headername is a user-defined header name. With the exception of the |
NameTrans fn="reverse-map" from="http://download.oracle.com/app/docs" to="/docs"
See Also:
The rewrite
function allows flexible mappings between URIs and file system paths.
The following table describes parameters for the rewrite
function.
Parameter | Description |
---|---|
(Optional) Wildcard pattern that specifies the path of requests that should be rewritten. The default is to match all paths. |
|
|
(Optional) File system path to the effective root document directory. |
|
(Optional) Name of an object in |
|
(Optional) Rewritten partial path. If non-empty, the path must begin with a slash (/). |
The following obj.conf
code maps requests for the URI /~user/index.html
to the file system path /home/user/public_html/index.html
:
<If $path =~ "^/~([^/]+)(|/.*)$"> NameTrans fn="rewrite" root="/home/$1/public_html" path="$2" </If>
See Also:
The PathCheck
directive checks the URL that is returned after the NameTrans
step to verify that the client is allowed to access the specified origin server. For more information, see Section 4.4.3, "PathCheck".
The following PathCheck
-class functions are described in detail in this section:
In addition, the following common SAFs are valid for the PathCheck directive:
The check-request-limits
function monitors incoming requests that match a given attribute (for example, client IP address) and computes an average requests per second on a configurable time interval. When requests that match the monitored attribute exceed a threshold that you configure, subsequent matching requests are not serviced until the request rate drops. Use this function to detect possible denial-of-service attacks.
You must specify either max-rps
or max-connections
, otherwise check-request-limits
does nothing. If you do not enter an attribute or attributes to monitor, the function monitors all requests.
By default, the function keeps entries on requests for 300 seconds (5 minutes) before purging them. To adjust this time, use the init-request-limits
SAF in the magnus.conf
file.
Table 5-6 describes the parameters for the check-request-limits
function.
Table 5-6 check-request-limits Parameters
Parameter | Description |
---|---|
(Optional) Threshold for matching requests per second. If this threshold is exceeded subsequent connections matching the criteria are not serviced. Because an acceptable threshold value can vary widely between sites, there is no default value for this parameter. |
|
(Optional) Maximum number of concurrent matching connections. If Oracle Traffic Director receives a request that matches the criteria while the number of matching requests currently being processed meets or exceeds this number, the request is denied. Note that this number is the current requests at any time, and is independent of the Because an acceptable value can vary widely between sites, there is no default value for this parameter. |
|
(Optional) In seconds, the time interval during which average requests per second is computed. The |
|
(Optional) Determines what condition must be met in order for a blocked request type to become available again for servicing. Valid values are:
Default value: |
|
(Optional) The HTTP status code to use for blocked requests. Default value: |
|
(Optional) A request attribute to monitor. Request rates are tracked in a bucket named by the value of this parameter. If the Although the value of the |
The following example limits a client IP to a maximum request rate of 10 requests per second in the default interval of 30 seconds:
PathCheck fn="check-request-limit" monitor="$ip" max-rps="10"
The following example limits a client IP to a maximum request rate of 10 requests per second when accessing any Perl CGIs. Other types of requests are unlimited:
<If path = "*.pl"> PathCheck fn="check-request-limits" monitor="$ip" max-rps="10" </If>
For more information on using the If
tag, see "If, ElseIf, and Else".
The following example limits requests globally for Perl CGIs to 10 requests per second. No specific monitor
parameter is specified:
<If path = "*.pl"> PathCheck fn="check-request-limits" max-rps="10" </If>
The following example limits a client IP from generating more than 10 Perl CGI requests per second, or 5 JSP requests per second. To track the Perl and JSP totals separately, the specified monitor
parameters contain both a fixed string identifier and the client IP variable:
<If path = "*.pl"> PathCheck fn="check-request-limits" max-rps="10" monitor="perl:$ip" </If> <If path = "*.jsp"> PathCheck fn="check-request-limits" max-rps="5" monitor="jsp:$ip" </If>
The following example limits any one client IP to no more than 5 connections at a given time:
PathCheck fn="check-request-limits" max-connections="2" monitor="$ip"
The deny-existence
function sends a 404 Not Found
message when a client tries to access a specified path.
Table 5-7 describes parameters for the deny-existence
function.
Table 5-7 deny-existence Parameters
Parameter | Description |
---|---|
(Optional) Wildcard pattern of the file system path to hide. If the path does not match, the function does nothing and returns |
|
(Optional) Specifies a file to send rather than responding with the |
PathCheck fn="deny-existence" path="/opt/oracle/webserver7/docs/private" PathCheck fn="deny-existence" bong-file="/svr/msg/go-away.html"
The get-client-cert
function gets the authenticated client certificate from the SSL3 session. It can apply to all HTTP methods, or only to those that match a specified pattern. It only works when SSL is enabled on Oracle Traffic Director.
If the certificate is present or obtained from the SSL3 session, the function returns REQ_NOACTION
and allows the request to proceed. Otherwise, it returns REQ_ABORTED
and sets the protocol status to 403 forbidden
, causing the request to fail.
The following table describes parameters for the get-client-cert
function.
Table 5-8 get-client-cert Parameters
Parameter | Description |
---|---|
(Optional) Controls whether to actually get the certificate, or just test for its presence.
Default value: |
|
(Optional) Controls whether failure to get a client certificate will abort the HTTP request.
Default value: |
|
(Optional) Specifies a wildcard pattern for the HTTP methods for which the function will be applied. If |
# Get the client certificate from the session. # If a certificate is not already associated with the session, request one. # The request fails if the client does not present a #valid certificate. PathCheck fn="get-client-cert" dorequest="1"
(Windows only) The nt-uri-clean
function denies access to any resource whose physical path contains \.\
, \..\
or \\
(these are potential security problems).
Table 5-9 describes the parameters for the nt-uri-clean
function.
Table 5-9 nt-uri-clean Parameters
Parameter | Description |
---|---|
(Optional) If present, allows tilde (~) characters in URIs. This is a potential security risk on the Windows platform, where |
|
(Optional) If present, |
PathCheck fn="nt-uri-clean"
See Also:
The ssl-logout
function invalidates the current SSL session in Oracle Traffic Director's SSL session cache. This does not affect the current request, but the next time that the client connects, a new SSL session is created. If SSL is enabled, this function returns REQ_PROCEED
after invalidating the session cache entry. If SSL is not enabled, it returns REQ_NOACTION
.
(UNIX only) The unix-uri-clean
function denies access to any resource whose physical path contains /./
or /../
or //
(these are potential security problems).
The following table describes parameters for the unix-uri-clean
function.
PathCheck fn="unix-uri-clean"
See Also:
The ObjectType
directives determine the MIME type of the file that has to be sent to the client in response to a request. For more information, see ObjectType.
The following ObjectType
-class functions are described in detail in this section:
In addition, the following common SAFs are valid for the ObjectType
directive:
The block-auth-cert
function instructs Oracle Traffic Director to not generate and forward its own Proxy-auth-cert
header to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-auth-cert"
See Also:
The block-cache-info
function instructs Oracle Traffic Director to not generate and forward its own Proxy-cache-info
header to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-cache-info"
See Also:
The block-cipher
function instructs Oracle Traffic Director to not generate and forward its own Proxy-cipher
header to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-cipher"
See Also:
The block-ip
function instructs Oracle Traffic Director to not generate and forward its own Client-ip
header (or Wl-proxy-client-ip
header for WebLogic Server) to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-ip"
See Also:
The block-issuer-dn
function instructs Oracle Traffic Director to not generate and forward its own Proxy-issuer-dn
header to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-issuer-dn"
See Also:
The block-jroute
function instructs Oracle Traffic Director to not generate and forward its own Proxy-jroute
header to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-jroute"
See Also:
The block-keysize
function instructs Oracle Traffic Director to not generate and forward its own Proxy-keysize
header (or Wl-proxy-client-keysize
header for WebLogic Server) to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-keysize"
See Also:
The block-proxy-agent
function instructs Oracle Traffic Director to not generate and forward its own Proxy-agent
header to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-proxy-agent"
See Also:
The block-secret-keysize
function instructs Oracle Traffic Director to not generate and forward its own Proxy-secret-keysize
header (or Wl-proxy-client-secretkeysize
header for WebLogic Server) to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-secret-keysize"
See Also:
The block-ssl
function instructs Oracle Traffic Director to not generate and forward its own Proxy-ssl
header (or Wl-proxy-ssl
header for WebLogic Server) to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-ssl"
See Also:
The block-ssl-id
function instructs Oracle Traffic Director to not generate and forward its own Proxy-ssl-id
header to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-ssl-id"
See Also:
The block-user-dn
function instructs Oracle Traffic Director to not generate and forward its own Proxy-user-dn
header to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-user-dn"
See Also:
The block-via
function instructs Oracle Traffic Director to not generate and forward its own Via
header to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-via"
See Also:
The block-xforwarded-for
function instructs Oracle Traffic Director to not generate and forward its own X-forwarded-for
header to the origin server. In addition, if the incoming request contains this header, then the SAF will allow Oracle Traffic Director to pass-through the incoming request containing this header to the origin server.
ObjectType fn="block-xforwarded-for"
See Also:
The forward-auth-cert
function instructs Oracle Traffic Director to generate information about client's SSL/TLS certificate within the header Proxy-auth-cert
and forward it to origin server. If an incoming request includes the header Proxy-auth-cert
, this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-11 describes the parameters for the forward-auth-cert
function.
Table 5-11 forward-auth-cert Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate the client's DER-encoded SSL/TLS certificate in Base 64 encoding. Default value: |
See Also:
The forward-cache-info
function instructs Oracle Traffic Director to generate information about local hits within the header Cache-info
and forward it to the origin server. If an incoming request includes the header Cache-info
, this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-12 describes the parameters for the forward-cache-info
function.
Table 5-12 forward-cache-info Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate information about local cache hits. Default value: |
See Also:
The forward-cipher
function instructs Oracle Traffic Director to generate information about the client's SSL/TLS cipher suite within the header Proxy-cipher
and forward it to origin server. If an incoming request includes the header Proxy-cipher
, this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-13 describes the parameters for the forward-cipher
function.
Table 5-13 forward-cipher Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate the name of the client's SSL/TLS cipher suite. Default value: |
See Also:
The forward-ip
function instructs Oracle Traffic Director to generate the client's IP address within the header Client-ip
(or WI-proxy-client-ip
for WebLogic Server) and forward it to origin server. If an incoming request includes the header Client-ip
(or WI-proxy-client-ip
for WebLogic Server), this SAF will cause Oracle Traffic Director to remove the header from the request that is forwarded to the origin server. Subsequently, Oracle Traffic Director generates and inserts this header with the appropriate value before forwarding the request to the origin server.
Table 5-14 describes parameters for the forward-ip
function.
Table 5-14 forward-ip Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate the client's IP address. Default value: |
See Also:
The forward-issuer-dn
function instructs Oracle Traffic Director to generate information about the client's SSL/TLS certificate within the header Proxy-issuer-dn
and forward it to origin server. If an incoming request includes the header Proxy-issuer-dn
, this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-15 describes the parameters for the forward-issuer-dn
function.
Table 5-15 forward-issuer-dn Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate the distinguished name of the issuer of the client's SSL/TLS certificate. Default value: |
See Also:
The forward-jroute
function instructs Oracle Traffic Director to generate information about request routing within the header Proxy-jroute
and forward it to origin server. The Proxy-jroute
header field is used by the set-origin-server function
and some Servlet containers to implement session stickiness. If an incoming request includes the header Proxy-jroute
, this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-16 describes the parameters for the forward-jroute
function.
Table 5-16 forward-jroute Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate the request routing information. Default value: |
See Also:
The forward-keysize
function instructs Oracle Traffic Director to generate information about the size of the client's SSL/TLS key within the header Proxy-keysize
and forward it to origin server. If an incoming request includes the header Proxy-keysize
, this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-17 describes the parameters for the forward-keysize
function.
Table 5-17 forward-keysize Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate the size of the client's SSL/TLS key. Default value: |
See Also:
The forward-proxy-agent
function instructs Oracle Traffic Director to generate its version information within the header Proxy-agent
and forward it to origin server. If an incoming request includes the header Proxy-agent
, this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-18 describes the parameters for the forward-proxy-agent
function.
Table 5-18 forward-proxy-agent Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate server version. Default value: |
See Also:
The forward-secret-keysize
function instructs Oracle Traffic Director to generate information about the size of the client's SSL/TLS secret key within the header Proxy-secret-keysize
(or Wl-proxy-client-secretkeysize
for WebLogic Server) and forward it to origin server. If an incoming request includes the header Proxy-secret-keysize
(or Wl-proxy-client-secretkeysize
for WebLogic Server), this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-19 forward-secret-keysize Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate the client's SSL/TLS secret key. Default value: |
ObjectType fn="forward-secret-keysize"
See Also:
The forward-ssl
function instructs the server to forward information to remote (origin) servers to check if the client sent the request to Oracle Traffic Director over an SSL connection. Accordingly, if the client connects to OTD using a non-SSL connection, this header is set with the value False. Similarly, if the client connects to OTD using an SSL connection, then this header is set with the value True. If an incoming request includes the header Proxy-ssl
(or WI-proxy-ssl
for WebLogic Server), this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Parameter | Description |
---|---|
hdr |
Name of the HTTP request header used to communicate that the connection between the client and OTD was over SSL. Default value: |
ObjectType fn="forward-ssl"
See Also:
The forward-ssl-id
function instructs Oracle Traffic Director to generate information about the client's SSL/TLS session ID within the header Proxy-ssl-id
and forward it to origin server. If an incoming request includes the header Proxy-ssl-id
, this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-21 describes the parameters for the forward-ssl-id
function.
Table 5-21 forward-ssl-id Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate the client's SSL/TLS session ID. Default value: |
See Also:
The forward-user-dn
function instructs Oracle Traffic Director to generate information about the distinguished name of the subject of the client's SSL/TLS certificate within the header Proxy-user-dn
and forward it to origin server. If an incoming request includes the header Proxy-user-dn
, this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-22 describes the parameters for the forward-user-dn
function.
Table 5-22 forward-user-dn Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate the distinguished name of the subject of the client's SSL/TLS certificate. Default value: |
See Also:
The forward-via
function instructs Oracle Traffic Director to generate information about request routing within the header Via
and forward it to origin server using the HTTP/1.1 Via
format. The HTTP/1.1 Via
header field records the proxy servers and protocol versions that were involved in routing a request. If an incoming request includes the header Via
, this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-23 describes parameters for the forward-via
function.
Table 5-23 forward-via Parameters
Parameter | Description |
---|---|
|
(Optional) Name of the HTTP request header used to communicate routing information. Default value: |
See Also:
The forward-xforwarded-for
function instructs Oracle Traffic Director to generate information about user-specified X-Forwarded-For
header values within the header X-Forwarded-For
and forward it to origin server. If the function is enabled, Oracle Traffic Director sends the X-Forwarded-For
header value to the origin server, where the value is a comma-separated list of IP addresses. This SAF is enabled by default. If an incoming request includes the header X-forwarded-for
, this SAF will cause OTD to remove the header from the request that is forwarded to the origin server.
Table 5-24 forward-xforwarded-for
Parameter | Description |
---|---|
hdr |
(Optional) Name of the HTTP request header used to communicate routing information. Default value: |
ObjectType fn="forward-xforwarded-for"
See Also:
The http-client-config
function configures Oracle Traffic Director's HTTP client.
Table 5-25 describes the parameters for the http-client-config
function.
Table 5-25 http-client-config Parameters
Parameter | Description |
---|---|
(Optional) Indicates if the HTTP client can reuse existing persistent connections for all types of requests. Default value: |
|
(Optional) Specifies the list of characters that Oracle Traffic Director should not escape. Various applications deployed in the application server requires certain characters not to be escaped. If you do not specify this parameter, Oracle Traffic Director may escape those characters. For example:
|
|
(Optional) Indicates if the HTTP client uses persistent connections. Default value: |
|
(Optional) The maximum number of seconds to keep a persistent connection open. Default value: |
|
(Optional) Specifies whether to log request or response headers in server log that Oracle Traffic Director sends and receives from the origin server. This parameter is useful for diagnostics purposes. For example:
|
|
(Optional) HTTP protocol version string. By default, the HTTP client uses either |
|
(Optional) Value of the proxy-agent HTTP request header. The default is a string that contains the web server product name and version. |
|
(Optional) Specifies the size of the buffer that is used by Oracle Traffic Director to store data before it is sent to the client. Higher the value of this buffer size, the lower the number of write system calls. By default, the value of proxy buffer size is 16 KB. To change the value to 32 KB, use the parameter as follows:
|
|
(Optional) The number of times to retry getting content from the origin web server before sending an error to the client. Only |
ObjectType fn="http-client-config" keep-alive="false"
The proxy-cache-config
function configures reverse proxy cache settings.
Table 5-26 describes the parameters for the proxy-cache-config
function.
Table 5-26 proxy-cache-config Parameters
Parameter | Type | Description | Default Value |
---|---|---|---|
Boolean |
Enable or disable caching of reverse proxy content. |
false |
|
|
Integer |
(Optional) Specifies the maximum time in seconds allowed between consecutive up-to-date checks. If set to 0 default value, a check is made every time the document is accessed, and the Note: Setting a value for this element will cause the server to behave in a manner different from what the HTTP specification mandates. |
|
|
Integer |
Specifies the minimum time in seconds allowed between consecutive up-to-date checks of a cached document. |
|
|
Float |
(Optional) Represents the factor used in estimating the expiry time, which defines how long a document will be up-to- date based on the time it was last modified. The time elapsed since the last modification is multiplied by this factor. The result gives the estimated time the document is likely to remain unchanged. Specifying a value of |
|
|
Integer |
The minimum size, in bytes, of any document to be cached. You can prefer to cache only larger documents. |
|
|
Integer |
The maximum size, in bytes, of any document to be cached. This setting enables users to limit the maximum size of cached documents, so that no single document can take too much space. This value cannot exceed the maximum value specified in |
|
|
Integer |
Specifies the number of characters in the query string (the "?string" part at the end of the URL that are still cacheable). The same queries are rarely repeated exactly in the same form by more than one user, and so caching them is often not desirable. |
|
|
Boolean |
If this parameter is set to |
|
|
Boolean |
If this parameter is set to |
|
ObjectType fn="proxy-cache-config" enable="1" max-reload-interval=300 min-reload-interval=60
The proxy-cache-override-http
function configures reverse proxy cache parameters that override certain HTTP caching rules.
Table 5-27 describes the parameters for the proxy-cache-override-http
function.
Table 5-27 proxy-cache-override-http Parameters
Parameter | Type | Description | Default Value |
---|---|---|---|
Boolean |
If this parameter is set to |
|
|
|
Boolean |
If this parameter is set to |
|
|
Boolean |
If this parameter is set to |
|
|
Boolean |
If set to |
|
|
Boolean |
If this parameter is set to |
|
|
Boolean |
If this parameter is set to |
|
|
Boolean |
If this parameter is set to |
|
|
Boolean |
If this parameter is set to |
|
|
Boolean |
If this parameter is set to |
|
<If uri =~ '^/images/'> ObjectType fn="proxy-cache-config" enable="1" max-reload-interval=600 ObjectType fn="proxy-cache-override-http" ignore-client-no-cache="true" </If> <Else uri =~ '^/myapp/'> ObjectType fn="proxy-cache-config" enable="1" max-reload-interval=120 </Else>
See Also:
The proxy-websocket-config
SAF disables WebSocket upgrade and modifies the idle-timeout for WebSocket connections. WebSocket upgrade is enabled by default. If WebSocket upgrade needs to be disabled, then proxy-websocket-config can be used with enabled=off. The proxy-websocket-config directive may be present in the route object for a route or the default object for the whole virtual server. This enables administrators to disable WebSocket traffic or set a different idle-timeout value for certain routes or for the whole virtual server.
Table 5-28 describes the parameters for the proxy-cache-override-http
function.
Table 5-28 proxy-websocket-config Parameters
Parameter | Default Value |
---|---|
'on' or 'off' |
|
|
Default is the timeout value mentioned in the tcp-thread-pool element |
ObjectType fn="proxy-websocket-config"
The reverse-block-date
SAF blocks the Date header sent from the origin server and causes Oracle Traffic Director to generate and insert its own Date header in the response.
ObjectType fn="reverse-block-date"
See Also:
The reverse-block-server
SAF blocks the Server header sent from the origin server and causes Oracle Traffic Director to insert its own Server header in the response.
ObjectType fn="reverse-block-server"
See Also:
The reverse-forward-date
SAF forwards the Date header sent from the origin server. In Oracle Traffic Director, this is the default behavior.
ObjectType fn="reverse-forward-date"
See Also:
The reverse-forward-server
SAF forwards the Server header sent from the origin server. If origin server does not generate any Server header then Oracle Traffic Director generates and uses its own Server header. This is the default behavior.
ObjectType fn="reverse-forward-server"
See Also:
The set-basic-auth
function allows you to set the HTTP basic authentication credentials, used by the server, when it sends an HTTP request. Use set-basic-auth
to authenticate to a remote origin server or proxy server.
The following table describes parameters for the set-basic-auth
function.
Table 5-29 set-basic-auth Parameters
Parameter | Description |
---|---|
Name of the user to authenticate. |
|
|
Password of the user to authenticate. |
|
(Optional) Name of the HTTP request header used to communicate the credentials. |
|
(Optional) Common to all |
ObjectType fn="set-basic-auth" user="admin" password="secret" hdr="proxy-authorization"
The set-cache-control
function allows you to specify the HTTP caching policy for the response being sent back to the client.
The following table describes parameters for the set-cache-control
function.
Table 5-30 set-cache-control Parameters
Parameter | Description |
---|---|
HTTP cache control directives. Separate multiple directives by commas. |
The following table describes some of the useful cache control directives defined by the HTTP/1.1 protocol.
Table 5-31 Cache Control Directives
Directive | Description |
---|---|
|
The response may be cached by any cache. |
|
The response must not be cached by a shared cache (for example, a proxy server). |
|
Clients must ask Oracle Traffic Director for updated content on each access. |
|
The response should not be cached for more than n seconds. |
ObjectType fn="set-cache-control" control="private,max-age=60"
The set-cookie
function allows you to set a cookie in the response being sent back to the client.
The following table describes parameters for the set-cookie
function.
Table 5-32 set-cookie Parameters
Parameter | Description |
---|---|
|
Name of the cookie. |
|
(Optional) Value of the cookie. Default value: |
|
(Optional) Base URI to which the cookie applies. Default value: |
(Optional) The domain name of servers to which the cookie must be sent. If no domain is specified, web browsers send the cookie only to Oracle Traffic Director that sets the cookie. |
|
(Optional) Maximum time (in seconds) after which the cookie expires. If |
<If not defined $cookie{'FIRSTVISITTIME'}> ObjectType fn="set-cookie" name="FIRSTVISITTIME" value="$time" max-age="31536000" </If>
The ssl-client-config
function configures options used when Oracle Traffic Director connects to a origin server using SSL/TLS.
Table 5-33 describes the parameters for the ssl-client-config
function.
Table 5-33 ssl-client-config Parameters
Parameter | Description |
---|---|
(Optional) Nickname of the client certificate to present to the remote server. The default is not to present a client certificate. |
|
(Optional) Boolean that indicates whether Oracle Traffic Director validates the certificate presented by the remote server. Default value: |
ObjectType fn="ssl-client-config" validate-server-cert="false"
See Also:
The type-by-exp
function matches the current path with a wildcard expression. If they match, the type
parameter information is applied to the file. This is the same as type-by-extension
, except that you use wildcard patterns for the files or directories specified in the URLs.
Table 5-34 describes the parameters for the type-by-exp
function.
Table 5-34 type-by-exp Parameters
Parameter | Description |
---|---|
Wildcard pattern of paths for which this function is applied. |
|
(Optional) Type assigned to a matching request (the |
|
(Optional) Encoding assigned to a matching request (the |
|
(Optional) Language assigned to a matching request (the |
|
(Optional) The character set for the |
ObjectType fn="type-by-exp" exp="*.test" type="application/html"
See Also:
The type-by-extension
function instructs Oracle Traffic Director to look in a table of MIME type mappings to find the MIME type of the requested resource. The MIME type is added to the Content-Type
header that is sent back to the client.
The table of MIME type mappings is created by a mime-file
element in the server.xml
file, which loads a MIME types file or list and creates the mappings.
For example, the following two lines are part of a MIME types file:
type=text/html exts=htm,html type=text/plain exts=txt
If the extension of the requested resource is htm
or html
, the type-by-extension
file sets the type to text/html
. If the extension is .txt
, the function sets the type to text/plain
.
ObjectType fn="type-by-extension"
See Also:
The Input
directives allow you to select filters that will process incoming request data read by the Service
stage. For more information, see Input.
The following common SAFs are valid for the Input
directive:
Every Input
directive has the following optional parameters.
Table 5-35 Input Directive's Optional Parameters
Parameters | Description |
---|---|
(Optional) Specifies a wildcard pattern of MIME types for which this function is executed. |
|
(Optional) Specifies a wildcard pattern of HTTP methods for which this function is executed. Common HTTP methods are |
|
(Optional) Specifies a wildcard pattern of query strings for which this function is executed. |
The Output
stage allows you to select filters that will process outgoing data. For more information, see Output.
Every Output
directive has the following optional parameters:
Table 5-36 Output Directive's Optional Parameters
Parameters | Description |
---|---|
(Optional) Specifies a wildcard pattern of MIME types for which this function is executed. |
|
(Optional) Specifies a wildcard pattern of HTTP methods for which this function is executed. Common HTTP methods are |
|
(Optional) Specifies a wildcard pattern of query strings for which this function is executed. |
The following common SAFs are valid for the Output directive:
The Route
directive specifies information as to where the Web Server should route requests. For more information, see Route.
The following Route
-class functions are described in detail in this section:
In addition, the following common SAFs are valid for the Route directive:
The set-origin-server
function distributes the load across a set of homogeneous HTTP origin servers. This SAF chooses the origin server from a given origin server pool for this request. The set-origin-server
SAF requires origin-server-pool
as mandatory parameter.
Table 5-37 describes the parameters for the set-origin-server
function.
Table 5-37 set-origin-server Parameters
Parameter | Description |
---|---|
|
(Mandatory) Name of the configured origin server pool. From this pool, one of the origin servers will be chosen based on the load balancing properties defined within the |
(Optional) Name of a cookie that, when present in a response, will cause subsequent requests to stick to that origin server. Accordingly, subsequent requests with this cookie are sent to the same origin server. This parameter accepts * as value, which means that any cookie received from the origin server will be considered as sticky. Default value: |
|
(Optional) Name of a URI parameter to inspect for route information. When the URI parameter is present in a request URI and its value contains a colon (:) followed by a route ID, the request will stick to the origin server identified by that route ID. Default value: |
|
(Optional) Name of the HTTP request header used to communicate route IDs to origin servers. |
|
(Optional) Name of the cookie generated by Oracle Traffic Director when it encounters a |
|
(Optional) Indicates whether the host HTTP request header is rewritten to match the host specified by the |
|
(Optional) Indicates whether the |
|
(Optional) Indicates whether the |
|
(Optional) Indicates whether the headername HTTP response headers that match Oracle Traffic Director parameter should be rewritten, where headername is a user-defined header name. headername is in lowercase. With the exception of the |
Route fn="set-origin-server" origin-server-pool="origin-server-pool-1"
See Also:
The set-proxy-server
function directs Oracle Traffic Director to retrieve the current resource from a particular proxy server.
Table 5-38 describes the parameters for the set-proxy-server
function.
Table 5-38 set-proxy-server
Parameters
Parameter | Description |
---|---|
|
URL of the remote proxy server. If multiple server parameters are given, Oracle Traffic Director distributes load among the specified remote servers. |
Route fn="set-proxy-server" server="http://webcache1.eng.sun.com:8080" server="http://webcache2.eng.sun.com:8080"
See Also:
The Service
directives send the response data to the client. For more information, see Service.
Every Service
directive has the following optional parameters to determine whether the function is executed. All optional parameters must match the current request for the function to be executed.
Table 5-39 Service Directive's Optional Parameters
Optional Parameters | Description |
---|---|
Specifies a wildcard pattern of MIME types for which this function is executed. The |
|
Specifies a wildcard pattern of HTTP methods for which this function is executed. Common HTTP methods are |
|
Specifies a wildcard pattern of query strings for which this function is executed. |
|
Determines the default output stream buffer size (in bytes), for data sent to the client. If this parameter is not specified, the default is Note: Set this parameter to zero ( |
|
Determines the maximum number of milliseconds between write operations in which buffering is enabled. If the interval between subsequent write operations is greater than the |
|
Determines the default buffer size, in bytes, for unchunking request data. If this parameter is not specified, the default is |
|
Determines the default timeout, in seconds, for unchunking request data. If this parameter is not specified, the default is |
If there is more than one Service
-class function, the first one matching the optional wildcard parameters (type
, method
, and query
) are executed.
The UseOutputStreamSize
, ChunkedRequestBufferSize
, and ChunkedRequestTimeout
parameters also have equivalent magnus.conf
directives. The obj.conf
parameters override the magnus.conf
directives.
By default, Oracle Traffic Director sends the requested file to the client by calling the send-file
function. The directive that sets the default is:
Service method="(GET|HEAD)" type="*~magnus-internal/*" fn="send-file"
This directive usually comes last in the set of Service
-class directives to give all other Service
directives a chance to be invoked. This directive is invoked if the method of the request is GET
, HEAD
, or POST
, and the type does not start with magnus-internal/
. Note here that the pattern *~
means "does not match." For a list of characters that can be used in patterns, see Wildcard Patterns.
The functions used in the Service
directive are described in the following sections:
In addition, the following common SAFs are valid for the Service directive:
The proxy-retrieve
function retrieves a document from a remote server and returns it to the client. This function also enables you to configure Oracle Traffic Director to allow or block arbitrary methods. This function only works on the HTTP protocol.
Table 5-40 describes the parameters for the proxy-retrieve
function.
Table 5-40 proxy-retrieve Parameters
Parameter | Description |
---|---|
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
# Normal proxy retrieve Service fn="proxy-retrieve" # Proxy retrieve with POST method disabled Service fn="proxy-retrieve" method="(POST)"
See Also:
The remove-filter
function 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.
The following table describes parameters for the remove-filter
function.
Table 5-41 remove-filter Parameters
Parameter | Description |
---|---|
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
Service fn="remove-filter"
The service-proxy-cache-dump
function dumps the current reverse proxy caching statistics.
Table 5-42 describes the parameters for the service-proxy-cache-dump
function.
Table 5-42 service-proxy-cache-dump Parameters
Parameter | Description |
---|---|
|
Lists the objects in the cache. The cache listing includes the URI, a set of flags, the current number of references to the cache entry and the size of the entry. |
|
Setting this parameter to a value |
|
Stops and restarts the cache. |
|
Starts the cache. |
|
Stops the cache. |
<Object name="default" NameTrans fn=assign-name name="proxy-cache" from="/.proxycache" </Object> <Object name="proxy-cache"> Service fn="service-proxy-cache-dump" </Object>
See Also:
The service-trace
function services TRACE
requests. TRACE
requests are used to diagnose problems with web proxy servers located between a web client and web server.
Table 5-43 describes the parameters for the service-trace
function.
Table 5-43 service-trace Parameters
Parameter | Description |
---|---|
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
<Object name="default"> ... Service method="TRACE" fn="service-trace" ... </Object>
The stats-xml
function creates a performance report in XML format. If performance buckets are defined, this performance report includes them.
The report is generated at:
http://server_id:portURI
For example:
http://example.com:80/stats-xml
The following table describes parameters for the stats-xml
function.
Table 5-44 stats-xml Parameters
Parameter | Description |
---|---|
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
<Object name="default"> <If uri = "/stats-xml/*"> Service fn="stats-xml" </If> ... </Object>
The AddLog
directives are executed to record information about the transaction. For more information, see AddLog.
The following AddLog
-class function is described in detail in this section:
In addition, the following common SAFs are valid for the AddLog
directive:
The flex-log
function records request-specific data in a flexible log format. It can also record requests in the common log format. There is a log analyzer, flexanlg
, in the /bin
directory for Web Server. There are also a number of free statistics generators for the common log format.
Specify the log format using the format
subelement of the access-log
element in server.xml
. For more information, see access-log. For more information about the log format, see "Using the Custom Access-Log File Format".
Table 5-45 describes the parameters for the flex-log
function.
Table 5-45 flex-log Parameters
Parameter | Description |
---|---|
(Optional) Specifies the name of a log file. The name must previously been defined by an |
|
(Optional) Instructs Oracle Traffic Director to log the IP address of the remote client rather than looking up and logging the DNS name. This improves performance if DNS is turned off. The value of |
# Log all accesses to the default log file AddLog fn="flex-log" # Log accesses from outside our subnet (198.93.5.*) to # nonlocallog <Client ip="*~198.93.5.*"> AddLog fn="flex-log" name="nonlocallog" </Client>
If an SAF results in an error, Oracle Traffic Director stops executing all other directives and immediately starts executing the Error
directives. For more information, see Error.
The following Error
-class functions are described in detail in this section:
In addition, the following common SAFs are valid for the Error
directive:
The qos-error
function returns an error page stating the quality of service that caused the error and the value of the QoS statistic.
Table 5-46 describes the parameters for the qos-error
function.
Table 5-46 qos-error Parameters
Error fn="qos-error" code="503"
Note:
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.
Table 5-47 describes the parameters for the send-error
function.
Table 5-47 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) Three-digit number representing the HTTP response status code, such as This can be any HTTP response status code or reason phrase according to the HTTP specification. A list of common HTTP response status codes and reason strings is as follows:
|
|
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
Error fn="send-error" code="401" path="/opt/oracle/webserver7/docs/errors/401.html"
This section lists SAFs that are common to multiple directives.
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 5-49 insert-filter
Parameters
Parameter | Description |
---|---|
Specifies the name of the filter to insert. For more information about predefined filters, see Input and Output. |
|
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
Input fn="insert-filter" filter="http-decompression"
This 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 Oracle Traffic Director Administration Guide.
The match-browser
function matches specific strings in the User-Agent
string supplied by the browser. It then modifies the behavior of Oracle Traffic Director 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 5-50 match-browser Parameters
Value | Description |
---|---|
stage |
Stage directive used in |
string |
Wildcard pattern to compare with the |
name |
Variable to be changed. The |
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 Oracle Traffic Director 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 asssl-unclean-shutdown
, see set-variable.
See Also:
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, Oracle Traffic Director 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
.
Table 5-51 describes the parameters for the redirect
function.
Table 5-51 redirect Parameters
Parameter | Description |
---|---|
(Optional) Specifies the prefix of the requested URI to match. If |
|
(Optional) Specifies a complete URL to return to the client. If you use this parameter, do not use |
|
(Optional) The new URL prefix to return to the client. The |
|
(Optional) Indicates whether the value of the |
|
|
(Optional) Customizes the HTTP status code. If |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
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:
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 5-52 remove-filter Parameters
Parameter | Description |
---|---|
Specifies the name of the filter to remove. |
|
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
|
(Optional) Common to all |
The restart
function allows URL rewriting within Oracle Traffic Director without sending an HTTP redirect to the client. The restart
function replaces the uri
and query
values inrq->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.
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. |
The following obj.conf
code directs Oracle Traffic Director to service requests for /index.html
as though they were requests for /index.jsp
:
NameTrans fn="restart" from="/index.html" uri="/index.jsp"
The set-variable
function enables you to change Oracle Traffic Director 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 5-54 set-variable Parameters
Value | Description |
---|---|
pblock |
Specifies one of the following session or request parameter block names:
|
name |
The variable to set. |
value |
The string assigned to the variable specified by name. |
The following tables lists variables supported by the set-variable
SAF.
Table 5-55 Supported Variables
Variable | Description |
---|---|
|
A value of |
|
Sets the HTTP status code and exits the request by returning For example, the following code will rewrite all <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. |
|
A Boolean value signifying whether a URL should be escaped using For information about |
|
Path information after the file name in a URI. |
|
HTTP version number (for example, 1.0). |
|
HTTP version number (for example, 1.0). |
|
A Boolean value that establishes whether a keep-alive request from a browser will be honored. |
|
Specifies an additional named object in the |
|
A value of |
|
Causes the server not to perform the |
|
A Boolean value that indicates whether HTTP response headers have been sent to the client. |
|
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. |
|
A value of |
|
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 Oracle Traffic Director classes use HTTP/1.1, the AuthTrans
directive is:
AuthTrans fn="set-variable" keep-alive="disabled" http-downgrade="1.0"
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 Oracle Traffic Director 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 Oracle Traffic Director is accessed after 5:00 p.m. and before 8:00 a.m. local time.
See Also: