Configuration files control how iPlanet Web Server operates. This appendix summarizes the Purpose, Location, and Contents or Syntax of each configuration file, then briefly describes all directives or parameters allowed in the file (if any) in a table. Cross references are listed after See Also headings when other manuals describe some of the directives or parameters in more detail.

Purpose
Allows you to program the server to perform maintenance activities at regular intervals, such as back up log files. The ns-cron.conf file controls whether or not the cron.conf file is activated.

Determines how dynamic groups are handled. If off, dynamic groups are not supported. If on, dynamic groups are supported. If recursive, dynamic groups can contain other groups.

binddn

A valid DN

The DN used for connecting to the database. If both binddn and bindpw are not present, binding is anonymous.

bindpw

The password used for connecting to the database. If both binddn and bindpw are not present, binding is anonymous.

dcsuffix

A valid DN (relative to the LDAP URL)

(none)

If present, the default value of the base DN for the request's virtual server is determined by a DC tree search of the connection group's servername attribute, starting at the dcsuffix DN. Otherwise, the default value of the base DN is the base DN value in the LDAP URL.

The basedn attribute of a USERDB element in the server.xml file overrides this value.

digestauth

off, on

off

Specifies whether the database can do digest authentication. If on, a special Directory Server plugin is required. For information about how to install this plugin, see the iPlanet Web Server Administrator's Guide.

iwsstats.xml

Purpose
Reports server performance statistics. Configured via the stats-xml SAF in obj.conf, and present only if this SAF is used. This file is intended to be read but not modified.

Location
Located here, dynamically generated:

server_root/https-server_id/stats-xml/iwsstats.xml

You can view it here:

http://server_id:port/stats-xml/iwsstats.xml

Syntax
The file has the following basic XML syntax, with nested elements:

Indicates whether more than maxVirtualServers are configured (yes). If this attribute is set to 1, statistics are not being tracked for all virtual servers.

connection-queue

(none)

Describes a connection queue (the queue in which requests are enqueued prior to being serviced). There is only one connection queue in iPlanet Web Server 6.0. Subsequent versions may introduce multiple connection queues.

id

The connection queue ID.

thread-pool

(none)

Describes a thread pool as defined in the magnus.conf file.

id

The thread pool ID.

name

The symbolic name of the thread pool.

profile

(none)

Describes an NSAPI performance profile bucket as defined in the magnus.conf file.

A JVM environment variable can be included in jvm.conf and given a value, for example (all on one line):

org.omg.CORBA.ORBClass=com.inprise.vbroker.orb.ORB

jvm.minHeapSize

1048576 (1 MB)

The minimum heap size allocated to Java.

For Solaris, change this value to 3145278 (3 MB). For HPUX, change this value to 4194304 (4 MB). For all other operating systems, 1 MB is ideal.

jvm.maxHeapSize

16777216 (16 MB)

The maximum heap size allocated to Java.

jvm.enableClassGC

0 (off), 1 (on)

0

Enables or disables class garbage collection.

jvm.verboseMode

0 (off), 1 (on)

0

Enables or disables JVM verbose mode. If on, the JVM logs a commentary on what it is doing, such as loading classes. The commentary appears in the error log.

jvm.enableDebug

0 (off), 1 (on)

0

Enables or disables JVM remote debugging.

jvm.printErrors

0 (off), 1 (logs to log file), 2 (logs to stderr)

0

Enables or disables reporting of errors through vfprintf.

jvm.option

Allows you to set vendor JVM options.

jvm.profiler

Specifies the profiler. If you use the optimizeit profiler from Intuitive Systems, you must also set the OPTIDIR setting.

jvm.disableThreadRecycling

0 (off), 1 (on)

0

Enables or disables thread recycling. If on, the server always creates a global scope thread to execute servlets. Otherwise a global scope thread is created only when the request handling thread is not in the global scope.

jvm.serializeAttach

0 (off), 1 (on)

0

If on, threads that attach to the JVM are serialized. By default (if off), threads can attach to the JVM in parallel.

jvm.stickyAttach

0 (off), 1 (on)

0

Setting the value of this parameter to 1 causes threads to remember that they are attached to the JVM.

Specifies the Java compiler. See your JVM documentation for options that turn the JIT (just in time) compiler on and off. This should be set to NONE when jvm.enableDebug is on.

OPTITDIR

A path

*

Specifies the path to the profiler if the profiler is optimizeit.

nes.jsp.enabledebug

0 (off), 1 (on)

1

Enables or disables verbose JSP compilation tracing.

jvm.include.CLASSPATH

0 (off), 1 (on)

1

Specifies whether to include the CLASSPATH environment variable value in the jvm.classpath setting.

nes.jsp.forkjavac

0 (off), 1 (on)

0

If on, Java compilation of JSPs runs in a separate process.

jvm.serializeFirstRequest

0 (off), 1 (on)

1 for Linux, AIX, and Compaq (DEC); 0 for other platforms

If on, ensures that only one request thread loads and constructs a servlet object. Once a servlet is loaded and initialized, new requests to the same servlet happen in parallel. This setting must be on for Linux, AIX, and Compaq (DEC).

jvm.classpath

A path with forward slashes only

Specifies the path(s) to JAR files dependent on the JVM. Enter additional classpath values as needed.

* N:/App/IntuitiveSystems/OptimizeIt30D, where N is the drive on which OptimizeIt is installed.

(optional) is a string of letters specifying the options to activate. Currently there is only one possible option:

s tells the server to scan each HTML file in the directory being indexed for the contents of the HTML <TITLE> tag to display in the description field. The <TITLE> tag must be within the first 255 characters of the file.

widths

Comma separated numbers of characters

Minimums required to display column titles

(optional) Specifies the width for each of the four columns in the indexing display: name, last-modified date, size, and description respectively.

The final three values can each be set to 0 to turn the display for that column off. The name column cannot be turned off.

timezone

GMT or local

local

(optional, iPlanet Web Server 4.x only) Indicates whether the last-modified time is shown in local time or in Greenwich Mean Time.

(optional) Specifies a wildcard pattern for file names the server should ignore while indexing. File names starting with a period (.) are always ignored.

icon-uri

/mc-icons/

(optional) Specifies the URI prefix the index-common function uses when generating URLs for file icons (.gif files). If icon-uri is different from the default, the pfx2dir function in the NameTrans directive must be changed so that the server can find these icons.

define-perf-bucket

Creates a performance bucket, which you can use to measure the performance of SAFs in obj.conf (see "The bucket Parameter"). This function works only if the perf-init function is enabled.

name

A name for the bucket, for example cgi-bucket.

description

A description of what the bucket measures, for example CGI Stats.

dns-cache-init

Configures DNS caching.

cache-size

32 to 32768 (32K)

1024

(optional) Specifies how many entries are contained in the cache.

expire

1 to 31536000seconds (1 year)

1200 seconds (20 minutes)

(optional) specifies how long (in seconds) it takes for a cache entry to expire.

flex-init

Initializes the flexible logging system.

logFileName

A path or file name

The full path to the log file or a file name relative to the server's logs directory. In this example, the log file name is access and the path is /logdir/access:

(optional) specifies the file name of a user-supplied program to execute following log file rotation. The program is passed the post-rotation name of the rotated log file as its parameter.

init-cgi

Changes the default settings for CGI programs.

timeout

Number of seconds

300

(optional) specifies how many seconds the server waits for CGI output before terminating the script.

cgistub-path

(optional) specifies the path to the CGI stub binary. If not specified, iPlanet Web Server looks in the following directories, in the following order, relative to the server instance's config directory: ../private/Cgistub, then ../../bin/https/bin/Cgistub.

(optional) specifies the name and value for an environment variable that the server places into the environment for the CGI.

init-clf

Initializes the Common Log subsystem.

logFileName

A path or file name

Specifies either the full path to the log file or a file name relative to the server's logs directory.

init-uhome

Loads user home directory information.

pwfile

(optional) specifies the full file system path to a file other than /etc/passwd. If not provided, the default Unix path (/etc/passwd) is used.

load-modules

Loads shared libraries into the server.

shlib

Specifies either the full path to the shared library or dynamic link library or a file name relative to the server configuration directory.

funcs

A comma separated list with no spaces

A list of the names of the functions in the shared library or dynamic link library to be made available for use by other Init or Service directives. The dash (-) character may be used in place of the underscore (_) character in function names.

NativeThread

yes, no

yes

(optional) specifies which threading model to use. no causes the routines in the library to use user-level threading. yes enables kernel-level threading.

pool

The name of a custom thread pool, as specified in thread-pool-init.

nt-console-init

Enables the NT console, which is the command-line shell that displays standard output and error streams.

stderr

console

Directs error messages to the NT console.

stdout

console

Directs output to the NT console.

perf-init

Enables system performance measurement via performance buckets.

disable

true, false

true

Disables the function when true.

pool-init

Configures pooled memory allocation.

free-size

1048576 bytes or less

(optional) maximum size in bytes of free block list.

disable

true, false

false

(optional) flag to disable the use of pooled memory if true.

register-http-method

Lets you extend the HTTP protocol by registering new HTTP methods.

methods

A comma separated list

Names of the methods you are registering.

stats-init

Enables reporting of performance statistics in XML format.

profiling

yes, no

no

Enables NSAPI performance profiling using buckets. This can also be enabled through perf-init.

update-interval

1 or greater

5

The period in seconds between statistics updates within the server.

virtual-servers

1 or greater

1000

The maximum number of virtual servers for which statistics are tracked. This number should be set higher than the number of virtual servers configured.

thread-pool-init

Configures an additional thread pool.

name

Name of the thread pool.

maxthreads

Maximum number of threads in the pool.

minthreads

Minimum number of threads in the pool.

queueSize

Number of bytes

Size of the queue for the pool.

stackSize

Number of bytes

Stack size of each thread in the native (kernel) thread pool.

Directives

Table 2-10 &nbsp&nbsp magnus.conf directives

Directive

Allowed Values

Default Value

Description

ACLCacheLifetime

Any number of seconds

120

Determines the number of seconds before cache entries expire. Each time an entry in the cache is referenced, its age is calculated and checked against ACLCacheLifetime. The entry is not used if its age is greater than or equal to the ACLCacheLifetime. If this value is set to 0, the cache is turned off.

ACLUserCacheSize

200

Determines the number of users in the User Cache.

ACLGroupCacheSize

4

Determines how many group IDs can be cached for a single UID/cache entry.

AdminLanguage

en (English),fr (French),de (German),ja (Japanese)

en

Specifies the language for the Server Manager.

AsyncDNS

on, off

off

Specifies whether asynchronous DNS is allowed.

CGIExpirationTimeout

Any number of seconds

300 (5 minutes) recommended

Specifies the maximum time in seconds that CGI processes are allowed to run before being killed.

CGIStubIdleTimeout

Any number of seconds

30

Causes the server to kill any CGIStub processes that have been idle for the number of seconds set by this directive. Once the number of processes is at MinCGIStubs, the server does not kill any more processes.

CGIWaitPid

on, off

on

(Unix only) makes the action for the SIGCHLD signal the system default action for the signal. Makes the SHTML engine wait explicitly on its exec cmd child processes.

ChildRestartCallback

on, off, yes, no, true, false

no

Forces the callback of NSAPI functions that were registered using the daemon_atrestart function when the server is restarting or shutting down.

ChunkedRequestBufferSize

Any number of bytes

8192

Determines the default buffer size for "un-chunking" request data.

ChunkedRequestTimeout

Any number of seconds

60 (1 minute).

Determines the default timeout for "un-chunking" request data.

ClientLanguage

en (English),fr (French),de (German),ja (Japanese)

en

Specifies the language for client messages (such as File Not Found).

ConnQueueSize

Any number of connections

5000

Specifies the number of outstanding (yet to be serviced) connections that the web server can have.

DefaultCharSet

A valid character set name

iso-8859-1

Specifies the default character set for the server. The default language is used for both the client responses and administration.

DefaultLanguage

en (English),fr (French),de (German),ja (Japanese)

en

Specifies the default language for the server. The default language is used for both the client responses and administration.

DNS

on, off

on

Specifies whether the server performs DNS lookups on clients that access the server.

ErrorLog

A path

(none)

Specifies the directory where the server logs its errors.

ErrorLogDateFormat

See the manual page for the C library function strftime

%d/%b/%Y:%H:%M:%S

The date format for the error log.

ExtraPath

A path

(none)

Appends the specified directory name to the PATH environment variable. This is used for configuring Java on Windows NT. There is no default value; you must specify a value.

HeaderBufferSize

Any number of bytes

8192 (8 KB)

The size (in bytes) of the buffer used by each of the request processing threads for reading the request data from the client. The maximum number of request processing threads is controlled by the RqThrottle setting.

HTTPVersion

m.n; m is the major version number and n the minor version number

1.1

The current HTTP version used by the server.

IOTimeout

Any number of seconds

30 for servers that don't use hardware encryption devices and 300 for those that do

Specifies the number of seconds the server waits for data to arrive from the client. If data does not arrive before the timeout expires then the connection is closed.

KeepAliveThreads

Any number of threads

1

Specifies the number of threads in the keep-alive subsystem. It is recommended that this number be a small multiple of the number of processors on the system.

KeepAliveTimeout

300 seconds maximum

30

Determines the maximum time that the server holds open an HTTP Keep-Alive connection or a persistent connection between the client and the server.

KernelThreads

0 (off), 1 (on)

0 (off)

If on, ensures that the server uses only kernel-level threads, not user-level threads. If off, uses only user-level threads.

ListenQ

Ranges are platform-specific

4096 (AIX), 200 (NT), 128 (all others)

Defines the number of incoming connections for a server socket.

LogFlushInterval

Any number of seconds

30

Determines the log flush interval, in seconds, of the log flush thread.

LogVerbose

on, off

off

If on, logs all server messages including those that are not logged by default.

LogVsId

on, off

off

Determines whether virtual server IDs are displayed in the error log. You should enable LogVsId when multiple virtual servers share the same log file.

MaxCGIStubs

Any number of CGI stubs

10

Controls the maximum number of CGIStub processes the server can spawn. This is the maximum concurrent CGIStub processes in execution, not the maximum number of pending requests.

MaxKeepAliveConnections

0 - 32768

256

Specifies the maximum number of Keep-Alive and persistent connections that the server can have open simultaneously.

MaxProcs

Any number of processes

1

(Unix only) Specifies the maximum number of processes that the server can have running simultaneously.

MaxRqHeaders

0 - 32

32

Specifies the maximum number of header lines in a request.

MinCGIStubs

Any number less than MaxCGIStubs

2

Controls the number of processes that are started by default.

MtaHost

A valid e-mail address

(none)

Specifies the SMTP mail server used by the server's agents. This value must be specified before reports can be sent to a mailing address.

NativePoolMaxThreads

Any number of threads

128

Determines the maximum number of threads in the native (kernel) thread pool.

NativePoolMinThreads

Any number of threads

1

Determines the minimum number of threads in the native (kernel) thread pool.

NativePoolQueueSize

Any nonnegative number

0

Determines the number of threads that can wait in the queue for the thread pool.

NativePoolStackSize

Any nonnegative number

0

Determines the stack size of each thread in the native (kernel) thread pool.

NetSiteRoot

A path

(none)

Specifies the absolute pathname to the top-level directory under which server instances can be found. There is no default value; you must specify a value.

PidLog

A valid path to a file

(none)

Specifies a file in which to record the process ID (pid) of the base server process.

PostThreadsEarly

1 (on), 0 (off)

0 (off)

If on, checks whether the minimum number of threads are available at a socket after accepting a connection but before sending the response to the request.

RcvBufSize

Range is platform-specific

0 (uses platform-specific default)

Controls the size of the receive buffer at the server's sockets.

RqThrottle

Any number of requests

512

Specifies the maximum number of simultaneous request processing threads that the server can handle simultaneously per socket.

RqThrottleMin

Any number less than RqThrottle

48

Specifies the number of request processing threads that are created when the server is started. As the load on the server increases, more request processing threads are created (up to a maximum of RqThrottle threads).

Security

on, off

off

Globally enables or disables SSL by making certificates available to the server instance. Must be on for virtual servers to use SSL.

ServerConfigurationFile

A file name

server.xml

The name of the file that specifies virtual servers.

ServerID

A string

(none)

Specifies the server ID, such as https-boots.mcom.com.

#ServerRoot

A path

(none)

Specifies the server root. This directive is set during installation and is commented out. Unlike other directives, the server expects this directive to start with #. Do not change this directive.

SndBufSize

Range is platform-specific

0 (uses platform-specific default)

Controls the size of the send buffer at the server's sockets.

SSL3SessionTimeout

5 - 86400

86400 (24 hours).

The number of seconds until a cached SSL3 session becomes invalid.

SSLCacheEntries

A non-negative integer

10000 (used if 0 is specified)

Specifies the number of SSL sessions that can be cached. There is no upper limit.

SSLClientAuthDataLimit

Number of Bytes

1048576 (1MB)

Specifies the maximum amount of application data that is buffered during the client certificate handshake phase.

SSLClientAuthTimeout

Any number of seconds

60

Specifies the number of seconds after which the client certificate handshake phase times out.

SSLSessionTimeout

5 - 100

100

Specifies the number of seconds until a cached SSL2 session becomes invalid.

StackSize

Number of Bytes

The most favorable machine- specific stack size.

Determines the maximum stack size for each request handling thread.

StrictHttpHeaders

on, off

off

If on, rejects connections that include inappropriately duplicated headers.

TempDir

A path

/tmp (Unix)

TEMP (environment variable for Windows NT)

Specifies the directory the server uses for its temporary files. On Unix, this directory should be owned by, and writable by, the user the server runs as.

TempDirSecurity

on, off

on

Determines whether the server checks if the TempDir directory is secure. On Unix, specifying TempDirSecurity off allows the server to use /tmp as a temporary directory.

TerminateTimeout

Any number of seconds

30

Specifies the time in seconds that the server waits for all existing connections to terminate before it shuts down.

ThreadIncrement

Any number of threads

10

The number of additional or new request processing threads created to handle an increase in the load on the server.

Umask

A standard UNIX umask value

(none)

Unix only: Specifies the umask value used by the NSAPI functions System_fopenWA() and System_fopenRW() to open files in different modes.

UseNativePoll

1 (on), 0 (off)

1 (on)

Uses a platform-specific poll interface when set to 1 (on). Uses the NSPR poll interface in the KeepAlive subsystem when set to 0 (off).

(Windows NT) specifies the user account the server runs with, allowing you to restrict or enable system features for the server.

(Unix) if the server is started by the superuser or root user, the server binds to the Port you specify and then switches its user ID to the user account specified with the User directive. This directive is ignored if the server isn't started as root.

WincgiTimeout

Any number of seconds

60

WinCGI processes that take longer than this value are terminated when this timeout expires.

mime.types

Purpose
Maps standard MIME types to file extensions. Each virtual server can have its own mime.types file.

Generates and sends the response to the client. This involves setting the HTTP result status, setting up response headers (such as content-type and content-length), and generating and sending the response data.

AddLog

Adds an entry to a log file to record information about the transaction.

Error

Handles an HTTP error resulting from execution of the previous directive. Typically the server handles an error by sending a custom HTML document to the user describing the problem and possible solutions.

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.

The all-requests bucket records.perf statistics for all NSAPI SAFs, including those in the default-bucket.

You can define additional performance buckets in the magnus.conf file (see the perf-init and define-perf-bucket functions).

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. Because bucket is a parameter of every obj.conf function, for brevity it is not listed in the following tables.

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.

Calls a custom function to verify user name and password. Optionally determines the user's group.

auth-type

basic

basic

Specifies the type of authorization to be used.

userdb

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

userfn

The name of the user custom function to verify authorization. This function must have been previously loaded with load-modules.

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 group custom function that must have been previously loaded with load-modules.

basic-ncsa

Verifies user name and password against an NCSA-style or system DBM database. Optionally determines the user's group.

auth-type

basic

basic

Specifies the type of authorization to be used.

dbm

(optional) specifies the full path and base file name of the user database in the server's native format. 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 name:password, where password is encrypted. If you use this parameter, don't use dbm.

grpfile

(optional) specifies the NCSA-style HTTPD group file to be used. Each line of a group file consists of group:user1 user2 ... userN where each user is separated by spaces.

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

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.

NameTrans Functions

Table 2-16 &nbsp&nbsp obj.conf NameTrans functions

Function/Parameter

Allowed Values

Default Value

Description

assign-name

Tells the server to process directives in a named object.

from

A wildcard pattern that specifies the path to be affected.

name

Specifies an additional named object in obj.conf whose directives will be applied to this request.

find-pathinfo- forward

The value is ignored

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

nostat

(optional) prevents the server from performing a stat on a specified URL whenever possible. Use nostat only when the path of the virtual-path does not exist on the system, for example, for NSAPI plugin URLs, to improve performance by avoiding unnecessary stats on those URLs.

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.

root

server_root/docs

The file system path to the server's root document directory.

home-page

Translates a request for the server's root home page (/) to a specific file.

path

The path and name of the home page file. If path starts with a slash (/), it is assumed to be a full path to a file.

pfx2dir

Translates any URL beginning with a given prefix to a file system directory and optionally enables directives in an additional named object.

from

The URI prefix to convert. It should not have a trailing slash (/).

dir

The local file system directory path that the 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.

find-pathinfo- forward

The value is ignored

(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 pfx2dir does by default.

redirect

Redirects the client to a different URL.

from

Specifies the prefix of the requested URI to match.

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

url-prefix

(maybe optional) 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).

escape

yes, no

yes

(optional) is a flag which tells the server to util_uri_escape the URL before sending it.

strip-params

Removes embedded semicolon-delimited parameters from the path. For example, a URI of /dir1;param1/dir2 becomes /dir1/dir2. If used, should be the first NameTrans directive listed.

unix-home

Translates a URL to a specified directory within a user's home directory.

from

The URL prefix to translate, usually "/~".

subdir

The subdirectory within the user's home directory that contains their web documents.

pwfile

(optional) the full path and file name of the password file if it is different from /etc/passwd.

name

(optional) specifies an additional named object whose directives will be applied to this request.

PathCheck Functions

Table 2-17 &nbsp&nbsp obj.conf PathCheck functions

Function/Parameter

Allowed Values

Default Value

Description

cert2user

Determines the authorized user from the client certificate.

userdb

Names the user database from which to obtain the certificate.

makefrombasic

Tells the function to establish a certificate-to-user mapping.

require

0 or 1

1

Governs the return value if the certificate cannot be mapped to a user name. If require=0, the function returns REQ_NOACTION, allowing the processing of the request to continue. If require is not 0, the function returns REQ_ABORTED and sets the protocol status to 403 FORBIDDEN.

method

Specifies a wildcard pattern for the HTTP methods for which this function will be applied. If method is absent, the function is applied for any method.

check-acl

Checks an access control list for authorization.

acl

The name of an Access Control List.

shexp

(optional) a wildcard pattern that specifies the path for which to apply the ACL.

bong-file

(optional) the path name for a file that will be sent if this ACL denies access.

deny-existence

Indicates that a resource was not found.

path

(optional) 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 send rather than responding with the "not found" message. It is a full file-system path.

find-index

Locates a default file when a directory is requested.

index-names

A comma separated list

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

find-links

Denies access to directories with certain file system links

disable

h, s, o

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.

dir

The directory to begin checking. If you specify an absolute path, any request to that path and its subdirectories is checked for symbolic links. If you specify a partial path, any request containing that partial path is checked for symbolic links.

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

get-client-cert

Gets the authenticated client certificate from the SSL3 session.

dorequest

0 or 1

0 if dorequest is absent

Controls whether to actually try to get the certificate, or just test for its presence.

1 tells the 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 dialog box to the user to select a client certificate.

0 tells the function not to redo the SSL3 handshake if the server does not already have the client certificate.

require

0 or 1

1 if require is absent

Controls whether failure to get a client certificate will abort the HTTP request.

1 tells the function to abort the HTTP request if the client certificate is not present after dorequest is handled. In this case, the HTTP status is set to PROTOCOL_FORBIDDEN, and the 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 will be applied. If method is absent, the function is applied to all requests.

load-config

Finds and loads extra configuration information from a file in the requested path

file

.nsconfig

(optional) the name of the dynamic configuration file containing the access rules to be applied to the requested resource.

disable-types

(optional) specifies a wildcard pattern of types to disable for the base directory, such as magnus-internal/cgi. Requests for resources matching these types are aborted.

descend

(optional) if present, specifies that the server should search in subdirectories of this directory for dynamic configuration files.

basedir

A path

The result of translating the requested resource's URL to a physical pathname

(optional) specifies base directory. This is the highest-level directory for which requests will invoke the load-config function and is also the directory where the server starts searching for configuration files.

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.

extension

The replacement file extension.

require-auth

Denies access to unauthorized users or groups.

path

(optional) a wildcard local file system path on which this function should operate. If no path is provided, the function applies to all paths.

auth-type

basic

basic

The type of HTTP authorization used and must match the auth-type from the previous authorization function in AuthTrans.

realm

A string sent to the browser indicating the secure area (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 access.

set-virtual-index

Specifies a virtual index for a directory.

virtual-index

The URI of the content generator that acts as an index for the URI the user enters.

from

A comma separated list

(optional) a list of URIs for which this virtual-index is applicable. If from is not specified, the virtual-index always applies.

ssl-check

Checks the secret keysize.

secret-keysize

(optional) the minimum number of bits required in the secret key.

bong-file

(optional) the name of a file (not a URI) to be served if the restriction is not met.

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.

ObjectType Functions

Table 2-18 &nbsp&nbsp obj.conf ObjectType functions

Function/Parameter

Allowed Values

Default Value

Description

force-type

Sets the content-type header for the response to a specific type.

type

(optional) the type assigned to a matching request (the content-type header).

enc

(optional) the encoding assigned to a matching request (the content-encoding header).

lang

(optional) the language assigned to a matching request (the content-language header).

charset

(optional) the character set for the magnus-charset parameter in rq->srvhdrs. If the browser sent the Accept-charset header or its User-agent is mozilla/1.1 or newer, then append "; charset=charset" to content-type, where charset is the value of the magnus-charset parameter in rq->srvhdrs.

set-default-type

Allows you to define a default charset, content-encoding, and content-language for the response being sent back to the client.

enc

(optional) the encoding assigned to a matching request (the content-encoding header).

lang

(optional) the language assigned to a matching request (the content-language header).

charset

(optional) the character set for the magnus-charset parameter in rq->srvhdrs. If the browser sent the Accept-charset header or its User-agent is mozilla/1.1 or newer, then append "; charset=charset" to content-type, where charset is the value of the magnus-charset parameter in rq->srvhdrs.

shtml-hacktype

Requests that .htm and .html files are parsed for server-parsed html commands.

exec-hack

The value is ignored

(Unix only, optional) if present, tells the function to change the content-type only if the execute bit is enabled.

type-by-exp

Sets the content-type header for the response based on the requested path.

exp

The wildcard pattern of paths for which this function is applied.

type

(optional) the type assigned to a matching request (the content-type header).

enc

(optional) the encoding assigned to a matching request (the content-encoding header).

lang

(optional) the language assigned to a matching request (the content-language header).

charset

(optional) the character set for the magnus-charset parameter in rq->srvhdrs. If the browser sent the Accept-charset header or its User-agent is mozilla/1.1 or newer, then append "; charset=charset" to content-type, where charset is the value of the magnus-charset parameter in rq->srvhdrs.

type-by-extension

Sets the content-type header for the response based on the files extension and the MIME types database.

Service Functions

Table 2-19 &nbsp&nbsp obj.conf Service functions

Function/Parameter

Allowed Values

Default Value

Description

Common Service parameters

The first seven parameters listed are common to all Service functions. For brevity, they are listed once.

type

(optional) specifies a wildcard pattern of MIME types for which this function will be executed. The magnus-internal/* MIME types are used only to select a Service function to execute.

method

(optional) specifies a wildcard pattern of HTTP methods for which this function will be executed. Common HTTP methods are GET, HEAD, and POST.

query

(optional) specifies a wildcard pattern of query strings for which this function will be executed.

(optional) determines the maximum time 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.

(optional) The pathname to the file containing the footer. Specify either file or uri.

uri

(optional) A URI pointing to the resource containing the footer. Specify either file or uri.

NSIntAbsFilePath

yes or no

no

(optional) if the file parameter is specified, the NSIntAbsFilePath parameter determines whether the file name is absolute (yes) or relative (no).

add-header

Prepends a header specified by a filename or URL to an HTML file.

file

(optional) The pathname to the file containing the header. Specify either file or uri.

uri

(optional) A URI pointing to the resource containing the header. Specify either file or uri.

NSIntAbsFilePath

yes or no

no

(optional) if the file parameter is specified, the NSIntAbsFilePath parameter determines whether the file name is absolute (yes) or relative (no).

append-trailer

Appends text to the end of an HTML file.

trailer

The text to append to HTML documents. The string is unescaped with util_uri_unescape before being sent. The text can contain HTML tags and can be up to 512 characters long after unescaping and inserting the date. If you use the string :LASTMOD:, which is replaced by the date the file was last modified; you must also specify a time format with timefmt.

Generates a fancy list of the files and directories in a requested directory.

header

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

readme

(optional) the path (relative to the directory being indexed) and name of a file (HTML or plain text) to append to the directory listing.

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. The request method must be INDEX.

make-dir

Creates a directory. The request method must be MKDIR.

query-handler

Handles the HTML ISINDEX tag.

path

The full path and file name of the CGI program to run.

remove-dir

Deletes an empty directory. The request method must be RMDIR.

remove-file

Deletes a file. The request method must be DELETE.

rename-file

Renames a file. The request method must be MOVE.

send-cgi

Sets up environment variables, launches a CGI program, and sends the response to the client.

user

(Unix only) The name of the user to execute CGI programs as.

group

(Unix only) The name of the group to execute CGI programs as.

chroot

(Unix only) The directory to chroot to before execution begins. This is relative to the Chroot defined in magnus.conf.

dir

(Unix only) The directory to chdir to after chroot but before execution begins.

rlimit_as

(Unix only) The maximum CGI program address space in bytes. 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_core

(Unix only) 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) 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 program's priority relative to the server. Typically, the server is run with a nice value of 0 and the nice increment would be between 0 (the CGI program runs at same priority as server) and 19 (the CGI program runs at much lower priority than server).

send-file

Sends a local file to the client. This directive is invoked if the method of the request is GET, HEAD, or POST, and the type does not start with magnus-internal/.

nocache

The value is ignored

(optional) prevents the server from caching responses to static file requests. For example, you can specify that files in a particular directory are not to be cached, which is useful for directories where the files change frequently.

send-range

Sends a range of bytes of a file to the client.

send-shellcgi

(Windows NT only) Sets up environment variables, launches a shell CGI program, and sends the response to the client.

send-wincgi

(Windows NT only) Sets up environment variables, launches a WinCGI program, and sends the response to the client.

service-dump

Creates a performance report based on collected performance bucket data (see "The bucket Parameter"). The mime.types file must contain the following line: type=perf exts=perf. To read the report, point the browser here: http://server_id:port/.perf.

type

perf

Specifies the MIME type of the report.

shtml_send

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. The shtml_send function is only available when the Shtml plugin (libShtml.so on Unix, libShtml.dll on Windows NT) is loaded.

ShtmlMaxDepth

10

Maximum depth of include nesting allowed.

addCgiInitVars

yes, no

no

(Unix only) If present and equal to yes, adds the environment variables defined in the init-cgi SAF to the environment of any command executed through the SHTML exec tag.

stats-xml

Creates a performance report in XML format. You must initialize this function using the stats-init function in magnus.conf, then use a NameTrans function to direct requests to the stats-xml function. The report is generated here: http://server_id:port/stats-xml/iwsstats.xml. The associated DTD file is here: http://server_id:port/stats-xml/iwsstats.dtd.

upload-file

Uploads and saves a file. The request method must be PUT.

AddLog Functions

Table 2-20 &nbsp&nbsp obj.conf AddLog functions

Function/Parameter

Allowed Values

Default Value

Description

common-log

Records information about the request in the common log format.

name

(optional) gives the name of a log file, which must have been given as a parameter to the init-clf Init function. If no name is given, the entry is recorded in the global log file.

iponly

The value is ignored

(optional) instructs the server to log the IP address of the remote client rather than looking up and logging the DNS name. This will improve performance if DNS is off in the magnus.conf file.

flex-log

Records information about the request in a flexible, configurable format.

name

(optional) gives the name of a log file, which must have been given as a parameter to the init-clf Init function. If no name is given, the entry is recorded in the global log file.

iponly

The value is ignored

(optional) instructs the server to log the IP address of the remote client rather than looking up and logging the DNS name. This will improve performance if DNS is off in the magnus.conf file.

record-useragent

Records the client's IP address and user-agent header.

name

(optional) gives the name of a log file, which must have been given as a parameter to the init-clf Init function. If no name is given, the entry is recorded in the global log file.

Error Functions

Table 2-21 &nbsp&nbsp obj.conf Error functions

Function/Parameter

Description

send-error

Sends an HTML file to the client in place of a specific HTTP response status.

path

Specifies the full file system path of an HTML file to send to the client. The file is sent as text/html regardless of its name or actual type. If the file does not exist, the server sends a simple default error page.

reason

(optional) the text of one of the reason strings (such as "Unauthorized" or "Forbidden"). The string is not case sensitive.

code

(optional) a three-digit number representing the HTTP response status code, such as 401 or 407. This can be any HTTP response status code or reason phrase according to the HTTP specification.

qos-error

Returns an error page stating which quality of service limits caused the error and what the value of the QOS statistic was.

code

(optional) a three-digit number representing the HTTP response status code, such as 401 or 407. This can be any HTTP response status code or reason phrase according to the HTTP specification. The recommended value is 503.

password.conf

Purpose
By default, the web server prompts the administrator for the key database password before starting up. If you want the web server to be able to restart unattended, you need to save the password in a password.conf file. Be sure that your system is adequately protected so that this file and the key databases are not compromised.

Location
server_root/https-admserv/config

server_root/https-server_id/config

This file is not present by default. You must create it if you need it.

Syntax
PKCS#11_module_name:password

If you are using the internal PKCS#11 software encryption module that comes with the server, type the following:

Communicator_Cert_DB:password

If you are using a different PKCS#11 module, for example for hardware encryption or hardware accelerators, you will need to specify the name of the PKCS#11 module, followed by the password, for example:

Enables quality of service features, which let you set limits on server entities or view server statistics for bandwidth and connections.

qosmetricsinterval

Number of seconds

30

(optional) The interval during which the traffic is measured.

qosrecomputeinterval

Number of milliseconds

100

(optional) The period in which the bandwidth gets recomputed for all server entities.

legacyls

The id attribute of the listen socket for legacy (4.x) applications. This LS should contain only one CONNECTIONGROUP, which should be configured to only one VS, its defaultvs. All legacy applications must run on this virtual server.

Defines variables that can be given values in server.xml and referenced in obj.conf. No variables are present by default, but the most commonly defined variable is docroot, used in the document-root function in obj.conf. For more information, see Chapter 8 of the NSAPI Programmer's Guide for iPlanet Web Server.

LS

(none)

Defines a listen socket.

id

Internal name for the listen socket. Used in VS elements to define the listen socket(s) a virtual server is bound to.

ip

An IP address in dotted-pair or IPv6 notation. Can also be 0.0.0.0 for INADDR_ANY.

IP address of the listen socket. Configuring a listen socket to listen on 0.0.0.0 is required if more than one CONNECTIONGROUP is configured to it.

port

1 - 65535

Port number to create the listen socket on. On Unix, creating sockets that listen on ports 1 - 1024 requires superuser privileges. Configuring an SSL listen socket to listen on port 443 is recommended. Two different IP addresses can't use the same port.

security

on, off, yes, no, 1, 0

no

(optional) Determines whether the listen socket runs SSL. You can turn SSL2 or SSL3 on or off and set ciphers using an SSLPARAMS object in a CONNECTIONGROUP object.

acceptorthreads

1 - 1024

1

(optional) Number of acceptor threads for the listen socket.

family

inet, inet6, nca

inet

(optional) The socket family type. Use the value inet6 for IPv6 listen sockets. When using the value of inet6, IPv4 addresses are prefixed with ::ffff: in the log file. Specify nca to make use of the Solaris Network Cache and Accelerator.

blocking

on, off, yes, no, 1, 0

no

(optional) Determines whether the listen socket and the accepted socket are put in to blocking mode. Use of blocking mode may improve benchmark scores. Should be no for production environments.

CONNECTIONGROUP

SSLPARAMS

Defines MIME types.

id

Internal name for the connection group. Used in a VS element to define the connections used by the virtual server.

matchingip

An IP address in dotted-pair or IPv6 notation or the value default. Cannot be 0.0.0.0 for INADDR_ANY.

IP address that the associated virtual servers use. Must be default if the containing LS does not have ip=0.0.0.0.

If the containing LS has ip=0.0.0.0, can be a specific IP address or default. In this case, default means any IP addresses not specified in other LS or CONNECTIONGROUP elements.

defaultvs

The id attribute of the default virtual server for this particular connection group.

servername

Tells the server what to put in the host name section of any URLs it sends to the client. If you append a colon and port number, that port will be used in URLs the server sends to the client.

SSLPARAMS

(none)

Defines SSL parameters of a connection group. An SSLPARAMS element is required inside, and only allowed inside, a CONNECTIONGROUP element contained by a listen socket that has its security attribute set to on.

servercertnickname

The nickname of the server certificate in the certificate database or the PKCS#11 token. In the certificate, the name format is tokenname:nickname. Including the tokenname: part of the name in this attribute is optional.

ssl2

on, off, yes, no, 1, 0

no

(optional) Determines whether SSL2 is enabled.

ssl2ciphers

rc4, rc4export, rc2, rc2export, idea, des, desede3

none

(optional) A space-separated list of the SSL2 ciphers used, with the prefix + to enable or - to disable, for example +rc4.

The name of the default ACL file is generated.https-server_id.acl, and the file resides in the server_root/server_id/httpacl directory. To use this file, you must reference it in server.xml.

VSCLASS

VARS, VS, QOSPARAMS

Defines a virtual server class. Subelements must be defined in the order shown.

id

Virtual server class ID. This is a unique ID that allows lookup of a specific virtual server class.

objectfile

The file name of the obj.conf file for this class of virtual servers. Cannot be overridden in a VS element.

rootobject

default

(optional) Tells the server which object loaded from an obj.conf file is the default. The default object is expected to have all the name translation (NameTrans) directives for the virtual server. The Server Manager assumes the default to be the object named default.

acceptlanguage

on, off

off

(optional) If on, the server parses the Accept-Language header and sends an appropriate language version based on which language the client can accept. You should set this value to on only if the server supports multiple languages. Can be overridden in a VS element.

VS

VARS, QOSPARAMS, USERDB

Defines a virtual server. Subelements must be defined in the order shown.

id

Must begin with a letter

Virtual server ID. This is a unique ID that allows lookup of a specific virtual server. Can also be referred to as the variable $id in an obj.conf file.

connections

(optional) A space-separated list of CONNECTIONGROUPids that specify the connection(s) the virtual server uses. Required only for a VS that is not the defaultvs of a CONNECTIONGROUP.

urlhosts

A space-separated list of values allowed in the URLHost request header to select the current virtual server. Each VS that is configured to the same CONNECTIONGROUP must have a unique urlhosts value for that group.

mime

The id of the MIME element used by the virtual server.

state

on, off, disable

on

(optional) Determines whether a VS is active (on) or inactive (off, disable). When inactive, a VS does not service requests.

If a VS is disable, only the global server administrator can turn it on.

aclids

(optional) One or more id attributes of ACLFILE elements, separated by spaces. Specifies the ACL file(s) used by the virtual server.

(optional) If on, the server parses the Accept-Language header and sends an appropriate language version based on which language the client can accept. You should set this value to on only if the server supports multiple languages.

QOSPARAMS

(none)

Defines quality of service parameters of a SERVER, VSCLASS, or VS.

maxbps

Bytes per second

(optional) The maximum bandwidth limit for the SERVER, VSCLASS, or VS.

enforcebandwidth

yes, no, on, off, 1, 0

no

Specifies whether the bandwidth limit should be enforced or not.

maxconn

Number of connections

(optional) The maximum number of concurrent connections for the SERVER, VSCLASS, or VS.

enforceconnections

yes, no, on, off, 1, 0

no

Specifies whether the connection limit should be enforced or not.

USERDB

(none)

Defines the user database used by the virtual server.

id

The user database name in the virtual server's ACL file.

database

The user database name in the dbswitch.conf file.

basedn

(optional) Overrides the base DN lookup in the dbswitch.conf file.

certmaps

(optional) Specifies which certificate to LDAP entry mappings (defined in certmap.conf) to use. If not present, all mappings are used. All lookups based on mappings in certmap.conf are relative to the final base DN of the VS.

servers.lst

Purpose
Lists the iPlanet servers managed by the Administration Server. Do not modify this file.

(optional) Configures a specific native user/group database for authentication and role mapping. If this element is not specified, authentication is enabled using the native default authentication database.

authdb

The native authentication database.

class-loader

(none)

The class loader for the web application.

classpath

The classpath used by the class loader.

delegate

true, false

false

Specifies that the class loader for the virtual server or system is called first to load a class.

reload-interval

Number of seconds

30

The time interval within which the server checks for web applications being modified.

description

(none)

A description of a parameter. Used within an init-param element. iPlanet Web Server ignores this element.

filter, filter-mapping

Implements the Filter API from the Servlet 2.3 specification. Used within a web-app element.

Although iPlanet Web Server 6.0 supports only the Servlet 2.2 API in the web.xml file, this feature is available in the web-apps.xml file.

Except for their file location, filter and filter-mapping are as described in the Servlet 2.3 specification. For more information, see:

Configures form-based authentication for single sign-on across all web applications in a virtual server. If not present, the default virtual server level session manager is used.

cookie-name

A cookie name

iwsformloginid

The name of the cookie that tracks the session ID.

timeOut

Number of seconds

600 (10 minutes)

The session timeout.

init-param

param-name, param-value, description

Specifies an initialization parameter for the containing element. The attributes of init-param depend on the object referenced by the containing element.

For example, if the containing element is session-manager and the session manager is IWSSessionManager, the attributes of init-param are the initialization parameters of IWSSessionManager.

jsp-servlet

init-param

Configures JSP compilation behavior. Set the initialization parameter use-precompiled to true to tell iPlanet Web Server that all JSPs in a virtual server are precompiled. See the iPlanet Web Server Programmer's Guide to Servlets for more information about jsp-servlet initialization parameters.

enable

true, false

true

Enables JSP.

interval

Number of seconds

0

The interval between flushes.

param-name

(none)

The name of a parameter. Used within an init-param element.

param-value

(none)

The value of a parameter. Used within an init-param element.

parameter-encoding

(none)

Advises the web server on how to decode parameters from forms.

enc

none, auto, or a specific encoding such as utf8 or Shift_JIS

auto

encoding: uses the specified encoding.

none: uses the system default encoding.

auto: tries to figure out the encoding from, in order, 1) the charset , 2) the parameterEncoding attribute, then 3) a hidden form field defined in form-hint-field. Otherwise same as none.

form-hint-field

j_encoding

The name of the hidden field in the form that specifies the encoding.

response-buffer

(none)

Configures the initial and default size of the HTTP servlet's response buffer.

flush-timeout

Number of seconds

0

Forces the stream to flush the data if the specified number of seconds has elapsed since the last flush. If set to 0 (the default) or a negative number, the output stream doesn't force a flush unless the buffer is full.

size

Number of bytes

8192

The buffer size.

response-cookie

(none)

Tells the server to respond with a specific cookie version.

version

A cookie version number

0

The cookie version.

role-mapping

(none)

Maps role-name values from web.xml to LDAP users or groups.

map-to

user, group

group

Specifies whether to map role-name values from web.xml to LDAP users or groups.

session-cookie

(none)

Sets parameters for the session cookie.

domain

A domain name

(none)

If this attribute is present, its value is tagged onto the cookie. There is no default value.

is-secure

true, false

false

If set to true, the server sends the secure attribute in the session cookie if the request came in a secure connection. The default is false.