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.