NetscapeCommunications Corporation ("Netscape")and its licensorsretain all ownership rights to the software programsoffered by
Netscape (referred to herein as "Software") a nd related documentation. Use of the Software and related documentation is governed
by the license agreement for the Software and applicable copyright law.
Your rightto copy this documentation is limited by copyright law. Making unauthorized copies, adaptationsor compilationworks is
prohibitedand constitutes a punishable violation of the law. Netscapemay revisethis documentation from time to time without
notice.
THIS DOCUMENTATION IS PROVIDED " AS IS" WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL NETSCAPE BE
LIABLE FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING FROM ANY
ERROR IN THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION ANY LOSS OR INTERRUPTION OF BUSINESS,
PROFITS, USE, OR DATA.
This product includes software developed by Apache Software Foundation (http://www.apache.org/).Copyright (c) 1999 The
Apache Software Foundation. All rights reserved.
This product includes software developed by the University of California,Berkeley and its contributors. Copyright(c) 1990, 1993,
1994 The Regents of the University of California. All rights reserved.
Netscapeand the Netscape N logo are registered trademarksof Netscape Communications Corporation in theUnited States and
other countries. Other Netscape logos, product names and servicenames are also trademarks of Netscape and may b e registered in
some countries. Sun, Sun Microsystems, and the Sun logo, iPlanet, and the iPlanet logo are trademarks or registered trademarks of
Sun Microsystems, Inc. in the United States and other countries. Other product and brand names are trademarks of their respective
owners.
The downloading, exporting, or reexporting of Netscape software or any underlying information or technology must be in full
compliance with all United States and other applicable laws and regulations. Any provision of N etscape software or documentation
to the U.S. government is with restricted rights as described in the license agreement for that Software.
Appendix G Alphabetical List of Directives in magnus.conf . . ...................... 345
Appendix H AlphabeticalListofPre-definedSAFs ............................... 351
Index ....................................................................... 357
14Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
About This Book
This book discusses how to use the Netscape® Server Application P rogrammer's
Interface (NSAPI) to build plugins that define Server Application Functions (SAFs)
to extend and modi fy Netscape Enterprise Server. The bo ok also discusses the
purpose and use of the configuration files
and
mime.types, and provides comprehensive lists of the directives and functions
that c a n be used in these configuration files. It also provides a reference of the
NSAPI functions you can use to define new plug ins.
This book has the following chapters and appendices:
•Chapter 1, “Basics of Server Operation”
This chapter discusses how the uses configuration files to perform
initialization tasks a n d to process client requests.
obj.conf, magnus.conf,server.xml,
•Chapter 2, “Syn tax and Use of obj.conf”
This chapter goes into detail on the configuration file
discusses the syntax and use of directives in this file, which instruct the server
how to process requests.
•Chapter 3, “Predefined SAFs and the Request Handling Process”
This chapter discusses each of the stages in the request handling process, and
provides an API reference of the Server Application Functions (SAFs) that can
be invoked at each stage.
•Chapter 4, “Creating Custom SAFs”
This chapter discusses how to create your own plugins thatdefine new SAFs to
modify or extend the way the server handles requests.
•Chapter 5, “NSAPI Function Reference”
obj.conf.Thechapter
15
This chapter presents a reference of the functions in the Netscape Server
Application Programming Interface (API). You use N SAPI functions to define
SAFs.
•Chapter 6, “Examples of Custom SAFs”
This chapter discusses examples of custom SAFs to use at each stage in the
request handling process.
•Chapter 7, “Syntax and Use of magnus.conf”
This appendix discusses the variables you can s et in the configuration fil e
magnus.conf to config ure the during initialization.
•Chapter 8, “Vir tual Server Configuration Files”
This appendix discusses the variables you can s et in the configuration fil e
server.xml to configure virtual servers in .
•Appendix A, “Data Structure Reference”
This appendix d iscusses some of the commonly used NSAPI data structures.
•Appendix B, “MIME Types”
This appendix discusses the MIME types file, which maps file extensions to file
types.
•Appendix C, “Wildcard Pat terns”
This appendix lists the wildcard patterns you can use when specifying values
in
obj.conf, various predefined SAFs, and in some NSAPI functions.
•Appendix D, “Time Formats”
This appendix lists time formats.
•Appendix E, “HyperText T ransfer Protocol”
This appendix gives an overview of HTTP.
•Appendix F, “Dynamic Results Caching Functions”
This appendix ex plains how to create a results caching plugin.
•Appendix G, “A lphabetical List of NSAPI Functions and Macros”
Appendix G, “ Alphabetical List of Directives in magnus.conf”
Appendix H, “ Alphabetical List of Pre-defined SAFs”
These appendices provide alphabetical lists for easy lookup of NSAPI
functions, predefined SAFs, and variables in
16Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
magnus.conf.
NOTEThroughout this manual, all descriptions specific to UNIX®
descriptions apply to the Linux® operating system as well, ex cept
where Linux is specifically mentioned.
Where to Find Related Information
AdditionalEnterpriseServer documentationincludes:
•Netscape Enterprise Server Installation and Migration Guide
•Netscape Enterprise Server Performance Tuning, Sizing, and Scaling Guide
•Netscape Enterpri se Server Administrator’s Guide
•Netscape Enterprise Server Programmer’s Guide
•Netscape Enterprise Server Programmer’s Guide to Servlets
•Netscape Enterprise Server Release Notes
You can find Enterprise Server documentation online in PDF and HTML formats
at:
Where to Find Related Information
http://enterprise.netscape.com/docs
About This Book17
Where to Find Related Information
18Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Chapter1
Basics of Server Operation
The configuration and behavior of Netscape Enterprise Server is determined by a
set of configurationfiles. You can change the settings in these configurationfiles
either by using the Server Manager interface or by manu ally editing the files.
The configuration file that contains instructions for how the server processes
requests from clients is called
handling process by adding or changing the instructions in
the Netscape Server Application Programming Interface (API) to create new Server
Application Functions (SAFs) to use in instructions in
This chapter discusses the configuration files used by the . Then the chapter looks
in more detail at the server’s process fo r handling requests. The chapter closes by
introducing the use of Netscape Server Applicat ion Programming Interface
(NSAPI) to define new functions to modify the request-handling process.
obj.conf. You can modify and extend the request
obj.conf.Youcanuse
obj.conf.
This chapter has the following sect ions:
•Configuration Files
•Dynamic Reconfiguration
•How the S er ver Handles Requests from Clients
•Writing New Server Application Functions
19
Configuration Files
Configuration Files
The configuration and operation of the is controlled by configuration files. The
configuration file s reside in the directory
directory contains various configuration files for controlling different components,
such as
configuring NetShare. The exact number and names of c onfiguration files d epends
on which c o mponents have been enabled or loaded in to the server.
However, this directory always contains four configuration files that are essential
for the server to operate. These files are:
•
•
•
•
jsa.conf for configuring server-side JavaScript™ and netshare.conf for
magnus.conf – contains global server initialization information.
server.xml – contains initialization information for virtual servers and listen
sockets.
obj.conf – contains instructio ns f or handling requests from clients.
mime.types – contains information for determining the content type of
requested resources.
server-root/server-id/config/.This
magnus.conf
This file sets values of variables that configure the server during initialization. The
serverlooksatthisfileandexecutesthesettingsonstartup.Theserverdoesnot
look at this file again until it is restarted.
See Chapter 7, “Syntax and Use of magnus.conf” for a list of all the variables and
Init directives that can be set in magnus.conf.
server.xml
This file configures the addresses and ports that the server listens on and assigns
virtual server classe s and virtual servers to the se listen sockets. A master file,
server.dtd, defines its format and content.
For more information about how the server uses
Chapter 8, “Virtual Server Configuration Files.”
NOTEVirtual servers are not the same thing as server instances. Each
server instance is a completely separate server that contains one or
more virtual servers.
20Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
server.dtd and server.xml,see
Configuration Files
obj.conf
This file contains instructions for the server about how to process requests from
clients (such as browsers). The serv er looks at the configuration defined by this file
every time it processes a request from a client.
There is one
servers. Wh enever this guide refers to “the
obj.conf file for each virtual server class, or grouping of virtual
obj.conf file,” it refers to all obj.conf
filesortotheobj.conf file for the virtual server class being described.
All the
They are typically named vsclass
obj.conf files are located in the server_root/server_id/config directory.
.obj.conf,wherevsclass is the virtual server class
name.
The
obj.conf file is essential to the operation of the . When you make changes to
the server through the Server Manager interface, the system automatically updates
obj.conf.
The file
obj.conf cont ains a series of instructions (directives) that tell the what to
do at each stage in the request-response process. Each directive invokes a Server
Application Function (SAF). These functions are written using the Netscape Server
Application Programming Interface (NSAPI). The comes with a set of pre-defined
SAFs, but you can also write your own using NSAPI to create new instructions that
modify the way the server handles requests.
For more information about how the server uses
obj.conf, see C hapter 2, “Syntax
and Use of obj.conf.”
mime.types
This file maps file ex tensions to MIME types to enab le the server to determine the
content type of a requested resource. For example, requests for resources with
.
html extensions indicate that the client is requesting an HTML file, while requests
for resources with
file in GIF format.
.gif extensions indicate that the client is requesting an image
For more information about how the server uses
“MIME Types.”
mime.types, see Appendix B,
Chapter 1Basics of Server Operation21
Dynamic Reconfiguration
Dynamic Reconfiguration
You do not have to restart the server for changes to obj.conf, mime.types,
server.xml, and virtua l-server-specific ACL files to take effect. All you need to do
is apply the changes b y c licking 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
into memory that contains all the information from the dynamically configurable
files.
Every new connection r eferences the newest configuration. Once the last ses sion
referencing a configurationends, the now unused old configuration i s deleted.
obj.conf and apply the changes, a new configuration is loaded
How the Server Handles Requests from Clients
is a web server that accepts and responds to HyperText Transfer Protocol (HTTP)
requests. Browsers like NetscapeCommunicator communicate using several
protocols including HTTP, FTP, and gopher. The handles HTTP specifically.
For more information abo ut the HTTP protocol refer to Appendix E, “HyperText
Transfer Protocol” and also the latest HT TP specification.
HTTP Basics
As a quick summary, the HTTP/1.1 protocol works as follows:
•theclient (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
The request consists of a line indicating a method such as
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 m a y provide various
information about the request or the client Body data. Headers are typically only
sentforPOSTandPUTmethods.
22Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Connection: Close header.
GET or POST,aUniversal
How the Server Handles Requests from Clients
The example request shown below would be sent b y a Netscape browser to request
the server
foo.com to send back the resource in /index.html.Inthisexample,no
bodydata is sent becausethe method is GET (thep oint of the request isto get some
data, not to send it.)
GET /index.html HTTP/1.0
User-agent: Mozilla
Accept: text/html, text/plain, image/jpeg, image/gif, */*
Host: example.com
The server receives the request and processes it. It handles each request
individually, although it may pro cess many requests simultaneo usly. Each request
is broken down into a series of steps that together make up the request handling
process.
The server gen erates a response which includes the HTTP proto col version, HTTP
status code, and a reason phrase separated by spaces. This is normally followed by
a number of headers. The end of the headers is indicated by a blank line. The body
data of the response follows. A typical HTTP response might look like this:
HTTP/1.0 200 OK
Server: Netscape-Enterprise/6.0
Content-type: text/html
Content-length: 83
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 t he body data contains the requeste d i tem. Other result
codes indicate redirection to another server or the browser’scache, or various types
of HTTP errors such as “404 Not Found.”
Chapter 1Basics of Server Operation23
How the Server Handles Requests from Clients
Steps in the Request Handling Process
When the server first starts up it performs some initialization and then waits for an
HTTP request from a client (such as a browser). When it receives a request, it first
selects a virtual server. For details about h ow the virtual server is determined, see
“Virtual Server Selection for Request Processing,” on page 306.
After t he virtual server is selected, t he
obj.conf file for the virtual server class
specifies how the re qu est is handled in the following steps:
1.AuthTrans (authorization translation)
verify any authorization information (such as name and password) sent in the
request.
2.NameTrans (name translation)
translate the logical URI into a local file system path.
3.PathCheck (path checking)
check the local file system path for validity and check that the requestor has
access privileges to the requested resource on the file system.
4.ObjectType (object typing)
determine the MIME-type (Multi-purpose Internet Mail Encoding) of the
requested resource (for example.
5.Service (generate the response)
text/html, image/gif, and so on).
generate and return the response to the client.
6.AddLog (adding log entries)
add entries to log file(s).
7.Error (service)
This step is executed only if an error occurs in t he previous steps. If an error
occurs, the server logs an error message and aborts the pr ocess.
24Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Writing New Server Application Functions
Directives for Handling Requests
The file obj.conf containsa series of instructions,known as directives, that tell the
what to do at each stage in the request handling process. Each directive invokes a
Server Application Function (SAF) wit h one or more arguments. Eac h directive
applies to a specific s tag e in the request handling process. The stages are
For example, the following directive applie s during the
the
document-root function with the root argument set to
D:/Netscape/Servers/docs. (The document-rootfunction translates the
http://server_name/ partof the URL to the document root, which in this example
The functions invoked by the directives in obj.conf are known as Server
Application Functions (SAFs).
NameTrans stage. It calls
Writing New Server Application Functions
The comes with a variety of pre-defined SAFs that you can use to create more
directives in
provided by t he NSAPI. After you write the SAF, you would add a directive to
obj.conf so that your new function gets invoked by the server at the appropriate
time.
Each SAF has its own arguments, which are passed to it by the directive in
obj.conf. Every SAF is also passed additional arguments that contain information
about the request (such as what resource was r equested and what kind of client
requested it) and any other server variables created or modified by SAFs called by
previously invoked directives. Each S A F may examine, modify, or create server
variables.
obj.conf. You can also write your own SAF using the functions
Each SAF returns a result code which tells the server whether it succeeded, did
nothing, or failed.
For more information about
For more information on the pre-defined SAFs, see Chapter 3, “Predefined SAFs
and the Request Handling Process.”
For more information on writing yourown SAFs, see Chapter 4, “Creating Custom
SAFs.”
obj.conf, see Chapter 2,“Syntax and Use of obj.conf.”
Chapter 1Basics of Server Operation25
Writing New Server Application Functions
26Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Chapter2
Syntax and Use of obj.conf
The obj.conf configuration file contains direct ives that instruct the N etscape
Enterprise Server how to handle requests from clients. This ch apter discusses
server instructions in
flow of control in
about example directives.
obj.conf; the syntax rules for editing obj.conf;andanote
•Variables Defin ed in server.xml
•Flow of Control in obj.conf
•Syntax Rules for Editing obj.c onf
•About obj.conf Directive Examples
Server Instructions in obj.conf
The obj.conf file contai ns directives that instruct the server how to handle
requests received from clients such as browser. These directives appear inside
OBJECT tags.
Each directive call s a function, indicating when to call it and specifying arguments
for it.
NameTrans fn="document-root" root="D:/Netscape/Servers/docs"
Directive indicates when this instruction is executed during the request handling
process. The value is one of
Service, Error,andAddLog.
AuthTrans, NameTrans, PathCheck, ObjectType,
The value of the
to execute. All directives must supply a value for the
fn argument is the name of the Server App lication Function (SAF)
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 t o function.
Enterprise 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,asdiscussed
in Chapter 3, “Predefined SAFs and the Request Ha ndling Process.” You can also
define new SAFs, as discussed in Chapter 4, “C reating 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 D irectives
Here are the categories of server directives and a description of what each does.
Each category correspondsto a stage in the request handling process. The section
“Flow of Control in obj.conf,” on page 35 exp lains exactly how the server decides
which directive o r directives to execute in at each s t age.
•
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’saccess privileges for
the requested resource.
This example calls the basic-auth function, which calls a custom function (in
this case
ntauth, toverify authorization information sent by the client. The
Authorization header is sent as part of the basic server authorization scheme.
28Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Server Instructions in obj.conf
•NameTrans
Translates the URL specified in the request from a logical URL to a physical file
system path fo r the requested resource. This may also result in redirection to
anothersite.Forexample:
This example calls the document-root function with a root argument of
D:/Netscape/Servers/docs. The functio n document-root function translates
the
http://server_name/ part of the requested to URL to the document root,
whichinthiscaseis
http://server-name/doc1.html is translated to
D:/Netscape/Servers/docs/doc1.html.
•
PathCheck
D:/Netscape/Servers/docs.Thusarequestfor
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 exam ple:
This example calls the find-index functionwith 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 (Mu lti-purpose Internet Mail Encoding) type of the
requested resource. The MIME type has attributes
content type),
encoding and language. The MIME type is sent in the hea ders
type (which indicates
of the response to the client. The MIME type also helps determine which
Service directive the server should execute.
The resulting type m ay be:
❍Acommon document type such as text/html or image/gif (for example,
the file name extension
❍An internal server type. Internal types always begin with
magnus-internal.
.gif translates to the MIME type image/gif).
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.
Chapter 2Syntax and Use of obj.conf29
Server Instructions in obj.conf
•Service
Generates and sends the responseto 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 method="(GET|HEAD|POST)" type="*~magnus-internal/*"
fn="send-file"
Service directive is:
This directive instructs the server to call the send-file function in response to
any request whose method is
begin with
magnus-internal/. (Note the use of the special characters *~ to
GET, HEAD,orPOST,andwhosetype does not
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,andthetypeof
the requested resource is
imagemap is called.
•
AddLog
"magnus-internal/imagemap",thefunction
Adds an entry to a log file to record information about the transaction. For
example:
AddLog fn="flex-log" name="access"
This ex ample calls the flex-log function to log information about the current
request in the log file named
•
Error
access.
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.
The server always starts handling a request by processing the directives in the
default object. However, the server switches to processing d irectives in another
object after the
conditions is true:
•The successful
•the physical pathname that results from the
ppath attribute of another object
When the s erver has been alerted to use an object other than the default object, it
processes the di rectives 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
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,” on page 35.
If a NameTrans directive in the default object specifies a name argument, the server
switches to pro cessing the directives in the object of that name before processing
the remaining directives in the default o bject.
For example, the following
name
cgi to any request whose URL starts with http://server_name/cgi/.
NameTrans directive in the default object assigns the
When that NameTrans directive is executed, the server starts processing directives
in the object named
<Object name="cgi">
more directives...
</Object>
cgi:
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
the server sw itches to processing the directives in that object before processing the
remaining ones in the default object.
ppath attribute of another object in obj.conf,
For example, the following
http://server_name/ part of the requested URL to D:/Netscape/Servers/docs/
32Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
The <Object> Tag and the <Client> Tag
The URL http://server_name/internalplan1.html would be translated to
D:/Netscape/Servers/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
D:/Netscape/Servers/docs/internalplan1.html. So now the server starts
*internal* matches the path
processing the directives in this object befo re processing the remaining directives
in the default object.
The Client Tag
The <Client> tag can be used within an object to limit the execution of a set of
directives to requests received from specific clients. Directives listed between a pair
of
<Client> </Client> tags are executed only if information in the client request
matches the parameter value specified by the
A
<Client> tag accepts the parameters ip, dns,orhost. Use one and only one of
these parameters to specify the client information to match.
Table 2-1<Client>Tag Parameters
ParameterDescription
ipThe IP address of the client.
dnsThe DNS name of the clie nt.
urlhost
The DNS name of the virtual server requested by the
client. This value is provided in the
client request. This is how virtual servers were defined
in earlier versions of Enterprise Server. See the NetscapeEnterprise Server Ad ministrator’s Guide for information
on how Netscape recommends implementing virtual
servers in Enterprise S erver 6.1.
<Client> tag.
Host header of the
Youcanusewildcardstospecify<Client> tag parameter values. For ex ample:
Chapter 2Syntax and Use of obj.conf33
Variables Defined in server.xml
<Client ip="198.95.251.*"> or <Client dns="*.example.com">
See “Wildcard Patterns,” on page 325 for more information on wildcards.
You can also use wildcards to specify a “negative” match, one that excludes clients
that match the parameter value specified in the
following combination of the
<Client> tag and the AddLog directive tells
Enterprise Server to log access requests from all clients except those that come from
the specified subne t.
Using the ~ wildcard to specify the valu e o f the ip parameter negates the
expression, so Enterprise Server will exclude clients from the
from the access log.
Variables Defined in server.xml
You can define variables in the server.xmlfile and reference them i n an obj.conf
file. For example, the following server.xml code defines and uses a variable called
docroot:
<Client> tag. For example, the
192.95.251. subnet
<!DOCTYPE SERVER SYSTEM "server.dtd" [
<!ATTLIST VARS
Before the server can process a request, it must direct the request to the correct
virtual s erver. For details about how t he virtual server is determined, see “Virtual
Server Selection for Request Processing,” on page 306.
After t he virtual server is determined, the server executes the
virtual server class to which the virtual server belongs. This section discusses how
the server d ecides which directives to execute in
AuthTrans
obj.conf file. It is not
obj.conf file m ust be defined in the
SERVER or VSCLASS level and
VS is recommended.
obj.conf file for the
obj.conf.
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 m ore 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 ser ver’s file
system. The server looks at each
untilitfindsonethatcanbeapplied.
If there is more than one
considers each directive until one succeeds.
NameTrans directivein the default object, the server
NameTrans directiveinthedefaultobjectinturn,
Chapter 2Syntax and Use of obj.conf35
Flow of Control in obj.conf
The NameTrans section in the default object must contain exactly one directive that
invokes the
http://server_name/par t of the requested URL to a physical directory that has
been designated as the server’s document root. For example:
Notice that if this directive appeared after the one tha t ca lls document-root,it
would never be ex ecuted, with the result that the resultant directory pathname
would be
directive that invokes
section.
document-root function. This functions translates the
pfx2dir (prefix to directory) function is used to s et up additional mappings
http://server_name/cgi/ into the directory pathname
D:/netscape/servers/docs/cgi/ (not mycgi). This illustrates why the
document-root must be the last one in the NameTrans
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
successfully executed specifies a name or generates a partial path that matches the
name or ppath attribute of another object.
If the successful
argument, the server starts processing directives i n 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
name
cgi to any request whose URL starts with http://server_name/cgi/.
D:/Netscape/Servers/docs/internalplan1.html. So now the server would
obj.conf contains an object as follows:
NameTrans directive translates the requested URL to
*internal* matches the path
start processing the directives in this object before processing the remaining
directives i n 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 r esource.
Ifthereismorethanone
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.
Chapter 2Syntax and Use of obj.conf37
Flow of Control in obj.conf
If the NameTrans directive assigned a name or generated a physical pathname that
matches 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
MIME type has three at tributes: type, encoding, and language. When the server
sends the response to the client, the type, language, and encoding v alues are
transmittedin the headers of the response. The
serverto determine which
the client.
name or ppath attribute of another object, the server fir s t applies the
ObjectType directives to determine the MIME type of the request. The
type also freq ue ntly helps the
Service directive to execute to generate the response to
If there is more than one
ObjectType directive, the server applies all the d ire ctives
in the order in which they appear. However, once a directivesets 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
As with the
as a result of the
the matching o bject before executing the
type, while another directive sets a different attribute, such as language.
PathCheck directives, if another o bject has been matched tothe request
NameTrans step, the server executes the ObjectType directivesin
ObjectType dire ctives 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
For example, the entry in the MIME types table for the extensions
usually:
type=text/htmlexts=htm,html
which says that all file s that have the extension .htm or .html are text files
formatted as HTML and the
mime.types).
.html and.htmis
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.
38Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Flow of Control in obj.conf
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
after
type-by-expression has been executed. Usually if t he server does not
recognize the file extension, it is a g ood idea to force the type to be
that t he content of the resource is treated as plain text. There are also other
situations w here you might want to set the t ype regardless of the file extension,
such as forcing all resour ces in the designated CGI dire ctory to have the MIME
type
magnus-internal/cgi.
MIME types table, the type still has no value even
text/plain,so
The function thatforces the type is
force-type.
For example, the following directives first instruct the server to look in the MIME
types table for the MIME typ e, then if the
the file ex tension was not found in the MIME types table), set the
If the server receives a request for a file
does not find a mapping for the extension
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
type is forced to magnus-internal/cgi before the server gets a chance to look in
type attribute has not been set (that is,
type attribute to
abc.dogs,it looks in the MIME types table,
.dogs, and consequently does not set the
force-type. In this example , the
the MIME types table. In this case, all requests for resources in
http://server_name/cgi/ are translatedinto r equests for resources in the
directory
request, the server processes
processing the ones in the default object. This o b j ect has one
which forces the
D:/netscape/servers/docs/mycgi/. Since a name i s assigned to the
ObjectType directives in the object named cgi before
ObjectType directive,
type to be magnus-internal/cgi.
Chapter 2Syntax and Use of obj.conf39
Flow of Control in obj.conf
The server continuesprocessing all ObjectType directives including those in the
default object, but since the
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
first one that matches the type, method and query string. If a
does not specify type, method, or query string, then the unspecified attribute
matches anything.
type attribute has already been set, no other directive
Service d irective in turn, to find the
Service directive
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
directives.
As with the
PathCheck and ObjectType directives, if another object has been
matchedtotherequestasaresultofthe
Service directives in the matching object before considering the ones in the default
object. If the server successfully executes a
object,itwillnotgetroundtoexecutingthe
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
directives executed by the server are in the default object.
NameTrans directive translates the requested URL to
•AssumethatthePathCheck directives all succeed.
40Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
D:/server_name/jos.html.Inthiscase,all
Service
NameTrans step, the server considers the
Service directive in the matching
Service directives in the default
Flow of Control in obj.conf
•Thefollowing ObjectType directivetellstheservertolookuptheresource’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 t he
type attribute to
type=text/html exts=htm,html
text/html:
•The server invokes t he following Service directive. The value of the type
parameter matches anything that does not begin with magnus-internal/.(For
a list o f all wildcard patterns, see Appendix C, “Wildcard Patterns.”) This
directive sends the requested file,
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*"
fn="send-file""
jos.html, to the client.
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/servers/docs/servlet/ has been registered as a s ervlet
directory (that is, the server treats all filesin that directory as servlets).
The server continuesprocessing all the ObjectTypedirectives in the default
object, but since the
•Whenprocessing
Service directive in the ServletByExt object which is:
Service type="magnus-internal/servlet" fn="NSServletService"
type attribute is already set its value cannot be changed.
Service directives, the server starts by considering the
•Thetype argument of this directive matches the type valuethatwassetbythe
ObjectType directive. So the server goes ahead and executes this Service
directive which calls the NSServletService functio n. This function invokes
the requested file as a servlet and sends t he output from the servlet as the
response to the client. (If the requested resource is not a servlet, an error
occurs.)
Since a
any other
Service directive that was executed, the server would continue looking at
Service directives in the d efault object.)
Service directive has now been executed, the server does not process
Service directives. (However, if the matching object had not had a
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 d ir ective
should come last in the list of
only gets called if no other
Service directive is usually:
Service directives in the default object, to ensure it
Service d irectives have succeeded. The default
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*"
fn="send-file"
42Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Flow of Control in obj.conf
This directive matches requests whose method is GET, HEAD,orPOST, which covers
nearly virtually all requests sent by browsers. The value of the
type argument uses
special pattern-matching characters. For complete in formation about the special
pattern-matching characters, see Appendix C, “W ildcard Patterns.”
The characters “
so the expression
magnus-internal/.” An asterisk by itse lf matches anything, so the who le
expression
magnus-internal/.
So if the server has not already executed a
directive, it executes the directive so long as t he request method is
POST,andthevalueofthetype attribute does not begin with magnus-internal/.
The invoked function is
*~” mean “anything that doesn’t match the following characters,”
*~magnus-internal/ means “anything that doesn’t match
*~magnus-internal/* matches anything thatdoes n ot begin with
Service directive when it reaches this
GET, HEAD or
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 execute s 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 us ed and which format they use, the
in
magnus.conf may need to have directives that initialize the logs. For example, if
one of the
the
AddLog directives ca lls flex-log, whi ch uses the extended log format,
Init sectio n must contain a directive that invokes flex-init to initialize the
flexible logging syste m.
Init section
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 a c cess to the requested resource, or the requested
resource does not exist, then the server immediately stops executing all other
directives and immediately starts executing t he
Error directives.
Chapter 2Syntax and Use of obj.conf43
Syntax Rules for Editing obj.conf
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 op erate incorrectly.
Order of Directives
The order o f directives is important, since the server executes them in the order
they appear in
other directives.
For
PathCheck directives, the order within the PathCheck section is not so
important, s ince the server executes all
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
following order (which is the wrong way round), every request w o uld have its
type value set to text/plain, and the server woul d nev e r have a chance to set the
type according to the extension of the requested resource.
obj.conf. The outcome of some directives affect the execution of
Similarly, the order of directives in the
server executes the first
does not execute any others.
Service directive that matches the current request and
Service section is very important. The
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.
44Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Syntax Rules for Editing obj.conf
Separators
The C language allows func tion 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 truefor function
names.
Quotes
Quotes (") are only req u ired around value strings when there is a space in the
string. Otherwise they are optional. Each open-quote must be m a tched 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 beg inning the next line with a
space or tab.
Path Names
Always use forwardslashes (/) rather than bac k- slashes (\)inpathnamesunder
Windows NT/Windows 2000. 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 i t updates
Chapter 2Syntax and Use of obj.conf45
obj.conf.
About obj.confDirective Examples
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 n ot 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
46Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Chapter3
Predefined SAFs and the Request
Handling Process
This chapter describes the standard directives and pre-defined Server Application
Functions (SAFs) that are used in the
server. For a discussion of the use and syntax of
chapter, Chapter 2, “Syntax and Use of obj.conf.”
obj.conf file to give instructions to the
obj.conf,seetheprevious
For a list of
magnus.conf.”
This chapter includes functions that are part of the core functionality of N etscape
Enterprise Server. It do es not include functions that are available only if additional
components, such a s servlets and server-parsed HTML, ar e enabled.
This chapter co ntains a section for ea ch directive which lists al l the pre-defined
Server Application Functions that can be used with that directive.
The directives are:
•
AuthTrans Stage
•NameTrans Stage
•PathCheck Stage
•ObjectType Stage
•Service Stage
•AddLog Stage
•Error Stage
For an alphabetical list of pre-defined SAFs, see Appendix G , “Alphabetical List of
Directives in magnus.conf.”
Init (initialization) SAFs, see Chapter 7, “Syntax and U se of
47
Table 3-1 lists the SAFs that can be used with each directive.
Table 3-1Available Server Application Functions (SAFs) Per Directive
AuthTrans Stagebasic-auth
The following per formance buckets are predefined in Enterprise Server:
•The
•The
You can define additional performance buckets in the
perf-init and define-perf-bucket functions).
default-bucket records statistics for the functions not associated with
any user-defined o r built-in bucket.
all-requests bucket records.perf statistics for all NSAPI SAFs,
including those in the
default-bucket.
flex-log
record-useragent
qos-error
magnus.conf file (see the
Chapter 3Predefined SAFs and the Request Handling Process49
AuthTrans Stage
You can measure the performance of any SAF in obj.conf by adding a
bucket=bucket-name parameter to the function, for example
bucket=cache-bucket.
To list the performance statistics, use the
As an alternative, you can use the
performance statistics; use of buc kets is optional.
For more information about performance buckets, see the Netscape Enterprise Server
Performance Tuning, Sizing, and Scaling Guide.
AuthTrans Stage
AuthTrans stands for Authorization Translation. AuthTrans directives give the
server instructions for checking authorization b efore allowing a client to access
resources.
Generally, an
with the req uest are acceptable, but it do es not allow or deny access to the request
-- it leaves that to a
The server handles the authorization of client users in two steps.
•AuthTrans Direct ive - validates authoriz ation information sent by the client in
•PathCheck Stage - checks that the authorized user is allowed access to the
AuthTrans directives work in conjunction with PathCheck directives.
AuthTrans function checks if the username and password associated
the Authorization header.
requested resource.
service-dump Serv ice function.
stats-xml Service function to generate
PathCheck function.
The authorization process is split into two steps so that multiple authorization
schemes can be eas ily incorporated, as well as providing the flexibility t o have
resources that record authorization information but do not require it.
AuthTrans functions get the username and password from the headers associated
with the request. W hen a client initially makes a request, t he username and
password are unknown so the
AuthTrans functions and PathCheck functionswork
together to reject the request, since they can’t validate the username and password.
When the client receives the rejection, its usual response is to pop up a dialog box
asking for the username and password to enter the appr opriate realm, and then the
client submits the request again, this time includ ing the username and password in
the headers.
If there is more than one
AuthTrans directivein obj.conf,eachfunctionis
executed in order until one succeeds in authorizing the user.
50Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
AuthTrans Stage
The following AuthTrans-class functions are described in detail in this section:
•
basic-auth calls a custom function to verify user name and passwo rd.
Optionally determines the user’s group.
•
basic-ncsa verifies user name and password against an NCSA-style or
system DB M database. Optionally determines the user’s group.
•
get-sslid retrieves a string that is unique to the current SSL session and
stores it as the
•
qos-handler handles t he current quality of service statistics.
ssl-id variable in the Session->client parameter block.
basic-auth
Applicable in AuthTrans-class directives.
The
basic-auth function calls a custom function to verify aut horization
information sent by the client . The Authorization header is sent as part of the basic
server aut horization scheme.
This function is usually used in conjunction with the PathCheck-class function
require-auth.
Parameters
auth-typespecifies the type of authorization to be used. This should
always be basic.
userdb(optional) specifies the full path and file name of the user
database to be used f or user verification.This parameter will
be passed to the user function.
userfnis the name of the user custom function to verify
authorization. This function must have been previously
loaded with load-modules. It has the same interfaceas all
the SAFs, but it is called w ith the user name (user),
password (pw),user database(userdb), and groupdatabase
(groupdb) if supplied, in the pb parameter. The user
function should check the name and password using the
database and return REQ_NOACTION if they are not valid. It
should return REQ_PROCEED if the name and password are
valid. The basic-auth function will then add auth-type,
auth-user (user), auth-db (userdb), and
auth-password (pw, Windows NT/Windows 2000 only)
to the rq->vars pblock.
Chapter 3Predefined SAFs and the Request Handling Process51
AuthTrans Stage
groupdb(optional) specifies the full path and file name of the user
database. This parameter will be passed to the group
function.
groupfn(optional) is the name of the g r oup custom function that
must ha ve been previously loaded with load-modules.It
has the same interface as all the SAFs, but it is called with
the user name (user), password (pw), user database
(userdb), and group database(groupdb)inthepb
parameter.It also hasaccess to the auth-type, auth-user
(user), auth-db (userdb), and auth-password(pw,
Windows NT/Windows 2000 only) parameters in the
rq->vars pblock. The group function should determine
the user’s group using the group database, add it to
rq->vars as auth-group, and return REQ_PROCEED if
found. It should return REQ_NOACTIONif the user’s group
is not found.
52Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
AuthTrans Stage
basic-ncsa
Applicable in AuthTrans-class directives.
The
basic-ncsa function verifies authorization information sent by the client
against a database. The Authorization header is sent as part of the basic server
authorization scheme.
This function is usually used in conjunction with the PathCheck-class function
require-auth.
Parameters
auth-typespecifies the type of authorization to be used. This should
always be basic.
dbm(optional) specifies the full path and base file name of the
user database in the server's native format. The native
format is a system DBM file, which is a hashed file format
allowing instantaneous access to billions of users. If you use
this parameter, don’t use the userfile parameter as well.
userfile(optional) specifies the full path name of the user database
in the NCSA-style HTTPD user file format. This format
consists of lines using the format
password is encrypted.If you use this parameter,don’tuse
dbm.
name:password,where
grpfile(optional) specifies the NCSA-style HTTPD group file to be
ssl-id is present when a CGI is invoked, it is passed to the CGI as
hasnoeffectifSSLisnotenabled.
Parameters
bucketoptional, common to all obj.conf functions
qos-handler
Applicable in AuthTrans-class directives.
The
qos-handler function examines the current quality of service statistics for the
virtual server, virtual server class, and global server, logs the statistics, and
enforces the QOS parameters by returning an error. This must be the first
AuthTrans functionconfigured in thedefault object in order to work properly.
Let’s s uppo se the server receives a request for http://server-name/personnel.
After processing this
personnel in obj.conf, and continues by processing the directives in the
personnel object.
The
assign-name function always returns REQ_NOACTION.
Parameters
fromis a wildcard p attern that specifies the path to b e affected.
namespecifies an additional named object in obj.conf whose
NameTrans directive, the server looks for an object named
directives will be applied to this request.
find-pathinfo-forward(optional) makes the server look for the PATHINFO
forward in the path right after the ntrans-base instead of
backward from the end of path as the server function
assign-name does by default.
The value you assign to this parameter is ignored. If you
do not wish to use this pa rameter, leave it out.
The find-pathinfo-forward parameter is ignored if
the ntrans-base parameter is not set in rq->vars.By
default, ntrans-base is set.
This feature can improve performance for certain URLs by
reducing the number of stats performed.
56Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
NameTrans Stage
nostat(optional) prevents the server from performing a stat on a
specified URL whenever possible.
The effect of nostat="
function assign-name is that the server assumes that a
stat on the specified
nostat only when the path of the
exist on the system, for example, for NSAPI plugin URLs,
to improve performance by avoiding unnecessary stats on
those URLs.
When the default PathCheck server functions are used,
the server does not stat for the paths
/
ntrans-base/virtual-path and
/
ntrans-base/virtual-path/* if ntrans-base is set (the
default condition); it does not stat for the URLs
/
virtual-pathand /virtual-path/* if ntrans-ba se is not
set.
bucketoptional, common to all obj.conf functions
Example
# This NameTrans directive is in the default object.
NameTrans fn=assign-name name=personnel from=/a/b/c/pers
...
<Object name=personnel>
...additional directives..
</Object>
document-root function specifies the root documentdirectory for the server.
If the physical path has not been set by a previous
http://server-name/ part of the path is replace by the physical pathname for t he
document root.
Chapter 3Predefined SAFs and the Request Handling Process57
NameTrans function, the
NameTrans Stage
When the server receives a request for http://server-name/somepath/somefile,
the
document-root function replaces http://server-name/ with the value of its
root parameter.For example, if the document root directoryis
/usr/netscape/servers/docs, thenwhen the serverreceives a request for
http://server-name/a/b/file.html,thedocument-root function translates the
pathname to
/usr/netscape/servers/docs/a/b/file.html for the requested
resource.
This function always returns
will never be called, so be sure that the dire ctive that invokes
last
NameTrans directive.
REQ_PROCEED. NameTrans directives listed after this
document-root is the
There can be only one root document directory. To specify additional document
directories, use the
Parameters
rootis the file system path to the server’s root document
with a slash (/), it is assumed to be a full path to a file.
This function sets the server’s path variable and returns
REQ_PROCEED.Ifpath is a relative path, it is appended to
the URI and the function returns REQ_NOACTION
continuing on to the other NameTrans directives.
pfx2dir function replaces a directory prefix in the requested URL with a real
directory name. It also optionally allows you to specify the name of an object that
matches the current request. (See the discussion of
assign-name for details of
using named objects.)
Parameters
fromis the URI prefix to convert. It should not have a tra iling
slash (/).
diris the local file system directory path that t he prefix is
converted to. It should not have a trailing slash (/).
name(optional) specifies an additional named object in
obj.conf whose directives will be applied to this
request.
Chapter 3Predefined SAFs and the Request Handling Process59
NameTrans Stage
find-pathinfo-forward(optional) makes the server look for the PATHINFO
forward in the path right after the ntrans-base instead of
backward from the end of path as the server function
find-pathinfo does by default.
The value you assign to this parameter is ignored. If you
do not wish to use this pa rameter, leave it out.
The find-pathinfo-forward parameter is ignored if
the ntrans-base parameter is not set in rq->vars
when the server function find-pathinfo is called. By
default, ntrans-base is set.
This feature can improve performance for certain URLs by
reducing the number of stats performed in the server
function find-pathinfo.
On Windows NT/Windows 2000, this feature can also be
used to prevent the PATHINFO from the server URL
normalization process (changing '\' to '/') when the
PathCheck server function find-pathinfo is used.
Some double-byte characters have hex values that may be
parsed as URL separator characters such as \ or ~. Using
the find-pathinfo-forward parameter can sometimes
prevent incorrect parsing of URLs containing double-byte
characters.
bucketoptional, common to all obj.conf functions
Examples
In the first example, the URL http://server-name/cgi-bin/resource (such as
http://x.y.z/cgi-bin/test.cgi) is translated to the physical pathname
/httpd/cgi-local/resource,(suchas/httpd/cgi-local/test.cgi)andthe
server also starts processing the directives in the object named
redirect function lets you change URLs and send the updated URL to the
client. When a client accesses your server with an old path, the server treats the
request as a request for the new URL.
Parameters
fromspecifies the prefix of the requested URI to ma tch .
url(may be optional) specifies a complete URL to return to the
client. If you use this parameter, don’t use url-prefix
(and vice versa).
url-prefix(may be optional) is the new URL prefix to return to the
client. The from p refix is simply replaced by this URL
prefix. If you u s e this parameter, don’t use url (and vice
versa).
escape(optional) is a flag which tells the server to
util_uri_escape t he URL before sending it. It should be
yes or no.Thedefaultisyes.
bucket(optional) common to all obj.conf functions
regex(optional) Specifies whether the expression is to be parsed as
a regular expression. Va lid values are yes and no.The
default is no.
Chapter 3Predefined SAFs and the Request Handling Process61
NameTrans Stage
Using Regular Expressions
The regex parameter allows you to use shell expressions to match a string. A shell
expression i s a string pattern made up o f ordinary characters and any o f the types
of pattern sequences listed below.
Table 3-2Shell Expression Pattern Sequences
PatternMatches
*Zero or more characters
?Exactly one character
$Matches the end of string
[abc]
Matches one instance of any of the ch aracters enclosed
in
[]
[a-z]
Matches one instance of any character in the specified
range of characters
[^abc]
Matches one instance of any character not in the
enclosed set
Backslash (\) is used to quote a character that would otherwise be considered part
of a pattern sequence. For example:
"2\*2=4"
The following composite shell expression structures a re also recognized:
Table 3-3
StructureMatches
shexp1~shexp2
Matches any string that matches shexp1, unless the
string also matches sh exp2. For example, t he following
string matches any string that does not end with
.netscape.com:
"*~*.netscape.com"
(
shexp1|...|shexpN)Matches any string that matches any one of the shell
expressions enclosed in
() andseparatedby|.
62Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
NameTrans Stage
Examples
In the first ex ample, any r equest for http://server-name/whatever is translated to a
request for
In the third example, any request that includes the string
http://server-name/toopopular/whatever
Netscape or netscape
has its prefix stripped off and replaced with http://www.netscape.com. The
remainder of t he URI/quer y string, if any, is attached t o the new prefix. A request
for
http://www.example.com/Netscape would be translated to
http://www.netscape.com.Arequestfor
http://www.example.com/netscape/foobar would be translated to
http://www.netscape.com/foobar.
strip-params function removes embedded semicolon-delimited parameters
from the path. For example, a URI of
/dir1/dir2.Whenused,thestrip-params function should be the first
NameTrans directivelisted.
Parameters
bucketoptional, common to all obj.conf functions
/dir1;param1/dir2 would become a path of
Chapter 3Predefined SAFs and the Request Handling Process63
NameTrans Stage
Example
NameTrans fn=strip-params
unix-home
Applicable in NameTrans-class directives.
UNIX Only. The
unix-home function translates user names (typically of the form
~username) into the user’s home directory on the server’s UNIX machine. You
specify a URL prefix that signa ls user directories. Any request that begins with the
prefix is translated to the user’s home directory.
You s pecify the list of users with either the
structure. Eac h line in the file should have this structure (elements in the
/etc/passwdfile o r a file with a similar
passwd
file that are not needed are indicated with *):
username:*:*:groupid:*:homedir:*
If you want the server to scan the password file only once at startup, use the
Init-class function
Parameters
fromis the URL prefix to translate, usually “/~”.
subdiris the subdirectorywithin the user’s home directory that
pwfile(optional) is the full path and file name of the password file if
name(optional) specifies an additionalnamed object whose
bucketoptional, commonto all obj.conf functions
init-uhome in magnus.conf.
contains their web documents.
it is different from /etc/passwd.
directives will be applied to this request.
Examples
NameTrans fn=unix-home from=/~ subdir=public_html
NameTrans fn=unix-home from /~ pwfile=/mydir/passwd
subdir=public_html
See Also
init-uhome, find-links
64Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
PathCheck Stage
PathCheck directives c heck the local file system path that is returned after the
NameTrans step. The path is checked for things such as CGI path i nformation and
for dangerous elements such as
restriction is applied.
PathCheck Stage
/./and /../ and //, and then any access
Ifthereismorethanone
PathCheck directive, each of the functions are executed in
order.
The followin g PathCheck-class functions are described in detail in this section:
•
check-acl checks an access control list for authorization.
•
deny-existence indicates that a resource was not found.
•
find-index locates a default file when a directory is requested.
•
find-links denies access to directories with certain file system links
•
find-pathinfo locates extra path info beyond the file name for the
PATH_INFO CGI environment variable.
•
get-client-cert gets the authenticated client certificate from the SSL3
session.
•
load-config finds and loads extra configuration information from a file in the
requested path
•
nt-uri-clean denies access to requests with unsafe path names by indicating
not found.
•
ntcgicheck looks for a CGI file with a specified extension.
•
require-auth deni es access to unauthorized users or groups.
•
set-virtual-index specifies a virtual index for a directory.
•
ssl-check checks the secret keysize.
•
ssl-logout invalidates the current SSL session in the server's SSL session
cache.
•
unix-uri-clean denies access to requests with unsafe path names by
indicating not found.
check-acl
Applicable in PathCheck-class directives.
Chapter 3Predefined SAFs and the Request Handling Process65
PathCheck Stage
The check-acl function specifies an Access Control List (ACL) to use to check
whether the client is allowedto access the requested resource. An access control list
containsinformationaboutwhoisorisnotallowedtoaccessaresource,andunder
what conditions access is allowed.
Regardless of the order of
PathCheck directives in the object, check-acl functions
are executed first. They cause user authentication to be performed, if required by
the specified ACL, and will also update the access control state.
Parameters
aclisthenameofanAccessControlList.
path(optional) is a wildcard pattern that specifies the path for
which to apply the ACL.
bucketoptional, common to all obj.conf functions
Examples
PathCheck fn=check-acl acl="*HRonly*"
deny-existence
Applicable in PathCheck-class directives.
The
deny-existence function sends a “not found” message when a client tries to
access a specifiedpath. The server sends “not found” instead of “forbidden,” so the
user cannot tell whether the path exists or not.
Parameters
path(optional) is a wildcard pattern of the file-system path to
hide. If the path does not match, the function does nothing
and returns REQ_NOACTION. If the path is not provided, it is
assumed to match.
bong-file(optional) specifies a file to sen d rather than responding
with the “not found” message. It is a full file-system path.
bucketoptional, common to all obj.conf functions
66Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
find-index function inve stigates whether the requested path is a directory. If
it is, the function searche s for an index file in the directory, and then changes the
path to point to the index file. If no index file is found, the server generates a
directory listing.
Note that if the file
obj.conf has a NameTrans directive that calls home-page,and
the requested directory is the root directory, then the home page rather than the
index page, is returned to the client.
The
find-index function do es nothing if there is a query string, if the HTTP
method is not GET, or if the path is that of a valid file.
Parameters
index-namesis a comma-separated list of index file names to look for. Use
spaces only if they are part of a file name. Do not include
spaces before or after the commas. This list is case-sensitive if
the file system is case-sensitive.
Chapter 3Predefined SAFs and the Request Handling Process67
PathCheck Stage
UNIX Only. The find-links function searches the current path for symbolic or
hard links to other directories or file s y stems. If any are found, an error is returned.
This function is normally used for directories that are not trusted (such as user
home directories ). It prevents someone from pointing to information that should
not be made public.
Parameters
disableis a character string of links to disable:
• h is hard links
• s is soft links
• o allows symbolic links from user home directories only if
the user owns the target of the link.
diris the directory to begin checking. If you specify an absolute
path, any request to that pathand itssubdirectories is checked
for symb olic links. If you specify a partial path, any request
containingt hat partial path is checked for symbolic links. For
example, if you use /user/ and a request comes in for
some/user/directory, then that directoryis checked for
symbolic links.
bucketoptional, commonto all obj.conf functions
checkFileExistencecheck linked file f or existence a nd abort request with 403
get-client-cert function gets the authenticated client certificate from t he
SSL3 session. It c an apply to all HTTP methods, or only to those that match a
specified pattern. It only works when SSL is enabled o n the server.
If the c ertificate is present or obtained fro m the SSL3 session, the function r eturns
REQ_NOACTION, allowing the request to proceed, otherwise it returns REQ_ABORTED
and sets the protocol status to 403 FORBIDDEN, causing the request to fail and the
client to be given the
FORBIDDEN status.
Parameters
dorequestcontrols whether to actually try to get the certificate, or just test for its
presence. If dorequest is absent the default value is 0.
• 1 tellsthe function to redo the SSL3 handshake to get a client
certificate, if the server does not already have the client certificate.
This typically causes the client to present a dia log box to the user
to select a client certificate. The server ma y already have the client
certificate if it was requested on the initial handshake, or if a
cached SSL session has been resumed.
• 0 tells the function not to redo the SSL3 handshake if the server
does not already have the client certificate.
If a certificate is obtained from the client and verified successfully by
the server, the ASCII base64 encoding of the DER-encoded X.509
certificate is placed in the parameter auth-cert in theRequest->vars pblock, and the function returns REQ_PROCEED,
allowing the request to proceed.
Chapter 3Predefined SAFs and the Request Handling Process69
PathCheck Stage
requirecontrols whether failure to get a client certificate will abort the HTTP
request. If require is absent the default value is 1.
• 1 tells the function to abort the HTTP request if the client
certificate is no t present after dorequest is handled. In this case,
the HTTP status is set to PROTOCOL_FORBIDDEN,andthe
function returns REQ_ABORTED.
• 0 tells the function to return REQ_NOACTION if the client
certificate is not present after dorequest is handled.
method(optional) specifies a wildcard pattern for the HTTP methods for
which the function willbe applied. If method is absent,the function is
applied to all requests.
bucketoptional, commonto all obj.conf functions
Examples
# Get the client certificate from the session.
# If a certificate is not already associated with the
# session, request one.
# The request fails if the client does not present a
# valid certificate.
PathCheck fn="get-client-cert" dorequest="1"
load-config
Applicable in PathCheck-class directives.
The
load-config function searches for configuration files in document directories
and adds the file’scontents to the server’s existing configuration. These
configuration files (also known as dynamic configuration files) spe cify additional
access c ontrol information for the requested resource. Depen ding on the rules in
the dynamic configuration files, the server mig ht or might not allow the client to
access t he requested resource.
Eachdirectivethat invokes
is either stated explicitly through the
directory for the requested resource. The base directory determines two things:
•the top-most directory for which requests will invoke this call to the
load-config function.
70Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
load-config is associated with a base directory, which
basedir par a meter or derived from the root
PathCheck Stage
For example, if the base directory is D:/netscape/servers/docs/nikki/,
then only requests for resources in this directory or its subdirectories (and their
subdirectories and so on) trigger the search for dynamic c onfiguration files. A
request for the resource
D:/netscape/servers/docs/somefile.html does
not trigger the search in this case, since the requested res ource is in a parent
directory of the base directory.
•the top-most directory in which the server looks for dynamic configuration
files to apply to the requested resource.
Ifthebasedirectoryis
D:/netscape/servers/docs/nikki/,theserverstarts
its search for dynamic configuration files in this directory. It may or may not
also search subdirectories (but never parent directories) depending on other
factors.
When you enable dynamic configuration files through the Server Manager
interface, the system writes additional objects with
obj.conf file. If you manually add d irectives that invoke load-config to the
ppath parameters into the
default object (rather than putting them in separate objects), the Server Manager
interface might not reflect yo ur changes.
If you manually add
obj.conf, put them in additional objects (created with the <OBJECT> tag) rather
than putting them in the default object. Use the
PathCheck directives that invoke load-config to the file
ppath attribute of theOBJECT tag to
specify the partial pathname for the resources to be affected by the access rules in
the dynamic configuration file. The partial pathname can be any pathname that
matches a pattern, which can include wildcard characters.
D:/netscape/servers/docs are subject to the access rules in the file
<OBJECT> tag specifies that requests for resources in the
Chapter 3Predefined SAFs and the Request Handling Process71
PathCheck Stage
NOTEIf the ppath resolvestoaresourceordirectorythatishigherinthe
directory tree (or is i n a different branch of the tree) than the base
directory, the
load-configfunction is not invoked. This is because
the base directory specifies the highest-level directory for which
requests will invoke the
load-config function.
The load-config functionreturns REQ_PROCEED if configuration files were loaded,
REQ_ABORTED on error, or REQ_NOACTION when no f iles are loaded.
Parameters
file(optional)is the name of the dynamic configuration file
containingt he access rules to be applied to the requested
resource. If not p rovided, the file name is assumed to be
.nsconfig.
disable-types(optional) specifies a wildcard pattern of types to disable for the
base directory, such as magnus-internal/cgi.Requestsfor
resourcesmatching these types are aborted.
descend(optional) if present, specifies that t he server should search in
subdirectories of this directory for dynamic configuration files.
For example, descend=1 specifies that the server should search
subdirectories. No descend parameter specifies that the
function should search o nly the base directory.
basedir(optional) specifies base directory. This is the highest-level
directory for which requests will invoke the load-config
function and is also the directorywhere the server starts
searching for configuration files.
If basedir is no t specified, the base directory is assumed to be
the root directory that results from translating the requested
resource’s URL to a physical pathname. For example, if the
request was for http://
physical file name would be
/
document-root/a/b/file.html.
bucketoptional, commonto all obj.conf functions
72Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
server-name/a/b/file.html,the
PathCheck Stage
Examples
In this example, wh enever the server receives a request for any resource containing
the substring
secret that resides in D:/netscape/servers/docs/nikki/ or a
subdirectory thereof, it searches for a configu ration file called
checkaccess.nsconfig.
The server starts the search in the directory
and searches subdirectories too. It loads each instance of
D:/netscape/servers/docs/nikki,
checkaccess.nsconfig
that it finds, applying the access control rules contained therein to determine
whether the c lient is allowed to access the r equested resource or not.
Applicable in PathCheck-class directives.
Windows NT/Windows2000 Only. The
any resource whose physical path contains
security problems).
Parameters
bucketoptional, commonto all obj.conf functions
tildeokif present, allows tilde”~” characters in URIs. This is a potential
security risk on Windows N T/Windows 2000, where
longfi~1.htm might reference longfilename.htm but does
not go through the proper ACL checking. If present, “//”
sequences are allowed.
nt-uri-clean function denies access to
\.\, \..\ or \\ (these are potential
dotdirokIf present, “//” sequences are allowed.
Examples
PathCheck fn=nt-uri-clean
Chapter 3Predefined SAFs and the Request Handling Process73
PathCheck Stage
See Also
unix-uri-clean
ntcgicheck
Applicable in PathCheck-class directives.
Windows NT/Windows2000 Only. The
ntcgicheck function specifies the file
name extension to be added to any file name that doe s not have an extension, or to
be substituted for any file name that has the extension
Parameters
extensionis the replacement file extension.
bucketoptional, common to all obj.conf functions
Examples
PathCheck fn=ntcgicheck extension=pl
See Also
init-cgi, send-cgi, send-wincgi, send-shellcgi
.cgi.
require-auth
Applicable in PathCheck-class directives.
The
require-auth function allowsaccess to resources only if the user or group is
authorized. Before this function is called, an authorization f unction (such as
basic-auth) must be called in an AuthTrans directive.
If a user was authorized in an
AuthTrans directive, and the auth-user parameter
is provided, then the user’s name must match the
if the
auth-group parameter is provided, the authorized user must belong to an
authorizedgroup which must match the
74Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
auth-user wildcard value. Also,
auth-user wildcard value.
PathCheck Stage
Parameters
path( op tional) is a wildcard local file system path on which t his
function should operate. If no path is provided, the function
applies to all paths.
auth-typeis the type of HTTP authorization used and must match the
auth-type from the previous authorization function in AuthTrans.
Currently, basic is the only authorization t ype defined.
realmis a string sent to the browser indicating the secure ar ea (or realm)
for which a user name and password are requested.
auth-user(optional) specifies a wildcard list of users who are allowed access.
If this parameter is not provided, then any user authorized by the
authorization function is allowed access.
auth-group(optional) specifies a wildcard list of groups that are allowed
set-virtual-index function specifie s a virtual index for a directory, whic h
determines the URL forwarding . The index can refer to a LiveWire application, a
servlet i n its own namespace, a Netscape Application Server applogic, and so on.
REQ_NOACTION is returned if none of the URIs listed in the from parameter match
the current URI.
virtual-index parameter is missing or if the current URI cannot be fou nd.
REQ_RESTART is returned if the current URI matches any one of the URIs mentioned
in the
from parameterorifthereisnofrom parameter.
REQ_ABORTED is returned if the file specified by the
Chapter 3Predefined SAFs and the Request Handling Process75
PathCheck Stage
Parameters
virtual-indexis the URI of the content generator that acts as an index for the
URI the user enters.
from(optional) is a c omma-separated list of URIs for which this
virtual-index is applicable. If from is not specified, the
virtual-index always applies.
bucketoptional, commonto all obj.conf functions
Examples
# MyLWApp is a LiveWire application
PathCheck fn=set-virtual-index virtual-index=MyLWApp
ssl-check
Applicable in PathCheck-class directives.
If a restriction is selected that is not consistent with the current cipher settings
under Security Preferences, this function opens a popup dialog which warns that
ciphers with larger secret keysizes need to be enabled . This function is designed to
be used together w ith a Client tag to limit access of certain directories to
non-exportable browsers.
The function returns
REQ_NOACTION if SSL is not enabled, or if the secret-keysize
parameter is not specified. If the secret keysize for the current session is less than
the specified
function returns
file is specified, the function returns
secret-keysize and the bong-file parameter is not specified, the
REQ_ABORTED with a status of PROTOCOL_FORBIDDEN.Ifthebong
REQ_PROCEED,andthepath variable is set to
the bong filename. A lso, when a keysizerestriction is not met, the SSL session
cache entry for the cur rent session is invalidated, so that a full SSL handshake will
occur the next time the sam e cl ie nt connects to the server.
Requests that use
ssl-check returnssomething other than REQ_NOACTION.
Parameters
secret-keysize(optional) is the m inimum number of bits required in the
76Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
ssl-check are not cacheable in the accelerator file cache if
secret key.
PathCheck Stage
bong-file(optional) is the name of a file (not a URI ) to be served if the
restriction is not met
bucketoptional, commonto all obj.conf functions
ssl-logout
Applicable in PathCheck-class directives.
ssl-logout invalidates the current SSL session in the server's SSL session cache.
This does not af f e ct the current request, but the next time the client connects, a new
SSL session will be created. If SSL is en abled, this function returns
after invalidating the session cache entry. If SSL is not enabled, it returns
REQ_NOACTION.
Parameters
bucketoptional, commonto all obj.conf functions
REQ_PROCEED
unix-uri-clean
Applicable in PathCheck-class directives.
UNIX Only. The
physical path contains
Parameters
bucketoptional, commonto all obj.conf functions
dotdirokIf present, “//” sequences are allowed.
Examples
PathCheck fn=unix-uri-clean
See Also
nt-uri-clean
unix-uri-clean function denies access to any resource whose
/./, /../ or // (these are potential securityproblems).
Chapter 3Predefined SAFs and the Request Handling Process77
ObjectType Stage
ObjectType Stage
ObjectType directives determine the MIME type of the file to send to the client in
response to a request. MIME attributes currently sent are
language. The MIME type sent to the clie nt a s the value of the content-type
header.
ObjectType directives also set the type parameter, which is used by Service
directives to determine how to process the request according to w hat kind of
content is bein g requested.
type, encoding,and
If there is more than one
ObjectType dire ctive in an object, all the directives are
applied in the order they appear. If a directive sets an attribute and later directives
try t o set that attribute to something else, the first setting is used and the
subsequent ones ignored.
The
obj.conf file almost always has an ObjectType directive that calls the
type-by-extension function. This function instructs the server to look in a
particular file (the MIME types file) to deduce the content type from the extension
of the requested resource.
The following
•
force-type sets the content-type header for the response to a specific type.
•
set-default-type allows you to define a default charset,
content-encoding,andcontent-language for the response being sent back
ObjectType-class functions are described in detail in this section:
to the client.
•
shtml-hacktype requests that .htm and .html files are parsed for
server-parsedhtml commands.
•
type-by-exp sets the content-type header for the response based on the
requested path.
•
type-by-extension sets the content-type header for the responsebased onthe
files extension and the MIME types database.
force-type
Applicable in ObjectType-class directives.
The
force-type function assigns a type to requests that do not already have a
MIME type. This is us ed to specify a default object type.
78Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
ObjectType Stage
Make sure that the directive that calls this function comes last in the list of
ObjectType directives so that all other ObjectType directives have a chanceto set
the MIME type first. If there is more than one
ObjectType directiveinanobject,all
the directives are applied in the order they appear. If a directive sets an attribute
and later directives try to set that attribute to something else, the first setting is
used and the subsequent ones ignored.
Parameters
type(optional) is the type assigned to a matching request (the
content-type header).
enc(optional) is the encoding assigned to a matching request (the
content-encoding header).
lang(optional) is the language assigned to a matching request (the
content-language header).
charset(optional) is the character set for the magnus-charset
parameter in rq->srvhdrs. If the browsersent the
Accept-charset header or its User-agentis mozilla/1.1
shtml-hacktype function changes the content-type of any .htm or .html file
to
magnus-internal/parsed-html and returns REQ_PROCEED.Thisprovides
backward compatibility with server-side includes for files with
extensions. The function may also check the execute bit for the file on UNIX
systems. The use of this function is not recommended.
Parameters
exec-hack(UNIX only, o ptional) tells the function to change the
content-type only if the execute bit is enabled. The va lue of the
parameter is not important. It need only be provided. You
may use exec-hack=true.
80Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
.htm or .html
ObjectType Stage
bucketoptional, common to all obj.conf functions
Examples
ObjectType fn=shtml-hacktype exec-hack=true
type-by-exp
Applicable in ObjectType-class directives.
The
type-by-exp function ma tches the current path with a wildcard expression. If
the two match, the
same as
type-by-extension, except you use wildcard patterns for the files or
directories spe cified in the URLs.
Parameters
expis t he wildcard pattern of paths for which this function is
type paramete r information is applied to the file. This is the
applied.
type(optional) is the type assigned to a matching request (the
content-type header).
enc(optional) is the encoding assigned to a matching request (the
content-encoding header).
lang(optional) is the language assigned to a matching request (the
content-language header).
charset(optional) is the character set for the magnus-charset
parameter in rq->srvhdrs.Ifthebrowsersentthe
Accept-charset header or its User-agent is mozilla/1.1
file sets the type to text/html. If the extension is .txt, the function setsthe type to
text/plain.
Parameters
bucketoptional, common to all obj.conf functions
Examples
ObjectType fn=type-by-extension
See Also
type-by-exp, force-type
82Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Service Stage
The Service class of functions sends the response data to the client.
Every
Service directive has the following optional parameters to determine
whether the fun ction is executed. All the optional par ameters must match the
current request for the function to be executed.
•
type
(optional) s pecifies a wildcard pattern of MIME types for which this func tion
will be executed. The
a
Service function to ex ecute.
•method
(optional) specifies a wildcard pattern of HTTP methods for whi ch this
function will be executed. Common HTTP methods are
•
query
(optional) specifies a wildcard pattern of query strings for which this function
will be executed.
Service Stage
magnus-internal/* MIME types are used only to select
GET, HEAD,andPOST.
Chapter 3Predefined SAFs and the Request Handling Process83
Service Stage
•UseOutputStreamSize
(optional) d etermines the default output stream buffer size, in bytes, for data
sent to the client. If this pa rameter is not specified, the default is
8192 bytes.
NOTEThe UseOutputStreamSize parameter can be set to zero in the
obj.conf file to disable output stream buffering. For the
magnus.conf file, setting UseOutputStreamSize to zero has no
effect.
•
flushTimer
(optional) determines the maximum number of millisec onds between write
operations in which buffering is enabled. If the interval between subsequent
write operations is greater than the
flushTimer value for an application,
further buffering is disabled. This is necessary for status monitoring CGI
applicationsthat run continuously and generate periodic statusupdate reports.
If this parameter is n ot specified, the default is
•
ChunkedRequestBufferSize
3000 milliseconds.
(optional) determines the default buffer size, in bytes, for “un-chunking”
request data. If this parameter is not specified, the default is
•
ChunkedRequestTimeout
(optional) determines the default timeout, in seconds, for “un-chunking”
request data. If this parameter is not specified, the default is
If there is more than one
optional wildcard parameters (
For more information about the
ChunkedRequestBufferSize,andChunkedRequestTimeout parameters, see
“Buffered Streams,” on page 334. The
ChunkedRequestBufferSize,andChunkedRequestTimeout parameters also have
equivalent
obj.conf parameters o verride the magnus.conf directives.
magnus.conf directives; see “Chunked E ncoding,” on page 286. The
Service-class function, the first one matching the
type, method,andquery)isexecuted.
UseOutputStreamSize, flushTimer,
UseOutputStreamSize,
By default, the server sends the requested file to the client by calling the
function. The directive t hat sets the default is:
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*"
fn="send-file"
84Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
8192 bytes.
60 seconds.
send-file
Service Stage
This directive usually comes last in the set of Service-class directives to give all
other Service directives a chance to be invoked. This directive is invoked if the
method of the request is
magnus-internal/. Note here that the pattern *~ means “does not match.” For a
GET, HEAD,orPOST,andthetypedoesnotstart with
list of characters that can be used in pat terns, see Appendix C, “Wildcard
Patterns.”
The following Service-class functions are described in detail in this section:
•
add-footer appends a footer specified by a filename or URL to a an HTML
file.
•
add-header prepends a header specified by a fil ename or URL to an HTML
file.
•
append-trailer appends text to the end of an HTML file.
•
imagemap handles server-side image maps.
•
index-common generates a fancy list of the files and d irectories in a requested
directory.
•
index-simple generates a simple list of files and directories in a requested
directory.
•
key-toosmall indicates to the client that the provided certificat e key size is too
small to accept.
•
list-dir lists the contents of a directory.
•
make-dir creates a directory.
•
query-handler handles the HTML ISINDEX tag.
•
remove-dir deletes an empty directory.
•
remove-file deletes a file.
•
rename-file renam es a file.
•
send-cgi sets up environment variables, launches a CGI program, and send s
the response t o the client.
•
send-file sends a local file to the client.
•
send-range sends a range of bytes of a file to the client.
Chapter 3Predefined SAFs and the Request Handling Process85
Service Stage
•send-shellcgi sets up environment variables, launches a shell CGI program,
and sends t he response to the client.
•
send-wincgi sets up environment variables, launchesa WinCGI program, and
sends the response to the client.
•
service-dump creates a performance report based on collected performance
bucket data.
•
shtml_send parses an HTML file for server-parsed html commands.
•
stats-xml creates a performance report in XML format.
•
upload-file uploadsandsavesafile.
add-footer
Applicable in Service-c lass directives.
This function appends a footer to an HTML file that is sent to the client. The footer
is specified either as a filename or a URI -- thus th e footer can be dynamica lly
generated. To specify static text as a footer, use the
Parameters
append-trailer function.
file(optional) The pathname to the file containing the
footer. Specify either file or uri.
By default the pathname is relative. If the pathname is
absolute,pass the NSIntAbsFilePath parameter as
yes.
uri(optional) A URI pointing to the resource containing
the footer. Specify either file or uri.
NSIntAbsFilePath(optional) if the file parameter is specified, the
NSIntAbsFilePath parameter determines whether
the file name is absolute or relative. The default is
relative. Set the value to yes to indicate an absolute
file path.
typeoptional,common to allService-class functions
methodoptional,common to allService-class functions
queryoptional,common to allService-class functions
UseOutputStreamSizeoptional, common to all Service-class functions
flushTimeroptional, common to all Service-classfunctions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
86Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Service Stage
ChunkedRequestTimeoutoptional, common t o all Service-class functions
bucketoptional, commonto all obj.conf functions
Examples
Service type=text/html method=GET fn=add-footer
file="footers/footer1.html"
Service type=text/html method=GET fn=add-footer
file="D:/netscape/servers/footers/footer1.html"
NSIntAbsFilePath="yes"
See Also
append-trailer, add-header
add-header
Applicable in Service-c lass directives.
This function prepends a header to an HTML file t hat is sent to the client. The
header is specified either as a filename or a URI -- thus the header can be
dynamically generated.
Parameters
file(optional)The pathname to the file containing the
header. Specify either file or uri.
By default the pathname is relative. If the pathname is
absolute,pass the NSIntAbsFilePath parameter as
yes.
uri(optional) A URI pointing to the r esource containing
the header. Specify either file or uri.
NSIntAbsFilePath(optional) if the file parameter is specified, the
NSIntAbsFilePath parameter determines whether
the file name is absolute or relative. The default is
relative. Set the value to yes to indicate an absolute
file path.
typeoptional, common to all Service-class functions
methodoptional, common to all Service-class functions
queryoptional, common to all Service-class functions
Chapter 3Predefined SAFs and the Request Handling Process87
Service Stage
UseOutputStreamSizeo ptional, common to all Service-class functions
flushTimeroptional, common to all Service-class functions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, common to all obj.conf functions
Examples
Service type=text/html method=GET fn=add-header
file="headers/header1.html"
Service type=text/html method=GET fn=add-footer
file="D:/netscape/servers/headers/header1.html"
NSIntAbsFilePath="yes"
See Also
add-footer, append-trailer
append-trailer
Applicable in Service-c lass directives.
The
append-trailer function sends an HTML file and appends text to the end. It
only appends text to HTML files. This is typically used for author information and
copyright text. The date the file was last modified can be inserted.
Returns
information after the file name in the URL, or if the file cannot be opened for
read-only access.
Parameters
traileris the text to append to HTM L documents. The string
88Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
REQ_ABORTED if a required parameter is missing, if there is extra path
is unescaped with util_uri_unescape beforebeing
sent. The text can contain HTML tags and can be up to
512 characterslong after unescaping and inserting the
date.
If you use the string :LASTMOD:,whichisreplacedby
the date the file was last modified; you must also
specify a time format with timefmt.
Service Stage
timefmt(optional) is a time format string for :LASTMOD:.For
details about time formats refer to Appendix D, “Time
Formats.” If timefmt is not provided, :LASTMOD:
will not be replaced with the time.
typeoptional,common to allService-class functions
methodoptional,common to allService-class functions
queryoptional,common to allService-class functions
UseOutputStreamSizeoptional, common to all Service-class functions
flushTimeroptional, common to all Service-classfunctions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common t o all Service-class functions
bucketoptional, commonto all obj.conf functions
Examples
Service type=text/html method=GET fn=append-trailer
trailer="<hr><img src=/logo.gif> Copyright 2001"
# Add a trailer with the date in the format: MM/DD/YY
Service type=text/html method=GET fn=append-trailer timefmt="%D"
trailer="<HR>File last updated on: :LASTMOD:"
See Also
add-footer, add-header
imagemap
Applicable in Service-c lass directives.
The
imagemap function responds to requests for imagemaps. Imagemaps are
images which are divided into multiple areas that each have an associated URL.
The information about which URL is associated with which area is stored in a
mapping file.
Parameters
typeoptional, common to all Service-class functions
methodoptional, common to all Service-class functions
Chapter 3Predefined SAFs and the Request Handling Process89
Service Stage
queryoptional, common to all Service-class functions
UseOutputStreamSizeo ptional, common to all Service-class functions
flushTimeroptional, common to all Service-class functions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, common to all obj.conf functions
Examples
Service type=magnus-internal/imagemap method=(GET|HEAD)
fn=imagemap
index-common
Applicable in Service-c lass directives.
The
index-common func tion generates a fancy (or common) list of files in t he
requested directory. The list is sorted alphab etically. Files beginning with a period
(.) are not displayed. Each item appears as an HTML link. This function displays
more informationthan
index-simple including the size, da te last modified, and
an icon for each fi l e. It may also include a header and/or readme file into the
listing.
The
Init-class function cindex-init in magnus.conf specifies the form at for the
index list, including where to look for the images.
If
obj.conf contains a call to index-common in the Service stage, magnus.conf
must initialize fancy (or common) indexing by invoking cindex-init during the
Init stage.
Indexing occurs when the requested resourceis a directory that does not contain an
index file o r a home page, or no index file or home page has been specified by the
functions
The icons displayed are
"text/*"text.gif
"image/*"image.gif
90Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
find-index or home-page.
.gif files dependent on the content-type of the file:
header(optional) is the path (relative to the directory being
indexed) and name of a file ( HTML or plain text)
which is included at the beginning of the directory
listing to introduce the contents of the directory. The
file is first tried with .html addedto the end. If found,
it is incorporated near the top of the directory list as
HTML. If the file is not found, then it is tried without
the .html and incorporated as preformatted plain text
(bracketed by <PRE> and).
readme(optional) is the path (relative to the directory being
indexed) and name of a file ( HTML or plain text) to
append to the directory listing. This file might give
more information about the contentsof the directory,
indicate copyrights, authors, or other information. The
file is first tried with .html addedto the end. If found,
it is incorporated at the bottom o f the directory list as
HTML. If the file is not found, then it is tried without
the .html and incorporated as preformatted plain text
(enclosed by <PRE>and </PRE>).
typeoptional, common to all Service-class functions
methodoptional, common to all Service-class functions
queryoptional, common to all Service-class functions
UseOutputStreamSizeo ptional, common to all Service-class functions
flushTimeroptional, common to all Service-class functions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, common to all obj.conf functions
Chapter 3Predefined SAFs and the Request Handling Process91
Service Stage
Examples
Service fn=index-common type=magnus-internal/directory
method=(GET|HEAD) header=hdr readme=rdme.txt
See Also
cindex-init, index-simple, find-index, home-page
index-simple
Applicable in Service-c lass directives.
The
index-simple function generates a simple index of the files in the reques ted
directory. It scans a directoryand returns an HTML page to the browser displaying
a bulleted list of the files and directories in the directory. The list is sorted
alphabetically. Files b eginning with a period (.) are not displayed. Each item
appears as an HTML link.
Indexing occurs when the requested resource is a directory that does not contain
either an index file or a home page, or no index file or home page has been
specified by the functions
find-index or home-page.
Parameters
typeoptional, common to all Service-class functions
methodoptional, common to all Service-class functions
queryoptional, common to all Service-class functions
UseOutputStreamSizeo ptional, common to all Service-class functions
flushTimeroptional, common to all Service-class functions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, common to all obj.conf functions
Examples
Service type=magnus-internal/directory fn=index-simple
92Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Service Stage
See Also
cindex-init, index-common
key-toosmall
Applicable in Service-c lass directives.
NOTEThis function is provided for backw ard compatibility only and was
deprecated in iPlanet™ Web Server 4.x. It is replaced by the
PathCheck-class SAF
key-toosmall func tion returns a message to the client sp ecifying that the
The
secret key size for SSL communications is too small. This function is designed to be
used together with a
Client tag to limit access of certain directories to
non-exportable browsers.
Parameters
typeoptional,common to allService-class functions
methodoptional,common to allService-class functions
queryoptional,common to allService-class functions
ssl-check.
UseOutputStreamSizeoptional, common to all Service-class functions
flushTimeroptional, common to all Service-classfunctions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, common to all obj.conf functions
Examples
<Object ppath=/mydocs/secret/*>
Service fn=key-toosmall
</Object>
Chapter 3Predefined SAFs and the Request Handling Process93
Service Stage
list-dir
Applicable in Service-c lass directives.
The
list-dir function returns a sequence of text lines to the client in response to a
requestwhose method is INDEX. The format of the returned lines is:
nametype sizemimetype
The namefield is the name of the file o r directory. It is relative tothe directorybeing
indexed. It is URL-encoded, that is, any character might be represented by
where
xx is the hexadecimal representation of the character's ASCII number.
%xx,
The type field is a M IME type such as
directory. A file for which the server doesn't have a type will be of type unknown.
text/html. Directories will be of type
The size field is the size of the file, in bytes.
The mtime field is the numerical representation of the date of last modification of
the file. The number is the number of seconds since the epoch (Jan 1, 1970 00:00
UTC) since the last modification of the file.
When remote file manipulation is enabled in the server, the
a
Service-class function that calls list-dir for requests whose method is INDEX.
Parameters
typeoptional,common to allService-class functions
methodoptional,common to allService-class functions
queryoptional,common to allService-class functions
UseOutputStreamSizeoptional, common to all Service-class functions
flushTimeroptional, common to all Service-classfunctions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, common to all obj.conf functions
obj.conf file contains
Examples
Service fn=list-dir method="INDEX"
94Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Service Stage
make-dir
Applicable in Service-c lass directives.
The
make-dir function creates a directory when the client sends a request whose
method is MKDIR. The function can fail if the server can’t write to that directory.
When remote file manipulation is enabled in the server, the
a
Service-class function that invokes make-dir when the request method is MKDIR.
Parameters
typeoptional,common to allService-class functions
methodoptional,common to allService-class functions
queryoptional,common to allService-class functions
UseOutputStreamSizeoptional, common to all Service-class functions
flushTimeroptional, common to all Service-classfunctions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, common to all obj.conf functions
Examples
Service fn="make-dir" method="MKDIR"
obj.conf file contains
query-handler
Applicable in Service-c lass directives.
NOTEThis function is provided for backward compatibility only and is
used mainly to support the ob solete ISINDEX tag. If possible, use
an HTML form instead.
The
query-handler function runs a CGI program instead of referencingthe path
requested.
Chapter 3Predefined SAFs and the Request Handling Process95
Service Stage
Parameters
pathis the full path and file name of the CGI program to
run.
typeoptional,common to allService-class functions
methodoptional,common to allService-class functions
queryoptional,common to allService-class functions
UseOutputStreamSizeoptional, common to all Service-class functions
flushTimeroptional, common to all Service-classfunctions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, common to all obj.conf functions
Examples
Service query=* fn=query-handler path=/http/cgi/do-grep
Service query=* fn=query-handler path=/http/cgi/proc-info
remove-dir
Applicable in Service-c lass directives.
The
remove-dir function removes a directory when the client sends an request
whose method is
functionwillfailif thedirectory is not empty or if the server doesn’thave the
privileges to remove the directory.
When remote file manipulation is enabled in the server, the
a
Service-class fun ction that invokes remove-dir when the request method is
RMDIR.
Parameters
typeoptional, common to a ll Service-class functions
methodoptional, common to a ll Service-class functions
queryoptional, common to a ll Service-class functions
UseOutputStreamSizeoptional, common to all Service-class functions
96Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
RMDIR. The directory must be empty (have no files in it). The
obj.conf file contains
Service Stage
flushTimeroptional, common to all S e rvice-class functions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, commonto all obj.conf functions
Examples
Service fn="remove-dir" method="RMDIR"
remove-file
Applicable in Service-c lass directives.
The
remove-file function deletes a file when the client sends a request whose
method is DELETE. It deletes the file indicated by the URL if the user is authorized
and the server has the needed file system privileges.
When remote file manipulation is enabled in the server, the
a
Service-class fun ction that invokes remove-file when the request method is
DELETE.
Parameters
typeoptional,common to allService-class functions
methodoptional,common to allService-class functions
queryoptional,common to allService-class functions
UseOutputStreamSizeoptional, common to all Service-class functions
flushTimeroptional, common to all Service-classfunctions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, common to all obj.conf functions
Chapter 3Predefined SAFs and the Request Handling Process97
obj.conf file contains
Service Stage
Examples
Service fn="remove-file" method="DELETE"
rename-file
Applicable in Service-c lass directives.
The
rename-file function renames a file when the client sends a request with a
New-URL head er whose method is MOVE. It renames the file indicated by the URL to
New-URL within the same directory if the user is authorized and the server has the
needed file system privileges.
When remote file manipulation is enabled in the server, the
a
Service-class fun ction that invokes rename-file when the request method is
MOVE.
Parameters
typeoptional,common to allService-class functions
methodoptional,common to allService-class functions
queryoptional,common to allService-class functions
UseOutputStreamSizeoptional, common to all Service-class functions
flushTimeroptional, common to all Service-classfunctions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, common to all obj.conf functions
Examples
Service fn="rename-file" method="MOVE"
obj.conf file contains
98Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Service Stage
send-cgi
Applicable in Service-c lass directives.
The
send-cgi function sets up the CGI environment variables, runs a file as a CGI
program in a new process, and sends the results to the client.
For details abou t the CGI environment variables and their NSAPI equivalents, refer
to section “CGI to NSAPI C onversion,” on page 135.
For additional information about CGI, see the Netscape Enterprise Server
Administrator’sGuideand the Netscape Enterprise ServerProgrammer’s Guide.
There are three ways to change the timing used to flush the CGI b uf fer:
•Adjust the interval between flushes using the
•Adjust the buffer size using the
UseOutputStreamSize parameter
flushTimer parameter
•Force Enterprise Server to flush its buffer by forcing spaces into the buffer in
the CGI script
For more information about
flushTimer and UseOutputStreamSize,see
“Buffered Streams,” on page 334.
Parameters
user(UNIX only) Specifies the name of the user to execute
CGI programs as.
group(UNIX only) Specifies the name of the group to
execute CGI programs as.
chroot(UNIX only) Specifies t he directory to chroot to before
execution begins. This is relative to the chroot
defined in magnus.conf.
dir(UNIX only) Specifies the directory to chdir to after
chroot but before execution begins.
rlimit_as(UNIX only) Specifies the maximum CGI program
address space in bytes. You can supply both current
(soft) and maximum (hard) limits, separated by a
comma. Th e soft limit must be listed first. If only on e
limit is specified, both limits are set to this value.
Chapter 3Predefined SAFs and the Request Handling Process99
Service Stage
rlimit_core(UNIX only) Specifies the maximum CGI program
core file size. A value of 0 disables writing cores. You
can supply both current (soft) and maximum (hard)
limits, separated by a comma. The soft limit must be
listed first. If only one limit is specified, both limits are
set to this value.
rlimit_nofile(UNIX only) Specifies the maximum number of file
descriptors for the CGI program. You can supply both
current (soft) and maximum (hard) limits, separated
by a comma. The soft limit must be listed first. If only
one limit is specified, both limits are set to this value.
nice(UNIX only) Accepts an increment that determines the
CGI p rogram's priority relative to the server.
Typically, the server is run with a nice value of 0 and
theniceincrementwouldbebetween0(theCGI
program runs at samepriority as server) and 19 (the
CGI program runs at much lower priority than server).
While it is possible to increase the priority of the CGI
program above that of the server by specifying a nice
increment of -1, this is not recommended.
typeoptional,common to allService-class functions
methodoptional,common to allService-class functions
queryoptional,common to allService-class functions
UseOutputStreamSizeoptional, common to all Service-class functions
flushTimeroptional, common to all Service-classfunctions
ChunkedRequestBufferSizeoptional, common to all Service-class functions
ChunkedRequestTimeoutoptional, common to all Service-class functions
bucketoptional, common to all obj.conf functions
Examples
The following ex ample uses variables defined in the server.xml file for the
send-cgi parameters. For more information about defining variables, see Chapter
8, “Virtual Server Configuration Files.”
100Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Loading...
+ hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.