Chapter 1 Syntax
and Use of obj.conf

The obj.conf configuration file contains directives
that instruct the Sun Java System Web Server how to handle HTTP and HTTPS
requests from clients and service web server content such as native server
plug-ins and CGI programs. You can modify and extend the request-handling
process by adding or changing the instructions in obj.conf.

All obj.conf files are located in the instance_dir/config directory, where instance_dir is
the path to the installation directory of the server instance. There is one obj.conf file for each virtual server class, unless several virtual
server classes are configured to share an obj.conf file.
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.

By default, the obj.conf file for the initial virtual
server class is named obj.conf, and the obj.conf files
for the administrator-defined virtual server classes are named virtual_server_class_id.obj.conf. Editing one of these files directly
or through the Administration interface changes the configuration of a virtual
server class.

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.

How the Server Handles Requests from Clients

Sun Java System Web Server is a web server that accepts and responds
to Hypertext Transfer Protocol (HTTP) requests. Browsers such as Netscape™ Communicator communicate using
several protocols including HTTP and FTP. The Sun Java System Web Server handles
HTTP specifically.

HTTP Basics

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 Uniform 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).

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

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.

NSAPI Filters

In previous versions of the Web Server, the NSAPI API allowed multiple
SAFs to interact in request processing. For example, one SAF could be used
to authenticate the client after which a second SAF would generate the content.

In addition to the existing NSAPI interfaces, Sun Java System Web Server
introduces NSAPI filters that enable a function to intercept (and potentially
modify) the content presented to or generated by another function.

Select filters that will process incoming request data
read by the Service step.

Output (prepare to
send output)

Select filters that will process outgoing response
data generated by the Service step.

Service (generate the
response)

Generate and return the response to the client.

AddLog (adding log
entries)

Add entries to log file(s).

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 Sun Java System Web Server what to do at
each stage in the request-handling process. Each directive invokes a 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, Input, Output, 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://Sun/WebServer61/server1/docs. (The document-root function translates the http://server_name/ part of the URL to the document root, which
in this example is D://Sun/WebServer61/server1/docs.)

NameTrans fn="document-root" root="D:/Sun/WebServer61/server1/docs"

The functions invoked by the directives in obj.conf are
known as SAFs.

Dynamic Reconfiguration

You do not need to restart the server for changes to certain configuration
files to take effect (for example, obj.conf, mime.types, server.xml, and virtual server-specific ACL
files). 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 of 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.

Server Instructions in obj.conf

The obj.conf file contains directives that instruct
the server how to handle requests received from clients such as browsers.
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-namename1="value1"...nameN="valueN"

For example:

NameTrans fn="document-root" root="D:/Sun/WebServer61/server1/docs"

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

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

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

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.

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:/Sun/WebServer61/server1/docs"

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

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.

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).

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 plug-in 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.

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 plug-in 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.

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.

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.”)

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.

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

Configuring HTTP Compression

When compression is enabled in the server, an entry gets added to the obj.conf file. A sample entry is shown below:

Output fn="insert-filter" filter="http-compression" type="text/*"

Depending on the options specified, this line might also contain these
options:

vary="on" compression-level="9"

To restrict compression to documents of only a particular type, or to
exclude browsers that don’t work well with compressed content, you would
need to edit the obj.conf file, as discussed below.

The option that appears as:

type="text/*"

restricts compression to documents that have a MIME type of text/* (for example, text/ascii, text/css, text/html, and so on). This can be modified to compress only certain
types of documents. If you want to compress only HTML documents, for example,
you would change the option to:

type="text/html"

Alternatively, you can specifically exclude browsers that are known
to misbehave when they receive compressed content (but still request it anyway)
by using the <Client> tag as follows:

This restricts compression to browsers that are not any
of the following:

Internet Explorer for Windows earlier than version 4

Internet Explorer for Macintosh earlier than version 6

Netscape Navigator/Communicator earlier than version 6

Internet Explorer on Windows earlier than version 4 may request compressed
data at times, but does not correctly support it. Internet Explorer on Macintosh
earlier than version 6 does the same. Netscape Communicator version 4.x requests
compression, but only correctly handles compressed HTML. It will not correctly
handle linked CSS or JavaScript from the compressed HTML, so administrators
often simply prevent their servers from sending any compressed content to
that browser (or earlier).

The Object Tag

Directives in the obj.conf file are grouped into
objects that begin with an <Object> tag and end with
an </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/sun/webserver61/server1/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 path name 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 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 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/:

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

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

Objects 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 path name. If this physical path name 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:/Sun/WebServer61/server1/docs/ (which
is the document root directory):

The URL http://server_name/internalplan1.html would be translated to D:/Sun/WebServer61/server1/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:/Sun/WebServer61/server1/docs/internalplan1.html. So
now the server starts processing the directives in this object before processing
the remaining directives in the default object.

The Client Tag

The <Client> tag is used to limit execution of
a set of directives to requests received from specific clients. Directives
listed between the <Client>and </Client> tags
are executed only when information in the client request matches the parameter
values specified.

Client Tag Parameters

The following table lists the <Client> tag parameters.

Table 1–1 Client Tag Parameters

Parameter

Description

browser

User-agent string sent by a browser to the Web Server

chunked

Boolean value set by a client requesting chunked encoding

code

HTTP response code

dns

DNS name of the client

internal

Boolean value indicating internally generated request

ip

IP address of the client

keep-alive

Boolean value indicating the client has requested a keep-alive connection

keysize

Key size used in an SSL transaction

match

Match mode for the <Client> tag; valid values
are all, any, and none

method

HTTP method used by the browser

name

Name of an object as specified in a previous NameTrans statement

odds

Sets a random value for evaluating the enclosed directive; specified
as either a percentage or a ratio (for example, 20% or 1/5)

path

Physical path to the requested resource

ppath

Physical path of the requested resource

query

Query string sent in the request

reason

Text version of the HTTP response code

restarted

Boolean value indicating a request has been restarted

secret-keysize

Secret key size used in an SSL transaction

security

Indicates an encrypted request

type

Type of document requested (such as text/html or image/gif)

uri

URI section of the request from the browser

urlhost

DNS name of the virtual server requested by the client (the value is
provided in the Host header of the client request)

The<Client> tag parameters
provide greater control over when and if directives are executed. In the following
example, use of the odds parameter gives a request a 25%
chance of being redirected:

One or more wildcard patterns can be used to specify Client tag parameter
values.

Wildcards can also be used to exclude clients that match the parameter
value specified in the <Client tag>. In the following
example, the <Client> tag and the AddLog directive are combined to direct the Web Server to log access
requests from all clients except those from the specified
subnet:

Using the ~ wildcard negates the expression, so the
Web Server excludes clients from the specified subnet.

You can also create a negative match by setting the match parameter
of the Client tag to none. In the following
example, access requests from the specified subnet are excluded, as are all
requests to the virtual server www.sunone.com:

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 Sun Java System Web Server configuration files.
Any variable referenced in an obj.conf file must be defined
in the server.xml file.

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
path name 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 function 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:/Sun/WebServer61/server1/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 path name D:/Sun/WebServer61/server1/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 path name would be D:/Sun/WebServer61/server1/docs/cgi/ (not mycgi). This illustrates why the directive
that invokes document-root must be the last one in the NameTrans section.

How and When the Server Processes 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/.

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 path name associated with the requested
resource. If the resultant path name 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 path name D:/Sun/WebServer61/server1/docs/internalplan1.html. In this case, the partial path *internal* matches
the path D:/Sun/WebServer61/server1/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
path name 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 of 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 path name 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 of 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 with 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.

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.

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:/Sun/WebServer61/server1/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.

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.

Input

The Input directive selects filters that will process
incoming request data read by the Service step. It allows
you to invoke the insert-filter SAF in order to install
filters that process incoming data.

The Input directives are executed at most once per
request.

You can define the appropriate position of a specific filter within
the filter stack. For example, filters that translate content from XML to
HTML are placed higher in the filter stack than filters that compress data
for transmission. You can use the filter_create function
to define the filter's position in the filter stack, and init-filter-order to override the defined position.

When two or more filters are defined to occupy the same position in
the filter stack, filters that were inserted later will appear higher than
filters that were inserted earlier. That is, the order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf becomes important.

Output

The Output directive 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 plug-in first attempts to write entity body
data from the client.

The Output directives are executed at most once per
request.

You can define the appropriate position of a specific filter within
the filter stack. For example, filters that translate content from XML to
HTML are placed higher in the filter stack than filters that compress data
for transmission. You can use the filter_create function
to define the filter's position in the filter stack, init-filter-order to
override the defined position.

When two or more filters are defined to occupy the same position in
the filter stack, filters that were inserted later will appear higher than
filters that were inserted earlier. That is, the order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf becomes important.

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 around 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:/Sun/WebServer61/server1/docs/jos.html:

NameTrans fn="document-root" root="D:/Sun/WebServer61/server1/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 Chapter 9,
Using Wildcard Patterns client.)

The following NameTrans directive assigns
the name personnel to the request.

NameTrans fn=assign-name name=personnel from=/personnel

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

<Object name="personnel">
Service fn="index-simple"
</Object>

The personnel object has no PathCheck or ObjectType directives, so the server processes the PathCheck and ObjectType directives in the default object. Let's assume that all PathCheck and ObjectType directives succeed.

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

Service fn="index-simple"

The server executes this Service directive,
which calls the index-simple function.

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 task (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:

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, seeChapter 9, Using 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 generates 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.

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, the server
immediately stops executing all other directives and immediately starts executing
the Error directives.

Changes in Function Flow

There are times when the function flow changes from the normal request-handling
process. This happens during internal redirects, restarts, and URI translation
functions.

Internal Redirects

An example of an internal redirect is a servlet include or forward.
In this case, because there is no exposed NSAPI function to handle an internal
redirect, when an internal redirect occurs, the request structure
is copied into rq->orig_rq. For more information on the request data structure, seeRequest

Restarts

A restart occurs when a REQ_RESTART is returned from
a PathCheck or Service function. For
example, when a CGI is redirected using a relative path.

On a restart, much of the request is cleared. Some elements of the HTTP
request (rq->reqpb), the server’s “working”
variables (rq->vars), and response headers (rq->srvhdrs) are cleared. The method, protocol, and clf-request variables
from rq->reqpb are saved. The saved variables are put back
into the data structure. The new URI is inserted (and if there is a query
string in the new URI, that too is inserted) into rq->reqpb.
The parameter rq->rq_attr.req_restarted is set to 1.
For more information on the request data structure, seeRequest.

URI Translation

At times it is necessary to find the physical path for a URI without
actually running a request. The function request_translate_uri does this. A new request structure is created
and run through the AuthTrans and NameTrans stages
to get the physical path. Thereafter, the new request is freed.

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 correctly.

Caution –

Do not remove any directives from any obj.conf file
that are present in the obj.conf file that exists when
you first install Sun Java System Web Server. The server may not function
properly.

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, the order within the ObjectType section 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 around), 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.

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 backslashes
(\) in path names under Windows. Backslash 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:

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: