obj.conf. You can modify and extend the request handling process by adding or changing the instructions in obj.conf. You can use the Netscape Server Application Programming Interface (API) to create new Server Application Functions (SAFs) to use in instructions in obj.conf.
This chapter discusses the configuration files used by the iPlanet Web Server. Then the chapter looks in more detail at the server's process for handling requests. The chapter closes by introducing the use of Netscape Server Application Programming Interface (NSAPI) to define new functions to modify the request-handling process.
This chapter has the following sections:
server-root/server-id/config/. This directory contains various configuration files for controlling different components, such as jsa.conf for configuring server-side JavaScript and netshare.conf for configuring NetShare. The exact number and names of configuration files depends on which components have been enabled or loaded into the server.
However, this directory always contains three configuration files that are essential for the server to operate. These files are:
magnus.conf -- contains server initialization information.
obj.conf -- contains instructions for handling requests from clients.
mime.types -- contains information for determining the content type of requested resources.
magnus.conf.
obj.conf file is essential to the operation of the iPlanet Web Server. When you make changes to the server through the Server Manager interface, the system automatically updates obj.conf.
The file obj.conf contains a series of instructions (directives) that tell the iPlanet Web Server what to do at each stage in the request-response process. Each directive invokes a Server Application Function (SAF). These functions are written using the Netscape Server Application Programming Interface (NSAPI). The iPlanet Web Server comes with a set of pre-defined SAFs, but you can also write your own using NSAPI to create new instructions that modify the way the server handles requests.
For more information about how the server uses obj.conf, see Chapter 2, "Syntax and Use of obj.conf."
html extensions indicate that the client is requesting an HTML file, while requests for resources with .gif extensions indicate that the client is requesting an image file in GIF format.
The server loads the mime.types file when it starts up. If you make changes to this file, you must restart the server before the changes will take effect.
For more information about how the server uses mime.types, see Appendix C, "MIME Types."
Connection: Keep-alive header.)GET or POST, a Universal Resource Identifier (URI) indicating which resource is being requested, and an HTTP protocol version separated by spaces.
This is normally followed by a number of headers, a blank line indicating the end of the headers, and sometimes body data. Headers may provide various information about the request or the client Body data. Headers are typically only sent for POST and PUT methods.
The example request shown below would be sent by a Netscape browser to request the server to send back the resource in /index.html. In this example, no body data is sent because the method is GET (the point of the request is to get some data, not to send it.)
GET /index.html HTTP/1.0The server receives the request and processes it. It handles each request individually, although it may process many requests simultaneously. Each request is broken down into a series of steps that together make up the request handling process. The server generates a response which includes the HTTP protocol version, HTTP status code, and a reason phrase separated by spaces. This is normally followed by a number of headers. The end of the headers is indicated by a blank line. The body data of the response follows. A typical HTTP response might look like this:
User-agent: Mozilla
Accept: text/html, text/plain, image/jpeg, image/gif, */*
HTTP/1.0 200 OK
Server: iPlanet Web Server/4.1
Content-type: text/html
Content-length: 83
<HTML>The status code and reason phrase tell the client how the server handled the request. Normally the status code 200 is returned indicating that the request was handled successfully and the body data contains the requested item. Other result codes indicate redirection to another server or the browser's cache, or various types of HTTP errors such as "404 Not Found."
<HEAD><TITLE>Hello World</Title></HEAD>
<BODY>Hello World</BODY>
</HTML>
verify any authorization information (such as name and password) sent in the request.
translate the logical URI into a local file system path.
check the local file system path for validity and check that the requestor has access privileges to the requested resource on the file system.
determine the MIME-type (Multi-purpose Internet Mail Encoding) of the requested resource (for example.text/html,image/gif, and so on).
generate and return the response to the client.
add entries to log file(s).
This step is executed only if an error occurs in the previous steps. If an error occurs, the server logs an error message and aborts the process.
obj.conf contains a series of instructions, known as directives, that tell the iPlanet Web 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 either to initialization or to a specific stage in the request handling process. The stages are Init, AuthTrans, NameTrans, PathCheck, ObjectType, Service, and AddLog.
For example, the following directive applies during the NameTrans stage. It calls the document-root function with the root argument set to D:/Netscape/Server4/docs. (The document-root function translates the http://server_name/ part of the URL to the document root, which in this example is D:/Netscape/Server4/docs.)
NameTrans fn="document-root" root="D:/Netscape/Server4/docs"The functions invoked by the directives in
obj.conf are known as Server Application Functions (SAFs).
obj.conf. You can also write your own SAF using the functions provided by the NSAPI. After you write the SAF, you would add a directive to obj.conf so that your new function gets invoked by the server at the appropriate time.
Each SAF has its own arguments, which are passed to it by the directive in obj.conf. Every SAF is also passed additional arguments that contain information about the request (such as what resource was requested and what kind of client requested it) and any other server variables created or modified by SAFs called by previously invoked directives. Each SAF may examine, modify, or create server variables.
Each SAF returns a result code which tells the server whether it succeeded, did nothing, or failed.
For more information about obj.conf, see Chapter 2, "Syntax and Use of obj.conf."
For more information on the pre-defined SAFs, see Chapter 3, "Predefined SAFs and the Request Handling Process."
For more information on writing your own SAFs, see Chapter 4, "Creating Custom SAFs."
Last Updated: 03/01/00 09:21:56
© Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.