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 obj.confexplains exactly how the server decides which directive or directives to execute in each stage.

• Init

  The Init functions load and initialize server modules and plugins, and initialize log files.

• AuthTrans

  Verifies any authorization information (normally sent in the Authorization header) provided in the HTTP request and translates it into a user and/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

  Translates the URL specified in the request from a logical URL to a physical file system path for the requested resource. This may also result in redirection to another site. For example:

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

  This example calls the map function which replaces http://myserver with http://yourserver in the request line.

• PathCheck

  Performs tests on the accessibility of the paths, and checks if the client is allowed access to 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

  Determines the MIME (Multi-purpose Internet Mail Encoding) 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 may 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

  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

  Selects filters that will process outgoing response data generated by the Service step. The Output directive allows 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. 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

  Generates and sends the response to the client. This involves setting the HTTP result status, setting up response headers (such as Content-Type and Content-Length), and generating and sending 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)" type="*~magnus-internal/*" 
  	fn="proxy-retrieve"

  This directive instructs the server to use the proxy-retrieve function in response to any request whose method is GET, HEAD, or POST, and whose type does not begin with magnus-internal/. (Note the use of the special characters *~ to mean “does not match.”)

• AddLog

  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

  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="/usr/sun/proxyServer40
  	/proxy-server1/errors/unauthorized.html"

  In this example, the server sends the file in /usr/sun/proxyServer40/proxy-server1/errors/unauthorized.html whenever a client requests a resource that it is not authorized to access.

• Connect

  The Connect directive calls the connect function you specify.

  Only the first applicable Connect function is called, starting from the most restrictive object. Occasionally it is desirable 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

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

• Filter

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

• Route

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