The obj.conf file contains directives for HTTP request processing. The obj.conf file is in the INSTANCE_HOME/net-configuration_name/config directory.
During the installation of Oracle Traffic Director, an obj.conf file is created. If you configure multiple virtual servers using the Oracle Traffic Director Administrator Console or Command-Line Interface (CLI), separate obj.conf files can be created for each virtual server. These files are named virtual-server-name-obj.conf, where virtual-server-name is the name of the virtual server.
When changes made through the Administrator Console or CLI do not impact the obj.conf file, no new virtual server specific obj.conf files are created, and the default obj.conf file will be used for all the virtual servers of the configuration.
When changes made through Administrator Console or CLI impact the obj.conf file, a new obj.conf file is created for each virtual server. The server.xml file is immediately updated to reflect the appropriate obj.conf file used for each virtual server. If there are two virtual servers, vs1 and vs2, two new virtual server specific obj.conf files are created, vs1-obj.conf and vs2-obj.conf. These new files are updated in the server.xml file with the exact object-file used by these two virtual servers.
<object-file>vs1-obj.conf</object-file>
<object-file>vs2-obj.conf</object-file>
From this point onward, the default obj.conf file is neither updated, used, nor deleted. However, if you want to modify the obj.conf file for either of the two virtual servers, you should edit the respective file only, not the original obj.conf file.
In this document, the obj.conf file refers to the obj.conf file specified by the object-file sub element of the virtual-server element in the server.xml file.
This chapter describes the obj.conf directives; the use of Object, Client, If, ElseIf, and Else tags; the flow of control in obj.conf; and the syntax rules for editing obj.conf.
This chapter includes the following topics:
When you first start Oracle Traffic Director, it performs some initialization tasks and then waits for an HTTP request from a client (such as a browser). When Oracle Traffic Director receives a request, it first selects a virtual server. The obj.conf file of the selected virtual server determines how Oracle Traffic Director handles a request.
The obj.conf file contains a series of instructions known as directives that tell Oracle Traffic Director what to do at each stage in the request-handling process. These directives are grouped inside Object tags. Each directive invokes a function with one or more arguments.
Each directive is applied to a specific stage in the request-handling process. For example, a directive that is applied during the authorization stage in the request-handling process is an AuthTrans directive.
AuthTrans (authorization translation)
Verify the authorization information (such as name and password) sent in the request.
Translate the logical URI into a local file system path.
Check the local file system path for validity and check if the requestor has access privileges to the requested resource on the file system.
Controls the flow of information from Oracle Traffic Director to the origin server and also configures Oracle Traffic Director to origin server connection attributes.
Select filters that will process incoming request data read by the Service step.
Output (prepare to send output)
Select filters that will process outgoing response data generated by the Service step.
Select where to route the request.
Service (generate the response)
Generate and return the response to the client.
Add entries to log files.
Send an error message to the client and exit processing. This step is executed only if an error occurs in the previous steps.
The directives in the obj.conf file invoke functions known as server application functions (SAFs). Each directive calls a function, indicating when to call it and specifying parameters for it.
The syntax of each directive is:
Directive fn="function" name1="value1"...nameN="valueN"
The value of the function (fn) parameter is the name of the SAF to execute. All directives must supply a value for the fn parameter; if there is no function, the instruction does nothing. The remaining parameters are the arguments needed by the function, and they vary from function to function.
Parameters can contain references to variables and expressions. The variables can be predefined variables, variables defined at request time using the set-variable SAF, or variables defined in the server.xml file. For more information about the set-variable SAF, see Section 5.12.11, "set-variable". For more information about defining variables in the server.xml file, see Section 3.1.39, "variable". For more information about expressions and variables, see Appendix A, "Using Variables, Expressions, Wildcards, and String Interpolation".
Oracle Traffic Director has a set of built-in SAFs that you can use to create and modify directives in the obj.conf file. Section 5, "Predefined Server Application Functions and Filters in obj.conf" describes these SAFs in detail.
The magnus.conf file contains Init directive SAFs that initialize NASPI plug-ins.
Directives in the obj.conf file are grouped into Object tags. The default object contains instructions to Oracle Traffic Director about how to process requests by default. Each new object modifies the default behavior of the object.
An Object tag can contain a name or ppath attribute. Either parameter can be a wildcard pattern.
Oracle Traffic Director starts handling a request by processing the directives in the default object. However, Oracle Traffic Director 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 Oracle Traffic Director 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, Oracle Traffic Director stops processing directives in that particular stage (such as the Service stage) as soon as one is successfully executed. Whereas for other stages, Oracle Traffic Director processes all directives in that stage, including the ones in the default object and those in the additional object. For more information, see Flow of Control in obj.conf.
If a NameTrans directive in the default object specifies a name argument, Oracle Traffic Director switches to processing the directives in the object of that name before processing the remaining directives in the default object.
When Oracle Traffic Director completes processing the NameTrans directives in the default object, the logical URL of the request is converted to a physical path name. If this physical path name matches the ppath attribute of another object in the obj.conf file, Oracle Traffic Director switches to processing the directives in that object before processing the remaining ones in the default object.
Additional tags are available to use within the Object tag. These tags give you greater flexibility when invoking directives within an object.
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.
Table 4-1 describes the parameters for the Client tag.
Table 4-1 Client Tag Parameters
| Parameter | Description |
|---|---|
|
|
The |
|
|
A Boolean value set by a client requesting chunked encoding. |
|
|
The HTTP response code. |
|
|
The DNS name of the client. |
|
|
The Boolean value indicating internally generated request. |
|
|
The IP address of the client. |
|
|
The Boolean value indicating whether the client has requested a keep-alive connection. |
|
|
The key size used in an SSL transaction. |
|
|
The match mode for the |
|
|
The HTTP method used by the browser. |
|
|
The name of an object as specified in a previous |
|
|
A random value for evaluating the enclosed directive. The value can be a percentage or a ratio (for example, 20% or 1/5). |
|
|
The physical path to the requested resource. |
|
|
The physical path of the requested resource. |
|
|
The query string sent in the request. |
|
|
The text version of the HTTP response code. |
|
|
A Boolean value indicating that a request was restarted. |
|
|
The secret key size used in an SSL transaction. |
|
|
An encrypted request. |
|
|
The type of document requested (such as |
|
|
The URI section of the request from the browser. |
|
|
The DNS name of the virtual server requested by the client. (The value is provided in the |
|
|
Prevents access to a specific site, based on the request by the client, for example: Client variable-headers="Weferer:SKVFVWRKJVZCMHVIBGDA Service type="image/*" fn="deny-existence" </Client> |
The Client tag parameter provides greater control when the If directive is executed. In the following example, 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 Oracle Traffic Director 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 example.com:
<Client match="none" ip="192.85.250.*" urlhost="www.example.com"> AddLog fn="flex-log" name="access" </Client>
For more information about wildcard patterns, see Section A.5, "Wildcard Patterns".
Similar to 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. For more information, see Section A.1, "If, ElseIf, and Else Tags".
Before Oracle Traffic Director can process a request, it must direct the request to the correct virtual server. After the virtual server is determined, Oracle Traffic Director executes the obj.conf file of the specified virtual server. This section describes how Oracle Traffic Director determines the directives to execute in obj.conf.
When Oracle Traffic Director receives a request, it executes the AuthTrans directives in the default object to check if the client is authorized to access Oracle Traffic Director. If there is more than one AuthTrans directive, Oracle Traffic Director executes them in sequence until one succeeds in authorizing the user, unless one of them results in an error. If an error occurs, Oracle Traffic Director skips all other directives except for the Error directive.
AuthTrans directives work in conjunction with the PathCheck directives. The AuthTrans directive checks if the user name and password associated with the request are acceptable, but it does not allow or deny access to the request; that is done by the PathCheck directive.
The authorization process is split into two steps to incorporate multiple authorization schemes easily and provide the flexibility to have resources that record authorization information.
When a client initially makes a request, the user name and password are unknown. The AuthTrans directive gets the user name and password from the headers associated with the request. The AuthTrans and PathCheck directives work together to reject the request if they cannot validate the user name and password. When a request is rejected, Oracle Traffic Director displays a dialog box. The client includes the user name and password in the headers and resubmits the request.
Oracle Traffic Director executes NameTrans directives in the default object to associate a named object (for example, an object that specifies the routing rules) with the URL of the requested resource.
Oracle Traffic Director evaluates each NameTrans directive in the default object in turn, until it finds one that can be applied.
Because Oracle Traffic Director might not execute all NameTrans directives, the order in which the directives appear is important.
As a result of executing a NameTrans directive, Oracle Traffic Director might start processing directives in another object. This happens if the NameTrans directive that was successfully executed specifies a name or generates a partial path that matches the name or ppath attribute of another object.
If the successful NameTrans directive assigns a name by specifying a name argument, Oracle Traffic Director starts processing directives in the named object (defined with the object tag) before processing directives in the default object for the rest of the request-handling process.
After converting the logical URL of the requested resource to a physical path name in the NameTrans step, Oracle Traffic Director executes PathCheck directives to verify that the client is allowed to access the requested resource.
If there is more than one PathCheck directive, Oracle Traffic Director executes all directives in the order in which they appear, unless one of the directives denies access. If access is denied, Oracle Traffic Director switches to executing directives in the Error section.
If the NameTrans directive assigned a name or generated a physical path name that matches the name or ppath attribute of another object, Oracle Traffic Director first applies the PathCheck directives in the matching object before applying the directives in the default object.
Assuming that the PathCheck directives approve access, Oracle Traffic Director next executes the ObjectType directives to determine the MIME type of the request. The MIME type has three attributes: type, encoding, and language. When Oracle Traffic Director sends the response to the client, the type, language, and encoding values are transmitted in the headers of the response. The type also frequently helps Oracle Traffic Director to determine which Service directive to execute to generate the response to the client.
If there is more than one ObjectType directive, Oracle Traffic Director applies all directives in the order in which they appear. However, once a directive sets an attribute of the MIME type, further attempts to set the same attribute are ignored. The reason why all ObjectType directives are applied is that one directive can set one attribute, for example type, while another directive sets a different attribute, such as language.
As with the PathCheck directives, if another object was matched to the request as a result of the NameTrans step, Oracle Traffic Director executes the ObjectType directives in the matching object before executing the ObjectType directives in the default object.
The Input directive selects filters that process incoming request data read by the Service step. Input directives are invoked when Oracle Traffic Director or plug-in first attempts to read entity body data from the client. You can add the NSAPI filters that process incoming data by invoking the insert-filter SAF in the Input stage of the request-handling process. NSAPI filters enable a function to intercept and potentially modify the content presented to or generated by another function. The Input directives are executed once per request.
The order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf is important if two or more filters are defined to be in the same location in the filter stack. Filters that were inserted later appear higher than filters that were inserted earlier.
The Output directive selects filters that process outgoing response data generated by the Service step. The Output directive allows you to invoke the insert-filter SAF to install NSAPI filters that process outgoing data. NSAPI filters enable a function to intercept and potentially modify the content presented to or generated by another function. Output directives are executed when Oracle Traffic Director or a plug-in first attempts to write entity body data from the client. The Output directives are executed once per request.
The order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf is important if two or more filters are defined to be in the same location in the filter stack. Filters that were inserted later appear higher than filters that were inserted earlier.
If a Service directive requires that the HTTP request be sent to another server, Oracle Traffic Director executes Route directives to determine how the request be routed. Routing a request can involve selecting Oracle Traffic Director that will service the request and selecting a proxy through which the request is sent.
Oracle Traffic Director executes a Service directive to generate the response to send to the client. Oracle Traffic Director looks at each Service directive to find the first one that matches the type, method, and query string. If a Service directive does not specify type, method, or query string, then the unspecified attribute matches anything.
If there is more than one Service directive, Oracle Traffic Director applies the first one that matches the conditions of the request and ignores all remaining Service directives.
For the PathCheck and ObjectType directives, if another object was matched to the request as a result of the NameTrans step, Oracle Traffic Director checks the Service directives in the matching object before considering the ones in the default object. If Oracle Traffic Director successfully executes a Service directive in the matching object, it does not execute the Service directives in the default object, because it only executes one Service directive.
After Oracle Traffic Director generates the response and sends it to the client, it executes AddLog directives to add entries to the log files. All AddLog directives are executed. Oracle Traffic Director can add entries to multiple log files.
If an error occurs during the request-handling process, for example, if a PathCheck or AuthTrans directive denies access to the requested resource or the requested resource does not exist, the SAF sets the HTTP response status code and returns the value REQ_ABORTED. When this happens, Oracle Traffic Director stops processing the request. Instead, it searches for an Error directive matching the HTTP response status code or its associated reason phrase and executes the directive's function. If Oracle Traffic Director does not find a matching Error directive, it returns the response status code to the client.
There are times when the function flow changes from the normal request-handling process. This happens during internal redirection, restarts, and URI translation functions.
Requests can be restarted, for example, a PathCheck directive might restart a request for http://server_name/ as a request for http://server_name/index.html.
Oracle Traffic Director can generate internal requests, for example, an SHTML file or servlet might include a file. While processing the original request, Oracle Traffic Director makes an internal request to retrieve this file.
Use caution when making changes to this file. Simple mistakes can make Oracle Traffic Director fail to start or operate incorrectly.
The order of directives is important, because Oracle Traffic Director executes them in the order in which they appear in obj.conf. The outcome of some directives affects the execution of other directives.
For PathCheck directives, the order within the PathCheck section is not important because Oracle Traffic Director executes all PathCheck directives. However, the order within the ObjectType section is very important, because if an ObjectType directive sets an attribute value, no other ObjectType directive can change that value.
Similarly, the order of directives in the Service section is very important. Oracle Traffic Director executes the first Service directive that matches the current request and does not execute the others.
The number and names of parameters depend on the function. The order of parameters on the line is not important.
Items in the obj.conf file are case-sensitive including function names, parameter names, parameter values, and path names.
Function names in the C language can be composed of letters, digits, and underscores. You can use the hyphen (-) in the configuration file in place of underscore (_) for your C code function names. This is only true for function names.
Quotation marks (") are only required around value strings when there is a space in the string. Otherwise, they are optional. Each open quotation mark must be matched by a closed quotation mark.
Spaces are not allowed at the beginning of a line except when continuing from the previous line.
Spaces are not allowed before or after the equal sign (=) that separates the name and value.
Spaces are not allowed at the end of a line or on a blank line.
A long line may be continued on the next line by beginning the next line with a space or tab.
Always use forward slashes (/), in path names. A backslash escapes the next character.