Required Behavior of SAFs for Each Directive

SAF definitions , you should define it to do certain things, depending on which stage of the request-handling process will invoke the SAF. For example, SAFs to be invoked during the Init stage must conform to different requirements than SAFs to be invoked during the Service stage.

The rq parameter is the primary mechanism for passing information throughout the request-response process. On input to a SAF, rq contains whatever values were inserted or modified by previously executed SAFs. On output, rq contains any modifications or additional information inserted by the SAF. Some SAFs depend on the existence of specific information provided at an earlier step in the process. For example, a PathCheck SAF retrieves values in rq->vars that were previously inserted by an AuthTrans SAF.

This section outlines the expected behavior of SAFs used at each stage in the request-handling process.

• Init SAFs

• AuthTrans SAFs

• NameTrans SAFs

• PathCheck SAFs

• ObjectType SAFs

• Input SAFs

• Output SAFs

• Service SAFs

• AddLog SAFs

• Error SAFs

• Connect SAFs

• DNS SAFs

• Filter SAFs

• Route SAFs

For more detailed information about these SAFs, see Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference.

Init SAFs

• Purpose: Initialize at startup.

• Called at server startup and restart.

• rq and sn are NULL.

• Initialize any shared resources such as files and global variables.

• Can register callback function with daemon_atrestart() to clean up.

• On error, insert error parameter into pb describing the error and return REQ_ABORTED.

• If successful, return REQ_PROCEED.

AuthTrans SAFs

• Verify any authorization information. Only basic authorization is currently defined in the HTTP/1.0 specification.

• Check for an Authorization header in rq->headers that contains the authorization type and uu-encoded user and password information. If a header was not sent, return REQ_NOACTION.

• If a header exists, check the authenticity of user and password.

• If the user name and password are authentic, create an auth-type, plus auth-user or auth-group parameter in rq->vars to be used later by PathCheck SAFs.

• Return REQ_PROCEED if the user was successfully authenticated Return REQ_NOACTION otherwise.

NameTrans SAFs

• Purpose: Convert a logical URI to a physical path.

• Perform operations on the logical path (ppath in rq->vars) to convert it into a full local file system path.

• Return REQ_PROCEED if ppath in rq->vars contains the full local file system path, or REQ_NOACTION if not.

• To redirect the client to another site, change ppath in rq->vars to /URL. Add url to rq->vars with full URL (for example, http://home.netscape.com/). Return REQ_PROCEED.

PathCheck SAFs

• Purpose: Check path validity and user’s access rights.

• Check auth-type, auth-user, or auth-group in rq->vars.

• Return REQ_PROCEED if the user and group are authorized for this area (ppath in rq->vars).

• If not authorized, insert WWW-Authenticate to rq->srvhdrs with a value such as: Basic; Realm=\\"Our private area\\". Call protocol_status() to set the HTTP response status to PROTOCOL_UNAUTHORIZED. Return REQ_ABORTED.

ObjectType SAFs

• Purpose: Determine content-type of data.

• If content-type in rq->srvhdrs already exists, return REQ_NOACTION.

• Determine the MIME type and create content-type in rq->srvhdrs

• Return REQ_PROCEED if content-type is created, REQ_NOACTION otherwise.

Input SAFs

• Purpose: Insert filters that process incoming (client-to-server) data.

• Input SAFs are executed when a plug-in or the server first attempts to read entity body data from the client.

• Input SAFs are executed at most once per request.

• Return REQ_PROCEED to indicate success, or REQ_NOACTION to indicate that the SAF performed no action.

Output SAFs

• Purpose: Insert filters that process outgoing (server-to-client) data.

• Output SAFs are executed when a plug-in or the server first attempts to write entity body data from the client.

• Output SAFs are executed at most once per request.

• Return REQ_PROCEED to indicate success, or REQ_NOACTION to indicate the SAF performed no action.

Service SAFs

• Purpose: Generate and send the response to the client.

• A Service SAF is only called if each of the optional parameters type, method, and query specified in the directive in obj.conf match the request.

• Remove existing content-type from rq->srvhdrs. Insert correct content-type in rq->srvhdrs.

• Create any other headers in rq->srvhdrs.

• Call protocol_set_finfo to set the HTTP response status.

• Call protocol_start_response to send the HTTP response and headers.

• Generate and send data to the client using net_write .

• Return REQ_PROCEED if successful, REQ_EXIT on write error, or REQ_ABORTED on other failures.

Error SAFs

• Purpose: Respond to an HTTP status error condition.

• The Error SAF is only called if each of the optional parameters code and reason specified in the directive in obj.conf match the current error.

• Error SAFs perform the same action as Service SAFs, but only in response to an HTTP status error condition.

AddLog SAFs

• Purpose: Log the transaction to a log file.

• AddLog SAFs can use any data available in pb, sn, or rq to log this transaction.

• Return REQ_PROCEED.

Connect

• Purpose: Call 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

• Purpose: Calls either the dns-config built-in function or a DNS function that you specify.

Filter

• Purpose: Run an external command and then pipes the data through the external command before processing that data in the proxy. This process is accomplished using the pre-filter function.

Route

• Purpose: Specify information about where the proxy server should route requests.