Chapter 1   Basics of Server Operation


The configuration and behavior of iPlanet Web Server is determined by a set of configuration files. You can change the settings in these configuration files either by using the Server Manager interface or by manually editing the files.

The configuration file that contains instructions for how the server processes requests from clients is called 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:

• Configuration Files

• Dynamic Reconfiguration

• How the Server Handles Requests from Clients

• Writing New Server Application Functions

Configuration Files

---

The configuration and operation of the iPlanet Web Server is controlled by configuration files. The configuration files reside in the directory 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 four configuration files that are essential for the server to operate. These files are:

• magnus.conf -- contains global server initialization information.

• server.xml -- contains initialization information for virtual servers and listen sockets.

• obj.conf -- contains instructions for handling requests from clients.

• mime.types -- contains information for determining the content type of requested resources.

magnus.conf

This file sets values of variables that configure the server during initialization. The server looks at this file and executes the settings on startup. The server does not look at this file again until it is restarted.

See Chapter 7 "Syntax and Use of magnus.conf" for a list of all the variables and Init directives that can be set in magnus.conf.

server.xml

This file configures the addresses and ports that the server listens on and assigns virtual server classes and virtual servers to these listen sockets. A master file, server.dtd, defines its format and content.

For more information about how the server uses server.dtd and server.xml, see Chapter 8 "Virtual Server Configuration Files."

---

Note	Virtual servers are not the same thing as server instances. Each server instance is a completely separate server that contains one or more virtual servers.

---

obj.conf

This file contains instructions for the server about how to process requests from clients (such as browsers). The server looks at the configuration defined by this file every time it processes a request from a client.

There is one obj.conf file for each virtual server class, or grouping of virtual servers. Whenever this guide refers to "the obj.conf file," it refers to all obj.conf files or to the obj.conf file for the virtual server class being described.

All the obj.conf files are located in the server_root/server_id/config directory. They are typically named vsclass.obj.conf, where vsclass is the virtual server class name.

The 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."

mime.types

This file maps file extensions to MIME types to enable the server to determine the content type of a requested resource. For example, requests for resources with .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.

For more information about how the server uses mime.types, see Appendix B "MIME Types."

Dynamic Reconfiguration

---

You do not have to restart the server for changes to obj.conf, mime.types, server.xml, and virtual-server-specific ACL files to take effect. All you need to do is apply the changes by clicking the Apply link and then clicking the Load Configuration Files button on the Apply Changes screen. If there are errors in installing the new configuration, the previous configuration is restored.

When you edit obj.conf and apply the changes, a new configuration is loaded into memory that contains all the information from the dynamically configurable files.

Every new connection references the newest configuration. Once the last session referencing a configuration ends, the now unused old configuration is deleted.

How the Server Handles Requests from Clients

---

iPlanet Web Server is a web server that accepts and responds to HyperText Transfer Protocol (HTTP) requests. Browsers like Netscape Communicator communicate using several protocols including HTTP, FTP, and gopher. The iPlanet Web Server handles HTTP specifically.

For more information about the HTTP protocol refer to Appendix E "HyperText Transfer Protocol" and also the latest HTTP specification.

HTTP Basics

As a quick summary, the HTTP/1.1 protocol works as follows:

• the client (usually a browser) opens a connection to the server and sends a request

• the server processes the request, generates a response, and closes the connection if it finds a Connection: Close header.

The request consists of a line indicating a method such as 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 foo.com 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.0 User-agent: Mozilla Accept: text/html, text/plain, image/jpeg, image/gif, */* Host: foo.com

The 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:

HTTP/1.0 200 OK Server: Netscape-Enterprise/6.0 Content-type: text/html Content-length: 83 <HTML> <HEAD><TITLE>Hello World</Title></HEAD> <BODY>Hello World</BODY> </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."

Steps in the Request Handling Process

When the server first starts up it performs some initialization and then waits for an HTTP request from a client (such as a browser). When it receives a request, it first selects a virtual server. For details about how the virtual server is determined, see "Virtual Server Selection for Request Processing."

After the virtual server is selected, the obj.conf file for the virtual server class specifies how the request is handled in the following steps:

1. AuthTrans (authorization translation)

   verify any authorization information (such as name and password) sent in the request.

2. NameTrans (name translation)

   translate the logical URI into a local file system path.

3. PathCheck (path checking)

   check the local file system path for validity and check that the requestor has access privileges to the requested resource on the file system.

4. ObjectType (object typing)

   determine the MIME-type (Multi-purpose Internet Mail Encoding) of the requested resource (for example. text/html, image/gif, and so on).

5. Service (generate the response)

   generate and return the response to the client.

6. AddLog (adding log entries)

   add entries to log file(s).

7. Error (service)

   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.

Directives for Handling Requests

The file 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 to a specific stage in the request handling process. The stages are 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).

Writing New Server Application Functions

---

The iPlanet Web Server comes with a variety of pre-defined SAFs that you can use to create more directives in 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."