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