Objects in obj.conf

Directives in the obj.conf file are grouped into Object tags. The default object contains instructions to the server on how to process requests by default. Each new object modifies the default object’s behavior.

An Object tag may contain a name or ppath attribute. Either parameter can be a wildcard pattern. For example:

<Object name="cgi">

<Object ppath="/usr/sun/webserver7/https-server/docs/private/*">

The server always starts handling a request by processing the directives in the default object. However, the server switches to processing directives in another object after the NameTrans stage of the default object if either of the following conditions is true:

• The successful NameTrans directive specifies a name argument.

• The physical path name that results from the NameTrans stage matches the ppath attribute of another object.

When the server is alerted to use an object other than the default object, it processes the directives in the other object before processing the directives in the default object. For some steps in the process, the server stops processing directives in that particular stage (such as the Service stage) as soon as one is successfully executed, whereas for other stages the server processes all directives in that stage, including the ones in the default object as well as those in the additional object. For more details, see Flow of Control in obj.conf.

Objects That Use the name Attribute

If a NameTrans directive in the default object specifies a name argument, the server switches to processing the directives in the object of that name before processing the remaining directives in the default object.

For example, the following NameTrans directive in the default object assigns the name cgi to any request whose URL starts with http://server_name/cgi:

<Object name="default">
NameTrans fn="pfx2dir"
          from="/cgi"
          dir="D:/sun/webserver7/https-server/docs/mycgi"
          name="cgi"
...
</Object>

When the NameTrans directive is executed, the server starts processing directives in the object named cgi:

<Object name="cgi">
...
</Object>

Objects That Use the ppath Attribute

When the server completes processing the NameTrans directives in the default object, the logical URL of the request has been converted to a physical path name. If this physical path name matches the ppath attribute of another object in obj.conf, the server switches to processing the directives in that object before processing the remaining ones in the default object.

For example, the following NameTrans directive translates the http://server_name/ part of the requested URL to D:/sun/webserver7/https-server/docs/, the document root directory:

<Object name="default">
NameTrans fn="document-root" 
          root="D:/sun/webserver7/https-server/docs"
...
</Object>

In this example, the URL http://server_name/internalplan1.html is translated to D:/sun/webserver7/https-server/docs/internalplan1.html.

However, if obj.conf contains the following additional object:

<Object ppath="*internal*">
   
</Object>

In this example, the partial path *internal* matches the path D:/sun/webserver7/https-server/docs/internalplan1.html. The server starts processing the directives in this object before processing the remaining directives in the default object.

Using the Client, If, ElseIf, and Else Tags

Additional tags are available to use within the Object tag. These tags give you greater flexibility when invoking directives within an object. This section contains the following sections:

• Client

• If, ElseIf, and Else

Client

The Client tag enables you to limit the execution of a set of directives to requests received from specific clients. Directives listed within the Client tag are executed only when information in the client request matches the parameter values specified.

Client Tag Parameters

The following table lists the Client tag parameters.

Table 6–1 Client Tag Parameters

Parameter	Description
browser	The User-Agent string sent by a browser to the Web Server.
chunked	A Boolean value set by a client requesting chunked encoding.
code	The HTTP response code.
dns	The DNS name of the client.
internal	The Boolean value indicating internally generated request.
ip	The IP address of the client.
keep-alive	The Boolean value indicating whether the client has requested a keep-alive connection.
keysize	The key size used in an SSL transaction.
match	The match mode for the Client tag. The valid values are all, any, and none.
method	The HTTP method used by the browser.
name	The name of an object as specified in a previous NameTrans statement.
odds	A random value for evaluating the enclosed directive. The value can be a percentage or a ratio (for example, 20% or 1/5).
path	The physical path to the requested resource.
ppath	The physical path of the requested resource.
query	The query string sent in the request.
reason	The text version of the HTTP response code.
restarted	A Boolean value indicating that a request has been restarted.
secret-keysize	The secret key size used in an SSL transaction.
security	Indicates an encrypted request.
type	The type of document requested (such as text/html or image/gif).
uri	The URI section of the request from the browser.
urlhost	The DNS name of the virtual server requested by the client (the value is provided in the Host header of the client request).

The Client tag parameter provides greater control when the If directive is executed. In the following example, use of the odds parameter gives the request a 25% chance of being redirected:

<Client odds="25%">
NameTrans fn="redirect"
          from="/Pogues"
          url-prefix="http://pogues.example.com"
</Client>

One or more wildcard patterns can be used to specify the Client tag parameter values. Wildcards can also be used to exclude clients that match the parameter value specified in the Client tag. In the following example, the Client tag and the AddLog directive are combined to direct the Web Server to log access requests from all clients except those from the specified subnet:

<Client ip="*~192.85.250.*">
AddLog fn="flex-log" name="access"
</Client>

You can also create a negative match by setting the match parameter of the Client tag to none. In the following example, access requests from the specified subnet are excluded as are all requests to the virtual server sun.com:

<Client match="none" ip="192.85.250.*" urlhost="www.sun.com">
AddLog fn="flex-log" name="access"
</Client>

For more information about wildcard patterns, see Appendix B, Using Wildcard Patterns.

If, ElseIf, and Else

The If, ElseIf, and Else tags enable you to define the conditions under which to execute a set of directives. Like the Client tag, these tags can only appear inside an Object tag. In addition, these tags can evaluate an expression, then conditionally execute one or more contained directives. However, there are some key differences between the these tags and the Client tag, as summarized below:

• If and ElseIf tags offer a richer expression syntax, including support for regular expressions. This expression syntax is different from the Client syntax. For more information on the If and ElseIf expression syntax, see Expressions.

• If, ElseIf, and Else tags can contain other tags.

• If and ElseIf expressions are evaluated once per request, not once per contained directive.

• If, ElseIf, and Else tags cannot contain multiple types of directives.

• Directives within the If and ElseIf tags can contain regular expression backreferences.

When used, an ElseIf or Else tag must immediately follow an If or ElseIf tag. ElseIf and Else tags are skipped if the preceding If or ElseIf expression evaluates to logical true.

The following example shows If, ElseIf, and Else tag syntax:

<If $path eq "/">
<If $browser =~ "MSIE">
NameTrans fn="rewrite" path="/msie.html"
</If>
<ElseIf $browser =~ "Mozilla">
NameTrans fn="rewrite" path="/mozilla.html"
</ElseIf>
<Else>
NameTrans fn="rewrite" path="/unknown.html"
</Else>
</If>

This example presents a different page based on whether the browser is Microsoft Internet Explorer, Mozilla, or another browser.