Chapter 2   Configuration Files


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.

For information about configuration file changes since iPlanet Web Server 4.x, see Appendix A "Configuration Changes Between iWS 4.x and 6.0."

The following configuration files are described in alphabetical order:

• backups.conf

• certmap.conf

• cjava.properties

• cluster.xml

• contexts.properties

• cron.conf

• dbswitch.conf

• iwsstats.xml

• jvm12.conf

• magnus.conf

• mime.types

• ns-cron.conf

• nsfc.conf

• obj.conf

• password.conf

• rules.properties

• server.xml

• servers.lst

• servlets.properties

• web.xml

• web-apps.xml

backups.conf

---

Purpose
Tracks backups of configuration files.

Location
server_root/https-admserv/conf_bk

server_root/https-server_id/conf_bk

Syntax
file:path_to_backup:version:timestamp:original_path
...

backup_version_history
...

Contents
backups.conf:Version 4.0

https-admserv.acl:httpacl/genwork.https-admserv.acl:2:952103058:httpacl/genwork.https-admserv.acl
magnus.conf:https-admserv/conf_bk/magnus.conf:2:952103070:https-admserv/config/magnus.conf
obj.conf:https-admserv/conf_bk/obj.conf:2:952103060:https-admserv/config/obj.conf
mime.types:https-admserv/conf_bk/mime.types:2:952103060:https-admserv/config/mime.types
jvm12.conf:https-admserv/conf_bk/jvm12.conf:2:952103068:https-admserv/config/jvm12.conf
servlets.properties:https-admserv/conf_bk/servlets.properties:2:952103068:https-admserv/config/servlets.properties
contexts.properties:https-admserv/conf_bk/contexts.properties:2:952103068:https-admserv/config/contexts.properties
rules.properties:https-admserv/conf_bk/rules.properties:2:952103068:https-admserv/config/rules.properties

952103058:https-admserv.acl/1::
952103060:https-admserv.acl/1:magnus.conf/1::
952103060:https-admserv.acl/1:magnus.conf/1:obj.conf/1::
952103060:https-admserv.acl/1:magnus.conf/1:obj.conf/1:mime.types/1::
952103068:https-admserv.acl/1:magnus.conf/1:obj.conf/1:mime.types/1:jvm12.conf/1::
952103068:https-admserv.acl/1:magnus.conf/1:obj.conf/1:mime.types/1:jvm12.conf/1:servlets.properties/1::
952103068:https-admserv.acl/1:magnus.conf/1:obj.conf/1:mime.types/1:jvm12.conf/1:servlets.properties/1:
   contexts.properties/1::
952103068:https-admserv.acl/1:magnus.conf/1:obj.conf/1:mime.types/1:jvm12.conf/1:servlets.properties/1:
   contexts.properties/1:rules.properties/1::
952103068:https-admserv.acl/2:magnus.conf/2:obj.conf/2:mime.types/2:jvm12.conf/2:servlets.properties/2:
   contexts.properties/2:rules.properties/2::Added ExtraPath for Java.--EOF--

Table 2-1    backup.conf

Item	Description
file	The name of the file for which backups are made. Examples are server.xml, obj.conf, and so on.
path_to_backup	The path to the backup of the file.
version	The version of the file.
timestamp	The timestamp of the backup.
original_path	The path to the file that is backed up.
backup_version_history	A version history listing for the files.

certmap.conf

---

Purpose
Configures how a certificate, designated by name, is mapped to an LDAP entry, designated by issuerDN.

Location
server_root/bin/https/install/misc

server_root/userdb

Syntax
certmap name issuerDN
name:property1 [value1]
name:property2 [value2]
...

The default certificate is named default, and the default issuerDN is also named default. Therefore, the first certmap defined in the file must be as follows:

certmap default default

You can use # at the beginning of a line to indicate a comment.

See Also
iPlanet Web Server Administrator's Guide

Table 2-2    certmap.conf

Property	Allowed Values	Default Value	Description
DNComps	See Description	Commented out	Used to form the base DN for performing an LDAP search while mapping the cert to a user entry. Values are as follows: Commented out: takes the user's DN from the cert as is. Empty: searches the entire LDAP tree (DN == suffix). Comma separated attributes: forms the DN.
FilterComps	See Description	Commented out	Used to form the filter for performing an LDAP search while mapping the cert to a user entry. Values are as follows: Commented out or empty: sets the filter to "objectclass=*". Comma separated attributes: forms the filter.
verifycert	on or off	off (commented out)	Specifies whether certificates are verified.
CmapLdapAttr	LDAP attribute name	certSubjectDN (commented out)	Specifies the name of the attribute in the LDAP database that contains the DN of the certificate.
library	Path to shared lib or dll	None	Specifies the library path for custom certificate mapping code.
InitFn	Name of initialization function	None	Specifies the initialization function in the certificate mapping code referenced by library.

cjava.properties

---

Purpose
Defines servlet and JVM error messages.

Location
server_root/bin/https/res

Syntax
error = message

Errors are not listed here because you should not edit them. You can edit the messages, but this is not recommended.

cluster.xml

---

Purpose
Defines a cluster of servers for backups and failover in a server farm. This file is present only if at least one cluster has been defined.

Location
server_root/https-admserv/config

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

<ELEMENT attribute="value" attribute="value" ... >
   <SUBELEMENT attribute="value" attribute="value" ... />
</ELEMENT>

In Table 2-3, elements are in bold to distinguish them from attributes.

See Also
iPlanet Web Server Administrator's Guide

Table 2-3    cluster.xml

Element/Attribute	Allowed Subelements or Values	Description
CLUSTER	MASTER	Defines a cluster of web servers.
id	A text string	The ID of the cluster.
MASTER	SLAVE	Defines the master server in the cluster.
id	A text string	The ID of the master.
hostname	Usually the server_id	The host name of the master.
adminport		The administration port of the master.
instance	https-server_id	The name of the server instance on the master.
SLAVE	(none)	Defines a slave server in the cluster.
id	A text string	The ID of the slave.
hostname	Usually the server_id	The host name of the slave.
adminport		The administration port of the slave.
instance	https-server_id	The name of the server instance on the slave.
protocol	http, https	The protocol used for communication with the client.
substitute	A master or slave id or null	The ID of a substitute server if this server is down.

contexts.properties

---

Purpose
Provided for backward compatibility with iPlanet Web Server 4.x. Using web-apps.xml instead to configure servlets is recommended.

Defines contexts, which allow multiple servlets to exchange data and access each other's fields. Contexts are useful for defining virtual servers or for code isolation. The default context is global. In iPlanet Web Server 6.0, supported for the default virtual server only.

Location
server_root/https-admserv/config

server_root/https-admserv/conf_bk

server_root/https-server_id/config

server_root/https-server_id/conf_bk

Syntax
context.context_name.property=value

Table 2-4 lists the properties and their possible values.

See Also
Programmer's Guide to Servlets for iPlanet Web Server

The server.xml and web-apps.xml files

Appendix A "Configuration Changes Between iWS 4.x and 6.0"

The Servlet 2.2 API specification at:

http://java.sun.com/products/servlet/index.html

Table 2-4    contexts.properties

Property	Allowed Value(s)	Default Value	Description
sessionmgr	A session manager object	com.iplanet. server.http. session. IWSSessionMan-ager (all on one line, no dash)	The name of the session manager for the context. Some session managers, such as MMapSessionManager, can only be instantiated once within the server.
sessionmgr.initArgs	Comma separated name=value pairs	Depends on session manager	A list of parameters specific to the session manager. For more information, see the Programmer's Guide to Servlets for iPlanet Web Server.
initArgs	Comma separated name=value pairs	initial=0	A list of additional context attributes.
respondCookieVersion	A cookie version number	0	Tells the server whether to respond with a specific cookie version.
tempDir	A path	/tmp	Sets up the Servlet API 2.2 property for the temporary directory. Use forward slashes only.
reloadInterval	Number of seconds	5	The time interval within which the server checks for JSP and servlet files being modified. Applies to the global context only.
bufferSize	Number of bytes	4096	The initial HTTP output stream buffer size.
docRoot	A path with forward slashes	Web server's document root	The document root for the context. If docRoot is not specified, the web server's document root is used.
inputStreamLengthCheck	true, false	true	Tells a ServletInputStream to stop reading data when Content-Length number of bytes are read.
outputStreamFlushTimer	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, this property is ignored.
uri	A URI	/	An additional URI prefix which serves as a context base.
authdb	A database name	default	The name of the authentication database. This database must also be defined in the server.xml file in the database attribute of a USERDB element, and in the dbswitch.conf file.
classpath	A path		The global classpath for this context.
singleClassLoader	true, false	false	Tells the servlet engine whether to use a single class loader for all servlets in the context.
serverName	A server instance name		Used to specify the server instance that runs the servlets in the context.
contentTypeIgnoreFromSSI	true, false	true	Ignores setContentType when invoked from SSI if true.
parameterEncoding	none, auto, responseCT, or a specific encoding such as utf8 or Shift_JIS	auto	Advises the web server on how to decode parameters from forms: 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, such as j_encoding. Otherwise same as none. responseCT: tries to figure out the encoding from the response content type if it is available, otherwise, same as none.
isModifiedCheckAggressive	true, false	false	Determines whether the servlet loader aggressively checks dependencies to reload modified servlets.

cron.conf

---

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.

Location
server_root/https-admserv/config

Syntax
<Object name=name>
Command "command"
User user
Time nn:nn
Days day day ...
</Object>

The following is an example of a cron.conf file that manages log rotation.

<Object name=https-server_id_rotatelg0>
Command "server_root/bin/https/httpadmin/bin/rotlog https-server_id"
User LocalSystem
Time 03:00
Days Sun Mon Tue Wed Thu Fri Sat
</Object>

Table 2-5    cron.conf

Directive	Allowed Values	Description
name		An object name for the maintenance activity.
Command		The command or script that performs the maintenance activity. This can be any command or executable file.
User		The name of the system user.
Time	A 24-hour time	The time of day at which the activity takes place.
Days	Sun, Mon, Tue, Wed, Thu, Fri, Sat	The days of the week on which the activity takes place.

dbswitch.conf

---

Purpose
Specifies the LDAP directory that iPlanet Web Server uses.

Location
server_root/userdb

Syntax
directory name LDAP_URL
name:property1 [value1]
name:property2 [value2]
...

The default contents of this file are as follows:

directory default null:///none

Edit the file as follows for anonymous binding over SSL:

directory default ldaps://directory.netscape.com:636:/dc%3Dcom

Edit the file as follows for anonymous binding not over SSL:

directory default ldap://directory.netscape.com:389:/dc%3Dcom

See Also
NSAPI Programmer's Guide for iPlanet Web Server, Chapter 8

Table 2-6    dbswitch.conf

Property	Allowed Values	Default Value	Description
nsessions	A positive integer	8	The number of LDAP connections for the database.
dyngroups	off, on, recursive	on	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:

<ELEMENT attribute="value" attribute="value" ... >
   <SUBELEMENT attribute="value" attribute="value" ... />
</ELEMENT>

In Table 2-7, elements are in bold to distinguish them from attributes.

See Also
NSAPI Programmer's Guide for iPlanet Web Server, Chapter 3

Table 2-7    iwsstats.xml

Element/Attribute	Subelements or Values	Description
stats	server	The top-level statistics element. All stats-xml statistics information is contained within this element.
enabled	0 (off), 1 (on)	Indicates whether statistics collection is enabled (on).
versionMajor		The major version of the statistics format. In this version of iPlanet Web Server, the value is frozen at 1.
versionMinor		The minor version of the statistics format.
server	connection-queue, thread-pool, profile, process, virtual-server	Describes a server instance.
id		The server instance ID (for example https-www.iplanet.com).
versionServer		A string describing the iPlanet Web Server version (for example iPlanet-WebServer-Enterprise/6.0 B1-12/20/2000 13:56 (SunOS DOMESTIC)).
timeStarted	A number of seconds after 00:00:00 1/1/1970	The time this server instance was started.
secondsRunning		The number of seconds since this server instance started.
ticksPerSecond		The number of ticks in a second. This value is system-dependent.
maxProcs		The maximum number of processes.
maxThreads		The maximum number of request processing threads.
maxVirtualServers		The maximum number of virtual servers tracked.
flagProfilingEnabled	0 (off), 1 (on)	Indicates whether NSAPI performance profiling is enabled (on).
flagVirtualServer Overflow	0 (no), 1 (yes)	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.
id		The NSAPI performance profile bucket ID.
name		The symbolic name of the NSAPI performance profile bucket.
description		The description of the NSAPI performance profile bucket.
process	connection-queue- bucket, thread-pool-bucket, dns-bucket, keepalive-bucket, cache-bucket, thread	Describes a single server process within a server instance.
pid		The operating system process identifier that uniquely identifies this process.
mode	unknown, active	Displays active when this process is active.
timeStarted	A number of seconds after 00:00:00 1/1/1970	The time this process was started.
countConfigurations		The number of times a configuration has been loaded, or 0 if this information is not available.
connection-queue-bucket	(none)	Tracks statistics pertaining to a specific connection-queue.
connection-queue		The ID of a connection-queue element.
countTotalConnections		The total number of new connections that have been accepted.
countQueued		The number of connections currently enqueued.
peakQueued		The largest number of connections that have been in the queue simultaneously.
maxQueued		The maximum number of connections that can be in the queue.
countOverflows		The number of times the queue has been too full to accommodate a connection.
countTotalQueued		The total number of connections that have been queued. A given connection may be queued multiple times, so countTotalQueued may be greater than or equal to countTotalConnections.
ticksTotalQueued	A tick is a system-dependent unit of time; see ticksPerSecond	The total number of ticks connections have spent in the queue.
thread-pool-bucket	(none)	Tracks statistics pertaining to a specific thread-pool.
thread-pool		The ID of a thread-pool element.
countThreadsIdle		The number of request processing threads currently idle.
countThreads		The number of request processing threads.
maxThreads		The maximum number of request processing threads that can exist concurrently.
countQueued		The number of requests queued for processing by this thread pool.
peakQueued		The largest number of requests that have been in the queue simultaneously.
maxQueued		The maximum number of requests that can be in the queue.
dns-bucket	(none)	Tracks DNS (Domain Name System) statistics.
flagCacheEnabled	0 (off), 1 (on)	Indicates whether the DNS cache is enabled (on).
countCacheEntries		The number of DNS entries presently in the cache.
maxCacheEntries		The maximum number of DNS entries the cache can accommodate.
countCacheHits		The number of times a DNS cache lookup has succeeded.
countCacheMisses		The number of times a DNS cache lookup has failed.
flagAsyncEnabled	0 (off), 1 (on)	Indicates whether asynchronous DNS lookups are enabled (on).
countAsyncNameLookups		The total number of asynchronous DNS name lookups performed.
countAsyncAddrLookups		The total number of asynchronous DNS address lookups performed.
countAsyncLookups InProgress		The number of asynchronous DNS lookups currently in progress.
keepalive-bucket	(none)	Tracks keepalive (persistent connection) statistics.
countConnections		The number of connections currently in keepalive mode.
maxConnections		The maximum number of simultaneous keepalive connections.
countHits		The total number of times connections in keepalive mode have subsequently made a valid request.
countFlushes		The number of times keepalive connections have been closed by the server.
secondsTimeout		The number of seconds before the server closes an idle keepalive connection.
cache-bucket	(none)	Tracks file cache (NSFC) statistics.
flagEnabled	0 (off), 1 (on)	Indicates whether the file cache is enabled (on).
secondsMaxAge	Number of seconds	The maximum age of a file cache entry.
countEntries		The number of entries currently in the file cache.
maxEntries		The maximum number of cache entries the file cache can accommodate simultaneously.
countOpenEntries		The number of entries associated with an open file.
maxOpenEntries		The maximum number of cache entries associated with an open file that the file cache can accommodate simultaneously.
sizeHeapCache	Number of bytes	The amount of heap used by cached file content.
maxHeapCacheSize	Number of bytes	The maximum amount of heap the file cache uses for cached file content.
sizeMmapCache	Number of bytes	The amount of address space used by memory mapped file content.
maxMmapCacheSize	Number of bytes	The maximum amount of address space that the file cache uses for memory mapped file content.
countHits		The number of times a cache entry lookup has succeeded.
countMisses		The number of times a cache entry lookup has failed.
countInfoHits		The number of times a file information lookup has succeeded.
countInfoMisses		The number of times a file information lookup has failed.
countContentHits		The the number of times a file content lookup has succeeded.
countContentMisses		The the number of times a file content lookup has failed.
thread	request-bucket, profile-bucket	Describes a request processing thread.
mode	unknown, idle, DNS, request, processing, response, updating	The thread's last known status.
timeStarted	A number of seconds after 00:00:00 1/1/1970	The time this thread was started.
connection-queue		The ID of the connection-queue the thread is servicing.
virtual-server		The ID of the virtual-server the thread most recently serviced.
virtual-server	request-bucket, profile-bucket	Describes a virtual server.
id		The virtual server ID.
mode	unknown, active	Displays active when this virtual server is active.
hosts		The software virtual server hostnames serviced by this virtual server (for example www.foo.com foo.com foo.isp.com).
interfaces		The interfaces (listen sockets) the virtual server is configured for (for example 192.168.1.2:80 192.168.1.2:443).
request-bucket	(none)	Tracks request-related statistics.
method		The method (for example GET) of the most recently serviced request.
uri		The URI (for example /index.html) of the most recently serviced request.
countRequests		The number of requests serviced.
countBytesReceived		The number of bytes received, or 0 if this information is not available.
countBytesTransmitted		The number of bytes transmitted, or 0 if this information is not available.
rateBytesTransmitted	Bytes per second	The rate at which data was transmitted over some server-defined interval, or 0 if this information is not available.
countOpenConnections		The number of open connections, or 0 if this information is not available.
count2xx		The number of 200-level responses sent.
count3xx		The number of 300-level responses sent.
count4xx		The number of 400-level responses sent.
count5xx		The number of 500-level responses sent.
countOther		The number of responses sent that were not 200, 300, 400, or 500 level.
count200		The number of 200 responses sent.
count302		The number of 302 responses sent.
count304		The number of 304 responses sent.
count400		The number of 400 responses sent.
count401		The number of 401 responses sent.
count403		The number of 403 responses sent.
count404		The number of 404 responses sent.
count503		The number of 503 responses sent.
profile-bucket	(none)	Tracks statistics pertaining to a profile element.
profile		The ID of a profile element.
countCalls		The number of calls to NSAPI SAFs.
countRequests		The number of requests processed.
ticksDispatch	A tick is a system-dependent unit of time; see ticksPerSecond	The number of ticks spent dispatching requests.
ticksFunction	A tick is a system-dependent unit of time; see ticksPerSecond	The number of ticks spent in NSAPI SAFs.

jvm12.conf

---

Purpose
Allows you to change Java Virtual Machine settings.

Location
server_root/https-admserv/config

server_root/https-admserv/conf_bk

server_root/https-server_id/config

server_root/https-server_id/conf_bk

Syntax
[JVMConfig]
setting=value
...

See Also
Programmer's Guide to Servlets for iPlanet Web Server

Table 2-8    jvm12.conf

Setting	Allowed Values	Default Value	Description
variable	Any JVM environment variable		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.
jvm.trace		5	Determines the trace level. For servlet and JSP debugging, the recommended level is 7. Level 5 displays servlet engine messages. Level 6 displays servlet and JSP engine messages. Level 7 displays these and other exceptions in the browser.
jvm.allowExit	0 (off), 1 (on)	0	Enables or disables exit from the process.
java.compiler		NONE	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.

magnus.conf

---

Purpose
Contains global variable settings that affect server functioning. This file is read only at server start-up.

Location
server_root/https-admserv/config

server_root/https-admserv/conf_bk

server_root/https-server_id/config

server_root/https-server_id/conf_bk

Syntax
Init functions have the following syntax:

Init fn=function param1="value1" ...paramN="valueN"

In Table 2-9, functions are in bold to distinguish them from parameters.

Directives have the following syntax:

directive value

See Also
NSAPI Programmer's Guide for iPlanet Web Server, Chapter 7

Appendix A "Configuration Changes Between iWS 4.x and 6.0"

Init Functions

Table 2-9    magnus.conf Init functions

Function/Parameter	Allowed Values	Default Value	Description
cindex-init			Changes the default characteristics for fancy indexing.
opts	s	(None)	(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.
format	Format for the UNIX function strftime()	%d-%b-%Y %H:%M	(optional, iPlanet Web Server 4.x only) Determines the format of the last modified date display.
ignore	Wildcard pattern	.*	(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 31536000 seconds (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: access="/logdir/access"
format.logFileName			Specifies the format of each log entry in the log file. See the NSAPI Programmer's Guide for iPlanet Web Server for more information.
buffer-size	Number of bytes	8192	Specifies the size of the global log buffer.
num-buffers		1000	Specifies the maximum number of logging buffers to use.
flex-rotate-init			Enables rotation for logs.
rotate-start	A 4-digit string indicating the time in 24-hour format		Indicates the time to start rotation. For example, 0900 indicates 9 am while 1800 indicates 9 pm.
rotate-interval	Number of minutes		Indicates the number of minutes to elapse between each log rotation.
rotate-access	yes, no	yes	(optional) determines whether common-log, flex-log, and record-useragent logs are rotated.
rotate-error	yes, no	yes	(optional) determines whether error logs are rotated.
rotate-callback	A path		(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. For information about installing an suid Cgistub, see Chapter 1 "Overview."
env-variable			(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    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).
UseOutputStreamSize	Any number of bytes	8192 (8 KB)	Determines the default output stream buffer size for the net_read and netbuf_grab NSAPI functions.
User	A login name, 8 characters or less	(none)	(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.

Location
server_root/https-admserv/config

server_root/https-admserv/conf_bk

server_root/https-server_id/config

server_root/https-server_id/conf_bk

server_root/bin/https/install/misc

Syntax
type=type/subtype exts=ext1,ext2,...
...
enc=subtype exts=ext1,ext2,...
...

See Also
NSAPI Programmer's Guide for iPlanet Web Server

Table 2-11    mime.types

Directive	Allowed Values	Description
type	application, image, text, video, audio, perf, x-world, x-conference, magnus-internal	The basic type of content.
subtype		The more specific type of content. For example, in text/html, the subtype is html.
ext1,ext2,...	A comma separated list of file extensions	The file extension(s) for the type. For example, for text/html, the file extensions are htm,html.

ns-cron.conf

---

Purpose
Activates or deactivates the cron.conf file.

Location
server_root/https-admserv/config

Contents
ConfFile server_root/https-admserv/config/cron.conf
Dir /tmp
Status on

Table 2-12    ns-cron.conf

Directive	Allowed Values	Default Value	Description
ConfFile	A path		The location of the cron.conf file.
Dir	A path		The location of a temporary directory.
Status	on, off	on	The status of the cron.conf file: on is activated, off is deactivated.

nsfc.conf

---

Purpose
Sets file cache parameters. This file is present only if file cache parameters have been changed from their defaults.

Location
server_root/https-admserv/config

Syntax
parameter=value

See Also
Performance Tuning, Sizing, and Scaling Guide for iPlanet Web Server

Table 2-13    nsfc.conf

Parameter	Allowed Values	Default Value	Description
FileCacheEnable	on, off	on	Enables the file cache.
CacheFileContent	on, off	on	Enables caching of file contents as well as file information for files smaller than MediumFileSizeLimit (smaller than SmallFileSizeLimit if TransmitFiles is on).
MaxAge	Number of seconds	30	The maximum age of a valid cache entry. This setting controls how long cached information is used once a file has been cached. An entry older than MaxAge is replaced by a new entry for the same file.
MediumFileSizeLimit	Limited by available memory	537600 (525K)	(Unix only) Maximum size of a file that can be cached as a memory-mapped file (if TransmitFiles is off).
MediumFileSpace	Limited by available memory	10485760 (10 M)	Total size of all files that are cached as memory-mapped files (if TransmitFiles is off).
SmallFileSizeLimit	Limited by available memory	2048 (2K)	(Unix only) Maximum size of a file that can be read into memory.
SmallFileSpace	Limited by available memory	1048576 (Unix, 1 M), 0 (NT)	Total size of all files that are read into memory.
TransmitFiles	on, off	on (NT), off (Unix)	Enables use of the TransmitFile system call. Not supported on IRIX, Compaq, Solaris, or Linux.
MaxFiles		1024	Maximum number of files in the file cache.
HashInitSize	Limited by available memory	0	Initial number of hash buckets. If 0, the number of hash buckets is dynamically determined as 2 * MaxFiles + 1.
CopyFiles	on, off	on	(NT only) Prevents sharing violations by copying files to a temporary directory.
TempDir	A path	system_temp/server_id	Specifies a temporary directory for the file cache if CopyFiles is on.

obj.conf

---

Purpose
Determines client responses to requests. Each virtual server can have its own obj.conf file.

Location
server_root/https-admserv/config

server_root/https-admserv/conf_bk

server_root/https-server_id/config

server_root/https-server_id/conf_bk

Syntax
directive fn=function param1="value1" ...paramN="valueN"

An object tag's directives are executed only if a NameTrans directive redirects the flow of control to the tag via a name/name or root/ppath match. An object tag follows this syntax:

NameTrans fn=function name="name"|root="path"

<object name="name"|ppath="path">
directive1
directive2
...
</object>

---

Note	In iPlanet Web Server 6.0, Init directives have been moved to the magnus.conf file.

---

In Table 2-15 through Table 2-21, functions are in bold to distinguish them from parameters.

See Also
NSAPI Programmer's Guide for iPlanet Web Server, Chapters 2-3.

For how to create your own functions, see NSAPI Programmer's Guide for iPlanet Web Server, Chapters 4-6.

Appendix A "Configuration Changes Between iWS 4.x and 6.0"

Table 2-14    obj.conf

Directive	Description
AuthTrans	Verifies any authorization information (normally sent in the Authorization header) provided in the HTTP request and translates it into a user or a group.
NameTrans	Translates the URL specified in the request from a logical URL to a physical file system path for the requested resource. This may also result in redirection to another site.
PathCheck	Performs tests on the physical path determined by the NameTrans step. In general, these tests determine whether the path is valid and whether the client is allowed to access the requested resource.
ObjectType	Determines the MIME (Multi-purpose Internet Mail Encoding) type of the requested resource.
Service	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.

For more information about performance buckets, see the Performance Tuning, Sizing, and Scaling Guide for iPlanet Web Server.

AuthTrans Functions

Table 2-15    obj.conf AuthTrans functions

Function/Parameter	Allowed Values	Default Value	Description
basic-auth			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    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    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.
find-pathinfo			Locates extra path info beyond the file name for the PATH_INFO CGI environment variable.
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 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    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    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.
UseOutputStreamSize	Number of bytes	8192	(optional) determines the default output stream buffer size for the net_read and netbuf_grab NSAPI functions.
flushTimer	Number of milli- seconds	3000	(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.
ChunkedRequestBufferSize	Number of bytes	8192	(optional) determines the default buffer size for "un-chunking" request data.
ChunkedRequestTimeout	Number of seconds	60	(optional) determines the default timeout, in seconds, for "un-chunking" request data.
add-footer			Appends a footer specified by a filename or URL to a an HTML file.
file			(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.
timefmt			(optional) a time format string for :LASTMOD:. If timefmt is not provided, :LASTMOD: is not replaced with the time. For details about time formats, see the NSAPI Programmer's Guide for iPlanet Web Server.
imagemap			Handles server-side image maps.
index-common			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    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    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:

internal:password

See Also
iPlanet Web Server Administrator's Guide

rules.properties

---

Purpose
Provided for backward compatibility with iPlanet Web Server 4.x. Using web.xml instead to configure servlets is recommended.

Defines servlet virtual path translations. In iPlanet Web Server 6.0, supported for the default virtual server only.

Location
server_root/https-admserv/config

server_root/https-admserv/conf_bk

server_root/https-server_id/config

server_root/https-server_id/conf_bk

Syntax
virtual_path=servlet_name

The URL http://server_id/virtual_path invokes the servlet that is given the name servlet_name in the servlets.properties file.

The virtual_path can be a regular expression. For example, the following expression tells the server to run the wasp servlet whenever there is a request for a URL such as /my/xxx.foo:

@.*[.]foo$=wasp

See Also
Programmer's Guide to Servlets for iPlanet Web Server

The web.xml file

Appendix A "Configuration Changes Between iWS 4.x and 6.0"

The Servlet 2.2 API specification at:

http://java.sun.com/products/servlet/index.html

server.xml

---

Purpose
Defines listen sockets and virtual servers.

Location
server_root/https-admserv/config

server_root/https-admserv/conf_bk

server_root/https-server_id/config

server_root/https-server_id/conf_bk

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

<ELEMENT attribute="value" attribute="value" ... >
   <SUBELEMENT attribute="value" attribute="value" ... />
</ELEMENT>

In Table 2-22, elements are in bold to distinguish them from attributes, and default values are assumed if the specified attributes are not present.

See Also
NSAPI Programmer's Guide for iPlanet Web Server, Chapter 8

Table 2-22    server.xml

Element/Attribute	Allowed Subelements or Values	Default Value	Description
SERVER	VARS, LS, MIME, ACLFILE, VSCLASS, QOSPARAMS		Defines a server. Subelements must be defined in the order shown.
qosactive	yes, no, on, off, 1, 0	no	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.
VARS	(no subelements; commonly defined variables are docroot, adminusers, webapps_file, webapps_enable, accesslog, user, group, chroot, dir, and nice)		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.
ssl3	on, off, yes, no, 1, 0	yes	(optional) Determines whether SSL3 is enabled.
ssl3tlsciphers	rsa_rc4_128_md5, rsa3des_sha, rsa_des_sha, rsa_rc4_40_md5, rsa_rc2_40_md5, rsa_null_md5, rsa_des_56_sha, rsa_rc4_56_sha	none	(optional) A space-separated list of the SSL3 and TLS ciphers used, with the prefix + to enable or - to disable, for example +rsa_des_sha.
tls	on, off, yes, no, 1, 0	no	(optional) Determines whether TLS is enabled.
tlsrollback	on, off, yes, no, 1, 0	on	(optional) Determines whether TLS rollback is enabled.
clientauth	on, off, yes, no, 1, 0	no	(optional) Determines whether SSL3 client authentication is performed on every request, independent of ACL-based access control.
MIME	(none)		Defines MIME types.
id			Internal name for the MIME types listing. Used in a VS element to define the MIME types used by the virtual server.
file			The name of a MIME types file. For information about the format of this file, see Appendix B of the NSAPI Programmer's Guide for iPlanet Web Server.
ACLFILE	(none)		References one or more ACL files.
id			Internal name for the ACL file listing. Used in a VS element to define the ACL file used by the virtual server.
file			A space-separated list of ACL files. Each ACL file must have a unique name. For information about the format of an ACL file, see the Administrator's Guide for iPlanet Web Server. 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 CONNECTIONGROUP ids 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.
errorlog			(optional) Specifies a log file for virtual-server-specific error messages.
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.
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.

Location
server_root/https-admserv/config

Syntax
protocol:server

Table 2-23    servers.lst

Directive	Allowed Values	Default Value	Description
protocol	http, https	https	A communication protocol.
server	An iPlanet server name	Web Server, Enterprise Edition	An iPlanet server that is managed by the Administration Server.

servlets.properties

---

Purpose
Provided for backward compatibility with iPlanet Web Server 4.x. Using web-apps.xml instead to configure servlets is recommended.

Defines global servlet settings and the list of servlets in the system. In iPlanet Web Server 6.0, supported for the default virtual server only.

Location
server_root/https-admserv/config

server_root/https-admserv/conf_bk

server_root/https-server_id/config

server_root/https-server_id/conf_bk

Syntax
servlets.property=value

servlet.servlet_name.property=value

The servlet properties, described in Table 2-24, apply only to the named servlet. The servlets properties, described in Table 2-25, apply to all servlets.

See Also
Programmer's Guide to Servlets for iPlanet Web Server

The server.xml and web-apps.xml files

Appendix A "Configuration Changes Between iWS 4.x and 6.0"

The Servlet 2.2 API specification at:

http://java.sun.com/products/servlet/index.html

Table 2-24    servlets.properties individual (servlet) properties

Property	Allowed Values	Default Value	Description
code	Class or class file name		The name of the class or class file for the servlet. The .class extension is optional.
context	Context name		The context to which the servlet belongs. You change context settings using the contexts.properties file.
classpath	URLs or paths with forward slashes only		The URL or path to the directory where classes are located or the list of directories (but not URLs) or jar files, like the CLASSPATH environment variable.
initArgs	Comma separated name=value pairs		List of name=value pairs which can be accessed by the servlet using the servlet API calls.
startup	true, false	true	Determines whether the servlet is started up automatically when the web server is started up.

Table 2-25    servlets.properties general (servlets) properties

Property	Allowed Values	Default Value	Description
config.docRoot	A path with forward slashes	Web server's document root	The document root for all servlets. If docRoot is not specified, the web server's document root is used.
config.realPathFromRequest	true, false	false	If true, calculates getRealPath based on the docRoot of the servlets. If false, tries to go through normal NSAPI steps.
config.respondCookieVersion	A cookie version number	0	Tells the server whether to respond with a specific cookie version.
config.sessionExpireOnClose	true, false	false	Tells the server to mark session cookies as directed to expire when the user quits the browser.
sessionmgr	A session manager object	com.iplanet. server.http. session. IWSSessionMan-ager (all on one line, no dash)	The name of the session manager for the servlet. Some session managers, such as MMapSessionManager, can only be instantiated once within the server.
config.reloadInterval	Number of seconds	5	The time interval within which the server checks for JSP and servlet files being modified.
config.bufferSize	Number of bytes	4096	The initial HTTP output stream buffer size.
startup	true, false	true	Determines whether all servlets are started up automatically when the web server is started up. Using the servlet.startup property instead is recommended.

web.xml

---

Purpose
Defines a web application, including its servlets, URL mappings, security constraints, and so on. Each web application has its own web.xml file.

Location
The location is application-specific and user-defined.

Syntax
Refer to the .DTD file at:

http://java.sun.com/j2ee/dtds/web-app_2_2.dtd

or at:

server_root/bin/https/dtds/web-app_2_2.dtd

See Also
iPlanet Web Server Programmer's Guide to Servlets

The Servlet 2.2 API specification at:

http://java.sun.com/products/servlet/index.html

The JSP 1.1 specification at:

http://java.sun.com/products/jsp/download.html

There is no listing of this file's elements and attributes because the Servlet 2.2 API specification describes them.

web-apps.xml

---

Purpose
Defines a set of web applications hosted by a virtual server. Each virtual server can have its own web-apps.xml file.

Location
This is the location for the default file only.

server_root/https-server_id/config

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

<ELEMENT attribute="value" attribute="value" ... >
   <SUBELEMENT attribute="value" attribute="value" ... />
</ELEMENT>

In Table 2-26, elements are in bold to distinguish them from attributes, and default values are assumed if the specified attributes are not present.

See Also
iPlanet Web Server Programmer's Guide to Servlets

The Servlet 2.2 API specification at:

http://java.sun.com/products/servlet/index.html

The JSP 1.1 specification at:

http://java.sun.com/products/jsp/download.html

Table 2-26    web-apps.xml

Element/Attribute	Allowed Subelements or Values	Default Value	Description
auth-native	(none)		(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: http://java.sun.com/products/servlet/index.html
form-login-session	session-manager		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.
session-manager	init-param		The session manager for the web application. See the Programmer's Guide to Servlets for iPlanet Web Server for the initialization parameters for each session manager.
class			The class for the session manager.
session-tracking	(none)		Determines the method of session tracking.
use-cookies	true, false	true	Uses cookies for session tracking if true.
use-url-rewriting	true, false	true	Uses URL rewriting for session tracking if true.
tempdir	(none)		A temporary directory used by the web application.
dir			The temporary directory.
vs	auth-native, class-loader, form-login-session, jsp-servlet, parameter-encoding, response-buffer, response-cookie, role-mapping, session-manager, session-tracking, session-cookie, tempdir, web-app		The top-level element in the web-apps.xml file. Subelements other than web-app set defaults for all web applications.
web-app	auth-native, class-loader, filter, filter-mapping, jsp-servlet, parameter-encoding, response-buffer, response-cookie, role-mapping, session-manager, session-tracking, session-cookie, tempdir		The web application. A web application is packaged in a WAR file and can contain servlets, JSPs, HTML pages, class files, and other resources of an application. The subelements of a web-app element override the equivalent subelements of the containing vs element for that web application.
dir			The directory where the web application contents are located.
uri			The URI that clients use to access the web application. This URI can be a regular expression.