[Chapter 25] 25.2 The obj.conf File

25.2 The obj.conf File

The obj.conf file contains the configuration directives that tell the server exactly how to handle client requests. This file has two main functions, corresponding to the two main sections of the file. The first section initializes subsystems, a diverse set of tasks that includes opening and naming log files, loading the MIME types file, loading Java classes and LiveWire applications, and describing logging and directory index formats. The second section contains the object definitions, which tell the server how to handle resource requests.

Resource Handling

The Netscape servers are modeled on the idea that all resources to be served are instances of objects. To tell the server how to treat a set of documents, you assign them to an object. You give an object all of the properties you want the resources to have, including URL mapping, access and authorization, assigning MIME types, logging format, and directory listings. For example, there is no need for a special CGI program directory, since you can assign any document you want to a common cgi object.

Subsystem Initialization

The Init directive is used to initialize subsystems of the server. The Init directives for the subsystems being used by the server are grouped at the top of the obj.conf file. They take the following form:

Init fn=function argument1=value1 [argument2=value2 ...]

where function is the function name, and the arguments and values depend on the function.

Which subsystem is being initialized depends on the value of the fn function. The subsystems and available functions depend on which server you have and the functionality it supports. You may also have your own functions if you have written plug-in applications with the server API.

This section lists the Init functions corresponding to basic subsystems used by the server. Functions for Java and LiveWire subsystems commonly appear in this section as well, but they will not be discussed here.

cindex-init

The cindex-init function configures fancy directory indexing. These settings apply globally, and cannot be custom configured for specific directories. This function does not turn on fancy indexing for any directory; that is done in the object definitions, if desired. There are four arguments available for this function:

icon-uri=path

This argument specifies the server path to the icon directory. Which icons are used with any given MIME type is determined by the mime.types file. The default server path for icons is /mc-icons/.

ignore=expr

This argument specifies which files should be omitted from directory indices. The value should be a regular expression for filenames to ignore. For example, to exclude log files from listings, you could use the setting:

Init fn=cindex-init ignore="*.log"

Files whose names begin with a period are automatically omitted, with no option to un-omit them.

opts=s|i

This argument specifies whether the icons are hyperlinked to the documents and whether the server should attempt to locate the titles of HTML documents to use as descriptions. If the value includes i, then icons are hyperlinked. If the value includes s, then the server will scan for HTML titles. The value should be one or both of these, e.g., opts=is.

widths=a,b,c,d

This argument specifies the widths of the different columns in the directory index. Setting a column's width to 0 omits that column. The columns are the filename, the last-modified time, the size, and the description. For example, the value 16,0,8,30 would make a name column 16 characters wide, a size column 8 characters wide, and a description column 30 characters wide.

Note that this function does not turn on fancy directory indexing for any directories, but merely configures what a fancy directory would look like if it were turned on. To turn on fancy directory indexing, use the index-common function of the Service directive.

init-clf

The init-clf function is used to initialize logging in the common log format. This function tells the server to create one or more common log files and open them to record transactions.

Each log file needs to be assigned a name for internal use by the server. The default name for logging (but not for this directive) is global, but you can use whatever name or names you wish. The argument names should be the names you want to use with their values being the absolute paths to the log files. For example, you might want to call your three logs member, newsletter, and global (for everything else). You would do this like so:

Init fn=init-clf member=/https-server/logs/members.log 
 newsletter=/https-server/logs/newsletter.log 
 global=/https-server/logs/access.log

(Remember to not break Init directives across lines, despite how this example is formatted.) A more common use would be to create a single general file:

Init fn=init-clf global=/usr/local/etc/httpd/logs/access.log

Note that this directive merely initializes the logging system. It does not tell the server to write anything to the log files. That is done by including an AddLog directive in the relevant object, which specifies a logfile name that is defined here.

init-uhome

The init-uhome function tells the server to initialize user directory handling. User directory handling will work perfectly well without this directive, but when used, the user directory locations are pre-cached in a directory table file (by default /etc/passwd) to improve performance.

The init-uhome function allows an optional second argument, pwfile, which specifies the name of the user directory table file other than /etc/passwd. A basic initialization would be:

Init fn=init-uhome

while one using /usr/local/etc/httpd/users.db as the user table would be:

Init fn=init-uhome pwfile=/usr/local/etc/httpd/users.db

load-types

The load-types function initializes the general MIME-type assignment subsystem. This function loads a types table, the mime.types file. The format of this file is simple, with one record per line:

type/subtype extension1 [extention2 ...] [icon=iconfile]

where type/subtype is a MIME type and subtype like text/html, extension is a filename extension such as html, and iconfile is the name of the icon to be shown if a file of that type is listed in a directory index. The icon names should be filenames in the index icon directory (specified by the icon-uri parameter of the cindex-init function).

This function can load two different types files, with one flagged as global and the other as local. The global file is given as the value of the mime-types argument, while the local file is defined by the local-types argument. The files may be specified as either absolute paths or file names inside the configuration directory. For example:

Init fn=load-types mime-types=mime.types local-types=clown.types

flex-init

This function is used to initialize the more enhanced logging system (called "flexible logging"). The first parameter gives the name of the logfile with the full path to its location. The second parameter is the format parameter, which takes a list of values for the various types of transaction information to log. The filename parameter looks like logname=fullpathname. Then the format parameter will be format.logname=format options. For example, the following line opens and specifies the format of a log named access:

Init fn="flex-init" access="/https-server/logs/access" format.acc
ess="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.
clf-request%\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"

The lines of the example are broken so poorly to remind you that the directive must be one long line and that all spaces in the format value count. Within the format value, everything between percent signs (%) is a transaction value parameter. Parameters surrounded by \" and "\ are "escaped" because their values may contain spaces. Any characters that are not escaped characters or between percents are literally printed to the logfile, giving your log lines spaces, separators, and readability. Here is the list of log parameter values:

%Ses->client.ip%

Client's hostname or IP address

%Req->vars.auth-user%"

User authentication required

%SYSDATE%

System date

%Req->reqpb.clf-request%

Full client request (escapes required)

%Req->srvhdrs.clf-status%

Server response status Content length

%Req->headers.referer%

Refering URL (escapes required) Client's browser identity (escapes required) Client request method Requesting URL URL query string HTTP version (escapes required) Accept header(s) Date header (escapes required) If-Modified-Since header Authorization header

Object Configuration

The rest of the object file (beyond the Init directives) consists of a set of objects. Each object comes in a block surrounded by <Object> and </Object> tags. The <Object> tag uses one of two attributes: name, which gives a name to an object, or ppath, which gives a URL path or regular expression for resources belonging to the object.

An object consists of a series of directives that specify the behavior of documents within that object. The directives may specify that directory indexing is not allowed, that authentication is required, that the document should be treated as an imagemap, that requests for documents should be logged into a special log file, and so on.

An object named research looks like this:

<object name="research">
directive1
directive2
...
</object>

Alternatively, you could specify the object by the server path:

<object ppath="/secret/research/*">
directive1
directive2
...
</object>

There are two objects included by default: default and cgi. All resources are at first handled by one of these two objects. Directives in the object block may then redirect a specific resource to another named object for handling. In addition, directives within an object may be designated as applying only to (or only not to) specific client hosts (within <client> ... </client> tags).

Client-specific directives are the same as other directives, but are wrapped within <client> ... </client> labels. These labels can be qualified using either the dns argument, which matches against the DNS-resolved name for the remote client, or the ip argument, which matches against the IP address itself. Either can be a regular expression. For example, to enable specific directives only within the ora.com domain, you could write:

<client dns=*ora.com>
special-directive1
special-directive2
...
</client>

As with the Init lines, the object directives take the following form:

directive fn=function argument1=value1 [argument2=value2 ...]

where directive is the directive name, function is the function name, and the arguments and values depend on the directive and function.

There are only seven directives, and they correspond closely to the request processing pipeline. When a request comes in, it is assigned to an object by matching either a regular expression or the root object. Then:

Authentication is performed, as specified by any AuthTrans directives.
The path is translated to a specific resource by any NameTrans directives. At this point, the document may also be assigned to a different object, in which case the process starts over in that object.
The translated path is checked by any PathCheck directives.
The resource is assigned a type by any applicable ObjectType directives.
The request is serviced in some appropriate way by a Service directive.
The request is logged by an AddLog directives.
If any of these steps fail, a special message may be sent, depending on the status case, where these messages are specified by any Error directives.

Within each stage, the directives are processed in the order they appear in the object file. This can lead to occasional problems if you are not careful to put special cases before defaults.

AuthTrans

The AuthTrans directive is responsible for requesting and interpreting authentication whenever necessary. This directive can use one of two functions: basic-auth or basic-ncsa. Both of these functions mean the same thing. basic-auth is used in 1.x servers. auth-ncsa supersedes it in 2.x servers.

The following parameters are used in the AuthTrans directive:

auth-type=basic

Specifies the authorization type to be used. It is always basic.

dbm=file

Indicates the name of a user database file. It should contain the full pathname of the file. If you use this parameter, you can't also list a userfile parameter.

userfile=file

Specifies a userfile in the NCSA format. These are files with user:password listings created by the htpasswd program. You must supply a full pathname.

grpfile=file

An optional parameter for specifying an NCSA-style group file. The group file contains lists of groups and their users in the format group:user1 user2 .... You must supply a full pathname.

The AuthTrans directive is usually used with the require-auth function of PathCheck.

NameTrans

The NameTrans directive is responsible for taking the requested server path and determining what actual resource corresponds to it. This includes resolving user directories, URL mapping, and redirections.

In addition, the NameTrans directive can assign documents to other objects for further processing. Any of the NameTrans functions, except for redirect, can take an extra argument name that specifies the name of the object to which the document should be transferred.

document-root

This function specifies the root directory of your server's document tree. If no other directive remaps the server path to an absolute path, it will be interpreted as being relative to this directory. The root directory is given as the value of the root argument. For example, to use /usr/local/etc/web/docs/ as the root directory, you would use this setting:

NameTrans fn=document-root root=/usr/local/etc/web/docs/

This function should be used in the default object.

home-page

The Netscape server allows you to assign a special document to the server home page request (i.e., a request for /) using this function. The home page document's path, absolute or relative to the document root, should be given as the value of the argument path. For example, to use /usr/local/etc/web/home.html as the server's home page, you would use this setting:

NameTrans fn=home-page path=/usr/local/etc/web/home.html

pfx2dir

This function allows you to remap a server path to a new absolute path by assigning a prefix directory. That is, you can say that a whole server path tree actually resides at the end of a branch of another tree. This function takes two arguments:

from=urlpath

The server path tree being remapped.

dir=path

The absolute path that is being mapped to.

For example, if you want children/kenny/ to map to the files in /monsters/gamera/kenny/, you would use:

NameTrans fn=pfx2dir from=/children/kenny/ dir=/monsters/gamera/kenny/

The optional name parameter supplies the name of another object to which the mapped path should derive its configuration.

redirect

This function allows the server to redirect the user to a resource's location if it has moved. It uses the following arguments:

from=path

The local server path that is being redirected.

url-prefix=urlpath

If the new location is simply a new URL prefix for the server path (i.e., on the same server), the url-prefix argument should be used.

url=url

If the new location is a full URL, then the url argument should be used.

For example, if you wanted to tell clients that everything in the /turtle/ directory had moved to http://www.gamera.com/, you would use this setting:

NameTrans fn=redirect from=/turtle/ url-prefix=http://www.gamera.com/

unix-home

This function sets up user directories with the following arguments:

from=prefix

Specifies the prefix indicating a user directory, such as a tilde (~) or a path like /staff/.

subdir=subdir

Specifies the subdirectory of each user's home directory to which the path should resolve.

pwfile=file

This optional argument specifies the user database (in /etc/passwd format) to use to locate user directories. If omitted, /etc/passwd will be used, or NIS if it is running.

For example, to map a request of the form /~user/ to the user subdirectory public_html, using the standard user table, you would use this directive:

NameTrans fn=unix-home from="/~" subdir="public_html"

You can also supply a name parameter to refer the path's objects to another object's configuration settings.

PathCheck

The PathCheck directive tells the server to check various things about the translated path. This may be a security check to identify any suspicious directories, a scan for CGI path info spackled onto the end of an otherwise perfectly good path, or an instruction to require authentication. PathCheck's functions are less clearly unified than those of the other directives, but they have the common need to be applied after the path has been translated but before the processing of the request's content begins.

deny-existence

This function is used to hide the existence of a file from the user. It can take two arguments:

path=path

Specifies which files should have their existences denied. If this argument is omitted, the server takes the severe stance of denying the existence of everything handled by the current object.

bong-msg=file

Sends a special file instead of the standard error message.

For example, to deny the existence of everything in the /secrets/ directory and send back the file /docs/nosy.html, you could use this setting:

PathCheck fn=deny-existence path=/secrets/ bong-msg=/docs/nosy.html

Alternatively, you could specify an entire object for that directory tree and only lock out outsiders:

<object ppath=/secrets/*>
<client dns=*~*.ora.com>
PathCheck fn=deny-existence bong-msg=/docs/nothing-to-see.html
</client>
</object>

find-index

When a user requests a directory, instead of a plain file, the server can either send a specified index file or create a directory listing (if enabled and authorized). The find-index function enables this ability. There is only one argument to this function:

index-names=file1,file2,...

Supplies a comma-separated list (no spaces) of names to look for in a directory to be used as the default file.

For example, to look first for index.html and then index.shtml and then index.cgi, you would use this setting:

PathCheck fn=find-index index-names=index.html,index.shtml,index.cgi

find-links

This function allows you to specify when hard or soft links will be followed as part of path resolution. There are potential security problems with allowing links to be followable. If a request comes in for the path you have listed, the server will check for symbolic links that you don't want to be accessed, and if it finds any in the directory, it returns an error. Two parameters are used with this function:

disable=h|s|o

Specifies which types of links you don't like. There are three choices that can be used in combination if you wish. h is used for hard symbolic links; s is used for soft links; and o means that you will allow symbolic links if the user owns the target link.

dir=path

Specifies the URL path that will be checked for symbolic links. All subdirectories of the path will be checked as well, if they are requested.

This example disables all symbolic links in user directories:

PathCheck fn=find-links dir=public_html disable=hs

find-pathinfo

When a user requests a document, he can put extra information (which may or may not get used) onto the end of the document's server path in the form of additional directory levels. In a CGI environment, this is what makes up the PATH_INFO variable. The Netscape server does not identify and strip out this information by default, which means if you want it to do so, you have to tell it to. The find-pathinfo function does just that. There are no arguments. To handle path info correctly, just include this directive:

PathCheck fn-find-pathinfo

require-auth

This function tells the server that it must be able to authenticate the user before any further processing can take place. If the authentication information has already been sent, this function causes it to be used. If it has not been sent, the user will be prompted for a user name and password which will be returned to your server. The following arguments are used:

auth-type=type

Gives the type of authorization used, usually auth-type=basic. Required.

realm=name

Provides a realm name (enclosed in quotes) to the server, so it will have a better idea of which username and password to send. Required.

auth-user=users

Used to specify a user or list of users who are authorized. The list is enclosed in parentheses and usernames are separated by | symbols.

auth-group=groups

Specifies a group or list of authorized groups.

For example:

PathCheck fn=require-auth auth-type=realm realm="web"
  auth-user=(linda|val|stephen)

unix-uri-clean

Users may try to break out of your server's document space by inserting extraneous path elements into their server paths. The unix-uri-clean function looks for /../, /./, and //, and denies access if any of them are present. There are no parameters.

PathCheck fn=unix-uri-clean

Remember that all PathCheck functions will be applied in order, so if your path info may contain these, you should make sure the find-pathinfo function is listed before the unix-uri-clean function.

load-config

This function tells the server to look for local configuration files in document directories. Local configuration files use obj.conf configuration directives to apply localized configuration options to specific directories. The following parameters are used:

file=name

Identifies the name of the file to look for in the directory.

disable-types=types

Allows you to disable local configuration for specific file types.

basdir=directory

Gives the directory in which to look for configuration files. Without this parameter, the server looks in the root directory given by the name translation.

descend=1

Tells the server to look in subdirectories of the base directories.

check-acl

This function tells the server to check a specific access control list for authorization requirements on the requested object. Access control lists (ACLs) are contained in sections of the ACLFile, which is set in magnus.conf. The function is executed before any require-auth settings in PathCheck. The following parameters can be used:

acl=name

Gives the name of the ACL to use.

shexp=expr

Gives a shell expression for the path that the ACL apply to.

bong-file=file

Gives the name of the file to return if access is denied.

ObjectType

The ObjectType directive is used to tell the server how to assign a MIME type, encoding, and/or language to an object. This may be by looking up the extension in the mime.types file or by forcing it directly. Unlike some other directives, multiple ObjectType directives do not override each other, but fortify each other. If one sets the MIME type and another sets the encoding, fine. If, however, one sets the type and another tries to set it again, the second loses rather than the first.

In addition, like many servers, the Netscape servers use several "magic" MIME types to cause special treatment to occur. They are called internal server types, but they are the same as magic types.

force-type

This function sets the MIME type by fiat. It may optionally also set the encoding and/or language.

type=type

Sets the MIME or media type.

enc=encoding

Sets the encoding type.

lang=language

Sets the language to be used.

For example, to make the type text/plain the default for a given object, you would add the following directive after all the other ObjectType directives:

ObjectType fn=force-type type=text/plain

type-by-exp

This function tells the server to assign a given type if the translated path matches a given regular expression. As with the force-type function, the server may also set the encoding and/or language.

exp=expr

Gives the regular expression to be matched for files to be assigned the specified type.

type=type

Sets the MIME or media type.

enc=encoding

Sets the encoding type.

lang=language

Sets the language to be used.

For example, to tell the server that everything in the directory /scratch-n-sniff/ should be assigned the type odor/oif, regardless of extensions, you could use this directive:

ObjectType fn=type-by-exp type=odor/oif exp=/scratch-n-sniff/*

type-by-extension

Rather than having to use a special ObjectType directive for every file type, you can set up most of them in a mime.types file in advance and use the type-by-extension function to have the server look the file type up. This lookup is done based on the document's extension, which explains the name of this directive. There are no arguments; you simply use:

ObjectType fn=type-by-extension

image-switch

This function allows you to send the client an image of a different type, if it exists in the directory, when the client can't accept a certain image type. For example, if a user requests image.gif, and there is also image.jpg in the same directory, the server will send the JPEG instead. There are no parameters for this function.

Service

The Service directive is where the server finally gets down to business and does something material to respond to a request. Up until now, the server has checked paths, remapped them, checked them again, and picked some MIME types. With the Service directive, it will finally decide what to do with the file it has found. Since an applicable Service directive tells the server how to handle a request, further Service directives are ignored, unless the first uses the append-trailer function.

Any Service function can take either (or none) of two constraint arguments. The type argument can take a regular expression to match against the MIME type. If this argument is present and it doesn't match, that Service directive is deemed inapplicable and the next one is tried. Similarly, the method argument, if present, must match the request method for the directive to apply. The value is GET, HEAD, or POST, or any combination delimited by vertical bars (|) within parentheses. For example, (GET|HEAD) will match GET requests and HEAD requests, but not POST requests.

append-trailer

append-trailer is the only Service function that does not actually send data to the client. Instead, it merely tells the server that when it does send data, it should append a fragment of HTML to any HTML file it does send.

trailer=html-string

Gives the HTML formatted string to append. It should be enclosed in quotes if you use spaces. If you want to include the last-modified time for the file, you can include the :LASTMOD: variable in the string and it will be replaced appropriately.

timefmt=format

Specifies the format of the time string; required when you use :LASTMOD:. Takes a strftime format string.

Service fn=append-trailer type=text/html trailer="Copyright &copy;1996"

imagemap

This function tells the server to process a request as an imagemap with type=magnus-internal/imagemap:

Service type=magnus-internal/imagemap fn=imagemap

index-common

This function generates a fancy directory index. Much of the format is controlled not here, but by the cindex-init function of the Init directive. What is controlled here is whether to build one (that is, whether this function is used) and what header and footer files to use, if any. The type given in this directive is type=magnus-internal/directory. You may also use the following parameters:

header=file

Specifies the filename to be looked for in the requested directory containing information to be placed at the top of the directory listing.

readme=file

Specifies the filename to be looked for in the requested directory containing information to be placed at the bottom of the directory listing.

index-simple

This function tells the server to produce a simple directory index. This does not include icons, sizes, etc., but only a bulleted list of linked file names. As with index-common, this function uses type=magnus_internal/directory.

parse-html

This function is used to serve server-side include files.

query-handler

Specifies a CGI program to act as a handler for non-CGI GET requests that include a query string. As such, it is only seen as applicable if the request matches those criteria. The program should be given as an absolute path in the path argument. For example, to use /l0/cgi-bin/doc_searcher, you would use this setting:

Service fn=query-handler path=/l0/cgi-bin/doc_searcher

This program is executed with the original document path stored in the PATH_INFO CGI variable.

send-cgi

This function tells the server to execute a requested object as a CGI program. For example, an object that runs everything in the server path /cgi-bin/ would be:

<object ppath=/cgi-bin/>
Service fn=send-cgi
</object>

send-error

This function sends a specified file when an error occurs. The absolute path to the file should be given in the path argument.

send-file

This function tells the server to send the file. It is often useful to provide this as a default behavior by adding this directive after all other Service directives:

Service method(GET|HEAD) fn=send-file

Error

The Error directive is where the server confesses to being unable to complete a request. It can use the same functions as the Service directive, but it is only used when an error has occurred, and it has different constraint arguments, reason and code, which correspond to the textual description of the error and the status code, respectively. You cannot place both code and reason in the same Error directive. There are four sets of values:

401, Unauthorized

Authorization was required and the user failed to deliver proper information.

403, Forbidden

The server was unable to read a file.

404, Not Found

The document could not be found.

500, Server Error

This could mean anything from a hardware or OS problem to a CGI program that returned bad data.

send-error

This function sends a specified file to the user when an error occurs. The absolute path to the file should be given in the path argument.

query-handler

You may want to use a CGI program to customize a response resulting from an error. Use the query-handler function to specify a CGI file (with the path parameter) for a given error code.

AddLog

The AddLog directive is applied after the server has handled the request and is purely for local bookkeeping. Its functions let you write a normal transaction log and record what user-agent was responsible for the transaction. If you have more than one, all AddLog directives in an object will be used.

common-log

This function is used to record transaction data in the common NCSA log format. This is the format used by most log analysis tools. It uses the following parameters:

name=logname

Specifies the name of a log file to use. This must be a logfile name that you initialized with Init fn=init-clf name=... at the top of the obj.conf file. Without this parameter, it logs to the global access log.

iponly=n

Tells the server not to perform host-name lookup for logging. Any value for iponly will do. The Server Manager creates iponly="1".

flex-log

This function tells the server to log transaction data in the extended or flexible logging format. This format is specified in the Init directives with the flex-init function. It uses the same parameters as the common-log function:

name=logname

iponly=n

Tells the server not to perform host-name lookup for logging. Any value for iponly will do. The Server Manager creates iponly="1".

record-useragent

This function tells the server to write the client IP address followed by the value of the User-Agent header into a log file. As with the common-log function, the argument name tells the server which log file to write to. If it is omitted, the information will be written to the global access log.