... *Back to [[Book|Administrator's Configuration File Reference#cfr]] [[Topic|Administrator's Configuration File Reference#chap6]]*
h2. 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:
{code}
<Object name="cgi">
{code}
{code}
<Object ppath="/usr/sun/webserver7/https-server/docs/private/*">
{code}
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].
h3. 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}}:
{code}
<Object name="default">
NameTrans fn="pfx2dir"
from="/cgi"
dir="D:/sun/webserver7/https-server/docs/mycgi"
name="cgi"
...
</Object>
{code}
When the {{NameTrans}} directive is executed, the server starts processing directives in the object named {{cgi}}:
{code}
<Object name="cgi">
...
</Object>
{code}
h3. 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:
{code}
<Object name="default">
NameTrans fn="document-root"
root="D:/sun/webserver7/https-server/docs"
...
</Object>
{code}
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:
{code}
<Object ppath="*internal*">
</Object>
{code}
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.
h3. 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]
h4. Client {anchor:conf61}
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.
h5. 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). |
|{{variable-headers}} |Prevents access to a specific site, based on the request by the client. For example,
{code}
Client variable-headers="Weferer:SKVFVWRKJVZCMHVIBGDA
Service type="image/*" fn="deny-existence"
</Client>
{code} |
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:
{code}
<Client odds="25%">
NameTrans fn="redirect"
from="/Pogues"
url-prefix="http://pogues.example.com"
</Client>
{code}
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:
{code}
<Client ip="*~192.85.250.*">
AddLog fn="flex-log" name="access"
</Client>
{code}
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}}:
{code}
<Client match="none" ip="192.85.250.*" urlhost="www.sun.com">
AddLog fn="flex-log" name="access"
</Client>
{code}
For more information about wildcard patterns, see [Appendix B: Using Wildcard Patterns|Administrator's Configuration File Reference#appB].
h4. If, ElseIf, and Else {anchor:conf62} |
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}}, {{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:
{code}
<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>
{code}
This example presents a different page based on whether the browser is Microsoft Internet Explorer, Mozilla, or another browser. |