Sun Java System Web Server 6.1 SP10 Administrator's Configuration File Reference

Chapter 2 Server Configuration Elements in server.xml

The server.xml file contains most of the server configuration. The encoding is UTF-8 to maintain compatibility with regular UNIX text editors. The server.xml file is located in the instance_dir/config directory. A schema file, sun-web-server_6_1.dtd, determines the format and content of the server.xml file.

This chapter describes server.xml and sun-server_1_0.dtd in the following sections:

sun-web-server_6_1.dtd File

The sun-web-server_6_1.dtd file defines the structure of the server.xml file, including the elements it can contain and the subelements and attributes these elements can have. The sun-web-server_6_1.dtd file is located in the install_dir/bin/https/dtds directory.

Each element defined in a DTD file (which might be present in the corresponding XML file) can contain the following:

Subelements

Elements can contain subelements. For example, the following file fragment defines the VSCLASS element.

<!ELEMENT VSCLASS (VARS?, VS*, QOSPARAMS?)>

The ELEMENT tag specifies that a VSCLASS element can contain VARS, VS, and QOSPARAMS elements in that order.

The following table shows how optional suffix characters of subelements determine the requirement rules or number of allowed occurrences for the subelements.

Table 2–1 Requirement Rules and Subelement Suffixes


Subelement Suffix	Requirement Rule
element*	Can contain zero or more of this subelement
element?	Can contain zero or one of this subelement
element+	Must contain one or more of this subelement
element (no suffix)	Must contain only one of this subelement

If an element cannot contain other elements, you see EMPTY or (#PCDATA) instead of a list of element names in parentheses.

Data

Some elements contain character data instead of subelements. These elements have definitions of the following format:

<!ELEMENT element-name (#PCDATA)>

For example:

<!ELEMENT DESCRIPTION (#PCDATA)>

In the server.xml file, white space is treated as part of the data in a data element. Therefore, there should be no extra white space before or after the data delimited by a data element. For example:

<DESCRIPTION>myserver</DESCRIPTION>

Attributes

Elements that have ATTLIST tags contain attributes (name-value pairs). For example:

<!ATTLIST JDBCRESOURCE

jndiname CDATA #REQUIRED

poolname CDATA #REQUIRED

enabled %boolean; "true">

A JDBCRESOURCE element can contain jndiname, poolname, and enabled attributes.

The #REQUIRED label means that a value must be supplied. The #IMPLIED label means that the attribute is optional, and that Sun Java System Web Server generates a default value. Wherever possible, explicit defaults for optional attributes (such as "true") are listed.

Attribute declarations specify the type of the attribute. For example, CDATA means character data, and %boolean is a predefined enumeration.

Elements in the server.xml File

This section describes the XML elements in the server.xml file. Elements are grouped as follows:

Note –

Subelements must be defined in the order in which they are listed under each Subelements heading unless otherwise noted.

For an alphabetical listing of elements in server.xml, see “Appendix D, Alphabetical List of Server Configuration Elements.

Core Server Elements

General elements are as follows:

SERVER

Defines a server. This is the root element. There can only be one server element in a server.xml file.

Subelements

The following table describes subelements for the SERVER element.

Table 2–2 SERVER Subelements


Element	Required	Description
VARS	zero or one	Defines variables that can be given values in `server.xml` and referenced in `obj.conf`
PROPERTY	zero or more	Specifies a property of the serve.
LS	one or more	Defines one or more HTTP listen sockets
MIME	zero or more	Defines the mime type
ACLFILE	zero or more	References one or more ACL files
VSCLASS	one or more	Defines a virtual server class
QOSPARAMS	zero or one	Defines quality of service parameters
JAVA	zero or one	Configures Java^TM Virtual Machine (JVM) parameters
LOG	zero or one	Configures the system logging service

Attributes

The following table describes attributes for the SERVER element.

Table 2–3 SERVER Attributes


Attribute	Default	Description
`qosactive`	`no`	Enables quality of service features, which let you set limits on server entities or view server statistics for bandwidth and connections. Allowed values are `yes`, `no`, `on`, `off`, `true`, `false`, `1` or `0`.
`qosmetricsinterval`	`30`	(optional) The interval in seconds during which the traffic is measured.
`qosrecomputeinterval`	`100`	(optional) The period in milliseconds in which the bandwidth gets recomputed for all server entities.

PROPERTY

Specifies a property, or a variable that is defined in server.xml and referenced in obj.conf. For information about variables, see Variables.

For a list of variables commonly defined in server.xml, see "Variables Used in the Interface."

A property adds configuration information to its parent element that is one or both of the following:

Optional with respect to Sun Java System Web Server
Needed by a system or object that Sun Java System Web Server does not have knowledge of, such as an LDAP server or a Java class

For example, an AUTHREALM element can include PROPERTY subelements:

<AUTHREALM name="file"

classname="com.iplanet.ias.security.auth.realm.file.FileRealm">

<PROPERTY name="file" value="instance_dir/config/keyfile>

<PROPERTY name="jaas-context" value="fileRealm">

</AUTHREALM>

The properties that an AUTHREALM element uses depends on the value of the AUTHREALM element's name attribute. The file realm uses file and jaas-context properties. Other realms use different properties.

Subelements

The following table describes subelements for the PROPERTY element.

Table 2–4 PROPERTY Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of the property.

Attributes

The following table describes attributes for the PROPERTY element.

Table 2–5 PROPERTY Attributes


Attribute	Default	Description
`name`	none	Specifies the name of the property or variable.
`value`	none	Specifies the value of the property or variable.

DESCRIPTION

Contains a text description of the parent element.

Subelements

None

Attributes

None

VARS

Defines variables that can be given values in server.xml and referenced in obj.conf. For more information, see Variables.

Subelements

none

Attributes

none

Listener Elements

The listener elements are as follows:

LS

Defines an HTTP listen socket.

Note –

When you create a secure listen socket through the Server Manager, security is automatically turned on globally in magnus.conf. When you create a secure listen socket manually in server.xml, security must be turned on by editing magnus.conf.

The CONNECTIONGROUP element from the schema file for server.xml in version 6.0 of Web Server is no longer supported. Its attributes and the subelement SSLPARAMS are added to the LS element in Sun Java System Web Server 6.1.

Subelements

The following table describes subelements for the LS element.

Table 2–6 LS Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of the listen socket.
SSLPARAMS	zero or one	Defines Secure Socket Layer (SSL) parameters.

Attributes

The following table describes attributes for the LS element.

Table 2–7 LS Attributes


Attribute	Default	Description
`id`	none	(Optional) The socket family type. A socket family type cannot begin with a number. When you create a secure listen socket in the `server.xml` file, security must be turned on in `magnus.conf`. When you create a secure listen socket in the Server Manager, security is automatically turned on globally in `magnus.conf`.
`ip`	any	Specifies the IP address of the listen socket. Can be in dotted-pair or IPv6 notation. Can also be `any` for `INADDR_ANY`.
`port`	none	Port number to create the listen socket on. Legal values are `1` - `65535`. 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`	`false`	(Optional) Determines whether the listen socket runs SSL. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`. You can turn SSL2 or SSL3 on or off and set ciphers using an `SSLPARAMS` subelement for this listen socket. The `Security` setting in the `magnus.conf` file globally enables or disables SSL by making certificates available to the server instance. Therefore, `Security` in `magnus.conf` must be `on` or security in `server.xml` does not work. For more information, see Chapter 3, Syntax and Use of magnus.conf
`acceptorthreads`	`1`	(Optional) Number of acceptor threads for the listener. The recommended value is the number of processors in the machine. Legal values are `1` - `1024`.
`family`	none	(Optional) The socket family type. Legal values are `inet, inet6, and nca`. 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 use the Solaris Network Cache and Accelerator.
`blocking`	false	(Optional) Determines whether the listen socket and the accepted socket are put in to blocking mode. Use of blocking mode may improve benchmark scores. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.
`defaultvs`	none	The `id` attribute of the default virtual server for this particular listen socket.
`servername`	none	Tells the server what to put in the host name section of any URLs it sends to the client. This affects URLs the server automatically generates. it does not affect the URLs for directories and files stored in the server. This name should be the alias name if your server uses an alias. If you append a colon and port number, that port will be used in URLs the server sends to the client.

SSLPARAMS

Defines SSL (Secure Socket Layer) parameters.

Subelements

None

Attributes

The following table describes attributes for the SSLPARAMS element.

Table 2–8 SSLPARAMS Attributes


Attribute	Default	Description
`servercertnickname`	`Server-Cert`	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`	`false`	(Optional) Determines whether SSL2 is enabled. Legal values are `on`, `off`, `yes`, `no`, `1`, `0, true,` and `false`. If both SSL2 and SSL3 are enabled for a virtual server, the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption.
`ssl2ciphers`	none	(Optional) A space-separated list of the SSL2 ciphers used, with the prefix + to enable or - to disable. For example +rc4. Allowed values are `rc4`, `rc4export`, `rc2`, `rc2export`, `idea`, `des`, `desede3`.
`ssl3`	`true`	(optional) Determines whether SSL3 is enabled. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true` and `false`. If both SSL2 and SSL3 are enabled for a virtual server, the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption.
`ssl3tlsciphers`	none	(optional) A space-separated list of the SSL3 ciphers used, with the prefix + to enable or - to disable, for example +rsa_des_sha. Allowed SSL3 values are `rsa_rc4_128_md5`, `rsa_3des_sha`, `rsa_des_sha`, `rsa_rc4_40_md5`, `rsa_rc2_40_md5`, `rsa_null_md5`. Allowed TLS values are `rsa_des_56_sha`, `rsa_rc4_56_sha`.
`tls`	`true`	(optional) Determines whether TLS is enabled. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, and `false`.
`tlsrollback`	`true`	(optional) Determines whether TLS rollback is enabled. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, and `false`. TLS rollback should be enabled for Microsoft Internet Explorer 5.0 and 5.5.
`clientauth`	`false`	(optional) Determines whether SSL3 client authentication is performed on every request, independent of ACL-based access control. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, and `false`.

MIME

Defines MIME types.

The most common way that the server determines the MIME type of a requested resource is by invoking the type-by-extension directive in the ObjectType section of the obj.conf file. The type-by-extension function does not work if no mime element has been defined in the SERVER element.

Attributes

The following table describes attributes for the MIME element.

Table 2–9 MIME Attributes


Attribute	Default	Description
`id`	none	Internal name for the MIME types listing. Used in a VS element to define the MIME types used by the virtual server. The MIME types name cannot begin with a number.
`file`	none	The name of a MIME types file. For more information, see Chapter 5, MIME Types.

ACLFILE

References one or more ACL files

Subelements

The following table describes subelements for the ACLFILE element.

Table 2–10 ACLFILE Subelements


Element	Required	Description
DESCRIPTION	Zero or one	Contains a text description of the `ACLFILE` element

Attributes

The following table describes attributes for the ACLFILE element.

Table 2–11 ACLFILE Attributes


Attribute	Default	Description
`id`	none	Internal name for the ACL file listing. Used in a VS element to define the ACL file used by the virtual server. An ACL file listing name cannot begin with a number.
`file`	none	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 Sun Java System Web Server 6.1 SP10 Administrator’s Guide. 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

Defines a virtual server class.

Subelements

The following table describes subelements for the VSCLASS element.

Table 2–12 VSCLASS Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of the `VSCLASS`.
VARS	zero or one	Specifies a property of the `VSCLASS`.
PROPERTY	zero or more	Specifies a property of the `VSCLASS`.
VS	zero or more	Defines a virtual server.
QOSPARAMS	zero or one	Defines quality of service parameters.

Attributes

The following table describes attributes for the VSCLASS element.

Table 2–13 VSCLASS Attributes


Attribute	Default	Description
`id`	none	Virtual server class ID. This is a unique ID that allows lookup of a specific virtual server class. A virtual server class ID cannot begin with a number.
`objectfile`	`obj.conf`	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, any server behavior that is configured in the default object affects the entire server. If you specify an object that doesn’t exist, the server does not report an error until a client tries to retrieve a document. The Server Manager assumes the default to be the object named `default`. Do not deviate from this convention if you use (or plan to use) the Server Manager.
`acceptlanguage`	`false`	(Optional) If `true`, 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. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, and `false.`

VS

Defines a virtual server. A virtual server, also called a virtual host, is a virtual web server that serves content targeted for a specific URL. Multiple virtual servers may serve content using the same or different host names, port numbers, or IP addresses. The HTTP service can direct incoming web requests to different virtual servers based on the URL.

Subelements

The following table describes subelements for the VS element.

Table 2–14 VS Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of this element.
VARS	zero or one	Specifies a property or a variable of the `VS`.
PROPERTY	zero or more	Specifies a property or a variable of the `VS`.
QOSPARAMS	zero or one	Defines quality of service parameters.
USERDB	zero or more	Defines the user database for the virtual server.
DAV	zero or one	Defines the WebDAV configuration for the virtual server.
SEARCH	zero or one	Defines the search configuration for the virtual server.
WEBAPP	zero or more	Specifies a web application.

Attributes

The following table describes attributes for the VS element.

Table 2–15 VS Attributes


Attribute	Default	Description
`id`	none	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. A virtual server ID cannot begin with a number.
`connections`	none	(optional) A space-separated list of LS ids that specify the connection(s) the virtual server uses. Required only for a `VS` that is not the `defaultvs` of a listen socket.
`urlhosts`	none	A space-separated list of values allowed in the Host request header to select the current virtual server. Each `VS` that is configured to the same listen socket must have a unique `urlhosts` value for that group.
`objectfile`	`objectfile` of the enclosing VSCLASS	(optional) The file name of the `obj.conf` file for this virtual server.
`rootobject`	`default`	(optional) Tells the server which object loaded from an `obj.conf` file is the default. 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; any server behavior that is configured in the default object affects the entire server. If you specify an object that doesn't exist, the server doesn't report an error until a client tries to retrieve a document.
`mime`	none	The `id` of the MIME element used by the virtual server.
`aclids`	none	(optional) One or more `id` attributes of ACLFILE elements, separated by commas. Specifies the ACL file(s) used by the virtual server.
`errorlog`	none	(optional) Specifies a log file for virtual-server-specific error messages. See the LOG description for details about logs.
`acceptlanguage`	`off`	(optional) If true, 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. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.
`state`	`on`	(optional) Determines whether a virtual-server is active (`on`) or inactive (`off`, `disabled`). The default is `on` (active). When inactive, a virtual server does not service requests. If a virtual server is disabled, only the global server administrator can turn it on.

QOSPARAMS

Defines quality of service parameters of an SERVER, VSCLASS, or VS element.

Subelements

none

Attributes

The following table describes attributes for the QOSPARAMS element.

Table 2–16 QOSPARAMS Attributes


Attribute	Default	Description
`maxbps`	none	(required if `enforcebandwidth` is `yes`) The maximum bandwidth limit for the `server`, `vsclass`, or `vs` in bytes per second.
`enforcebandwidth`	`false`	(optional) Specifies whether the bandwidth limit should be enforced or not. Allowed values are `yes`, `no`, `true`, `false`, `on`, `off`, `1`, `0`.
`maxconn`	none	(required if `enforceconnections` is `yes`) The maximum number of concurrent connections for the SERVER, VSCLASS, or VS.
`enforceconnections`	`false`	(optional) Specifies whether the connection limit should be enforced or not. Allowed values are `yes`, `no`, `true`, `false`, `on`, `off`, `1`, `0`.

USERDB

Defines the user database used by the VS element.

Subelements

The following table describes subelements for the USERDB element.

Table 2–17 USERDB Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of this element.

Attributes

The following table describes attributes for the USERDB element.

Table 2–18 USERDB Attributes


Attribute	Default	Description
`id`	none	The user database name in the virtual server's ACL file. A user database name cannot begin with a number.
`database`	none	The user database name in the `dbswitch.conf` file.
`basedn`	none	(optional) Overrides the base DN lookup in the `dbswitch.conf` file. However, the `basedn` value is still relative to the base DN value from the `dbswitch.conf` entry.
`certmaps`	none	(optional) Specifies which certificate mapped 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.

WebDAV Elements

The WebDAV elements are as follows:

DAV

Defines the WebDAV (Web-based Distributed Authoring and Versioning) configuration for the VS element.

Subelements

The following table describes subelements for the DAV element.

Table 2–19 DAV Subelements


Element	Required	Description
PROPERTY	zero or more	Specifies a property or a variable.
DAVCOLLECTION	zero or more	Collections for which DAV is enabled.

Attributes

The following table describes attributes for the DAV element.

Table 2–20 DAV Attributes


Attribute	Default	Description
`lockdb`	server-instance`/lock-db/vs`	(optional) Specifies the directory where the locking database will be maintained.
`lockdbupdateinterval`	0	(optional) specifies the frequency with which the memory representation of the lock database should be synced up to the disk copy of the lock database. The interval is specified in seconds. A value of zero disables the memory representation of the lock database.
`minlocktimeout`	none	(optional) Minimum lifetime of a lock in seconds, `-1` implies never expires. A value of `0` sets `minlocktimeout` to infinity.
`propdbupdateinterval`	0	(optional) specifies the frequency with which the memory representation of the property database should be synced up to the disk copy of the database. The interval is specified in seconds. A value of zero disables the memory representation of the property database.
`maxpropdbsize`	8192	(optional) specifies an upper limit on the total size of the memory representation of the property databases in the collection. When this size is reached, any additional databases accessed in this collection will not have a memory representation.
`maxxmlrequestbodysize`	`8192`	(optional) Maximum size of the XML request body. Needed to prevent potential Denial of Service (DOS) attacks.
`maxpropdepth`	`1`	(optional) The depth of the PROPFIND request. If the request is to a collection, then the depth of the subdirectories included in the response is specified by this attribute. Legal values are `0`, `1`, and `infinity`.
`enabled`	`true`	(optional) Specifies if DAV functionality is enabled for a virtual server. Legal values are `yes`, `no`, `true`, `false`, `on`, `off`, `1`, `0`.

DAVCOLLECTION

Defines a DAV-enabled collection of documents rooted at a URI; the source of the documents are accessed via a separate URI space.

The DAVCOLLECTION element defines WebDAV functionality for a URI space. The attributes specified on a collection override any virtual server attribute values.

Subelements

The following table describes subelements for the DAVCOLLECTION element.

Table 2–21 DAVCOLLECTION Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of this element.

Attributes

The following table describes attributes for the DAVCOLLECTION element.

Table 2–22 DAVCOLLECTION Attributes


Attribute	Default	Description
`uri`	none	(required) Specifies the URI by which the output content is accessed.
`sourceuri`	none	(optional) Specifies the URI by which the source content of the documents are accessed.
`lockdb`	`lockdb` value specified in the DAV element	(optional) Specifies the directory where the locking database will be maintained.
`lockdbupdateinterval`	The value specified in the DAV element.	(optional) specifies the frequency with which the memory representation of the lock database should be synced up to the disk copy of the lock database. The interval is specified in seconds. A value of zero disables the memory representation of the lock database.
`minlocktimeout`	`minlocktimeout` attribute value specified in the DAV element	(optional) Minimum lifetime of a lock in seconds, `-1` implies never expires, `0` turns locking off.
`propdbupdateinterval`	The value specified in the DAV element.	(optional) specifies the frequency with which the memory representation of the property database should be synced up to the disk copy of the database. The interval is specified in seconds. A value of zero disables the memory representation of the property database.
`maxpropdbsize`	The value specified in the DAV element.	(optional) specifies an upper limit on the total size of the memory representation of the property databases in the collection. When this size is reached, any additional databases accessed in this collection will not have a memory representation.
`maxxmlrequestbodysize`	The value specified in the DAV element.	(optional) Maximum size of the XML request body. Needed to prevent potential Denial of Service (DOS) attacks.
`maxpropdepth`	The value specified in the DAV element.	(optional) The maximum depth permitted for a DAV PROPFIND request. Allowed values are `0`, `1`, and `infinity`.
`enabled`	`true`	(optional) Specifies if DAV functionality is enabled for this collection.

Search Elements

Search elements are as follows:

SEARCH

Defines search related configuration parameters for a given VS.

Subelements

The following table describes subelements for the SEARCH element.

Table 2–23 SEARCH Subelements


Element	Required	Description
WEBAPP	zero or one	The default search web application for this virtual server
SEARCHCOLLECTION	zero or more	Specifies a searchable index of documents called a collection.
PROPERTY	zero or more	Specifies name-value pairs to pass extra configuration information to the search engine.

Attributes

The following table describes attributes for the SEARCH element.

Table 2–24 SEARCH Attributes


Attribute	Default	Description
`maxhits`	none	The maximum number of results that will be retrieved by the search engine in a single search.

SEARCHCOLLECTION

Specifies a searchable index of documents called a search collection.

Subelements

The following table describes subelements for the SEARCHCOLLECTION element.

Table 2–25 SEARCHCOLLECTION Subelements


Element	Required	Description
DISPLAYNAME	zero or one	Optional display name that can be used while displaying searchable collections to the end user.
DESCRIPTION	zero or one	Contains a text description of the collection.
PROPERTY	zero or more	Contains name-value pairs to pass extra configuration information to the search engine.

Attributes

The following table describes attributes for the SEARCHCOLLECTION element.

Table 2–26 SEARCHCOLLECTION Attributes


Attribute	Default	Description
`name`	none	Specifies unique identifier for this collection. Should be a legal XML ID type.
`path`	none	Specifies a file system location for storing search collection meta data.
`uri`	none	Specifies a URI for the indexable collection of documents.
`docroot`	none	Specifies a file system path for the collection of documents.
`enabled`	`true`	Specifies whether a collection can be searched. Legal values are `yes`, `no`, `true`, `false`, `on`, `off`, `1`, and `0`.

DISPLAYNAME

Specifies a human-readable name for the collection to be used while displaying the collection to the end user. Example:

<DISPLAYNAME>  Omega Manual </DISPLAYNAME>

Subelements

none

Attributes

none

Web Application Elements

The Web application elements are as follows:

WEBAPP

WEBAPP

Defines a Java web application rooted at a given URI within a VS.

Subelements

The following table describes subelements for the WEBAPP element.

Table 2–27 webapp Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of this element.

Attributes

The following table describes attributes for the WEBAPP element.

Table 2–28 WEBAPP attributes


Attribute	Default	Description
`uri`	empty string	This is the context path at which the web application is installed (Section 5.4 of the Servlet 2.3 specification). If this attribute is "/" then this web application is designated to be the default web application for the virtual server. The default web application for a virtual server responds to all requests that cannot be resolved to other web applications deployed to the virtual server. Every virtual server has a default web application.
`path`	none	A fully qualified or relative path to the directory in which the contents of the `.war` file have been extracted.
`enabled`	`true`	This attribute can be used to temporarily disable the web application from servicing requests without removing the contents of the web application (on disk).Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.

Java Configuration Elements

The Java configuration elements are as follows:

JAVA

Defines configurable properties for the integrated Java Virtual Machine (JVM), and for Java-based security and resources.

Subelements

The following table describes subelements for the JAVA element.

Table 2–29 JAVA Subelements


Element	Required	Description
PROPERTY	zero or more	Specifies a property or a variable.
JVMOPTIONS	zero or more	Contains JVM command line options.
PROFILER	zero or one	Configures a profiler for use with the server.
SECURITY	zero or one	Defines parameters and configuration information needed by the security service.
RESOURCES	zero or one	Specifies configured resources.

Attributes

The following table describes attributes for the JAVA element.

Table 2–30 JAVA Attributes


Attribute	Default	Description
`javahome`	`<`install-root`>/bin/https/jdk` For SVR 4 package-based installation for Solaris: `/usr/java`	The path to the directory where the JDK is installed.
`debug`	`false`	(optional) If `true`, the server starts up in debug mode ready for attachment with a JPDA-based (Java Platform Debugger Architecture-based) debugger. Legal values are `on`, `off`, `yes`, `no`, `true`, `false`, `1`, `0`.
`debugoptions`	`-Xdebug -Xrunjdwp:transport=dt_socket, server=y,suspend=n`	(optional) Specifies JPDA options. A list of debugging options that you can include is available at: `http://java.sun.com/products/jpda/doc/conninv.html#Invocation`
`classpathprefix`	none	(optional) Specifies a prefix for the system classpath. You should only prefix the system classpath if you wish to override system classes, such as the XML parser classes. Use this attribute with caution.
`serverclasspath`	none	(optional) Specifies the classpath for the environment from which the server was started. This classpath can be accessed using `System.getProperty("java.class.path")`.
`classpathsuffix`	none	(optional) Specifies a suffix for the system classpath.
`nativelibrarypathprefix`	none	(optional) Specifies a prefix for the native library path. The native library path is the automatically constructed concatenation of the path to the server's native shared libraries, the standard JRE (Java Runtime Environment) native library path, the shell environment setting (LD_LIBRARY_PATH on UNIX), and any path specified in the PROFILER element. Since this is synthesized, it does not appear explicitly in the server configuration.
`nativelibrarypathsuffix`	none	(optional) Specifies a suffix for the native library path.
`envclasspathignored`	`true`	(optional) If `false`, the CLASSPATH environment variable is read and appended to the server classpath. The CLASSPATH environment variable is added after the `classpath-suffix`, at the very end. For a development environment, this value should be set to false. For a production environment, this value should be set to `true` to prevent environment variable side effects. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.
`bytecodepreprocessors`	none	(optional) A comma-separated list of class names, each of which must implement the `com.sun.appserv.BytecodePreprocessor` interface. Each of the specified preprocessor classes is called in the order specified.
`dynamicreloadinterval`	`2`	Specifies the interval, in seconds, after which a deployed application is reloaded.
`loglevel`	Value of `level` attribute of LOG element	(optional) Controls the type of messages logged by this element to the errors log. For details, see the description of the `level` attribute of the LOG element.

JVMOPTIONS

Defines configurable system-wide Java VM properties., for example:

<JVMOPTIONS>-Xdebug -Xmx128m</JVMOPTIONS>

In addition, web server looks for a system property, -Dcom.sun.webserv.startupclasses, whose value is a comma-separated list of fully qualified Java classes that server loads into the Virtual Machine upon startup. Example:

<JVMOPTIONS> 
-Dcom.sun.webserv.startupclasses=com.sample.MyInitializer,com.jdo
.PersistenceManagerFactory
</JVMOPTIONS>

For information about the available options, see http://java.sun.com/docs/hotspot/VMOptions.html.

Note –

(On Windows only). Logging out of the machine where the web server is installed might abort the web server process. To avoid this problem, perform these steps:

Add the following line to the server.xml file of the web server instance.

<JVMOPTIONS>-Xrs</JVMOPTIONS>
Restart the instance.

Subelements

none

Attributes

none

PROFILER

Configures a profiler for use with the server.

Subelements

The following table describes subelements for the PROFILER element.

Table 2–31 PROFILER Subelements


Element	Required	Description
PROPERTY	zero or more	Specifies a property.
JVMOPTIONS	zero or more	Contains profiler-specific JVM command line options.

Attributes

The following table describes attributes for the PROFILER element.

Table 2–32 PROFILER Attributes


Attribute	Default	Description
`classpath`	none	(optional) Specifies the classpath for the profiler.
`nativelibrarypath`	none	(optional) Specifies the native library path for the profiler.
`enabled`	`true`	(optional) Determines whether the profiler is enabled. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.

SECURITY

Defines parameters and configuration information needed by the security service.

Subelements

The following table describes subelements for the SECURITY element.

Table 2–33 SECURITY Subelements


Element	Required	Description
PROPERTY	zero or more	Specifies a property or a variable.
AUTHREALM	one or more	Defines a realm for authentication.

Attributes

The following table describes attributes for the SECURITY element.

Table 2–34 SECURITY Attributes


Attribute	Default	Description
`defaultrealm`	`file`	(optional) Specifies the default authentication realm (an AUTHREALM name attribute) for this server instance. The default realm will be used to process authentication events for any web applications which do not otherwise specify which realm to use.
`anonymousrole`	`ANYONE`	(optional) Used as the name for default, or anonymous, role. The anonymous role is always assigned to all principals.
`audit`	`false`	(optional) If `true`, additional access logging is performed to provide audit information. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`. Audit information consists of: Authentication success and failure events Servlet access grants and denials
loglevel	Value of `level` attribute of LOG element	(optional) Controls the type of messages logged by this element to the errors log. For details, see the description of the `level` attribute of the LOG element.

AUTHREALM

Defines a realm for authentication.

Authentication realms require provider-specific properties, which vary depending on the needs of a particular implementation.

Here is an example of the default file realm:

<authrealm name="file"

classname="com.iplanet.ias.security.auth.realm.file.FileRealm">

<property name="file" value="instance_dir/config/keyfile">

<property name="jaas-context" value="fileRealm">

</authrealm>

Which properties an AUTHREALM element uses depends on the value of the AUTHREALM element's name attribute. The file realm uses file and jaas-context properties. Other realms use different properties.

Subelements

The following table describes subelements for the AUTHREALM element.

Table 2–35 AUTHREALM Subelements


Element	Required	Description
PROPERTY	zero or more	Specifies a property or a variable.

Attributes

The following table describes attributes for the AUTHREALM element.

Table 2–36 AUTHREALM Attributes


Attribute	Default	Description
`name`	none	Specifies the name of this realm.
`classname`	none	Specifies the Java class that implements this realm.

Properties

The standard realms provided have both required and optional properties. A custom realm may have different properties. For details about the properties and configuration characteristics of the AUTHREALM realms, refer to the chapter “Securing Web Applications” in the Sun Java System Web Server 6.1 Programmer's Guide to Web Applications.

Resource Elements

Resource elements are as follows:

RESOURCES

Contains configured resources, such as database connections.

Subelements

The following table describes subelements for the RESOURCES element.

Table 2–37 RESOURCES Subelements


Element	Required	Description
CUSTOMRESOURCE	zero or more	Defines a custom resource.
EXTERNALJNDIRESOURCE	zero or more	Defines a resource that resides in an external JNDI (Java Naming and Directory Interface) repository.
JDBCRESOURCE	zero or more	Defines a JDBC (Java Database Connectivity) resource.
JDBCCONNECTIONPOOL	zero or more	Defines the properties that are required for creating a JDBC connection pool.
MAILRESOURCE	zero or more	Defines the properties that are required for creating a mail resource.

Attributes

none

CUSTOMRESOURCE

Defines a custom resource, which specifies a custom server-wide resource object factory. Such object factories implement the javax.naming.spi.ObjectFactory interface.

Subelements

The following table describes subelements for the CUSTOMRESOURCE element.

Table 2–38 CUSTOMRESOURCE Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of this element.
PROPERTY	zero or more	Specifies a property or a variable.

Attributes

The following table describes attributes for the CUSTOMRESOURCE element.

Table 2–39 CUSTOMRESOURCE Attributes


Attribute	Default	Description
`jndiname`	none	Specifies the JNDI name for the resource.
`restype`	none	Specifies the fully qualified type of the resource.
`factoryclass`	none	Specifies the fully qualified name of the user-written factory class, which implements `javax.naming.spi.ObjectFactory`.
`enabled`	true	(optional) Determines whether this resource is enabled at runtime. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.

EXTERNALJNDIRESOURCE

Defines a resource that resides in an external JNDI repository. For example, a generic Java object could be stored in an LDAP server. An external JNDI factory must implement the javax.naming.spi.InitialContextFactory interface.

Subelements

The following table describes subelements for the EXTERNALJNDIRESOURCE element.

Table 2–40 EXTERNALJNDIRESOURCE Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of this element.
PROPERTY	zero or more	Specifies a property or a variable.

Attributes

The following table describes attributes for the EXTERNALJNDIRESOURCE element.

Table 2–41 EXTERNALJNDIRESOURCE Attributes


Attribute	Default	Description
`jndiname`	none	Specifies the JNDI name for the resource.
`jndilookupname`	none	Specifies the JNDI lookup name for the resource.
`restype`	none	Specifies the fully qualified type of the resource.
`factoryclass`	none	Specifies the fully qualified name of the factory class, which implements `javax.naming.spi.InitialContextFactory`.
`enabled`	`true`	(optional) Determines whether this resource is enabled at runtime. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.

JDBCRESOURCE

Defines a JDBC (javax.sql.DataSource) resource.

Subelements

The following table describes subelements for the JDBCRESOURCE element.

Table 2–42 JDBCRESOURCE Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of this element.
PROPERTY	zero or more	Specifies a property or a variable.

Attributes

The following table describes attributes for the JDBCRESOURCE element.

Table 2–43 JDBCRESOURCE Attributes


Attribute	Default	Description
`jndiname`	none	Specifies the JNDI name for the resource.
`poolname`	none	Specifies the name of the associated JDBC connection pool, defined in a JDBCCONNECTIONPOOL element.
`enabled`	`true`	(optional) Determines whether this resource is enabled at runtime. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.

JDBCCONNECTIONPOOL

Defines the properties that are required for creating a JDBC connection pool.

Note –

The restype attribute of the JDBCCONNECTIONPOOL element is reserved and ignored in Sun Java System Web Server 6.1. Any value set for this attribute is ignored by the server.

Subelements

The following table describes subelements for the JDBCCONNECTIONPOOL element.

Table 2–44 JDBCCONNECTIONPOOL Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of this element.
PROPERTY	zero or more	Specifies a property or a variable.
CONNECTIONPROPERTY	zero or more	Specifies the connection properties for the connection pool.

Attributes

The following table describes attributes for the JDBCCONNECTIONPOOL element.

Table 2–45 JDBCCONNECTIONPOOL Attributes


Attribute	Default	Description
`name`	none	Specifies the name of the connection pool. A JDBCRESOURCE element's `poolname` attribute refers to this `name`.
`datasourceclassname`	none	Specifies the class name of the associated vendor-supplied data source. This class must implement `java.sql.DataSource` or `java.sql.XADataSource` or both.
`steadypoolsize`	`8`	(optional) Specifies the initial and minimum number of connections maintained in the pool.
`maxpoolsize`	`32`	(optional) Specifies the maximum number of connections that can be created to satisfy client requests.
`maxwaittime`	`60000`	(optional) Specifies the amount of time, in milliseconds, that the caller is willing to wait for a connection. If `0`, the caller is blocked indefinitely until a resource is available or an error occurs.
`poolresizequantity`	`2`	(optional) Specifies the number of connections to be destroyed if the existing number of connections is above the `steady-pool-size` (subject to the `max-pool-size` limit). This is enforced periodically at the `idle-time-out-in-seconds` interval. An idle connection is one that has not been used for a period of `idle-time-out-in-seconds`.
`idletimeout`	`300`	(optional) Specifies the maximum time that a connection can remain idle in the pool. After this amount of time, the pool can close this connection.
`transactionisolationlevel`	default JDBC driver isolation level	(optional) Specifies the transaction isolation level on the pooled database connections. Allowed values are `read-uncommitted`, `read-committed`, `repeatable-read`, or `serializable`. Applications that change the isolation level on a pooled connection programmatically risk polluting the pool, which can lead to errors. See `isolationlevelguaranteed` for more details.
`isolationlevelguaranteed`	`true`	(optional) Applicable only when `transactionisolationlevel` is explicitly set. If `true`, every connection obtained from the pool is guaranteed to have the desired isolation level. This may impact performance on some JDBC drivers. You can set this attribute to `false` if you are certain that the hosted applications do not return connections with altered isolation levels.
`connectionvalidationrequired`	`false`	(optional) Specifies whether connections must be validated before being given to the application. If a resource's validation fails, it is destroyed, and a new resource is created and returned. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.
`connectionvalidationmethod`	`auto-commit`	(optional) Legal values are as follows: `auto-commit` (default), which uses `Connection.setAutoCommit(Connection.getAutoCommit())` `meta-data`, which uses `Connection.getMetaData()` `table`, which performs a query on a table specified in the `validation-table-name` attribute
`validationtablename`	none	(optional) Specifies the table name to be used to perform a query to validate a connection. This parameter is mandatory if and only if `connectionvalidationtype` is set to `table`.
`failallconnections`	`false`	(optional) If true, closes all connections in the pool if a single validation check fails. This parameter is mandatory if and only if `isconnectionvalidationrequired` is set to `true`. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.

Properties

Most JDBC 2.0 drivers allow use of standard property lists to specify the user, password, and other resource configuration information. Although properties are optional with respect to Sun Java System Web Server, some properties may be necessary for most databases. For details, see Section 5.3 of the JDBC 2.0 Standard Extension API.

When properties are specified, they are passed to the vendor's data source class (specified by the datasourceclassname attribute) using setName(value) methods.

The following table describes some common properties for the JDBCCONNECTIONPOOL element. The left column lists the property name, and the right column describes what the property does.

Table 2–46 JDBCCONNECTIONPOOL Properties


Property	Description
`user`	Specifies the user name for this connection pool.
`password`	Specifies the password for this connection pool.
`databaseName`	Specifies the database for this connection pool.
`serverName`	Specifies the database server for this connection pool.
`port`	Specifies the port on which the database server listens for requests.
`networkProtocol`	Specifies the communication protocol.
`roleName`	Specifies the initial SQL role name.
`datasourceName`	Specifies an underlying `XADataSource`, or a `ConnectionPoolDataSource` if connection pooling is done.
`description`	Specifies a text description.
`url`	Specifies the URL for this connection pool. Although this is not a standard property, it is commonly used.

CONNECTIONPROPERTY

Specifies the connection properties for a JDBC connection pool.

Subelements

The following table describes subelements for the CONNECTIONPROPERTY element.

Table 2–47 CONNECTIONPROPERTY Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of this element.

Attributes

The following table describes attributes for the CONNECTIONPROPERTY element.

Table 2–48 CONNECTIONPROPERTY Attributes


Attribute	Default	Description
`name`	none	Specifies a name for the connection property.
`value`	`none`	Specifies a value for the connection property.
`invocationfrequency`	`at-creation`	(optional) Specifies the frequency with which the connection property is invoked. Legal values are `at-creation` and `every-lease`.

MAILRESOURCE

Defines a JavaMail (javax.mail.Session) resource.

Subelements

The following table describes subelements for the MAILRESOURCE element.

Table 2–49 MAILRESOURCE Subelements


Element	Required	Description
DESCRIPTION	zero or one	Contains a text description of this element.

Attributes

The following table describes attributes for the MAILRESOURCE element.

Table 2–50 MAILRESOURCE Attributes


Attribute	Default	Description
`jndiname`	none	Specifies the JNDI name for the resource.
`storeprotocol`	`imap`	(optional) Specifies the storage protocol service, which connects to a mail server, retrieves messages, and saves messages in folder(s). Example values are `imap` and `pop3`.
`storeprotocolclass`	`com.sun.mail.imap.IMAPStore`	(optional) Specifies the service provider implementation class for storage. You can find this class at: `http://java.sun.com/products/javamail/` `http://java.sun.com/products/javabeans/glasgow/`
`transportprotocol`	`smtp`	(optional) Specifies the transport protocol service, which sends messages.
`transportprotocolclass`	`com.sun.mail.smtp.SMTPTransport`	(optional) Specifies the service provider implementation class for transport. You can find this class at: `http://java.sun.com/products/javamail/` `http://java.sun.com/products/javabeans/glasgow/`
`host`	none	The mail server host name
`user`	none	The mail server user name
`from`	none	The e-mail address the mail server uses to indicate the message sender.
`enabled`	`true`	(optional) Determines whether this resource is enabled at runtime. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.

LOG

Configures the system logging service, which includes the following log files:

The errors log file stores messages from the default virtual server. Messages from other configured virtual servers also go here, unless the logfile attribute is explicitly specified in the VSCLASS or VS element. The default name is errors.
The access log file stores HTTP access messages from the default virtual server. The default name is access.log. To configure the access log, you use server application functions in the magnus.conf and obj.conf files.
A virtual server log file stores messages from a VSCLASS or VS element that has an explicitly specified log-file attribute.

Subelements

The following table describes subelements for the LOG element.

Table 2–51 LOG Subelements


Element	Required	Description
PROPERTY	zero or more	Specifies a property or a variable.

Attributes

The following table describes attributes for the LOG element.

Table 2–52 LOG Attributes


Attribute	Default	Description
`file`	`errors`	Specifies the file that stores messages from the default virtual server. Messages from other configured virtual servers also go here, unless the `errorlog` attribute is explicitly specified in the VS element.
`loglevel`	`info`	Controls the default type of messages logged by other elements to the error log. Allowed values are as follows, from highest to lowest: `finest`, `finer,` `fine`, `info`, `warning`, `failure`, `config, security`, and `catastrophe`.
`logvsid`	`false`	(optional) If `true`, virtual server IDs are displayed in the virtual server logs. This is useful if multiple VS elements share the same log file. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.
`logstdout`	`true`	(optional) If `true`, redirects `stdout` output to the errors log. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.
`logstderr`	`true`	(optional) If `true`, redirects `stderr` output to the errors log. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.
`logtoconsole`	`true`	(optional, UNIX only) If `true`, redirects log messages to the console.
`createconsole`	`false`	(optional, Windows only) If `true`, creates a Windows console. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.
`usesyslog`	`false`	(optional) If `true`, uses the UNIX `syslog` service or Windows Event Logging to produce and manage logs. Legal values are `on`, `off`, `yes`, `no`, `1`, `0`, `true`, `false`.

User Database Selection

A USERDB object selects a user database for the parent virtual server. This selection occurs in the following manner:

The USERDB element's id attribute maps to an ACL file's database attribute.
The USERDB element's database attribute maps to a dbswitch.conf entry.

This layer between the ACL file and the dbswitch.conf file gives the server administrator full control over the databases to which virtual server administrators and users have access.

The dbswitch.conf file establishes the root of the search tree for LDAP databases as follows:
The base DN in the LDAP URL in dbswitch.conf defines a root object for all further DN specifications. So, for most new installations, it can be empty, because the final base DN is determined in other ways -- either through a dc tree lookup or an explicit basedn value in the USERDB tag.
A new dbswitch.conf attribute for LDAP databases, dcsuffix, defines the root of the dc tree. This root is relative to the base DN in the LDAP URL. If the database is schema compliant you can use dcsuffix . Requirements for schema compliance are listed in Sun Java System LDAP Schema.

A user database is selected for a virtual server as follows:
If a VS has no USERDB subelement, user- or group-based ACLs fail.
When no database attribute is present in a virtual server’s ACL definition, the VS must have a USERDB subelement with an id attribute of default. The database attribute of the USERDB then points to a database in dbswitch.conf. If no database attribute is present, default is used.
If an LDAP database is schema compliant, the base DN of the access is computed using a dc tree lookup of the VS element's hosts attribute that matches the client-supplied host header. If no hosts attribute matches, the servername attribute of the parent SERVER is used. The dc tree lookup is based at the dcsuffix DN. The result must contain an inetDomainBaseDN attribute that contains the base DN. This base DN is taken as is and is not relative to any of the base DN values.
If the basedn attribute of the USERDB element is not present and the database is not schema compliant, the access requests are relative to the base DN in the dbswitch.conf entry, as in previous Sun Java System Web Server versions.

Sun Java System LDAP Schema

This section describes the Sun Java System LDAP Schema that defines a set of rules for directory data.

You can use the dcsuffix attribute in the dbswitch.conf file if your LDAP database meets the requirements outlined in this section. For more information about the dbswitch.conf file, see dbswitch.conf.

The subtree rooted at an ISP entry (for example, o=isp) is called the convergence tree. It contains all directory data related to organizations (customers) served by an ISP.

The subtree rooted at o=internet is called the domain component tree, or dc tree. It contains a sparse DNS tree with entries for the customer domains served. These entries are links to the appropriate location in the convergence tree where the data for that domain is located.

The directory tree may be single rooted, which is recommended (for example, o=root may have o=isp and o=internet under it), or have two separate roots, one for the convergence tree and one for the dc tree.

Convergence Tree

The top level of the convergence tree must have one organization entry for each customer (or organization), and one for the ISP itself.

Underneath each organization, there must be two organizationalUnit entries: ou=People and ou=Groups. A third, ou=Devices, can be present if device data is to be stored for the organization.

Each user entry must have a unique uid value within a given organization. The namespace under this subtree can be partitioned into various ou entries that aggregate user entries in convenient groups (for example, ou=eng, ou=corp). User uid values must still be unique within the entire People subtree.

User entries in the convergence tree are of type inetOrgPerson. The cn, sn, and uid attributes must be present. The uid attribute must be a valid email name (specifically, it must be a valid local-part as defined in RFC822). The cn contains name initial sn. The RDN of the user entry the uid value. User entries must contain the auxiliary class inetUser if they are to be considered enabled for service or valid.

User entries can also contain the auxiliary class inetSubscriber, which is used for account management purposes. If an inetUserStatus attribute is present in an entry and has a value of inactive or deleted, the entry is ignored.

Groups are located under the Groups subtree and consist of LDAP entries of type groupOfUniqueNames.

Domain Component (dc) Tree

The dc tree contains hierarchical domain entries, each of which is a DNS name component.

Entries that represent the domain name of a customer are overlaid with the LDAP auxiliary class inetDomain. For example, the two LDAP entries dc=customer1,dc=com,o=Internet,o=root and dc=customer2,dc=com,o=Internet,o=root contain the inetDomain class, but dc=com,o=Internet,o=root does not. The latter is present only to provide structure to the tree.

Entries with an inetDomain attribute are called virtual domains. These must have the attribute inetDomainBaseDN filled with the DN of the top level organization entry where the data of this domain is stored in the convergence tree. For example, the virtual domain entry in dc=cust2,dc=com,o=Internet,o=root contains the attribute inetDomainBaseDN with value o=Cust2,o=isp,o=root.

If an inetDomainStatus attribute has a value of inactive or deleted, the entry is ignored.

Variables

Some variables are defined in server.xml for use in the obj.conf file. The following file fragment defines a docroot variable:

<PROPERTY name="docroot" value="/server/docs/class2/acme" >

A docroot variable allows different document root directories to be assigned for different virtual servers. The variable is then used in the obj.conf file. For example:

NameTrans fn=document-root root="$docroot"

Using this docroot variable allows you to define different document roots for different virtual servers within the same virtual server class.

Format of a Variable

A variable is found in obj.conf when the following regular expression matches:

\$[A-Za-z][A-Za-z0-9_]*

This expression represents a $ followed by one or more alphanumeric characters. A delimited version ("${property}") is not supported. To get a regular $ character, use $$ to have variable substitution.

The id Variable

A special variable, id, is always available within a VS element and refers to the value of the id attribute. It is predefined and cannot be overridden. The id attribute uniquely identifies a virtual server. For example:

<PROPERTY name=docroot value="/export/$id" >

If the id attribute of the parent VS element is myserver, the docroot variable is set to the value /export/myserver.

Other Important Variables

In a default installation, the following variables are used to configure various aspects of the server's operation. Unlike the $id variable, they are not predefined in the server, and they can be overridden.

General Variables

The following table lists general server.xml variables. The left column lists variables, and the right column lists descriptions of those variables.

Table 2–53 General Variables


Property	Description
`docroot`	The document root of the virtual server. Typically evaluated as the parameter to the `document-root` function in the `obj.conf` file.
accesslog	The access log file for a virtual server.

send-cgi Variables

The following table lists server.xml variables used by the send-cgi function in the obj.conf file. The left column lists variables, and the right column lists descriptions of those variables.

Table 2–54 send-cgi Variables


Property	Description
`user`	The value of the `user` CGI parameter.
group	The value of the `group` CGI parameter.
chroot	The value of the `chroot` CGI parameter.
dir	The value of the `dir` CGI parameter.
nice	The value of the `nice` CGI parameter.

For more information about the send-cgi function, see the Sun Java System Web Server 6.1 SP10 NSAPI Programmer’s Guide.

Variable Evaluation

Variables are evaluated when generating specific objectsets for individual virtual servers. Evaluation is recursive: variable values can contain other variables. For example:

...
<VSCLASS>
   ... 
   <VS ...> 
      ... 
      <PROPERTY name=docroot value="$docrootbase/nonjava/$id" > 
   </VS> 
   <VS...> 
      ... 
      <PROPERTY name=docroot value="$docrootbase/java/$id" > 
   </VS> 
   ... 
   <PROPERTY name=docrootbase value="/export" > 
</VSCLASS> 
...

Variables in subelements override variables in the parent elements. For example, it is possible to set a variable for a class of virtual servers and override it with a definition of the same variable in an individual virtual server.

Sample server.xml File

<?xml version="1.0" encoding="UTF-8"?>
<!--
   Copyright (c) 2003 Sun Microsystems, Inc.  All rights reserved.
   Use is subject to license terms.
-->
<!DOCTYPE SERVER PUBLIC "-//Sun Microsystems Inc.//DTD Sun Java 
System Web Server 6.1//EN" 
"file:///home/nb136819/space/servers/s1ws61/bin/https/dtds/sun-web-
server_6_1.dtd">

<SERVER>
    <PROPERTY name="docroot" 
value="/home/nb136819/space/servers/s1ws61/docs">
    <PROPERTY name="accesslog" 
value="/home/nb136819/space/servers/s1ws61/https-admserv/logs/
access">
    <PROPERTY name="user" value="">
    <PROPERTY name="group" value="">
    <PROPERTY name="chroot" value="">
    <PROPERTY name="dir" value="">
    <PROPERTY name="nice" value="">
<LS id="ls1" port="5555" servername="plaza.india.sun.com" 
defaultvs="vs-admin">

<LS id="ls2" port="9999" servername="plaza.india.sun.com" 
defaultvs="useradmin">

<MIME id="mime1" file="mime.types">

<ACLFILE id="acl1" 
file="/home/nb136819/space/servers/s1ws61/httpacl/generated.https
-admserv.acl">
<VSCLASS id="vsclass-admin" objectfile="obj.conf">
        <VS id="vs-admin" connections="ls1" mime="mime1" 
aclids="acl1" urlhosts="plaza.india.sun.com">
            
        <PROPERTY name="docroot" 
value="/home/nb136819/space/servers/s1ws61/docs">
            <USERDB id="default">
            <WEBAPP uri="/admin-app" 
path="/home/nb136819/space/servers/s1ws61/bin/https/webapps/admin-app">
        </VS>
    </VSCLASS>
<VSCLASS id="userclass" objectfile="userclass.obj.conf">
        <VS id="useradmin" connections="ls2" mime="mime1" 
aclids="acl1" urlhosts="plaza.india.sun.com">
            <PROPERTY name="docroot" 
value="/home/nb136819/space/servers/s1ws61/docs">
            <USERDB id="default">
            <WEBAPP uri="/user-app" 
path="/home/nb136819/space/servers/s1ws61/bin/https/webapps/user-app">
        </VS>
    </VSCLASS>
<JAVA javahome="/home/nb136819/space/servers/s1ws61/bin/https/jdk" 
serverclasspath="/home/nb136819/space/servers/s1ws61/bin/https/jar/
webserv-rt.jar:${java.home}/lib/tools.jar:/home/nb136819/space/serv
ers/s1ws61/bin/https/jar/webserv-ext.jar:/home/nb136819/space/serve
rs/s1ws61/bin/https/jar/webserv-jstl.jar:/home/nb136819/space/serve
rs/s1ws61/bin/https/jar/webserv-admin.jar:/home/nb136819/space/serv
ers/s1ws61/bin/https/jar/ktsearch.jar" classpathsuffix="" 
envclasspathignored="true" nativelibrarypathprefix="" debug="false" 
debugoptions="-Xdebug 
-Xrunjdwp:transport=dt_socket,server=y,suspend=n" 
dynamicreloadinterval="-1">
        
<JVMOPTIONS>-Dorg.xml.sax.parser=org.xml.sax.helpers.XMLReaderAdapter
</JVMOPTIONS>
        
<JVMOPTIONS>-Dorg.xml.sax.driver=org.apache.crimson.parser.XMLReaderImpl
</JVMOPTIONS>
        
<JVMOPTIONS>-Djava.security.manager
</JVMOPTIONS>
        
<JVMOPTIONS>-Djava.security.policy=/home/nb136819/space/servers/s1ws61
/https-admserv/config/server.policy</JVMOPTIONS>
        
<JVMOPTIONS>-Djava.security.auth.login.config=/home/nb136819/space
/servers/s1ws61/https-admserv/config/login.conf
</JVMOPTIONS>
        
<JVMOPTIONS>-Djava.util.logging.manager=com.iplanet.ias.server.logging
.ServerLogManager
</JVMOPTIONS>
        
<JVMOPTIONS>-Xms128m -Xmx256m
</JVMOPTIONS>

  <SECURITY defaultrealm="file" anonymousrole="ANYONE" audit="false">
            <AUTHREALM name="file" 
classname="com.iplanet.ias.security.auth.realm.file.FileRealm">
              
             <PROPERTY name="file" 
value="/home/nb136819/space/servers/s1ws61/https-admserv/config/keyfile">
              
             <PROPERTY name="jaas-context" value="fileRealm">
            </AUTHREALM>
    </SECURITY>
<RESOURCES> 
            </RESOURCES>
    </JAVA>
<LOG 
file="/home/nb136819/space/servers/s1ws61/https-admserv/
logs/errors" loglevel="info">

</SERVER>