5 Predefined Server Application Functions and Filters in obj.conf

5.2.1 get-sslid

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.

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.

5.2.2 qos-handler

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.

Example

AuthTrans fn= "qos-handler"

5.2.3 webapp-firewall

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.

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.

5.3.1 assign-name

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.

Example

# This NameTrans directive is in the default object.
NameTrans fn="assign-name" name="proxy-cache" from="/.proxycache"
...
<Object name="proxy-cache">
...additional directives..
</Object>

5.3.2 map

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.

Example

NameTrans fn="map" from="/" name="reverse-proxy" to="/"

5.3.3 reverse-map

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.

Example

NameTrans fn="reverse-map" from="http://download.oracle.com/app/docs" to="/docs"

5.3.4 rewrite

The rewrite function allows flexible mappings between URIs and file system paths.

The following table describes parameters for the rewrite function.

Example

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>

5.3.5 strip-params

The strip-params function removes the embedded semicolon-delimited parameters from the path. For example, a URI of /dir1;param1/dir2 would become a path of /dir1/dir2. When used, the strip-params function should be the first NameTrans directive listed.

Example

NameTrans fn="strip-params"

5.3.6 sed-request-header

The sed-request-header function applies the sed edit commands to rewrite the value of a specified HTTP request header.

Table 5-6 describes the parameters for sed-request-header.

Example

NameTrans fn="sed-request-header" 
     name="x-someheader" 
     sed="s/abcd/123/g"

5.3.7 sed-response-header

The sed-response-header function applies the sed edit commands to rewrite the value of a specified HTTP response header.

Table 5-7 describes the parameters for sed-response-header.

Example

NameTrans fn="sed-response-header" 
     name="server" 
     sed="s/backend/frontend/g"

5.3.8 sed-param-name

The sed-param-name function applies the sed edit commands to rewrite an arbitrary pblock parameter name.

Table 5-8 describes the parameters for sed-param-name.

Example

NameTrans fn="sed-param-name" 
     pblock="headers" 
     name="content-length" 
     sed="s/-length/-Length/g"

5.3.9 sed-param-value

The sed-param-value function applies the sed edit commands to rewrite an arbitrary pblock parameter value (corresponding to a specified name).

Table 5-9 describes the parameters for sed-param-value.

Example

NameTrans fn="sed-param-name" 
     pblock="reqpb" 
     name="uri" 
     sed="s/test/plan/g"

5.4.1 check-request-limits

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-10 describes the parameters for the check-request-limits function.

Example

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"

5.4.2 deny-existence

The deny-existence function sends a 404 Not Found message when a client tries to access a specified path.

Table 5-11 describes parameters for the deny-existence function.

Example

PathCheck fn="deny-existence" path="/opt/oracle/webserver7/docs/private"

PathCheck fn="deny-existence" bong-file="/svr/msg/go-away.html"

5.4.3 get-client-cert

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.

Example

# 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"

5.4.4 nt-uri-clean

(Windows only) The nt-uri-clean function denies access to any resource whose physical path contains \.\, \..\ or \\ (these are potential security problems).

Table 5-13 describes the parameters for the nt-uri-clean function.

Example

PathCheck fn="nt-uri-clean"

5.4.5 ssl-logout

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.

5.4.6 unix-uri-clean

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

Example

PathCheck fn="unix-uri-clean"

5.5.1 block-auth-cert

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.

Example

ObjectType fn="block-auth-cert"

5.5.2 block-cache-info

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.

Example

ObjectType fn="block-cache-info"

5.5.3 block-cipher

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.

Example

ObjectType fn="block-cipher"

5.5.4 block-ip

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.

Example

ObjectType fn="block-ip"

5.5.5 block-issuer-dn

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.

Example

ObjectType fn="block-issuer-dn"

5.5.6 block-jroute

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.

Example

ObjectType fn="block-jroute"

5.5.7 block-keysize

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.

Example

ObjectType fn="block-keysize"

5.5.8 block-proxy-agent

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.

Example

ObjectType fn="block-proxy-agent"

5.5.9 block-secret-keysize

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.

Example

ObjectType fn="block-secret-keysize"

5.5.10 block-ssl

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.

Example

ObjectType fn="block-ssl"

5.5.11 block-ssl-id

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.

Example

ObjectType fn="block-ssl-id"

5.5.12 block-user-dn

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.

Example

ObjectType fn="block-user-dn"

5.5.13 block-via

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.

Example

ObjectType fn="block-via"

5.5.14 block-xforwarded-for

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.

Example

ObjectType fn="block-xforwarded-for"

5.5.15 forward-auth-cert

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-15 describes the parameters for the forward-auth-cert function.

5.5.16 forward-cache-info

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-16 describes the parameters for the forward-cache-info function.

5.5.17 forward-cipher

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-17 describes the parameters for the forward-cipher function.

5.5.18 forward-ip

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-18 describes parameters for the forward-ip function.

5.5.19 forward-issuer-dn

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-19 describes the parameters for the forward-issuer-dn function.

5.5.20 forward-jroute

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-20 describes the parameters for the forward-jroute function.

5.5.21 forward-keysize

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-21 describes the parameters for the forward-keysize function.

5.5.22 forward-proxy-agent

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-22 describes the parameters for the forward-proxy-agent function.

5.5.23 forward-secret-keysize

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.

Example

ObjectType fn="forward-secret-keysize"

5.5.24 forward-ssl

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.

Example

ObjectType fn="forward-ssl"

5.5.25 forward-ssl-id

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-25 describes the parameters for the forward-ssl-id function.

5.5.26 forward-user-dn

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-26 describes the parameters for the forward-user-dn function.

5.5.27 forward-via

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-27 describes parameters for the forward-via function.

5.5.28 forward-xforwarded-for

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.

Example

ObjectType fn="forward-xforwarded-for"

5.5.29 http-client-config

The http-client-config function configures Oracle Traffic Director's HTTP client.

Table 5-29 describes the parameters for the http-client-config function.

Example

ObjectType fn="http-client-config" keep-alive="false"

5.5.30 proxy-cache-config

The proxy-cache-config function configures reverse proxy cache settings.

Table 5-30 describes the parameters for the proxy-cache-config function.

Example

ObjectType fn="proxy-cache-config" enable="1" max-reload-interval=300 min-reload-interval=60

5.5.31 proxy-cache-override-http

The proxy-cache-override-http function configures reverse proxy cache parameters that override certain HTTP caching rules.

Table 5-31 describes the parameters for the proxy-cache-override-http function.

Example

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

5.5.32 proxy-websocket-config

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-32 describes the parameters for the proxy-cache-override-http function.

Example

ObjectType fn="proxy-websocket-config"

5.5.33 reverse-block-date

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.

Example

ObjectType fn="reverse-block-date"

5.5.34 reverse-block-server

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.

Example

ObjectType fn="reverse-block-server"

5.5.35 reverse-forward-date

The reverse-forward-date SAF forwards the Date header sent from the origin server. In Oracle Traffic Director, this is the default behavior.

Example

ObjectType fn="reverse-forward-date"

5.5.36 reverse-forward-server

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.

Example

ObjectType fn="reverse-forward-server"

5.5.37 set-basic-auth

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.

Example

ObjectType fn="set-basic-auth" user="admin" password="secret" hdr="proxy-authorization"

5.5.38 set-cache-control

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.

The following table describes some of the useful cache control directives defined by the HTTP/1.1 protocol.

Example

ObjectType fn="set-cache-control" control="private,max-age=60"

5.5.39 set-cookie

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.

Example

<If not defined $cookie{'FIRSTVISITTIME'}>
ObjectType fn="set-cookie"
           name="FIRSTVISITTIME"
           value="$time"
           max-age="31536000"
</If>

5.5.40 ssl-client-config

The ssl-client-config function configures options used when Oracle Traffic Director connects to a origin server using SSL/TLS.

Table 5-37 describes the parameters for the ssl-client-config function.

Example

ObjectType fn="ssl-client-config" validate-server-cert="false"

5.5.41 type-by-exp

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-38 describes the parameters for the type-by-exp function.

Example

ObjectType fn="type-by-exp" exp="*.test" type="application/html"

5.5.42 type-by-extension

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.

Example

ObjectType fn="type-by-extension"

5.6.1 sed-request

The sed-request filter applies the sed edit commands to an incoming request entity body, for example, an uploaded file or submitted form.

Table 5-40 describes the parameters for sed-request.

Example

The following obj.conf code instructs sed-request to encode any (<) and (>) characters posted in an HTML form:

Input fn="insert-filter"
      method="POST"
      filter="sed-request"
      sed="s/</\\&lt;/g"
      sed="s/%3c/\\&lt;/g"
      sed="s/%3C/\\&lt;/g"
      sed="s/>/\\&gt;/g"
      sed="s/%3e/\\&gt;/g"
      sed="s/%3E/\\&gt;/g"

Because POST bodies are usually URL-encoded, it is important to check for URL-encoded forms when editing POST bodies. %3C is the URL-encoded form of (<) and %3E is the URI-encoded form of (>).

5.7.1 sed-response

The sed-response filter applies the sed edit commands to an incoming request entity body, for example, an uploaded file or submitted form.

Table 5-42 describes the parameters for sed-response.

Example

The following obj.conf code instructs sed-response to rewrite any occurrence of http://127.0.0.1/ in an HTML response to http://server.example.com/:

Output fn="insert-filter"
       type="text/html"
       filter="sed-response"
       sed="s|http://127.0.0.1/|http://server.example.com/|g"

5.8.1 set-origin-server

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-43 describes the parameters for the set-origin-server function.

Example

Route fn="set-origin-server" origin-server-pool="origin-server-pool-1"

5.9.1 proxy-retrieve

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-45 describes the parameters for the proxy-retrieve function.

Example

# Normal proxy retrieve
Service fn="proxy-retrieve"
# Proxy retrieve with POST method disabled
Service fn="proxy-retrieve"
     method="(POST)"

5.9.2 remove-filter

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.

Example

Service fn="remove-filter"

5.9.3 service-proxy-cache-dump

The service-proxy-cache-dump function dumps the current reverse proxy caching statistics.

Table 5-47 describes the parameters for the service-proxy-cache-dump function.

Example

<Object name="default"
NameTrans fn=assign-name name="proxy-cache" from="/.proxycache"
</Object>
<Object name="proxy-cache">
    Service fn="service-proxy-cache-dump"
</Object>

5.9.4 service-trace

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-48 describes the parameters for the service-trace function.

Example

<Object name="default">
...
Service method="TRACE" fn="service-trace"
...
</Object>

5.9.5 stats-xml

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.

Example

<Object name="default">
<If uri = "/stats-xml/*">
Service fn="stats-xml"
</If>
...
</Object>

5.10.1 flex-log

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-50 describes the parameters for the flex-log function.

Example

# 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>

5.11.1 qos-error

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-51 describes the parameters for the qos-error function.

Example

Error fn="qos-error" code="503"

5.11.2 send-error

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-52 describes the parameters for the send-error function.

Example

Error fn="send-error" code="401" path="/opt/oracle/webserver7/docs/errors/401.html"

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

Input fn="insert-filter" filter="http-decompression"

5.12.2 match-browser

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.

Syntax

stage fn="match-browser" browser="string" name="value" [name="value" ...]

Parameters

The following table describes parameter values for the match-browser function.

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

5.12.3 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, 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-56 describes the parameters for the redirect function.

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"

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

Input fn="remove-filter" filter="http-compression"

5.12.5 restart

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.

Example

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"

5.12.6 set-variable

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.

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.

Variables

The following tables lists variables supported by the set-variable SAF.

<Client code="302">
Output fn="set-variable" error="301 Moved Permanently"
     noaction="true"
</Client>

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