Sun ONE Web Server 6.1 Administrator's Configuration File Reference |
Chapter 2
Server Configuration Elements in server.xmlThe 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 module describes server.xml and sun-server_1_0.dtd in the following sections:
The sun-web-server_6_1.dtd FileThe 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 may 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.
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 ONE 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 FileThis section describes the XML elements in the server.xml file. Elements are grouped as follows:
For an alphabetical listing of elements in server.xml, see “Alphabetical List of Server Configuration Elements.”
Core Server ElementsGeneral 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.
Attributes
The following table describes attributes for the SERVER element.
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:
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>
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 PROPERTY element.
PROPERTY subelements
Element
Required
Description
zero or one
Contains a text description of the property.
Attributes
The following table describes attributes for the PROPERTY element.
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 ElementsThe Listener elements are as follows:
LS
Defines an HTTP listen socket.
Subelements
The following table describes subelements for the LS element.
LS subelements
Element
Required
Description
zero or one
Contains a text description of the listen socket.
zero or one
Defines Secure Socket Layer (SSL) parameters.
Attributes
The following table describes attributes for the LS element.
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 will be prefixed with ::ffff: in the log file. Specify nca to make use of 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 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 (Secure Socket Layer) parameters.
Subelements
none
Attributes
The following table describes attributes for the SSLPARAMS element.
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
The following table describes subelements for the MIME element.
MIME subelements
Element
Required
Description
zero or more
Specifies the mime type of the requested resource.
Attributes
The following table describes attributes for the MIME element.
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 MIME Types.
TYPE
Defines the type of the requested resource.
Subelements
none
Attributes
The following table describes attributes for the TYPE element.
ACLFILE
References one or more ACL files.
Subelements
The following table describes subelements for the ACLFILE element.
ACLFILE subelements
Element
Required
Description
zero or one
Contains a text description of the ACLFILE element.
Attributes
The following table describes attributes for the ACLFILE element.
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 ONE Web Server 6.1 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.
Attributes
The following table describes attributes for the VSCLASS element.
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.
Attributes
The following table describes attributes for the VS element.
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.
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.
USERDB subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the USERDB element.
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 ElementsThe 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.
DAV subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
zero or more
Collections for which DAV is enabled.
Attributes
The following table describes attributes for the DAV element.
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.
DAVCOLLECTION subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the DAVCOLLECTION element.
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.
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.
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 ElementsSearch elements are as follows:
SEARCH
Defines search related configuration parameters for a given VS.
Subelements
The following table describes subelements for the SEARCH element.
Attributes
The following table describes attributes for the SEARCH element.
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.
Attributes
The following table describes attributes for the SEARCHCOLLECTION element.
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 ElementsThe Web application elements are as follows:
WEBAPP
Defines a Java web application rooted at a given URI within a VS.
Subelements
The following table describes subelements for the WEBAPP element.
webapp subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the WEBAPP element.
Java Configuration ElementsThe 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.
Attributes
The following table describes attributes for the JAVA element.
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.
bytecodeprocessors
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.P ersistenceManagerFactory
</JVMOPTIONS>
For information about the available options, see:
http://java.sun.com/docs/hotspot/VMOptions.html
Subelements
none
Attributes
none
PROFILER
Configures a profiler for use with the server.
Subelements
The following table describes subelements for the PROFILER element.
PROFILER subelements
Element
Required
Description
zero or more
Specifies a property.
zero or more
Contains profiler-specific JVM command line options.
Attributes
The following table describes attributes for the PROFILER element.
SECURITY
Defines parameters and configuration information needed by the security service.
Subelements
The following table describes subelements for the SECURITY element.
SECURITY subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
one or more
Defines a realm for authentication.
Attributes
The following table describes attributes for the SECURITY element.
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:
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.
Attributes
The following table describes attributes for the AUTHREALM element.
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 ONE Web Server 6.1 Programmer's Guide to Web Applications.
Resource ElementsResource elements are as follows:
RESOURCES
Contains configured resources, such as database connections.
Subelements
The following table describes subelements for the RESOURCES element.
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.
CUSTOMRESOURCE subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the CUSTOMRESOURCE element.
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.
EXTERNALJNDIRESOURCE subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the EXTERNALJNDIRESOURCE element.
JDBCRESOURCE
Defines a JDBC (javax.sql.DataSource) resource.
Subelements
The following table describes subelements for the JDBCRESOURCE element.
JDBCRESOURCE subelements
Element
Required
Description
zero or one
Contains a text description of this element.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the JDBCRESOURCE element.
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 ONE 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.
Attributes
The following table describes attributes for the JDBCCONNECTIONPOOL element.
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:
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 ONE 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.
CONNECTIONPROPERTY
Specifies the connection properties for a JDBC connection pool.
Subelements
The following table describes subelements for the CONNECTIONPROPERTY element.
CONNECTIONPROPERTY subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the CONNECTIONPROPERTY element.
MAILRESOURCE
Defines a JavaMail (javax.mail.Session) resource.
Subelements
The following table describes subelements for the MAILRESOURCE element.
MAILRESOURCE subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the MAILRESOURCE element.
LOGConfigures 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.
Subelements
The following table describes subelements for the LOG element.
Attributes
The following table describes attributes for the LOG element.
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, fine, 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 SelectionA USERDB object selects a user database for the parent virtual server. This selection occurs in the following manner:
This 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.
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. You can use dcsuffix if the database is schema compliant. Requirements for schema compliance are listed in "The Sun ONE LDAP Schema".”
A user database is selected for a virtual server as follows:
- 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 ONE Web Server versions.
The Sun ONE LDAP SchemaThis section describes the Sun ONE 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.
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.
VariablesSome 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.
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.
For more information about the send-cgi function, see the Sun ONE Web Server 6.1 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 ONE 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/acces s"/>
<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-a dmserv.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-a pp"/>
</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-ap p"/>
</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.XMLReaderAdapt er</JVMOPTIONS>
<JVMOPTIONS>-Dorg.xml.sax.driver=org.apache.crimson.parser.XMLReade rImpl</JVMOPTIONS>
<JVMOPTIONS>-Djava.security.manager</JVMOPTIONS>
<JVMOPTIONS>-Djava.security.policy=/home/nb136819/space/servers/s1w s61/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.logg ing.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/key file"/>
<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>