Previous     Contents     Index     DocHome     Next     
iPlanet Web Server, Enterprise Edition NSAPI Programmer's Guide



Chapter 2   Syntax and Use of obj.conf


The obj.conf configuration file contains directives that instruct the iPlanet Web Server how to handle requests from clients. This chapter discusses server instructions in obj.conf; the use of Object tags; the use of variables; the flow of control in obj.conf; the syntax rules for editing obj.conf; and a note about example directives.

The sections in this chapter are:



Server Instructions in obj.conf

The obj.conf file contains directives that instruct the server how to handle requests received from clients such as browser. 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:

NameTrans fn="document-root" root="D:/Netscape/Server4/docs"

Directive indicates when this instruction is executed during the request handling process. The value is one of AuthTrans, NameTrans, PathCheck, ObjectType, Service, Error, and AddLog.

The value of the fn argument is the name of the Server Application Function (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.

iPlanet Web 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, as discussed in Chapter 3 "Predefined SAFs and the Request Handling Process." You can also define new SAFs, as discussed in Chapter 4 "Creating Custom SAFs."

The magnus.conf file contains Init directive SAFs that initialize the server. For more information, see Chapter 7 "Syntax and Use of magnus.conf."


Summary of the Directives

Here 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.conf" explains exactly how the server decides which directive or directives to execute in at each stage.

  • 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="document-root" root="D:/Netscape/Server4/docs"

    This example calls the document-root function with a root argument of D:/Netscape/Server4/docs. The function document-root function translates the http://server_name/ part of the requested to URL to the document root, which in this case is D:/Netscape/Server4/docs. Thus a request for http://server-name/doc1.html is translated to D:/Netscape/Server4/docs/doc1.html.

  • PathCheck

    Performs tests on the physical path determined by the NameTrans step. In general, 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

    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.

  • 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="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, and whose type does not begin with magnus-internal/. (Note the use of the special characters *~ to mean "does not match.")

    Another example is:

    Service method="(GET|HEAD)" type="magnus-internal/imagemap" fn="imagemap"

    In this case, if the method of the request is either GET or HEAD, and the type of the requested resource is "magnus-internal/imagemap", the function imagemap is called.

  • 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="D:/netscape/server4/errors/unauthorized.html"

    In this example, the server sends the file in D:/netscape/server4/errors/unauthorized.html whenever a client requests a resource that it is not authorized to access.



The Object Tag

Directives in the obj.conf file are grouped into objects that begin with an <Object> tag and end with a </Object> tag. The default object provides instructions to the server about how to process requests by default. Each new object modifies the default object's behavior.

An Object tag may have a name attribute or a ppath attribute. Either parameter may be a wildcard pattern. For example:

<Object name="cgi">

or

<Object ppath="/usr/netscape/server4/docs/private/*">

The server always starts handling a request by processing the directives in the default object. However, the server switches to processing directives in another object after the NameTrans stage of the default object if either of the following conditions is true:

  • The successful NameTrans directive specifies a name argument

  • the physical pathname that results from the NameTrans stage matches the ppath attribute of another object

When the server has been alerted to use an object other than the default object, it processes the directives in the other object before processing the directives in the default object. For some steps in the process, the server stops processing directives in that a particular stage (such as the Service stage) as soon as one is successfully executed, whereas for other stages the server processes all directives in that stage, including the ones in the default object as well as those in the additional object. For more details, see the section "Flow of Control in obj.conf."


Objects that Use the name Attribute

If a NameTrans directive in the default object specifies a name argument, the server switches to processing the directives in the object of that name before processing the remaining directives in the default object.

For example, the following NameTrans directive in the default object assigns the name cgi to any request whose URL starts with http://server_name/cgi/.

<Object name="default">
NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/server4/docs/mycgi" name="cgi"
...
</Object>

When that NameTrans directive is executed, the server starts processing directives in the object named cgi:

<Object name="cgi">
more directives...
</Object>


Object that Use the ppath Attribute

When the server finishes processing the NameTrans directives in the default object, the logical URL of the request will have been converted to a physical pathname. If this physical pathname matches the ppath attribute of another object in obj.conf, the server switches to processing the directives in that object before processing the remaining ones in the default object.

For example, the following NameTrans directive translates the http://server_name/ part of the requested URL to D:/Netscape/Server4/docs/ (which is the document root directory).

<Object name="default">
NameTrans fn="document-root" root="D:/Netscape/Server4/docs"
...
</Object>

The URL http://server_name/internalplan1.html would be translated to D:/Netscape/Server4/docs/internalplan1.html. However, suppose that obj.conf contains the following additional object:

<Object ppath="*internal*">
more directives...
</Object>

In this case, the partial path *internal* matches the path D:/Netscape/Server4/docs/internalplan1.html. So now the server starts processing the directives in this object before processing the remaining directives in the default object.



Variables Defined in server.xml


You can define variables in the server.xml file and reference them in an obj.conf file. For example, the following server.xml code defines and uses a variable called docroot:

<!DOCTYPE SERVER SYSTEM "server.dtd" [
<!ATTLIST VARS
   docroot CDATA #IMPLIED
>
]>
...
      <VS id="a.com" connections="maingroup" urlhosts="a.com"
            mime="mime1" aclids="std">
         <VARS docroot="/u/server6/a/docs" />
      </VS>
...

You can reference the variable in obj.conf as follows:

NameTrans fn=document-root root="$docroot"

Using this docroot variable saves you from having to define document roots for virtual server classes in the obj.conf files. It also allows you to define different document roots for different virtual servers within the same virtual server class.


Note Variable substitution is allowed only in an obj.conf file. It is not allowed in any other iPlanet Web Server configuration files.

Any variable referenced in an obj.conf file must be defined in the server.xml file at the SERVER, VSCLASS, or VS level. Defining variables with default values at the SERVER or VSCLASS level and overriding them in the VS is recommended.


For more information, see Chapter 8 "Virtual Server Configuration Files."



Flow of Control in obj.conf


Before the server can process a request, it must direct the request to the correct virtual server. For details about how the virtual server is determined, see "Virtual Server Selection for Request Processing."

After the virtual server is determined, the server executes the obj.conf file for the virtual server class to which the virtual server belongs. This section discusses how the server decides which directives to execute in obj.conf.


AuthTrans

When the server receives a request, it executes the AuthTrans directives in the default object to check that the client is authorized to access the server.

If there is more than one AuthTrans directive, the server executes them all (unless one of them results in an error). If an error occurs, the server skips all other directives except for Error directives.


NameTrans

Next, the server executes a NameTrans directive in the default object to map the logical URL of the requested resource to a physical pathname on the server's file system. The server looks at each NameTrans directive in the default object in turn, until it finds one that can be applied.

If there is more than one NameTrans directive in the default object, the server considers each directive until one succeeds.

The NameTrans section in the default object must contain exactly one directive that invokes the document-root function. This functions translates the http://server_name/part of the requested URL to a physical directory that has been designated as the server's document root. For example:

NameTrans fn="document-root" root="D:/Netscape/Server4/docs"

The directive that invokes document-root must be the last directive in the NameTrans section so that it is executed if no other NameTrans directive is applicable.

The pfx2dir (prefix to directory) function is used to set up additional mappings between URLs and directories. For example, the following directive translates the URL http://server_name/cgi/ into the directory pathname D:/netscape/server4/docs/mycgi/:

NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/server4/docs/mycgi"

Notice that if this directive appeared after the one that calls document-root, it would never be executed, with the result that the resultant directory pathname would be D:/netscape/server4/docs/cgi/ (not mycgi). This illustrates why the directive that invokes document-root must be the last one in the NameTrans section.


How the Server Knows to Process Other Objects

As a result of executing a NameTrans directive, the server might start processing directives in another object. This happens if the NameTrans directive that was successfully executed specifies a name or generates a partial path that matches the name or ppath attribute of another object.

If the successful NameTrans directive assigns a name by specifying a name argument, the server starts processing directives in the named object (defined with the OBJECT tag) before processing directives in the default object for the rest of the request handling process.

For example, the following NameTrans directive in the default object assigns the name cgi to any request whose URL starts with http://server_name/cgi/.

<Object name="default">
...
NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/server4/docs/mycgi" name="cgi"
...
</Object>

When that NameTrans directive is executed, the server starts processing directives in the object named cgi:

<Object name="cgi">
more directives...
</Object>

When a NameTrans directive has been successfully executed, there will be a physical pathname associated with the requested resource. If the resultant pathname matches the ppath (partial path) attribute of another object, the server starts processing directives in the other object before processing directives in the default object for the rest of the request handling process.

For example, suppose obj.conf contains an object as follows:

<Object ppath="*internal*">
more directives...
</Object>

Now suppose the successful NameTrans directive translates the requested URL to the pathname D:/Netscape/Server4/docs/internalplan1.html. In this case, the partial path *internal* matches the path D:/Netscape/Server4/docs/internalplan1.html. So now the server would start processing the directives in this object before processing the remaining directives in the default object.


PathCheck

After converting the logical URL of the requested resource to a physical pathname in the NameTrans step, the server executes PathCheck directives to verify that the client is allowed to access the requested resource.

If there is more than one PathCheck directive, the server executes all the directives in the order in which they appear, unless one of the directives denies access. If access is denied, the server switches to executing directives in the Error section.

If the NameTrans directive assigned a name or generated a physical pathname that matches the name or ppath attribute of another object, the server first applies the PathCheck directives in the matching object before applying the directives in the default object.


ObjectType

Assuming that the PathCheck directives all approve access, the server next executes the ObjectType directives to determine the MIME type of the request. The MIME type has three attributes: type, encoding, and language. When the server sends the response to the client, the type, language, and encoding values are transmitted in the headers of the response. The type also frequently helps the server to determine which Service directive to execute to generate the response to the client.

If there is more than one ObjectType directive, the server applies all the directives in the order in which they appear. However, once a directive sets an attribute of the MIME type, further attempts to set the same attribute are ignored. The reason that all ObjectType directives are applied is that one directive may set one attribute, for example type, while another directive sets a different attribute, such as language.

As with the PathCheck directives, if another object has been matched to the request as a result of the NameTrans step, the server executes the ObjectType directives in the matching object before executing the ObjectType directives in the default object.


Setting the Type By File Extension

Usually the default way the server figures out the MIME type is by calling the type-by-extension function. This function instructs the server to look up the MIME type according to the requested resource's file extension in the MIME types table. This table was created during virtual server initialization by the MIME types file, (which is usually called mime.types).

For example, the entry in the MIME types table for the extensions .html and.htm is usually:

type=text/html exts=htm,html

which says that all files that have the extension .htm or .html are text files formatted as HTML and the type is text/html.

Note that if you make changes to the MIME types file, you must reconfigure the server before those changes can take effect.

For more information about MIME types, see Appendix B "MIME Types."


Forcing the Type

If no previous ObjectType directive has set the type, and the server does not find a matching file extension in the MIME types table, the type still has no value even after type-by-expression has been executed. Usually if the server does not recognize the file extension, it is a good idea to force the type to be text/plain, so that the content of the resource is treated as plain text. There are also other situations where you might want to set the type regardless of the file extension, such as forcing all resources in the designated CGI directory to have the MIME type magnus-internal/cgi.

The function that forces the type is force-type.

For example, the following directives first instruct the server to look in the MIME types table for the MIME type, then if the type attribute has not been set (that is, the file extension was not found in the MIME types table), set the type attribute to text/plain.

ObjectType fn="type-by-extension"
ObjectType fn="force-type" type="text/plain"

If the server receives a request for a file abc.dogs, it looks in the MIME types table, does not find a mapping for the extension .dogs, and consequently does not set the type attribute. Since the type attribute has not already been set, the second directive is successful, forcing the type attribute to text/plain.

The following example illustrates another use of force-type. In this example, the type is forced to magnus-internal/cgi before the server gets a chance to look in the MIME types table. In this case, all requests for resources in http://server_name/cgi/ are translated into requests for resources in the directory D:/netscape/server4/docs/mycgi/. Since a name is assigned to the request, the server processes ObjectType directives in the object named cgi before processing the ones in the default object. This object has one ObjectType directive, which forces the type to be magnus-internal/cgi.

NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/server4/docs/mycgi" name="cgi"
<Object name="cgi">
ObjectType fn="force-type" type="magnus-internal/cgi"
Service fn="send-cgi"
</Object>

The server continues processing all ObjectType directives including those in the default object, but since the type attribute has already been set, no other directive can set it to another value.


Service

Next, the server needs to execute a Service directive to generate the response to send to the client. The server looks at each Service directive in turn, to find the first one that matches the type, method and query string. If a Service directive does not specify type, method, or query string, then the unspecified attribute matches anything.

If there is more than one Service directive, the server applies the first one that matches the conditions of the request, and ignores all remaining Service directives.

As with the PathCheck and ObjectType directives, if another object has been matched to the request as a result of the NameTrans step, the server considers the Service directives in the matching object before considering the ones in the default object. If the server successfully executes a Service directive in the matching object, it will not get round to executing the Service directives in the default object, since it only executes one Service directive.


Service Examples

For an example of how Service directives work, consider what happens when the server receives a request for the URL D:/server_name/jos.html. In this case, all directives executed by the server are in the default object.

  • The following NameTrans directive translates the requested URL to D:/netscape/server4/docs/jos.html:

       NameTrans fn="document-root" root="D:/Netscape/Server4/docs"

  • Assume that the PathCheck directives all succeed.

  • The following ObjectType directive tells the server to look up the resource's MIME type in the MIME types table:

       ObjectType fn="type-by-extension"

  • The server finds the following entry in the MIME types table, which sets the type attribute to text/html:

       type=text/html exts=htm,html

  • The server invokes the following Service directive. The value of the type parameter matches anything that does not begin with magnus-internal/. (For a list of all wildcard patterns, see Appendix C "Wildcard Patterns.") This directive sends the requested file, jos.html, to the client.

    Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file""

    For an example that involves using another object, consider what happens when the server receives a request for http://server_name/servlet/doCalculation.class. This example assumes that servlets have been activated and the directory D://netscape/server4/docs/servlet/ has been registered as a servlet directory (that is, the server treats all files in that directory as servlets).

  • The following NameTrans directive translates the requested URL to D:netscape/Server4/docs/servlet/doCalculation.class. This directive also assigns the name ServletByExt to the request.

    NameTrans fn="pfx2dir" from="/servlet" dir="D:/Netscape/Server4/docs/servlet" name="ServletByExt"

  • As a result of the name assignment, the server switches to processing the directives in the object named ServletByExt. This object is defined as:

    <Object name="ServletByExt">
    ObjectType fn="force-type" type="magnus-internal/servlet"
    Service type="magnus-internal/servlet" fn="NSServletService"
    </Object>

  • The ServletByExt object has no PathCheck directives, so the server processes the PathCheck directives in the default object. Let's assume that all PathCheck directives succeed.

  • Next, the server processes the ObjectType directives, starting with the one in the ServletByExt object. This directive sets the type attribute to magnus-internal/servlet.

       ObjectType fn="force-type" type="magnus-internal/servlet"

    The server continues processing all the ObjectType directives in the default object, but since the type attribute is already set its value cannot be changed.

  • When processing Service directives, the server starts by considering the Service directive in the ServletByExt object which is:

       Service type="magnus-internal/servlet" fn="NSServletService"

  • The type argument of this directive matches the type value that was set by the ObjectType directive. So the server goes ahead and executes this Service directive which calls the NSServletService function. This function invokes the requested file as a servlet and sends the output from the servlet as the response to the client. (If the requested resource is not a servlet, an error occurs.)

    Since a Service directive has now been executed, the server does not process any other Service directives. (However, if the matching object had not had a Service directive that was executed, the server would continue looking at Service directives in the default object.)


Default Service Directive

There is usually a Service directive that does the default thing (sends a file) if no other Service directive matches a request sent by a browser. This default directive should come last in the list of Service directives in the default object, to ensure it only gets called if no other Service directives have succeeded. The default Service directive is usually:

Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"

This directive matches requests whose method is GET, HEAD, or POST, which covers nearly virtually all requests sent by browsers. The value of the type argument uses special pattern-matching characters. For complete information about the special pattern-matching characters, see Appendix C "Wildcard Patterns."

The characters "*~" mean "anything that doesn't match the following characters," so the expression *~magnus-internal/ means "anything that doesn't match magnus-internal/." An asterisk by itself matches anything, so the whole expression *~magnus-internal/* matches anything that does not begin with magnus-internal/.

So if the server has not already executed a Service directive when it reaches this directive, it executes the directive so long as the request method is GET, HEAD or POST, and the value of the type attribute does not begin with magnus-internal/. The invoked function is send-file, which simply sends the contents of the requested file to the client.


AddLog

After the server generate the response and sends it to the client, it executes AddLog directives to add entries to the log files.

All AddLog directives are executed. The server can add entries to multiple log files.

Depending on which log files are used and which format they use, the Init section in magnus.conf may need to have directives that initialize the logs. For example, if one of the AddLog directives calls flex-log, which uses the extended log format, the Init section must contain a directive that invokes flex-init to initialize the flexible logging system.

For more information about initializing logs, see the discussion of the functions flex-init and init-clf in Chapter 7 "Syntax and Use of magnus.conf."


Error

If an error occurs during the request handling process, such as if a PathCheck or AuthTrans directive denies access to the requested resource, or the requested resource does not exist, then the server immediately stops executing all other directives and immediately starts executing the Error directives.



Syntax Rules for Editing obj.conf


Several rules are important in the obj.conf file. Be very careful when editing this file. Simple mistakes can make the server fail to start or operate incorrectly.


Order of Directives

The order of directives is important, since the server executes them in the order they appear in obj.conf. The outcome of some directives affect the execution of other directives.

For PathCheck directives, the order within the PathCheck section is not so important, since the server executes all PathCheck directives. However, in the ObjectType section the order is very important, because if an ObjectType directive sets an attribute value, no other ObjectType directive can change that value. For example, if the default ObjectType directives were listed in the following order (which is the wrong way round), every request would have its type value set to text/plain, and the server would never have a chance to set the type according to the extension of the requested resource.

ObjectType fn="force-type" type="text/plain"
ObjectType fn="type-by-extension"

Similarly, the order of directives in the Service section is very important. The server executes the first Service directive that matches the current request and does not execute any others.


Parameters

The number and names of parameters depends on the function. The order of parameters on the line is not important.


Case Sensitivity

Items in the obj.conf file are case-sensitive including function names, parameter names, many parameter values, and path names.


Separators

The C language allows function names to be composed only of letters, digits, and underscores. You may use the hyphen (-) character in the configuration file in place of underscore (_) for your C code function names. This is only true for function names.


Quotes

Quotes (") are only required around value strings when there is a space in the string. Otherwise they are optional. Each open-quote must be matched by a close-quote.


Spaces

Spaces are not allowed at the beginning of a line except when continuing the previous line. Spaces are not allowed before or after the equal (=) sign that separates the name and value. Spaces are not allowed at the end of a line or on a blank line.


Line Continuation

A long line may be continued on the next line by beginning the next line with a space or tab.


Path Names

Always use forward slashes (/) rather than back-slashes (\) in path names under Windows NT. Back-slash escapes the next character.


Comments

Comments begin with a pound (#) sign. If you manually add comments to obj.conf, then use the Server Manager interface to make changes to your server, the Server Manager will wipe out your comments when it updates obj.conf.



About obj.conf Directive Examples


Every line in the obj.conf file begins with one of the following keywords:

AuthTrans
NameTrans
PathCheck
ObjectType
Service
AddLog
Error
<Object
</Object>

If any line of any example begins with a different word in the manual, the line is wrapping in a way that it does not in the actual file. In some cases this is due to line length limitations imposed by the PDF and HTML formats of the manuals.

For example, the following directive is all on one line in the actual obj.conf file:

NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/server4/docs/mycgi" name="cgi"


Previous     Contents     Index     DocHome     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated May 15, 2001