NSAPI Programmer's Guide: Chapter 8 Virtual Server Configuration Files

Previous Contents Index DocHome Next

NSAPI Programmer's Guide

Chapter 8 Virtual Server Configuration Files

The server.xml file configures virtual servers. A master file, server.dtd, determines the format and content of the server.xml file. This chapter describes both these files and contains the following sections:

The server.dtd File

The server.xml File

Elements in server.dtd and server.xml

Virtual Server Selection for Request Processing

User Database Selection

The iPlanet LDAP Schema

The server.dtd File

The server.dtd file defines the various elements that the server.xml file can contain and the attributes these elements can have. The server.dtd file is located in the server_root/server_id/config directory.

Note Do not edit the server.dtd file. Its contents change only with new versions of iPlanet Web Server.

For example, the following code defines the VSCLASS (or virtual server class) element. The first line specifies that a VS element can contain VARS, VS, or QOSPARAMS elements (if this element could not contain other elements, you would see EMPTY instead of a list of element names in parentheses). The remaining lines specify that a VSCLASS element can contain id, connections, objectfile, or rootobject attributes, but only the id attribute is required.
<!ELEMENT VSCLASS (VARS?,VS*,QOSPARAMS?)>
<!ATTLIST VSCLASS
   id ID #REQUIRED
   objectfile CDATA #IMPLIED
   rootobject CDATA #IMPLIED
   acceptlanguage (yes|no|on|off|1|0) #IMPLIED

Labels such as ID and CDATA are XML data types. For more information about XML, see the XML specification at:
http://www.w3.org/TR/REC-xml

The server.xml File

The server.xml file configures the addresses and ports that the server listens on and assigns virtual servers to these listen sockets. The encoding is UTF-8 to maintain compatibility with regular UNIX text editors. The server.xml file is located in the server_root/https-server_id/config directory.
Here is a simple server.xml file. It contains two listen sockets (LS), two virtual server classes (VSCLASS), and three virtual servers (VS).
<?xml version="1.0" encoding="UTF-8"?>


<!DOCTYPE SERVER SYSTEM "server.dtd" [
<!ATTLIST VARS
   docroot CDATA #IMPLIED
   adminusers CDATA #IMPLIED
   webapps_file CDATA #IMPLIED
   webapps_enable CDATA #IMPLIED
   accesslog CDATA #IMPLIED
   user CDATA #IMPLIED
   group CDATA #IMPLIED
   chroot CDATA #IMPLIED
   dir CDATA #IMPLIED
   nice CDATA #IMPLIED
>
]>

<SERVER legacyls="ls1">
   <VARS accesslog="/iws60/https-server.iplanet.com/logs/access"/>
   <LS id="ls1" ip="1.1.1.1" port="80" security="off"
   acceptorthreads="1">
      <CONNECTIONGROUP id="group1" matchingip="default"
      servername="server.iplanet.com"
      defaultvs="server.iplanet.com"/>
   </LS>
   <LS id="ls2" ip="any" port="80" security="off"
   acceptorthreads="1">
      <CONNECTIONGROUP id="group2" matchingip="default"
      servername="server2.iplanet.com"
      defaultvs="server2.iplanet.com"/>
   </LS>
   <MIME id="mime1" file="mime.types" />
   <ACLFILE id="acl1"
   file="/iws60/httpacl/generated.https-server.iplanet.com.acl" />
   <VSCLASS id="defaultclass" objectfile="obj.conf"
   rootobject="default" >
      <VARS docroot="/iws60/docs" />
      <VS id="server.iplanet.com" connections="group1" mime="mime1"
      aclids="acl1">
         <VARS webapps_file="web-apps.xml" webapps_enable="on" />
         <USERDB id="default" database="default" />
      </VS>
   </VSCLASS>
   <VSCLASS id="class2" objectfile="class2.obj.conf"
   rootobject="default" >
      <VARS docroot="/iws60/docs/class2" />
      <VS id="server2.iplanet.com" connections="group2"
      mime="mime1" aclids="acl1">
         <VARS webapps_file="web-apps.xml" webapps_enable="on" />
         <USERDB id="default" database="default" />
      </VS>
      <VS id="acme.com" connections="group2"
      mime="mime1" aclids="acl1">
         <VARS docroot="/iws60/docs/class2/acme"
         webapps_file="web-apps.xml" webapps_enable="on" />
         <USERDB id="default" database="default" />
      </VS>
   </VSCLASS>
</SERVER>
If no virtual server (VS) can be found that matches an IP address or Host header, requests are processed using the default VS defined in the CONNECTIONGROUP. This VS could be made to output a customized error message, or even handle the request using a special document root.

Variables

Defining variables for use in the obj.conf file is not required, but it is sometimes useful. The following code defines and uses a docroot variable:
<?xml version="1.0" encoding="UTF-8"?>


<!DOCTYPE SERVER SYSTEM "server.dtd" [
<!ATTLIST VARS
   docroot CDATA #IMPLIED
   ...
>
]>
...
      <VS id="acme.com" connections="group2"
      mime="mime1" aclids="acl1">
         <VARS docroot="/iws60/docs/class2/acme"
         webapps_file="web-apps.xml" webapps_enable="on" />
         <USERDB id="default" database="default" />
      </VS>
...
This variable allows different document root directories to be assigned for different virtual servers. The variable can then be used in the obj.conf file. For example:
NameTrans fn=document-root root="$docroot"
Using this docroot variable saves you from having to define document roots for virtual server classes in the obj.conf files. It also allows you to define different document roots for different virtual servers within the same virtual server class.

Note Variable substitution is allowed only in an obj.conf file. It is not allowed in any other iPlanet Web Server configuration files.
Any variable referenced in an obj.conf file must be defined in the server.xml file at the SERVER, VSCLASS, or VS level. Defining variables with default values at the SERVER or VSCLASS level and overriding them in the VS is recommended.

Format of a Variable

A variable is found 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 ("${VARS}") is not supported. To get a regular $ character, use $$ in files 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:
<VARS
   docroot="/export/$id"
/>
If the id attribute of the containing VS is myserver, the docroot variable is set to the value /export/myserver.

Variables Used in the Interface

The following variables are used by the Administration Server, Server Manager, Class Manager, and Virtual Server Manager. Unlike the $id variable, they are not predefined in the server, and they can be overridden.

$docroot

The document root of the virtual server. Typically evaluated as the value of the document-root parameter in the obj.conf file.

$webapps_file

The path and name of the web application configuration file, which is usually web-apps.xml. For more information about web-apps.xml, see the Programmer's Guide to Servlets for iPlanet Web Server.

$webapps_enable

A flag that indicates whether web applications are enabled for a VS. Allowed values are on and off. If the webapps_file variable has a value for a VS, this variable need not be defined and is assumed to be on.

$accesslog

The log file for a virtual server.

$user

The value of the user parameter of the send-cgi SAF.

$group

The value of the group parameter of the send-cgi SAF.

$chroot

The value of the chroot parameter of the send-cgi SAF.

$dir

The value of the dir parameter of the send-cgi SAF.

$nice

The value of the nice parameter of the send-cgi SAF.

Variable Evaluation

Variables are evaluated when generating specific objset for individual virtual servers.
Evaluation is recursive: variable values can contain other variables. For example:
...
<SERVER>
   <VARS docrootbase = "/export" />
   ...
   <VSCLASS ...>
      <VARS docroot = "$docrootbase/nonjava/$id" />
      ...
   </VSCLASS>
   <VSCLASS ...>
      <VARS docroot = "$docrootbase/java/$id" />
      ...
   </VSCLASS>
   ...
</SERVER>
...
Variables lower in the tree override variables from above. 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.

Using the Server Manager and Class Manager

You can add virtual server classes and virtual servers to iPlanet Web Server through the Server Manager and Class Manager interface, as described in the iPlanet Web Server Administrator's Guide.

Elements in server.dtd and server.xml

This section describes the XML elements in the server.dtd and server.xml files. Subelements must be defined in the order in which they are listed.

SERVER
Defines a server. There can only be one of this element in a server.xml file.
Subelements: VARS, LS, MIME, ACLFILE, VSCLASS, QOSPARAMS
Attributes:

qosactive

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, 1, 0. The default is no.

qosmetricsinterval

(optional) The interval in seconds during which the traffic is measured. The default is 30.

qosrecomputeinterval

(optional) The period in milliseconds in which the bandwidth gets recomputed for all server entities. The default is 100 ms.

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, which is the default virtual server for the entire server.

VARS
Defines variables that can be given values in server.xml and referenced in obj.conf. "Variables". For a list of variables commonly defined in server.xml, see "Variables Used in the Interface".Variables Used in the Interface
Subelements: none
Attributes: none

LS (Listen Socket)
Defines a 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.

Subelements: CONNECTIONGROUP
Attributes:

id

(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. A listen socket name cannot begin with a number.

ip

IP address of the listen socket. Can be in dotted-pair or IPv6 notation. Can also be any for INADDR_ANY. Configuring a listen socket to listen on any is required if more than one CONNECTIONGROUP is configured to it.

port

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

(optional) Determines whether the listen socket runs SSL. Legal values are on, off, yes, no, 1, 0. The default is no. You can turn SSL2 or SSL3 on or off and set ciphers using an SSLPARAMS object in a CONNECTIONGROUP object.
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 7 "Syntax and Use of magnus.conf."

acceptorthreads

(optional) Number of acceptor threads for the listen socket. The recommended value is the number of processors in the machine. The default is 1, legal values are 1 - 1024.

family

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

blocking

(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. The default is no.

Caution
Blocking mode sockets should not be used in real world deployments. Use of blocking mode sockets precludes dynamic reconfiguration and exposes the server to denial of service attacks.

CONNECTIONGROUP
Defines a group of connection properties to which you can assign virtual servers. See "Virtual Server Selection for Request Processing" for more information.
Subelements: SSLPARAMS
Attributes:

id

Internal name for the connection group. A CONNECTIONGROUP name cannot begin with a number.

matchingip

IP address that the associated virtual servers use or the value default. Can be in dotted-pair or IPv6 notation. Cannot be any for INADDR_ANY. Must be default if the containing LS does not have ip=any.
If the containing LS has ip=any, 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. This affects URLs the server automatically generates; it doesn't 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 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.
Subelements: none
Attributes:

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

(optional) Determines whether SSL2 is enabled. Legal values are on, off, yes, no, 1, 0. The default is no.
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

(optional) A space-separated list of the SSL2 ciphers used, with the prefix + to enable or - to disable, for example +rc4. Allowed values are rc4export, rc2export, idea, des.

ssl3

(optional) Determines whether SSL3 is enabled. Legal values are on, off, yes, no, 1, 0. The default is yes.
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

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

(optional) Determines whether TLS is enabled. Legal values are on, off, yes, no, 1, 0. The default is on.

tlsrollback

(optional) Determines whether TLS rollback is enabled. Legal values are on, off, yes, no, 1, 0. The default is on. TLS rollback should be enabled for Microsoft Internet Explorer 5.0 and 5.5. For more information, see the iPlanet Web Server Administrator's Guide.

clientauth

(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. The default is no.

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.
Subelements: none
Attributes:

id

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

(required if no TYPE subelements are present; otherwise optional) The name of a MIME types file. For information about the format of this file, see Appendix B "MIME Types."

TYPE
Defines a MIME type.
Subelements: none
Attributes:

type

(required if no language or encoding is present) The type assigned to a matching request (the content-type header), for example text/html.

language

(required if no type or encoding is present) The encoding assigned to a matching request (the content-encoding header).

encoding

(required if no type or language is present) The language assigned to a matching request (the content-language header).

extensions

A comma-separated list of file extensions that use the same type, for example htm,html.

ACLFILE
References one or more ACL files.
Subelements: none
Attributes:

id

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

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 iPlanet Web Server 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: VARS, VS, QOSPARAMS
Attributes:

id

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

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

rootobject

(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. The default value is default.
If you specify an object that doesn't exist, the server doesn't report an error until a client tries to retrieve a document. The Server Manager assumes the default to be the object named default. Don't deviate from this convention if you use (or plan to use) the Server Manager.

acceptlanguage

(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. The default is off. Can be overridden in a VS element.

VS (Virtual Server)
Defines a virtual server.
Subelements: VARS, QOSPARAMS, USERDB
Attributes:

id

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

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

(optional) Determines whether a VS is active (on) or inactive (off, disable). The default is on (active). 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

(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. The default is off.

QOSPARAMS
Defines quality of service parameters of a SERVER, VSCLASS, or VS.
Attributes of the SERVER element activate the quality of service features. In addition, the qos-handler and qos-error SAFs must be included in the obj.conf file.
For more information, see the Performance Tuning, Sizing, and Scaling Guide for iPlanet Web Server.
Subelements: none
Attributes:

maxbps

(optional) The maximum bandwidth limit for the SERVER, VSCLASS, or VS in bytes per second.

enforcebandwidth

(optional) Specifies whether the bandwidth limit should be enforced or not. Allowed values are yes, no, on, off, 1, 0. The default is no.

maxconn

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

enforceconnections

(optional) Specifies whether the connection limit should be enforced or not. Allowed values are yes, no, on, off, 1, 0. The default is no.

USERDB
Defines the user database used by the virtual server.
See "User Database Selection" for more information about how a user database is selected for a given virtual server.
Subelements: none
Attributes:

id

The user database name in the virtual server's ACL file. A user database name cannot begin with a number.

database

The user database name in the dbswitch.conf file.

basedn

(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

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

Virtual Server Selection for Request Processing

Before the server can process a request, it must accept the request via a listen socket, then direct the request to the correct connection group and virtual server. This section discusses how the virtual server is determined.
After the virtual server is determined, the server executes the obj.conf file for the virtual server class to which the virtual server belongs. For details about how the server decides which directives to execute in obj.conf, see "Flow of Control in obj.conf.".
A connection group is first selected as follows:

If the listen socket is configured to listen on a particular IP address, it can contain only one connection group, and that group is selected.

If the listen socket is configured to listen on any, the IP address to which the client connected is matched to the matchingip attribute of a connection group contained by that listen socket. If no matchingip attribute matches, the connection group with matchingip=default is selected.
A virtual server is then selected as follows:

If the connection group is configured to only a default virtual server, that virtual server is selected.

If the connection group has more than one virtual server configured to it, the request Host header is matched to the urlhosts attribute of a virtual server. If no Host header is present or no urlhosts attribute matches, the default virtual server for the connection group is selected.
If a virtual server is configured to an SSL listen socket, its urlhosts attribute is checked against the subject pattern of the certificate at server startup, and a warning is generated and written to the error log if they don't match.

User Database Selection

A USERDB object selects a user database for the containing virtual server. How this selection occurs depends on the virtual server's ACL file and the dbswitch.conf file.
The ACL file format is unchanged from previous iPlanet Web Server versions. However, the following changes have been made in iPlanet Web Server 6.0:

Virtual servers in server.xml reference ACL files. The magnus.conf file no longer references ACL files.

The ACL file's database attribute does not map to a dbswitch.conf entry directly, but instead maps to an id attribute of a USERDB element. The database attribute of the USERDB element then maps to a dbswitch.conf entry. This extra layer between the ACL file and the dbswitch.conf file gives the server administrator full control over which databases virtual server administrators and users have access to.
iPlanet Web Server 6.0 introduces the following changes to the dbswitch.conf file and LDAP databases:

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. You can use dcsuffix if the database is schema compliant. Requirements for schema compliance are listed in "The iPlanet 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 servername attribute of the CONNECTIONGROUP. 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 accesses happen relative to the base DN in the dbswitch.conf entry, as in previous iPlanet Web Server versions.

The iPlanet LDAP Schema

You can use the dcsuffix attribute in the dbswitch.conf file if your LDAP database meets the requirements outlined in this section.
The subtree rooted at an ISP entry (for example, o=isp) is called the convergence tree. It contains all the 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.

The 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 e-mail name (specifically, it must be a valid local-part as defined in RFC822). It is recommended that the cn contain name initial sn. It is recommended that the RDN of the user entry be 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.

The 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 would contain the attribute inetDomainBaseDN with value o=Cust2,o=isp,o=root.
If an inetDomainStatus attribute is present in an entry and has a value of inactive or deleted, the entry is ignored.

Previous Contents Index DocHome Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated April 12, 2002

$docroot	The document root of the virtual server. Typically evaluated as the value of the document-root parameter in the obj.conf file.
$webapps_file	The path and name of the web application configuration file, which is usually web-apps.xml. For more information about web-apps.xml, see the Programmer's Guide to Servlets for iPlanet Web Server.
$webapps_enable	A flag that indicates whether web applications are enabled for a VS. Allowed values are on and off. If the webapps_file variable has a value for a VS, this variable need not be defined and is assumed to be on.
$accesslog	The log file for a virtual server.
$user	The value of the user parameter of the send-cgi SAF.
$group	The value of the group parameter of the send-cgi SAF.
$chroot	The value of the chroot parameter of the send-cgi SAF.
$dir	The value of the dir parameter of the send-cgi SAF.
$nice	The value of the nice parameter of the send-cgi SAF.

qosactive	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, 1, 0. The default is no.
qosmetricsinterval	(optional) The interval in seconds during which the traffic is measured. The default is 30.
qosrecomputeinterval	(optional) The period in milliseconds in which the bandwidth gets recomputed for all server entities. The default is 100 ms.
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, which is the default virtual server for the entire server.

id	(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. A listen socket name cannot begin with a number.
ip	IP address of the listen socket. Can be in dotted-pair or IPv6 notation. Can also be any for INADDR_ANY. Configuring a listen socket to listen on any is required if more than one CONNECTIONGROUP is configured to it.
port	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	(optional) Determines whether the listen socket runs SSL. Legal values are on, off, yes, no, 1, 0. The default is no. You can turn SSL2 or SSL3 on or off and set ciphers using an SSLPARAMS object in a CONNECTIONGROUP object. 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 7 "Syntax and Use of magnus.conf."
acceptorthreads	(optional) Number of acceptor threads for the listen socket. The recommended value is the number of processors in the machine. The default is 1, legal values are 1 - 1024.
family	(optional) The socket family type. The default is inet, legal values are inet, inet6, and nca. Use the value inet6 for IPv6 listen sockets. When using the value of inet6, IPv4 addresses will be prefixed with ::ffff: in the log file. Specify nca to make use of the Solaris Network Cache and Accelerator.
blocking	(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. The default is no.

id	Internal name for the connection group. A CONNECTIONGROUP name cannot begin with a number.
matchingip	IP address that the associated virtual servers use or the value default. Can be in dotted-pair or IPv6 notation. Cannot be any for INADDR_ANY. Must be default if the containing LS does not have ip=any. If the containing LS has ip=any, 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. This affects URLs the server automatically generates; it doesn't 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.

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	(optional) Determines whether SSL2 is enabled. Legal values are on, off, yes, no, 1, 0. The default is no. 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	(optional) A space-separated list of the SSL2 ciphers used, with the prefix + to enable or - to disable, for example +rc4. Allowed values are rc4export, rc2export, idea, des.
ssl3	(optional) Determines whether SSL3 is enabled. Legal values are on, off, yes, no, 1, 0. The default is yes. 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	(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_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	(optional) Determines whether TLS is enabled. Legal values are on, off, yes, no, 1, 0. The default is on.
tlsrollback	(optional) Determines whether TLS rollback is enabled. Legal values are on, off, yes, no, 1, 0. The default is on. TLS rollback should be enabled for Microsoft Internet Explorer 5.0 and 5.5. For more information, see the iPlanet Web Server Administrator's Guide.
clientauth	(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. The default is no.

id	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	(required if no TYPE subelements are present; otherwise optional) The name of a MIME types file. For information about the format of this file, see Appendix B "MIME Types."

type	(required if no language or encoding is present) The type assigned to a matching request (the content-type header), for example text/html.
language	(required if no type or encoding is present) The encoding assigned to a matching request (the content-encoding header).
encoding	(required if no type or language is present) The language assigned to a matching request (the content-language header).
extensions	A comma-separated list of file extensions that use the same type, for example htm,html.

id	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	The file name of the obj.conf file for this class of virtual servers. Cannot be overridden in a VS element.
rootobject	(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. The default value is default. If you specify an object that doesn't exist, the server doesn't report an error until a client tries to retrieve a document. The Server Manager assumes the default to be the object named default. Don't deviate from this convention if you use (or plan to use) the Server Manager.
acceptlanguage	(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. The default is off. Can be overridden in a VS element.

id	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	(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 Host 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	(optional) Determines whether a VS is active (on) or inactive (off, disable). The default is on (active). 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	(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. The default is off.

maxbps	(optional) The maximum bandwidth limit for the SERVER, VSCLASS, or VS in bytes per second.
enforcebandwidth	(optional) Specifies whether the bandwidth limit should be enforced or not. Allowed values are yes, no, on, off, 1, 0. The default is no.
maxconn	(optional) The maximum number of concurrent connections for the SERVER, VSCLASS, or VS.
enforceconnections	(optional) Specifies whether the connection limit should be enforced or not. Allowed values are yes, no, on, off, 1, 0. The default is no.

id	The user database name in the virtual server's ACL file. A user database name cannot begin with a number.
database	The user database name in the dbswitch.conf file.
basedn	(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	(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.