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."
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, web publishing, WAI, and server-parsed HTML are enabled.
The functions and arguments described here are applicable to Enterprise Server 3.x and iPlanet Web Server 4.x. Functions and arguments that are new to iPlanet Web Server 4.x are indicated as such.
This chapter contains a section for each directive which lists all the pre-defined Server Application Functions that can be used with that directive.
The directives are:
Init Stage
AuthTrans Stage
NameTrans Stage
PathCheck Stage
ObjectType Stage
Service Stage
AddLog Stage
Error Stage
Init directives are invoked during server initialization when the server is started or restarted. These directives perform tasks such as initializing log files and loading plugins.
On Unix platforms, each Init directive has an optional LateInit parameter. If it is set to "yes" or is not provided, the function is executed by the child process after it is forked from the parent. If it is set to "no", the function is executed by the parent process before the fork. Any activities that must be performed as the user root (such as writing to a root-owned file) must be done before the fork. Any activities involving the creation of threads must be performed after the fork, with the exception of thread-pool-init, which requires the optional EarlyInit parameter to be used and set to "yes."
Upon failure, Init-class functions return REQ_ABORTED. The server logs the error according to the instructions in the Error directives, and terminates. Any other result code is considered a success.
The following Init-class functions are described in detail in this section:
cache-init configures server caching for increased performance.
cindex-init changes the default characteristics for fancy indexing.
dns-cache-init configures DNS caching.
flex-init initializes the flexible logging system.
flex-rotate-init enables rotation for flexible logs.
init-cgi changes the default settings for CGI programs.
init-clf initializes the Common Log subsystem.
init-uhome loads user home directory information.
load-modules loads shared libraries into the server.
load-types loads file extension to MIME type mapping information.
pool-init configures pooled memory allocation.
register-http-method lets you extend the HTTP protocol by registering new HTTP methods.
thread-pool-init configures an additional thread pool.
Init-class directives.
The cache-init function controls file caching for static files, such as HTML pages, GIF files and sound files. The server caches files to improve performance. If a request is received for a file that is in the cache, the server retrieves the requested resource from the cache, which is more efficient than retrieving it from its source. File caching is enabled by default.
To optimize server speed, you should ideally have enough RAM for the server and cache because swapping can be slow. Do not allocate a cache that is greater in size than the amount of memory on the system.
Files can be cached in various ways. Small files might be read into the heap space; larger files might be cached using memory-mapping; and in some circumstance files might be cached as open file descriptors.
In iPlanet Web Server 4.x, much of the functionality of the file cache is controlled by a new configuration file callednsfc.conf. For information aboutnsfc.conf, see the tuning chapter in the iPlanet Web Server Administrator's Guide.
(optional) Maximum number of memory-mapped cached files that can be open simultaneously.
(optional) maximum size of a file that can be cached as a memory-mapped file.
Init fn=cache-init PollIntervale=2 MaxNumberOfCachedFiles=8192
Init-class directives.
The function cindex-init sets the default settings for common indexing. Common indexing (also known as fancy indexing) is performed by the Service function index-common. Indexing occurs when the requested URL translates to a directory that does not contain an index file or home page, or no index file or home page has been specified.
In common (fancy) indexing, the directory list shows the name, last modified date, size and description for each indexed file or directory.
index-common, find-index, home-page
Init-class directives.
The dns-cache-init function specifies that DNS lookups should be cached when DNS lookups are enabled. If DNS lookups are cached, then when the server gets a client's host name information, it stores that information in the DNS cache. If the server needs information about the client in the future, the information is available in the DNS cache.
You may specify the size of the DNS cache and the time it takes before a cache entry becomes invalid. The DNS cache can contain 32 to 32768 entries; the default value is 1024 entries. Values for the time it takes for a cache entry to expire (specified in seconds) can range from 1 second to 1 year; the default value is 1200 seconds (20 minutes).
Init-class directives.
The flex-init function opens the named log file to be used for flexible logging and establishes a record format for it. The log format is recorded in the first line of the log file. You cannot change the log format while the log file is in use by the server.
The flex-log function writes entries into the log file during the AddLog stage of the request handling process.
The log file stays open until the server is shut down or restarted (at which time all logs are closed and reopened).
Note: If the server has AddLog Stage directives that call flex-log, the flexible log file must be initialized by flex-init during server initialization.
You may specify multiple log file names in the same flex-init function call. Then use multiple AddLog directives with the flex-log function to log transactions to each log file.
The flex-init function may be called more than once. Each new log file name and format will be added to the list of log files.
If you move, remove, or change the log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup a log file, you need to rename the file and then restart the server. The server first looks for the log file by name, and if it doesn't find it, creates a new one (the renamed original log file is left for you to use). The exception to this rule is if log rotation has been enabled in iPlanet Web Server 4.x.
For information on rotating log files, see flex-rotate-init.
The flex-init function has three parameters: one that names the log file, one that specifies the format of each record in that file, and one that specifies the logging mode.
The flex-init function recognizes anything contained between percent signs
(%) as the name portion of a name-value pair stored in a parameter block in the
server. (The one exception to this rule is the %SYSDATE% component which
delivers the current system date.) %SYSDATE% is formatted using the time
format %d/%b/%Y:%H:%M:%S plus the offset from GMT.
(See Chapter 4, "Creating Custom SAFs," for more information about parameter blocks and Chapter 5, "NSAPI Function Reference," for functions to manipulate pblocks.)
Any additional text is treated as literal text, so you can add to the line to
make it more readable. Typical components of the formatting parameter are
listed in Table 3.2. Certain components might contain spaces, so they
should be bounded by escaped quotes (\")
If no format parameter is specified for a log file, the common log format is used:
"%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%]
\"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status%
%Req->srvhdrs.content-length%"
New in iPlanet Web Server 4.0: you can now log cookies by logging the
Req->headers.cookie.namecomponent.
iPlanet Web Server can use cache acceleration for serving static pages (as
discussed in cache-init). However, some components of log format
entries block this acceleration (unless the logging mode is relaxed) causing
the server to use the unaccelerated path for serving static pages. (The server
always uses the unaccelerated path to serve dynamically-generated pages.)
The following table indicates which components of the log format entry
allow static page acceleration to proceed for the current request. If the log
format uses any components that do not allow static page acceleration, the
performance of serving static pages may decrease significantly (unless the
logging mode is relaxed).
In the following table, the components that are enclosed in escaped double quotes (\") are the ones that could potentially resolve to values that have white spaces.
Table 3.2 Typical components of flex-init formatting
Flex-log option Component Allows static page acceleration Client Host name (unless
iponlyis specified in flex-log or DNS name is not available) or IP address
The first example below initializes flexible logging into the file /usr/
netscape/server4/https-servername/logs/access.
This will record the following items
This is the default format, which corresponds to the Common Log Format (CLF).
It is advisable that the first six elements of any log always be in exactly this format, because a number of log analyzers expect that as output.
The following example initializes flexible logging into the file /user/
netscape/server4/https-servername/logs/extended.
flex-rotate-init, flex-log
Init-class directives. New in iPlanet Web Server 4.0.
The flex-rotate-init function enables log rotation for logs that use the flexible logging format. Call this function in the Init stage of obj.conf before calling flex-init. The flex-rotate-init function allows you to specify a time interval for rotating log files. At the specified time interval, the server moves the log file to a file whose name indicates the time of moving. The flex-log function in the AddLog stage then starts logging entries in a new log file. The server does not need to be shut down while the log files are being rotated.
Note that the server keeps all rotated log files forever, so you will need to clean them up as necessary to free up disk space.
By default, log rotation is disabled.
Indicates the number of minutes to elapse between each log rotation.
This example enables log rotation, starting at midnight and occurring every hour.
Init fn=flex-rotate-init rotate-start=2400 rotate-intervals=60
flex-init, flex-log
Init-class directives.
The init-cgi function performs certain initialization tasks for CGI execution. Two options are provided: timeout of the execution of the CGI script, and establishment of environment variables.
send-cgi, send-wincgi, send-shellcgi
Init-class directives.
The init-clf function opens the named log files to be used for common logging. The common-log function writes entries into the log files during the AddLog stage of the request handling process. The log files stay open until the server is shut down (at which time the log files are closed) or restarted (at which time the log files are closed and reopened).
Note: If the server has an AddLog Stage directive that calls common-log, common log files must be initialized by init-clf during the Init stage.
Note: This function should only be called once. If it is called again, the new call will replace log file names from all previous calls.
If you move, remove, or change the log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup a log file, you need to rename the file (and for Unix, send the -HUP signal) and then restart the server. The server first looks for the log file by name, and if it doesn't find it, creates a new one (the renamed original log file is left for you to use).
access="/usr/netscape/server4/https-servername/logs/access"
mylogfile = "log1"You will use the log file name later, as a parameter to the
common-logfunction.
Init fn=init-clf access=/usr/netscape/server4/https-boots/logs/access
Init fn=init-clf templog=/tmp/mytemplog templog2=/tmp/mytemplog2
common-log, record-useragent
Init-class directives.
Unix Only. The init-uhome function loads information about the system's user home directories into internal hash tables. This increases memory usage slightly, but improves performance for servers that have a lot of traffic to home directories.
unix-home, find-links
Init-class directives.
The load-modules function loads a shared library or Dynamic Link Library into the server code. Specified functions from the library can then be executed from any subsequent directives. Use this function to load new plugins or SAFs.
If you define your own Server Application Functions, you get the server to load them by using the load-modules function and specifying the shared library or dll to load.
the name of a custom thread pool, as specified in
thread-pool-init.
Init fn=load-modules shlib="C:/mysrvfns/corpfns.dll" funcs="moveit"
Init fn=load-modules shlib="/mysrvfns/corpfns.so" funcs="myinit,myservice"
Init fn=myinit
Init-class directives.
The load-types function loads the file that the server uses to look up mime types.
More explicitly, this function uses the indicated file to create a table that maps file-name extensions to a file's content-type, content-encoding, and content-language. During the ObjectType phase, the function type-by-extension instructs the server to look in this table to determine the type of content requested by the client, based on the extension of the requested resource.
If you edit the MIME types file, you will need to restart the server to load the changes.
The file name extensions are not case-sensitive.
This function must be called in order for the type-by-extension and type-by-exp SAFs, and the cinfo_find NSAPI functions to work properly.
Note: MIME types files must begin with the following line or they will not be accepted:#--Netscape Communications Corporation MIME Information
Init fn=load-types mime-types=mime.types local-types=/usr/netscape/server4/local.types
type-by-extension, type-by-exp, force-type
Init-class directives.
The pool-init function changes the default values of pooled memory settings. The size of the free block list may be changed or pooled memory may be entirely disabled.
Memory allocation pools allow the server to run significantly faster. If you are programming with the NSAPI, note that MALLOC, REALLOC, CALLOC, STRDUP, and FREE work slightly differently if pooled memory is disabled. If pooling is enabled, the server automatically cleans up all memory allocated by these routines when each request completes. In most cases, this will improve performance and prevent memory leaks. If pooling is disabled, all memory is global and there is no clean-up.
If you want persistent memory allocation, add the prefix PERM_ to the name of each routine (PERM_MALLOC, PERM_REALLOC, PERM_CALLOC, PERM_STRDUP, and PERM_FREE).
Note: Any memory you allocate from Init-class functions will be allocated as persistent memory, even if you use MALLOC. The server cleans up only the memory that is allocated while processing a request, and because Init-class functions are run before processing any requests, their memory is allocated globally.
(optional) maximum size in bytes of free block list. May not be greater than 1048576.
Init-class directives. New in iPlanet Web Server 4.1.
This function lets you extend the HTTP protocol by registering new HTTP methods. (You do not need to register the default HTTP methods.)
Upon accepting a connection, the server checks to see if the method that it received is known to it. If the server does not recognize the method, it returns a "501 Method Not Implemented" error message.
is a comma separated list of the names of the methods you are registering.
The following example shows the use ofregister-http-methodand aServicefunction for one of the methods.
Init-class directives.
This function creates a new pool of user threads. A pool must be declared before it's used. To tell a plugin to use the new pool, specify the pool parameter when loading the plugin with the Init-class function load-modules.
One reason to create a custom thread pool would be if a plugin is not thread-aware, in which case you can set the maximum number of threads in the pool to 1.
The older parameter NativeThread=yes always engages one default native pool, called NativePool.
The native pool on Unix is normally not engaged, as all threads are OS-level threads. Using native pools on Unix may introduce a small performance overhead as they'll require an additional context switch; however, they can be used to localize the jvm.stickyAttach effect or for other purposes, such as resource control and management or to emulate single-threaded behavior for plug-ins (by setting maxThreads=1).
On Windows NT, the default native pool is always being used and iPlanet Web Server uses fibers (user-scheduled threads) for initial request processing. Using custom additional pools on Windows NT introduces no additional overhead.
In addition, native thread pool parameters can be added to the magnus.conf file for convenience. For more information, see "Native Thread Pools" in Appendix B, "Variables in magnus.conf."
stack size of each thread in the native (kernel) thread pool.
Init fn=thread-pool-init name="my-custom-pool" maxthreads=100 minthreads=1 queuesize=200
Init fn=load-modules shlib="C:/mydir/myplugin.dll" funcs="tracker" pool="my-custom-pool"
load-modules
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 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.
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.
require-auth
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.
specifies the type of authorization to be used. This should always be
basic.
require-auth
AuthTrans-class directives.
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.
Note: iPlanet Web Server 4.x incorporates the functionality of get-sslid into the standard processing of an SSL connection, so there should no longer be a need to use get-sslid as of iPlanet Web Server 4.x.
NameTrans stands for Name Translation. NameTrans directives translate virtual URLs to physical directories on your server. For example, the URL
http://www.test.com/some/file.html /usr/netscape/server4/docs/some/file.htmlNameTrans 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.
unix-home translates a URL to a specified directory within a user's home directory.
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=/personnelhttp://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,
NameTrans fn="assign-name" from="/perf" find-pathinfo-forward="" name="perf"
NameTrans fn="assign-name" from="/nsfc" nostat="/nsfc" name="nsfc"
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.
pfx2dir
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.
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)
In the first example, the URLhttp://server-name/cgi-bin/resource(such ashttp://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 namedcgi.
In the second example, the URL
NameTrans fn=pfx2dir from=/cgi-bin dir=/httpd/cgi-local name=cgi
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)
The third example shows the use of the
NameTrans fn=pfx2dir from=/icons/happy dir=/users/nikki/images
find-pathinfo-forward parameter. The URL http://server-name/cgi-bin/resource is translated to the physical pathname /export/home/cgi-bin/resource.
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.
(optional) is a flag which tells the server to
util_uri_escapethe URL before sending it. It should beyesorno. The default isyes.
In the first example, any request forhttp://server-name/whateveris translated to a request forhttp://tmpserver/whatever.
In the second example, any request forhttp://server-name/ toopopular/whateveris translated to a request forhttp://bigger/ better/stronger/morepopular/whatever.
NameTrans fn=redirect from=/toopopular url=http://bigger/better/stronger/morepopular
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:*init-uhome.
NameTrans fn=unix-home from /~ pwfile=/mydir/passwd subdir=public_html
init-uhome, find-links
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:
cert2user determines the authorized user from the client certificate.
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.
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.
PathCheck-class directives.
Thecert2userfunction maps the authenticated client certificate from the SSL3 session to a user name, using the certificate-to-user mappings in the user database specified byuserdb.
names the user database from which to obtain the certificate.
The server allows the certificate-to-user mapping to be created automatically by:
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.
(optional) is the path name for a file that will be sent if this ACL denies access.
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.
Use this function inside a <Client> block to deny the existence of a resource to specific users. For example, these lines deny existence of all resources to any user not in the personal.com domain:
<Client dns=*~.personal.com>
PathCheck fn=deny-existence
</Client>
PathCheck fn=deny-existence path=/usr/netscape/server4/docs/private
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.
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.
init-uhome, unix-home
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.
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.
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:
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.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.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.
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.
Note: If the ppath resolves to a resource or directory that is higher in the directory tree (or is in a different branch of the tree) than the base directory, the load-config function 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 function returns REQ_PROCEED if configuration files were loaded, REQ_ABORTED on error, or REQ_NOACTION when no files are loaded.
In this example, whenever the server receives a request for any resource containing the substringsecretthat resides inD:/Netscape/Server4/docs/ nikki/or a subdirectory thereof, it searches for a configuration file calledcheckaccess.nsconfig.
The server starts the search in the directoryD:/Netscape/Server4/docs/ nikki, and searches subdirectories too. It loads each instance ofcheckaccess.nsconfigthat it finds, applying the access control rules contained therein to determine whether the client is allowed to access the requested resource or not.
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).
Parameters
unix-uri-clean
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.
Parameters
init-cgi, send-cgi, send-wincgi, send-shellcgi
PathCheck-class directives.
The require-auth function allows access to resources only if the user or group is authorized. Before this function is called, an authorization function (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 auth-user wildcard value. Also, if the auth-group parameter is provided, the authorized user must belong to an authorized group which must match the auth-user wildcard value.
(optional) specifies a wildcard list of groups that are allowed access.
basic-auth, basic-ncsa
PathCheck-class directives. New in iPlanet Web Server 4.0.
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 with 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 secret-keysize and the bong-file parameter is not specified, the function returns REQ_ABORTED with a status of PROTOCOL_FORBIDDEN. If the bong file is specified, the function returns REQ_PROCEED, and the path variable is set to the bong filename. Also, when a keysize restriction is not met, the SSL session cache entry for the current session is invalidated, so that a full SSL handshake will occur the next time the same client connects to the server.
Requests that use ssl-check are not cacheable in the accelerator file cache if ssl-check returns something other than REQ_NOACTION.
This function supersedes the key-toosmall Service-class function that was used in Enterprise Server prior to release 4.0.
(optional) is the minimum number of bits required in the secret key.
(optional) is the name of a file (not a URI) to be served if the restriction is not met
PathCheck-class directives.
ssl-logoutinvalidates the current SSL session in the server's SSL session cache. This does not affect the current request, but the next time the client connects, a new SSL session will be created. If SSL is enabled, this function returnsREQ_PROCEEDafter invalidating the session cache entry. If SSL is not enabled, it returnsREQ_NOACTION.
PathCheck-class directives.
Unix Only. The unix-uri-clean function denies access to any resource whose physical path contains /./, /../ or // (these are potential security problems).
nt-uri-clean
ObjectType directives determine the MIME type of the file to send to the client in response to a request. MIME attributes currently sent are type, encoding, and language. The MIME type sent to the client as 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 what kind of content is being requested.
If there is more than one ObjectType directive in an object, 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.
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 ObjectType-class functions are described in detail in this section:
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, and content-language for the response being sent back to the client.
shtml-hacktype requests that .htm and .html files are parsed for server-parsed html 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 response based on the files extension and the MIME types database.
ObjectType-class directives.
The force-type function assigns a type to requests that do not already have a MIME type. This is used to specify a default object type.
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 chance to set the MIME type first. If there is more than one ObjectType directive in an object, 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.
load-types, type-by-extension, type-by-exp
ObjectType-class directives. New in iPlanet Web Server 4.1.
This function allows you to define a default charset, content-encoding, and content-language for the response being sent back to the client.
If the charset, content-encoding, and content-language have not been set for a response, then just before the headers are sent the defaults defined by set-default-type are used. Note that by placing this function in different objects in obj.conf, you can define different defaults for different parts of the document tree.
(optional) is the encoding assigned to a matching request (the
content-encodingheader).(optional) is the language assigned to a matching request (the
content-languageheader).
ObjectType-class directives.
The shtml-hacktype function changes the content-type of any .htm or .html file to magnus-internal/parsed-html and returns REQ_PROCEED. This provides backward compatibility with server-side includes for files with .htm or .html extensions. The function may also check the execute bit for the file on Unix systems. The use of this function is not recommended.
ObjectType-class directives.
The type-by-exp function matches the current path with a wildcard expression. If the two match, the type parameter information is applied to the file. This is the same as type-by-extension, except you use wildcard patterns for the files or directories specified in the URLs.
load-types, type-by-extension, force-type
ObjectType-class directives.
This function instructs the server to look in a table of MIME type mappings to find the MIME type of the requested resource according to the extension of the requested resource. The MIME type is added to the content-type header sent back to the client.
The table of MIME type mappings is created during the server's Init stage by the load-types function, which loads a MIME types file and creates the mappings. The MIME types file is usually called mime.types, but you can specify a different file by providing a different file name to load-types.
For example, the following two lines are part of the MIME types file:
type=text/html exts=htm,html
type=text/plain exts=txthtm or html, the type-by-extension file sets the type to text/html. If the extension is .txt, the function sets the type to text/plain.
For more information about MIME types, see Appendix C, "MIME Types."
load-types, type-by-exp, force-type
Service class of functions sends the response data to the client.
Every Service directive has the following optional parameters to determine whether the function is executed. All the optional parameters must match the current request for the function to be executed.
magnus-internal/* MIME types are used only to select a Service-class function to execute.Service-class function, the first one matching the optional parameters above is executed.
By default, the server sends the requested file to the client by calling the send-file function. The directive that sets the default is:
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"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 GET, HEAD, or POST, and the type does not start with magnus-internal/. Note here that the pattern *~ means "does not match." For a list of characters that can be used in patterns, see Appendix D, "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 filename 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 directories 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 certificate key size is too small to accept.
list-dir lists the contents of a directory.
make-dir creates a directory.
parse-html parses an HTML file for server-parsed html commands.
query-handler handles the HTML ISINDEX tag.
remove-dir deletes an empty directory.
remove-file deletes a file.
rename-file renames a file.
send-cgi sets up environment variables, launches a CGI program, and sends the response to the client.
send-file sends a local file to the client.
send-range sends a range of bytes of a file to the client.
send-shellcgi sets up environment variables, launches a shell CGI program, and sends the response to the client.
send-wincgi sets up environment variables, launches a WinCGI program, and sends the response to the client.
upload-file uploads and saves a file.
Service-class directives. New in iPlanet Web Server 4.0.
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 the footer can be dynamically generated. To specify static text as a footer, use the append-trailer function.
(optional) The pathname to the file containing the footer. Specify either
fileoruri.(optional) A URI pointing to the resource containing the footer. Specify either
fileoruri.
Service type=text/html method=GET fn=add-footer file="footers/footer1.html"
append-trailer, add-header
Service-class directives. New in iPlanet Web Server 4.0.
This function prepends a header to an HTML file that is sent to the client. The header is specified either as a filename or a URI -- thus the header can be dynamically generated.
(optional) The pathname to the file containing the header. Specify either
fileoruri.(optional) A URI pointing to the resource containing the header. Specify either
fileoruri.
Service type=text/html method=GET fn=add-header file="headers/header1.html"
add-footer, append-trailer
Service-class 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 REQ_ABORTED if a required parameter is missing, if there is extra path information after the file name in the URL, or if the file cannot be opened for read-only access.
(optional) is a time format string for
:LASTMOD:. For details about time formats refer to Appendix E, "Time Formats." Iftimefmtis not provided,:LASTMOD:will not be replaced with the time.
Service type=text/html method=GET fn=append-trailer trailer="<hr><img src=/logo.gif> Copyright 1999"
add-footer, add-header
Service-class 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.
Service type=magnus-internal/imagemap method=(GET|HEAD) fn=imagemap
Service-class directives.
The index-common function generates a fancy (or common) list of files in the requested directory. The list is sorted alphabetically. Files beginning with a period (.) are not displayed. Each item appears as an HTML link. This function displays more information than index-simple including the size, date last modified, and an icon for each file. It may also include a header and/or readme file into the listing.
The Init-class function cindex-init specifies the format for the index list, including where to look for the images.
If obj.conf contains a call to index-common in the Service stage, it must initialize fancy (or common) indexing by invoking cindex-init during the Init stage.
Indexing occurs when the requested resource is a directory that does not contain 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.
The icons displayed are .gif files dependent on the content-type of the file:
Service fn=index-common type=magnus-internal/directory method=(GET|HEAD) header=hdr readme=rdme.txt
cindex-init, index-simple, find-index, home-page
Service-class directives.
The index-simple function generates a simple index of the files in the requested directory. It scans a directory and 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 beginning 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.
cindex-init, index-common
Service-class directives. This function is deprecated in iPlanet Web Server 4.x. It is replaced by the PathCheck-class SAF ssl-check.
The key-toosmall function returns a message to the client specifying that 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.
<Object ppath=/mydocs/secret/*>
<Client secret-keysize=40)
Service fn=key-toosmall
</Client>
</Object>
Service-class directives.
The list-dir function returns a sequence of text lines to the client in response to a request whose method is INDEX. The format of the returned lines is:
name type size mimetypename field is the name of the file or directory. It is relative to the directory being indexed. It is URL-encoded, that is, any character might be represented by %xx, where xx is the hexadecimal representation of the character's ASCII number.
The type field is a MIME type such as text/html. Directories will be of type directory. A file for which the server doesn't have a type will be of type unknown.
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 obj.conf file contains a Service-class function that calls list-dir for requests whose method is INDEX.
Service-class 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 obj.conf file contains a Service-class function that invokes make-dir when the request method is MKDIR.
Service-class directives.
The parse-html function parses an HTML document, scanning for embedded commands. These commands may provide information from the server, include the contents of other files, or execute a CGI program. Refer to Appendix F, "Server-Parsed HTML Tags," for server-parsed HTML commands.
Service type=magnus-internal/parsed-html method=(GET|HEAD) fn=parse-html
Service-class directives.
The query-handler function runs a CGI program instead of referencing the path requested. This is used mainly to support the obsolete ISINDEX tag . If possible, use an HTML form instead.
Service-class directives.
The remove-dir function removes a directory when the client sends an request whose method is RMDIR. The directory must be empty (have no files in it). The function will fail if the directory is not empty or if the server doesn't have the privileges to remove the directory.
When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes remove-dir when the request method is RMDIR.
Service-class 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 obj.conf file contains a Service-class function that invokes remove-file when the request method is DELETE.
Service-class directives.
The rename-file function renames a file when the client sends a request with a New-URL header 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 obj.conf file contains a Service-class function that invokes rename-file when the request method is MOVE.
Service-class 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 about the CGI environment variables and their NSAPI equivalents refer to section "CGI to NSAPI Conversion" in Chapter 4, "Creating Custom SAFs."
Service-class directives.
The send-file function sends the contents of the requested file to the client. It provides the content-type, content-length, and last-modified headers.
Most requests are handled by this function using the following directive (which usually comes last in the list of Service-class directives in the default object so that it acts as a default)
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"This directive is invoked if the method of the request is
GET, HEAD, or POST, and the type does not start with magnus-internal/. Note here that the pattern *~ means "does not match." For a list of characters that can be used in patterns, see Appendix D, "Wildcard Patterns."
Service type="*~magnus-internal/*" method="(GET|HEAD)" fn="send-file"
In the following example, the server does not cache static files from/export/ somedir/when requested by the URL prefix/myurl.
<Object name=default>
...
NameTrans fn="pfx2dir" from="/myurl" dir="/export/mydir", name="myname"
...
Service method=(GET|HEAD|POST) type=*~magnus-internal/* fn=send-file
...
</Object>
Service-class directives.
When the client requests a portion of a document, by specifying HTTP byte ranges, the send-range function returns that portion.
Service-class directives.
Windows NT only. The send-shellcgi function runs a file as a shell CGI program and sends the results to the client. Shell CGI is a server configuration that lets you run CGI applications using the file associations set in Windows NT. For information about shell CGI programs, consult the iPlanet Web Server Administrator's Guide.
Service-class directives.
Windows NT only. The send-wincgi function runs a file as a Windows CGI program and sends the results to the client. For information about Windows CGI programs, consult the iPlanet Web Server Administrator's Guide.
Service-class directives.
The upload-file function uploads and saves a new file when the client sends a request whose method is PUT if the user is authorized and the server has the needed file system privileges.
When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes upload-file when the request method is PUT.
AddLog directive, all are executed.
The following AddLog-class functions are described in detail in this section:
common-log records information about the request in the common log format.
flex-log records information about the request in a flexible, configurable format.
record-useragent records the client's ip address and user-agent header.
AddLog-class directives.
This function records request-specific data in the common log format (used by most HTTP servers). There is a log analyzer in the /extras/log_anly directory for iPlanet Web Server. The common log must have been initialized previously by the init-cgi function.
There are also a number of free statistics generators for the common log format.
(optional) gives the name of a log file, which must have been given as a parameter to the
init-clfInit function. If no name is given, the entry is recorded in the global log file.
# Log all accesses to the global log file
# Log accesses from outside our subnet (198.93.5.*) to
# nonlocallog
init-clf
AddLog-class directives.
This function records request-specific data in a flexible log format. It may also record requests in the common log format. There is a log analyzer in the /extras/flexanlg directory for iPlanet Web Server.
There are also a number of free statistics generators for the common log format.
The log format is specified by the flex-init function call. For information about rotating logs, see flex-rotate-init.
(optional) gives the name of a log file, which must have been given as a parameter to the
flex-initInit function. If no name is given, the entry is recorded in the global log file.
# Log all accesses to the global log file
# Log accesses from outside our subnet (198.93.5.*) to
flex-rotate-init, flex-init, init-clf, common-log, record-
useragent
AddLog-class directives.
The record-useragent function records the IP address of the client, followed by its User-Agent HTTP header. This indicates what version of Netscape Navigator (or other client) was used for this transaction.
(optional) gives the name of a log file, which must have been given as a parameter to the
init-clfInit function. If no name is given, the entry is recorded in the global log file.
flex-init,init-clf,common-log,record-useragent,flex-log
REQ_ABORTED. When this happens, the server stops processing the request. Instead, it searches for an Error directive matching the HTTP response status code or its associated reason phrase, and executes the directive's function. If the server does not find a matching Error directive, it returns the response status code to the client.
The following Error-class functions are described in detail in this section:
Error-class directives.
The send-error function sends an HTML file to the client in place of a specific HTTP response status. This allows the server to present a friendly message describing the problem. The HTML page may contain images and links to the server's home page or other pages.
Error fn=send-error code=401 path=/netscape/server4/docs/errors/401.html
Last Updated: 03/01/00 09:21:58
© Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.