Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference

Chapter 4 Syntax and Use of the `obj.conf` File

The obj.conf configuration file contains directives that instruct Proxy Server how to handle HTTP and HTTPS requests from clients. You can modify and extend the request-handling process by adding or changing the instructions in obj.conf.

All obj.conf files are located in the instance-dir/config directory, where instance-dir is the path to the installation directory of the server instance.

By default, the obj.conf file for the server is named obj.conf.

This chapter discusses server instructions in obj.conf, the use of OBJECT tags, the use of variables, the flow of control in obj.conf, the syntax rules for editing obj.conf, and a note about example directives.

Note –

For detailed information about the standard directives and predefined Server Application Functions (SAFs) that are used in the obj.conf file, see Chapter 5, Predefined SAFs in the obj.conf File.

This chapter contains the following sections:

How the Proxy Server Functions

“Proxy” is a general term that means “to act on behalf of a user in an authorized capacity.” A web proxy server intercepts client connections and obtains the requested content from an origin server, the owner of the content on behalf of the client.

A typical web proxy accepts connections from clients, makes decisions as to whether the clients are permitted to use the proxy or access the requested resources, and then completes connections on behalf of the clients to the various origin servers. In this manner, the web proxy acts as both a server as well as a client of the requested resource.

The two basic types of web proxy server are: a forward proxy and a reverse proxy. While they share much of the same functionality, some definite differences exist between the two types.

Forward Proxy Scenario

A Forward proxy provides internal clients access through a firewall to resources on the Internet. This service is often provided as part of a larger intranet security strategy. Forward proxying allows clients to access resources outside of the firewall without compromising the integrity of the private network.

A forward proxy can be configured to keep copies of content within their local cache. Subsequent requests for that content can then be serviced from the local cache rather than obtaining the content from the origin server. Caching increases performance by decreasing the time involved in traversing the network.

Most proxy servers have the capability to filter requests from users. Administrators can choose to limit access to certain resources that might not be appropriate for the workplace and therefore deny such access.

In a forward proxy scenario, the client is aware of the proxy server and is configured to use it for various requests. The firewall can then be configured to allow only certain traffic from the proxy server rather than permitting such access to all internal clients.

Reverse Proxy Scenario

A proxy server can also provide external clients with access to internal resources the reside behind the corporate firewall. When a proxy server is used to handle connections into a private network, the process is called reverse proxying. The term “reverse” refers to the fact that traffic flows in the opposite direction from normal proxy traffic flow.

A forward proxy is best used to filter content, increase performance, and log user accesses. A reverse proxy provides these benefits and more. You can use a reverse proxy to load balance across multiple servers, provide failover capabilities, and provide access to corporate resources in a safe and secure manner.

In a reverse proxy scenario, the client is not even aware that it is using a proxy server. This transparency is one of the key differences between a forward and reverse proxy server scenario.

URL Mapping

The URL Mapping feature enables the Proxy Server to function as a reverse proxy or a junction by acting as a front-end server. Based on the client's URI, access is provided to the back-end application servers.

The features included in URL Mapping are:

URL Mapping
URL rewriting in HTTP headers, HTML content, JavaScript, and Style Sheets
Per-application cookie management
Pass-through cookies, including cookie renaming
Junction selection based on a last-seen cookie

For information on the Server Application Functions (SAFs) used in URL Mapping, see Server Application Functions (SAFs).

NSAPI Filters

The NSAPI API enables multiple Server Application Functions (SAFs) to interact in request processing. For example, one SAF can be used to authenticate the client after which a second SAF would generate the content.

Request-Handling Process

At startup, the server performs some initialization and then waits for a request from a client, such as a browser.

The obj.conf file for the server specifies how the request is handled.

Init - Loads and initializes server modules and plugins, and initializes log files.
AuthTrans (authorization translation) - Verifies any authorization information (such as name and password) sent in the request.
NameTrans (name translation) - Translates the logical URI into a local file system path.
PathCheck (path checking) - Checks the local file system path for validity and checks that the requestor has access privileges to the requested resource on the file system.
ObjectType (object typing) - Determines the MIME-type (Multi-purpose Internet Mail Encoding) of the requested resource (for example, text/html, image/gif, and so on).
Input (prepare to read input) - Selects filters that will process incoming request data read by the Service step.
Output (prepare to send output) - Selects filters that will process outgoing response data generated by the Service step.
Service (generate the response) - Generates and returns the response to the client.
AddLog (adding log entries) - Adds entries to log file(s).
Error (service) - Executes only if an error occurs in the previous steps. If an error occurs, the server logs an error message and aborts the process.
Connect - Calls the connect function you specify.
DNS - Calls either the dns-config built-in function or a DNS function that you specify.
Filter - Runs an external command and then sends the data through the external command before processing that data in the proxy.
Route - Specifies information about where the proxy server should route requests.

Directives for Handling Requests

The obj.conf file contains a series of instructions, known as directives, that tell Proxy Server what to do at each stage in the request-handling process. Each directive invokes a Server Application Function (SAF) with one or more arguments. Each directive applies to a specific stage in the request-handling process. The stages are Init, AuthTrans, NameTrans, PathCheck, ObjectType, Input, Output, Service, AddLog, Connect, DNS, Filter, and Route.

Dynamic Reconfiguration

You do not need to restart the server for changes to certain configuration files to take effect (for example, obj.conf, mime.types, and server.xml,). All you need to do is apply the changes by clicking the Apply link and then clicking the Load Configuration Files button on the Apply Changes screen. If there are errors in installing the new configuration, the previous configuration is restored.

When you edit obj.conf and apply the changes, a new configuration is loaded into memory that contains all of the information from the dynamically configurable files.

Every new connection references the newest configuration. Once the last session referencing a configuration ends, the now unused old configuration is deleted.

Server Instructions in `obj.conf`

The obj.conf file contains directives that instruct the server how to handle requests received from clients such as browsers. These directives appear inside OBJECT tags.

Each directive calls a function, indicating when to call it and specifying arguments for it.

The syntax of each directive is:

Directive fn=func-name name1="value1"...nameN="valueN"

For example:

Init fn="flex-init" access="$accesslog" format.access="%Ses->client.ip% 
	- %Req->vars.auth-user% [%SYSDATE%] ’%Req->reqpb.clf-request%’ 
	%Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%”

Directive indicates when this instruction is executed during the request-handling process. The value is one of Init, AuthTrans, NameTrans, PathCheck, ObjectType, Service, AddLog, Error, Connect, DNS, Filter, and Route.

The value of the fn argument is the name of the SAF to execute. All directives must supply a value for the fn parameter; if there’s no function, the instruction won’t do anything.

The remaining parameters are the arguments needed by the function, and they vary from function to function.

Proxy Server is shipped with a set of built-in Server Application Functions (SAFs) that you can use to create and modify directives in obj.conf.

Summary of the Directives

Following are the categories of server directives and a description of what each does. Each category corresponds to a stage in the request-handling process. The section Flow of Control in the obj.conf File explains how the server decides which directives to execute in each stage.

Init Directive - Loads and initializes server modules and plugins, and initializes log files.
AuthTrans Directive - Verifies any authorization information that is normally sent in the Authorization header provided in the HTTP request; and translates it into a user or a group. Server access control occurs in two stages. AuthTrans verifies the authenticity of the user. Later, PathCheck tests the user’s access privileges for the requested resource.
```
AuthTrans fn=basic-auth userfn=ntauth auth-type=basic userdb=none
```
This example calls the basic-auth function, which calls a custom function (in this case ntauth) to verify authorization information sent by the client. The Authorization header is sent as part of the basic server authorization scheme.
NameTrans Directive - Translates the URL specified in the request from a logical URL to a physical file system path for the requested resource. This process might also result in redirection to another site.
PathCheck Directive - Performs tests on the physical path determined by the NameTrans step. These tests determine whether the path is valid and whether the client is allowed to access the requested resource. For example:
```
PathCheck fn="find-index" index-names="index.html,home.html"
```
This example calls the find-index function with an index-names argument of index.html,home.html. If the requested URL is a directory, this function instructs the server to look for a file called either index.html or home.html in the requested directory.
ObjectType Directive - Determines the MIME type of the requested resource. The MIME type has attributes type, which indicates content type, encoding, and language. The MIME type is sent in the headers of the response to the client. The MIME type also helps determine which Service directive the server should execute.

The resulting type might be:
- A common document type such as text/html or image/gif. For example, the file name extension .gif translates to the MIME type image/gif.
- An internal server type. Internal types always begin with magnus-internal.
  
  For example:
```
ObjectType fn="type-by-extension"
```
  This example calls the type-by-extension function, which causes the server to determine the MIME type according to the requested resource’s file extension.
Input Directive - Selects filters that will process incoming request data read by the Service step. The Input directive allows you to invoke the insert-filter SAF in order to install filters that process incoming data. All Input directives are executed when the server or a plugin first attempts to read entity body data from the client. The Input directives are executed at most once per request. For example:
```
Input fn="insert-filter" filter="http-decompression"
```
This directive instructs the insert-filter function to add a filter named http-decompression to the filter stack, which would decompress incoming HTTP request data before passing it to the Service step.
Output Directive - Selects filters that will process outgoing response data generated by the Service step. The Output directive enables you to invoke the insert-filter SAF to install filters that process outgoing data. All Output directives are executed when the server or a plug-in first attempts to write entity body data from the client. The Output directives are executed at most once per request. For example:
```
Output fn="insert-filter" filter="http-compression"
```
This directive instructs the insert-filter function to add a filter named http-compression to the filter stack, which would compress outgoing HTTP response data generated by the Service step.
Service Directive - Generates and sends the response to the client. This process sets the HTTP result status, sets up response headers such as Content-Type and Content-Length, and generates and sends the response data. The default response is to invoke the send-file function to send the contents of the requested file along with the appropriate header files to the client.

The default Service directive is:
```
Service method="(GET|HEAD|POST)" fn="send-file"
```
This directive instructs the server to call the send-file function in response to any request whose method is GET, HEAD, or POST.

Another example:
```
Service method="(GET|HEAD)" fn="imagemap"
```
In this case, if the method of the request is either GET or HEAD, the function imagemap is called.
AddLog Directive - Adds an entry to a log file to record information about the transaction. For example:
```
AddLog fn="flex-log" name="access"
```
This example calls the flex-log function to log information about the current request in the log file named access.
Error Directive - Handles an HTTP error. This directive is invoked if a previous directive results in an error. Typically the server handles an error by sending a custom HTML document to the user describing the problem and possible solutions.

For example:
```
Error fn="send-error" reason="Unauthorized" path="D:/Oracle/Middleware/ProxyServer4
	/Server1/errors/unauthorized.html"
```
In this example, the server sends the file in D:/Oracle/Middleware/ProxyServer4/Server1/errors/unauthorized.html whenever a client requests a resource that it is not authorized to access.
Connect Directive - Calls the connect function you specify.

Only the first applicable Connect function is called, starting from the most restrictive object. Occasionally you might want to call multiple functions until a connection is established. The function returns REQ_NOACTION if the next function should be called. If it fails to connect, the return value is REQ_ABORT. If it connects successfully, the connected socket descriptor will be returned.
DNS Directive - Calls either the dns-config built-in function or a DNS function that you specify.
Filter Directive - Runs an external command and then pipes the data through the external command before processing that data in the proxy by using the pre-filter function.
Route Directive - Specifies information about where the proxy server should route requests.

Configuring HTTP Compression

When compression is enabled in the server, an entry gets added to the obj.conf file. A sample entry is shown below:

Output fn="insert-filter" filter="http-compression" type="text/*"

Depending on the options specified, this line might also contain these options:

vary="on" compression-level="9"

To restrict compression to documents of only a particular type, or to exclude browsers that don’t work well with compressed content, you would need to edit the obj.conf file, as discussed below.

The option that appears as type="text/*" restricts compression to documents that have a MIME type of text/*, For example, text/ascii, text/css, text/html, and so on. This can be modified to compress only certain types of documents. If you want to compress only HTML documents, for example, you would change the option to:

type="text/html"

Alternatively, you can specifically exclude browsers that are known to misbehave when they receive compressed content by using the <Client> tag as follows:

<Client match="none"\\
 browser="*MSIE [1-3]*"\\
 browser="*MSIE [1-5]*Mac*"\\
 browser="Mozilla/[1-4]*Nav*">
Output fn="insert-filter" filter="http-compression" type="text/*"
</Client>

This example restricts compression to browsers other than the following browsers:

Internet Explorer for Windows earlier than version 4
Internet Explorer for Macintosh earlier than version 6
Netscape Navigator/Communicator earlier than version 6

Internet Explorer on Windows earlier than version 4 may request compressed data at times, but does not correctly support it. Internet Explorer on Macintosh earlier than version 6 does the same. Netscape Communicator version 4.x requests compression, but only correctly handles compressed HTML. It will not correctly handle linked CSS or JavaScript code from the compressed HTML, so administrators often simply prevent their servers from sending any compressed content to that browser or earlier versions.

For more information about the <Client> tag, see Client Tag.

Object and Client Tags

This section discusses the use of <Object> and <Client> tags in the obj.conf file.

<Object> tags group directives that apply to requests for particular resources, while <Client> tags group directives that apply to requests received from specific clients.

These tags are described in the following topics:

Object Tag

Directives in the obj.conf file are grouped into objects that begin with an <Object> tag and end with an </Object> tag. The default object provides instructions to the server about how to process requests by default. Each new object modifies the default object’s behavior.

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

<Object name="cgi">

<Object ppath="/home/user1/Oracle/Middleware/ProxyServer4/server1/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 has been alerted to use an object other than the default object, the server 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. 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 the obj.conf File

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="
               <install-root>/
               <instance-directory>/mycgi" name="cgi"
...
</Object>

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

<Object name="cgi">

               more directives...</Object>

Objects that Use the ppath Attribute

When the server finishes processing the NameTrans directives in the default object, the logical URL of the request will have 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 install-root/instance-directory/mydir

The URL http://server_name/internalplan1.html would be translated to <install-root>/<instance-directory>/mydir/internalplan1.html. However, suppose that obj.conf contains the following additional object:

<Object ppath="*internal*">

               more directives...</Object>

In this case, the partial path *internal* matches the path install-root/instance-directory/mydir/internalplan1.html. The server then starts processing the directives in this object before processing the remaining directives in the default object.

Client Tag

The <Client> tag is used to limit execution of a set of directives to requests received from specific clients. Directives listed between the <Client> and </Client> tags 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 4–1 Client Tag Parameters


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

The <Client> tag parameters provide greater control over when and if directives are executed. In the following example, use of the odds parameter gives a 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 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>

Using the ~ wildcard negates the expression, which causes the Web Server to exclude clients from the specified subnet.

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 server www.mycompany.com

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

Variables Defined in server.xml

You can define variables in the server.xml file and reference them in an obj.conf file. For example, the following server.xml code defines and uses a variable called docroot:

<!DOCTYPE SERVER SYSTEM "server.dtd" [
<!ELEMENT LS (DESCRIPTION?,SSLPARAMS?)>
<!ATTLIST LS
          id ID #REQUIRED
          ip CDATA "any"
          port CDATA #REQUIRED
          security %boolean; "false"
          acceptorthreads CDATA "1"
          family CDATA #IMPLIED
          blocking %boolean; "false"
          servername CDATA #REQUIRED
>

You can reference the variable in obj.conf as follows:

NameTrans fn=document-root root="$docroot"

Using this docroot variable saves you from having to define document roots for virtual server classes in the obj.conf files. This variable also enables you to define different document roots for different virtual servers within the same virtual server class.

Note –

Variable substitution is allowed only in an obj.conf file, not in any other Proxy Server configuration files. Any variable referenced in an obj.conf file must be defined in the server.xml file.

Flow of Control in the `obj.conf` File

Before the server can process a request, it must direct the request to the correct server.

After the server is determined, the server executes the obj.conf file for the server. This section discusses how the server decides which directives to execute in obj.conf.

Init Directive

Loads and initializes server modules and plug-ins, and initialize log files.

AuthTrans Directive

When the server receives a request, it executes the AuthTrans directives in the default object to check that the client is authorized to access the server.

If the object includes more than one AuthTrans directive, the server executes them all unless one of them results in an error. If an error occurs, the server skips all other directives except for Error directives.

NameTrans Directive

After authorization, the server executes a NameTrans directive in the default object to map the logical URL of the requested resource to a physical path name on the server’s file system. The server looks at each NameTrans directive in the default object in turn, until the server finds one that can be applied.

If the default object contains more than one NameTrans directive, the server considers each directive until one succeeds.

The NameTrans section in the default object must contain exactly one directive that invokes the map function. For example:

NameTrans fn="map" from="<http://myserver> to http://yourserver

The pfx2dir (prefix to directory) function is used to set up additional mappings between URLs and directories. For example, the following directive translates the URL http://server-name/cgi/ into the directory path name install-root/instance-directory/docs/mycgi/:

NameTrans fn="pfx2dir" from="/cgi" dir="install-root/instance-directory/docs
	/mycgi"

If this directive appears after the one that calls document-root, it will never be executed and will result in the directory path name <install-root>/<instance-directory>/docs/cgi/ (not mycgi). This example illustrates why the directive that invokes document-root must be the last one in the NameTrans section.

How and When the Server Processes Other Objects

As a result of executing a NameTrans directive, the server might start processing directives in another object. This process 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, the server starts processing directives in the named object, which is defined with the OBJECT tag before processing directives in the default object for the rest of the request-handling process.

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="
               <install-root>/<
               instance-directory>/mycgi" name="cgi"
...
</Object>

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

<Object name="cgi">

               more directives...</Object>

When a NameTrans directive has been successfully executed, a physical path name will be associated with the requested resource. If the resultant path name matches the ppath (partial path) attribute of another object, the server starts processing directives in the other object before processing directives in the default object for the rest of the request-handling process.

For example, suppose obj.conf contains an object as follows:

<Object ppath="*internal*">

               more directives...</Object>

Now suppose the successful NameTrans directive translates the requested URL to the path name <install-root>/<instance-directory>/mydir/internalplan1.html. In this case, the partial path *internal* matches the path <install-root>/<instance-directory>/mydir/internalplan1.html. The server would then start processing the directives in this object before processing the remaining directives in the default object.

PathCheck Directive

After converting the logical URL of the requested resource to a physical path name in the NameTrans step, the server executes PathCheck directives to verify that the client is allowed to access the requested resource.

If the object contains more than one PathCheck directive, the server executes all of the directives in the order in which they appear, unless one of the directives denies access. If access is denied, the server 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, the server first applies the PathCheck directives in the matching object before applying the directives in the default object.

ObjectType Directive

Assuming that the PathCheck directives all approve access, the server next executes the ObjectType directives to determine the MIME type of the request. The MIME type has three attributes: type, encoding, and language. When the server 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 the server to determine which Service directive to execute to generate the response to the client.

If the object contains more than one ObjectType directive, the server applies all of the 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. All ObjectType directives are applied because one directive may set one attribute, for example type, while another directive sets a different attribute, such as language.

As with the PathCheck directives, if another object has been matched to the request as a result of the NameTrans step, the server executes the ObjectType directives in the matching object before executing the ObjectType directives in the default object.

Setting the Type by File Extension

Usually, the default way the server determines the MIME type is by calling the type-by-extension function. This function instructs the server to look up the MIME type according to the requested resource’s file extension in the MIME types table. This table is created during virtual server initialization by the MIME types file, which is usually called mime.types.

For example, the entry in the MIME types table for the extensions .html and.htm is usually:

type=text/html  exts=htm,html

This table indicates that all files with the extension .htm or .html are text files formatted as HTML, and the type is text/html.

If you make changes to the MIME types file, you must reconfigure the server before those changes can take effect.

Forcing the Type

If no previous ObjectType directive has set the type and the server does not find a matching file extension in the MIME types table, the type still has no value even after type-by-expression has been executed. If the server does not recognize the file extension, force the type to be text/plain, so that the content of the resource is treated as plain text. Another situation in which you can set the type regardless of the file extension is forcing all resources in the designated CGI directory to have the MIME type magnus-internal/cgi.

The function that forces the type is force-type.

For example, the following directives first instruct the server to look in the MIME types table for the MIME type. Then, if the type attribute has not been set (that is, the file extension was not found in the MIME types table), set the type attribute to text/plain.

ObjectType fn="type-by-extension"
ObjectType fn="force-type" type="text/plain"

If the server receives a request for a file abc.dogs, it looks in the MIME types table. When it does not find a mapping for the extension .dogs, it consequently does not set the type attribute. Because the type attribute has not already been set, the second directive is successful, forcing the type attribute to text/plain.

The following example illustrates another use of force-type. In this example, the type is forced to magnus-internal/cgi before the server gets a chance to look in the MIME types table. In this case, all requests for resources in http://server_name/cgi/ are translated into requests for resources in the directory <install-root>/<instance-directory>/mycgi/. Since a name is assigned to the request, the server processes ObjectType directives in the object named cgi before processing the ones in the default object. This object has one ObjectType directive, which forces the type to be magnus-internal/cgi.

NameTrans fn="pfx2dir" from="/cgi" dir="<
               install-root>/<
               instance-directory>/mycgi" name="cgi"
<Object name="cgi">
ObjectType fn="force-type" type="magnus-internal/cgi"
Service fn="send-cgi"
</Object>

The server continues processing all ObjectType directives including those in the default object. However, because the type attribute has already been set, no other directive can set it to another value.

Input Directive

The Input directive selects filters that will process incoming request data read by the Service step. This directive enables you to invoke the insert-filter SAF in order to install filters that process incoming data.

The Input directives are executed at most once per request.

You can define the appropriate position of a specific filter within the filter stack. For example, filters that translate content from XML to HTML are placed higher in the filter stack than filters that compress data for transmission. You can use the filter_create function to define the filter’s position in the filter stack, and init-filter-order to override the defined position.

When two or more filters are defined to occupy the same position in the filter stack, filters that were inserted later will appear higher than filters that were inserted earlier. The order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf is important.

Output Directive

The Output directive selects filters that will process outgoing response data generated by the Service step. The Output directive enables you to invoke the insert-filter SAF to install filters that process outgoing data. All Output directives are executed when the server or a plugin first attempts to write entity body data from the client.

The Output directives are executed at most once per request.

You can define the appropriate position of a specific filter within the filter stack. For example, filters that translate content from XML to HTML are placed higher in the filter stack than filters that compress data for transmission. You can use the filter_create function to define the filter’s position in the filter stack, init-filter-order to override the defined position.

Service Directive

Next, the server executes a Service directive to generate the response to send to the client. The server looks at each Service directive in turn, 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 the object contains more than one Service directive, the server applies the first one that matches the conditions of the request, and ignores all remaining Service directives.

As with the PathCheck and ObjectType directives, if another object has been matched to the request as a result of the NameTrans step, the server considers the Service directives in the matching object before considering the ones in the default object. If the server successfully executes a Service directive in the matching object, it will not execute the Service directives in the default object, because it only executes one Service directive.

Service Examples

Assume that the PathCheck directives all succeed.
The following ObjectType directive tells the server to look up the resource’s MIME type in the MIME types table:
```
ObjectType fn="type-by-extension"
```
The server finds the following entry in the MIME types table, which sets the type attribute to text/html:
```
type=text/html exts=htm,html
```
The server invokes the following Service directive. The value of the type parameter matches anything that does not begin with magnus-internal/. This directive sends the requested file, jos.html, to the client.

Service method="(GET|HEAD|POST)" fn="send-file""

The following example uses another object:

The NameTrans directive assigns the name personnel to the request.

NameTrans fn=assign-name name=personnel from=/personnel

As a result of the name assignment, the server switches to processing the directives in the object named personnel. This object is defined as:

<Object name="personnel">
 Service fn="index-simple"
 </Object>

The personnel object has no PathCheck or ObjectType directives, so the server processes the PathCheck and ObjectType directives in the default object. Assume that all PathCheck and ObjectType directives succeed.
When processing Service directives, the server starts by considering the Service directive in the personnel object, which is:
```
Service fn="index-simple"
```
The server executes this Service directive, which calls the index-simple function.

Since a Service directive has now been executed, the server does not process any other Service directives. However, if the matching object had not had a Service directive that was executed, the server would continue looking at Service directives in the default object.

Default Service Directive

AService directive usually performs the default task, sending a file if no other Service directive matches a request sent by a browser. This default directive must come last in the list of Service directives in the default object to ensure it only gets called if no other Service directives have succeeded. The default Service directive is usually:

Service method="(GET|HEAD|POST)" fn="send-file"

This directive matches requests whose method is GET, HEAD, or POST, which covers nearly virtually all requests sent by browsers.

If the server has not already executed a Service directive when it reaches this directive, it executes the directive so long as the request method is GET, HEAD or POST. The invoked function is send-file, which simply sends the contents of the requested file to the client.

AddLog Directive

After the server generate the response and sends it to the client, the server executes AddLog directives to add entries to the log files.

All AddLog directives are executed. The server can add entries to multiple log files.

Depending on which log files are used and which format they use, the Init section in magnus.conf might need to have directives that initialize the logs. For example, if one of the AddLog directives calls flex-log, which uses the extended log format, the Init section must contain a directive that invokes flex-init to initialize the flexible logging system.

For more information about initializing logs, see the discussion of the functions flex-init and init-clf in Chapter 5, Predefined SAFs in the obj.conf File.

Error Directive

If an error occurs during the request-handling process, such as if a PathCheck or AuthTrans directive denies access to the requested resource, or the requested resource does not exist, the server immediately stops executing all other directives and immediately starts executing the Error directives.

Connect Directive

The Connect directive calls the connect function you specify.

Only the first applicable Connect function is called, starting from the most restrictive object. Occasionally you might want to call multiple functions until a connection is established. The function returns REQ_NOACTION if the next function should be called. If it fails to connect, the return value is REQ_ABORT. If the function connects successfully, the connected socket descriptor will be returned.

DNS Directive

The DNS directive calls either the dns-config built-in function or a DNS function that you specify.

Filter Directive

The Filter directive runs an external command and then sends the data through the external command before processing that data in the proxy. This process is accomplished using the pre-filter function.

Route Directive

The Route directive specifies information about where the proxy server should route requests.

Changes in Function Flow

Sometimes the function flow changes from the normal request-handling process. This change happens during internal redirects, restarts, and URI translation functions.

Internal Redirects

An example of an internal redirect is a servlet include or forward. Because there is no exposed NSAPI function to handle an internal redirect, when an internal redirect occurs, the request structure is copied into rq->orig_rq.

Restarts

A restart occurs when a REQ_RESTART is returned from a PathCheck or Service function, for example, when a CGI is redirected using a relative path.

On a restart, much of the request is cleared. Some elements of the HTTP request (rq->reqpb), the server’s “working” variables (rq->vars), and response headers (rq->srvhdrs) are cleared. The method, protocol, and clf-request variables from rq->reqpb are saved. The saved variables are put back into the data structure. The new URI is inserted (if the new URI contains a query string in , that too is inserted) into rq->reqpb. The parameter rq->rq_attr.req_restarted is set to 1.

URI Translation

At times you might need to find the physical path for a URI without actually running a request. The function request_translate_uri creates a new request structure puts the structure through the AuthTrans and NameTrans stages to get the physical path. Thereafter, the new request is freed.

Syntax Rules for Editing obj.conf

Several rules are important in the obj.conf file. Be very careful when editing this file. Simple mistakes can make the server fail to start or operate correctly.

Caution –

Do not remove any directives from any obj.conf files that are present in the obj.conf file that exists when you first install Proxy Server. The server might not function properly.

Order of Directives

The order of directives is important because the server executes them in the order they appear in obj.conf. The outcome of some directives affect the execution of other directives.

For PathCheck directives, the order within the PathCheck section is not so important, since the server 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. For example, if the default ObjectType directives were listed in the following reverse order every request would have its type value set to text/plain, and the server would never have a chance to set the type according to the extension of the requested resource.

ObjectType fn="force-type" type="text/plain"
ObjectType fn="type-by-extension"

Similarly, the order of directives in the Service section is very important. The server executes the first Service directive that matches the current request and does not execute any others.

Parameters

The number and names of parameters depend on the function. The order of parameters on the line is not important.

Case Sensitivity

Items in the obj.conf file are case sensitive, including function names, parameter names, many parameter values, and path names.

Separators

Function names can be composed only of letters, digits, and underscores. You may use the hyphen (-) character in the configuration file in place of underscore (_) for your C code function names. This rule is only true for function names.

Quotation Marks

Quotation Marks (“) are required around value strings only when a space is included in the string. Otherwise quotation marks are optional. Each open-quote mark must be matched by a close-quote mark.

Spaces

Spaces are not allowed at the beginning of a line except when continuing 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.

Line Continuation

A long line may be continued on the next line by beginning the next line with a space or tab.

Path Names

Always use forward slashes (/) rather than backslashes (\\) in path names under Windows. The backslash character escapes the next character.

Comments

Comments begin with a pound (#) sign. If you manually add comments to obj.conf and then use the Server Manager interface to make changes to your server, the Server Manager will wipe out your comments when it updates obj.conf.

About obj.conf Directive Examples

Every line in the obj.conf file begins with one of the following keywords:

Init
AuthTrans
 NameTrans
 PathCheck
 ObjectType
 InputOutputService
 AddLog
 Error
 Connect
DNS
Filter
Route
<Object>
 </Object>

If any line of any example begins with a different word in this manual, the line is wraps in a different way that in the actual file. In some cases, this wrapping is due to line-length limitations imposed by the PDF and HTML formats of the manuals.

For example, the following directive is contained on one line in the actual obj.conf file:

Init fn="flex-init" access="$accesslog" format.access="%Ses->client.ip% 
	- %Req->vars.auth-user% [%SYSDATE%] ’%Req->reqpb.clf-request%’ 
	%Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"

Chapter 4 Syntax and Use of the obj.conf File