Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference

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.

Flow of Control in the obj.conf File