| Previous Contents Index DocHome Next |
| iPlanet Web Server, Enterprise Edition NSAPI Programmer's Guide |
Chapter 3 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 obj.conf file to give instructions to the server. For a discussion of the use and syntax of obj.conf, see the previous chapter, Chapter 2 "Syntax and Use of obj.conf."For a list of Init (initialization) SAFs, see Chapter 7 "Syntax and Use of magnus.conf."
This chapter includes functions that are part of the core functionality of iPlanet Web Server. It does not include functions that are available only if additional components, such as servlets and server-parsed HTML, are enabled.
This chapter contains a section for each directive which lists all the pre-defined Server Application Functions that can be used with that directive.
AuthTrans Stage
For an alphabetical list of pre-defined SAFs, see Appendix H "Alphabetical List of Directives in magnus.conf."Table 3-1 lists the SAFs that can be used with each directive.
The bucket Parameter
The following performance buckets are predefined in iPlanet Web Server:
The default-bucket records statistics for the functions not associated with any user-defined or built-in bucket.
You can define additional performance buckets in the magnus.conf file (see the perf-init and define-perf-bucket functions).The all-requests bucket records.perf statistics for all NSAPI SAFs, including those in the default-bucket.
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 service-dump Service function.
As an alternative, you can use the stats-xml Service function to generate performance statistics; use of buckets is optional.
For more information about performance buckets, see the Performance Tuning, Sizing, and Scaling Guide for iPlanet Web Server.
AuthTrans Stage
AuthTrans stands for Authorization Translation. AuthTrans directives give the server instructions for checking authorization before allowing a client to access resources. AuthTrans directives work in conjunction with PathCheck directives. Generally, an AuthTrans function checks if the username and password associated with the request are acceptable, but it does not allow or deny access to the request -- it leaves that to a PathCheck function.The server handles the authorization of client users in two steps.
AuthTrans Directive - validates authorization information sent by the client in the Authorization header.
The authorization process is split into two steps so that multiple authorization schemes can be easily incorporated, as well as providing the flexibility to have resources that record authorization information but do not require it.PathCheck Stage - checks that the authorized user is allowed access to the requested resource.
AuthTrans functions get the username and password from the headers associated with the request. When a client initially makes a request, the username and password are unknown so the AuthTrans functions and PathCheck functions work 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 appropriate realm, and then the client submits the request again, this time including the username and password in the headers.
If there is more than one AuthTrans directive in obj.conf, each function is executed in order until one succeeds in authorizing the user.
The following AuthTrans-class functions are described in detail in this section:
basic-auth calls a custom function to verify user name and password. Optionally determines the user's group.
basic-ncsa verifies user name and password against an NCSA-style or system DBM 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 ssl-id variable in the Session->client parameter block.
qos-handler handles the current quality of service statistics.
Applicable in AuthTrans-class directives.
The basic-auth function calls a custom function to verify authorization information sent by the client. 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.
specifies the type of authorization to be used. This should always be basic.
(optional) specifies the full path and file name of the user database to be used for user verification. This parameter will be passed to the user function.
is the name of the user custom function to verify authorization. This function must have 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) 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 only) to the rq->vars pblock.
(optional) specifies the full path and file name of the user database. This parameter will be passed to the group function.
(optional) is the name of the group custom function that must have 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) in the pb parameter. It also has access to the auth-type, auth-user (user), auth-db (userdb), and auth-password (pw, Windows NT 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_NOACTION if the user's group is not found.
Init fn=load-modules shlib=/path/to/mycustomauth.so funcs=hardcoded_auth
AuthTrans fn=basic-auth auth-type=basic userfn=hardcoded_auth
PathCheck fn=require-auth auth-type=basic realm="Marketing Plans"
See Also
require-auth
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.
See Also
require-auth
Applicable in AuthTrans-class directives.
Note This function is provided for backward compatibility only. The functionality of get-sslid has been incorporated into the standard processing of an SSL connection.
The get-sslid function retrieves a string that is unique to the current SSL session, and stores it as the ssl-id variable in the Session->client parameter block.
If the variable ssl-id is present when a CGI is invoked, it is passed to the CGI as the HTTPS_SESSIONID environment variable.
The get-sslid function has no parameters and always returns REQ_NOACTION. It has no effect if SSL is not enabled.
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 function configured in the default object in order to work properly.
The code for this SAF is one of the examples in Chapter 6 "Examples of Custom SAFs."
For more information, see the Performance Tuning, Sizing, and Scaling Guide for iPlanet Web Server.
See Also
qos-error
NameTrans Stage
NameTrans stands for Name Translation. NameTrans directives translate virtual URLs to physical directories on your server. For example, the URLhttp://www.test.com/some/file.html
could be translated to the full file-system path
/usr/netscape/server4/docs/some/file.html
NameTrans directives should appear in the default object. If there is more than one NameTrans directive in an object, the server executes each one in order until one succeeds.
The following NameTrans-class functions are described in detail in this section:
assign-name tells the server to process directives in a named object.
document-root translates a URL into a file system path by replacing the http://server-name/ part of the requested resource with the document root directory.
home-page translates a request for the server's root home page (/) to a specific file.
pfx2dir translates any URL beginning with a given prefix to a file system directory and optionally enables directives in an additional named object.
redirect redirects the client to a different URL.
strip-params removes embedded semicolon-delimited parameters from the path.
unix-home translates a URL to a specified directory within a user's home directory.
Applicable in NameTrans-class directives.
The assign-name function specifies the name of an object in obj.conf that matches the current request. The server then processes the directives in the named object in preference to the ones in the default object.
For example, consider the following directive in the default object:
NameTrans fn=assign-name name=personnel from=/personnel
Let's suppose the server receives a request for http://server-name/personnel. After processing this NameTrans directive, the server looks for an object named personnel in obj.conf, and continues by processing the directives in the personnel object.
The assign-name function always returns REQ_NOACTION.
Applicable in NameTrans-class directives.
The document-root function specifies the root document directory for the server. If the physical path has not been set by a previous NameTrans function, the http://server-name/ part of the path is replace by the physical pathname for the document root.
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 directory is /usr/netscape/server4/docs, then when the server receives a request for http://server-name/a/b/file.html, the document-root function translates the pathname for the requested resource to /usr/netscape/server4/docs/a/b/file.html.
This function always returns REQ_PROCEED. NameTrans directives listed after this will never be called, so be sure that the directive that invokes document-root is the last NameTrans directive.
There can be only one root document directory. To specify additional document directories, use the pfx2dir function to set up additional path name translations.
is the file system path to the server's root document directory.
See also
pfx2dir
Applicable in NameTrans-class directives.
The home-page function specifies the home page for your server. Whenever a client requests the server's home page (/), they'll get the document specified.
Applicable in NameTrans-class directives.
The 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.)
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, (such as /httpd/cgi-local/test.cgi) and the server also starts processing the directives in the object named cgi.
NameTrans fn=pfx2dir from=/cgi-bin dir=/httpd/cgi-local name=cgi
In the second example, the URL http://server-name/icons/resource (such as http://x.y.z/icons/happy/smiley.gif) is translated to the physical pathname /users/nikki/images/resource, (such as /users/nikki/images/smiley.gif)
NameTrans fn=pfx2dir from=/icons/happy dir=/users/nikki/images
The third example shows the use of the find-pathinfo-forward parameter. The URL http://server-name/cgi-bin/resource is translated to the physical pathname /export/home/cgi-bin/resource.
NameTrans fn="pfx2dir" find-pathinfo-forward="" from="/cgi-bin" dir="/export/home/cgi-bin" name="cgi"
Applicable in NameTrans-class directives.
The 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.
(maybe optional) specifies a complete URL to return to the client. If you use this parameter, don't use url-prefix (and vice-versa).
(maybe optional) is the new URL prefix to return to the client. The from prefix is simply replaced by this URL prefix. If you use this parameter, don't use url (and vice-versa).
(optional) is a flag which tells the server to util_uri_escape the URL before sending it. It should be yes or no. The default is yes.
Examples
In the first example, any request for http://server-name/whatever is translated to a request for http://tmpserver/whatever.
In the second example, any request for http://server-name/toopopular/whatever is translated to a request for http://bigger/better/stronger/morepopular/whatever.
NameTrans fn=redirect from=/toopopular url=http://bigger/better/stronger/morepopular
Applicable in NameTrans-class directives.
The strip-params function removes embedded semicolon-delimited parameters from the path. For example, a URI of /dir1;param1/dir2 would become a path of /dir1/dir2. When used, the strip-params function should be the first NameTrans directive listed.
Example
NameTrans fn=strip-params
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 signals user directories. Any request that begins with the prefix is translated to the user's home directory.
You specify the list of users with either the /etc/passwd file or a file with a similar structure. Each line in the file should have this structure (elements in the 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 init-uhome in magnus.conf.
NameTrans fn=unix-home from /~ pwfile=/mydir/passwd subdir=public_html
See Also
init-uhome, find-links
PathCheck Stage
PathCheck directives check the local file system path that is returned after the NameTrans step. The path is checked for things such as CGI path information and for dangerous elements such as /./and /../ and //, and then any access restriction is applied.If there is more than one PathCheck directive, each of the functions are executed in order.
The following 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 denies 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.
Applicable in PathCheck-class directives.
The check-acl function specifies an Access Control List (ACL) to use to check whether the client is allowed to access the requested resource. An access control list contains information about who is or is not allowed to access a resource, and under 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.
(optional) is a wildcard pattern that specifies the path for which to apply the ACL.
Applicable in PathCheck-class directives.
The deny-existence function sends a "not found" message when a client tries to access a specified path. The server sends "not found" instead of "forbidden," so the user cannot tell whether the path exists or not.
PathCheck fn=deny-existence path=/usr/netscape/server4/docs/private
Applicable in PathCheck-class directives.
The find-index function investigates whether the requested path is a directory. If it is, the function searches 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 does nothing if there is a query string, if the HTTP method is not GET, or if the path is that of a valid file.
Applicable in PathCheck-class directives.
Unix Only. The find-links function searches the current path for symbolic or hard links to other directories or file systems. 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.
See Also
init-uhome, unix-home
Applicable in PathCheck-class directives.
The find-pathinfo function finds any extra path information after the file name in the URL and stores it for use in the CGI environment variable PATH_INFO.
Applicable in PathCheck-class directives.
The get-client-cert function gets the authenticated client certificate from the SSL3 session. It can apply to all HTTP methods, or only to those that match a specified pattern. It only works when SSL is enabled on the server.
If the certificate is present or obtained from the SSL3 session, the function returns 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.
# 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.
Applicable in PathCheck-class directives.
The load-config function searches for configuration files in document directories and adds the file's contents to the server's existing configuration. These configuration files (also known as dynamic configuration files) specify additional access control information for the requested resource. Depending on the rules in the dynamic configuration files, the server might or might not allow the client to access the requested resource.
Each directive that invokes load-config is associated with a base directory, which is either stated explicitly through the basedir parameter or derived from the root 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.
When you enable dynamic configuration files through the Server Manager interface, the system writes additional objects with ppath parameters into the obj.conf file. If you manually add directives that invoke load-config to the default object (rather than putting them in separate objects), the Server Manager interface might not reflect your changes.
the top-most directory in which the server looks for dynamic configuration files to apply to the requested resource.
- For example, if the base directory is D:/Netscape/Server4/docs/nikki/, then only requests for resources in this directory or its subdirectories (and their subdirectories and so on) trigger the search for dynamic configuration files. A request for the resource D:/Netscape/Server4/docs/somefile.html does not trigger the search in this case, since the requested resource is in a parent directory of the base directory.
- If the base directory is D:/Netscape/Server4/docs/nikki/, the server starts 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.
If you manually add PathCheck directives that invoke load-config to the file obj.conf, put them in additional objects (created with the <OBJECT> tag) rather than putting them in the default object. Use the ppath attribute of the OBJECT 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.
For example, the following <OBJECT> tag specifies that requests for resources in the directory D:/Netscape/Server4/docs are subject to the access rules in the file my.nsconfig.
<Object ppath="D:/Netscape/Server4/docs/*">
PathCheck fn="load-config" file="my.nsconfig" descend=1 basedir="D:/Netscape/Server4/docs"
</Object>
The load-config function returns REQ_PROCEED if configuration files were loaded, REQ_ABORTED on error, or REQ_NOACTION when no files are loaded.
Examples
In this example, whenever the server receives a request for any resource containing the substring secret that resides in D:/Netscape/Server4/docs/nikki/ or a subdirectory thereof, it searches for a configuration file called checkaccess.nsconfig.The server starts the search in the directory D:/Netscape/Server4/docs/nikki, and searches subdirectories too. It loads each instance of checkaccess.nsconfig that it finds, applying the access control rules contained therein to determine whether the client is allowed to access the requested resource or not.
<Object ppath="*secret*">
PathCheck fn="load-config" file="checkaccess.nsconfig" basedir="D:/Netscape/Server4/docs/nikki" descend="1"
</Object>
Applicable in PathCheck-class directives.
Windows NT Only. The nt-uri-clean function denies access to any resource whose physical path contains \.\, \..\ or \\ (these are potential security problems).
See Also
unix-uri-clean
Applicable in PathCheck-class directives.
Windows NT Only. The ntcgicheck function specifies the file name extension to be added to any file name that does not have an extension, or to be substituted for any file name that has the extension .cgi.
See Also
init-cgi, send-cgi, send-wincgi, send-shellcgi