| Sun ONE Application Server 7 Administrator's Configuration File Reference |
Chapter 2
Server Configuration FilesThe 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-server_1_0.dtd, determines the format and content of the server.xml file.
This chapter describes server.xml and sun-server_1_0.dtd in these sections:
The sun-server_1_0.dtd FileThe sun-server_1_0.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-server_1_0.dtd file is located in the install_dir/lib/dtds directory.
Note
Do not edit the sun-server_1_0.dtd file; its contents change only with new versions of Sun ONE Application Server.
For general information about DTD files and XML, see the XML specification at:
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 iiop-listener element.
<!ELEMENT iiop-listener (ssl?, property*)>
The ELEMENT tag specifies that an iiop-listener element can contain ssl and property 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. The left column lists the subelement ending character, and the right column lists the corresponding requirement rule.
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>shopping cart bean</description>
Attributes
Elements that have ATTLIST tags contain attributes (name-value pairs). For example:
<!ATTLIST iiop-listener id CDATA #REQUIRED
address CDATA #REQUIRED
port CDATA "3700"
enabled %boolean; "true">An iiop-listener element can contain id, address, port, 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 Application 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 Appendix B, "Alphabetical List of Server Configuration Elements".
General 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. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Attributes
The following table describes attributes for the server element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-3 server attributes
Attribute
Default
Description
name
none
Specifies the name of the server instance.
locale
operating system default
(optional) Specifies the server instance language.
log-root
instance_dir/logs
(optional) Specifies where the server instance’s log files are kept. The directory in which the server log is kept must be writable by whatever user account the server runs as. See the log-service description for details about logs.
application-root
instance_dir/applications
(optional) Specifies the absolute path where deployed applications reside for this server instance.
session-store
instance_dir/session-store
(optional) Specifies the directory where passivated beans are stored in the file system.
property
Specifies a property, or a variable that is defined in server.xml and referenced in obj.conf. For information about variables, see "Variables".
A property adds configuration information to its parent element that is one or both of the following:
For example, an auth-realm element can include property subelements:
<auth-realm 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"/>
</auth-realm>Which properties an auth-realm element uses depends on the value of the auth-realm 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. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-4 property subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the property element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
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
admin-service
This element is not implemented and should not be used.
server-instance
This element is not implemented and should not be used.
Listener Service ElementsListener service elements are as follows:
http-service
Defines the HTTP service.
For more information about the quality of service features defined in this element’s attributes, see the Sun ONE Application Server Performance Tuning, Sizing, and Scaling Guide.
Subelements
The following table describes subelements for the http-service element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Note
The http-listener, mime, acl, and virtual-server-class elements can occur in any order, but http-qos and property elements must occur second to last and last, respectively.
Attributes
The following table describes attributes for the http-service element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
http-listener
Defines an HTTP listen socket.
Note
When you create a secure listener through the Administration interface, security is automatically turned on globally in init.conf. When you create a secure listener manually in server.xml, you must manually turn on security by editing the init.conf. file’s Security directive.
Subelements
The following table describes subelements for the http-listener element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-8 http-listener subelements
Element
Required
Description
zero or one
Defines SSL parameters.
Attributes
The following table describes attributes for the http-listener element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-9 http-listener attributes
Attribute
Default
Description
id
none
The unique listener name. An http-listener name cannot begin with a number.
address
none
IP address of the listener. Can be in dotted-pair or IPv6 notation. Can be any (for INADDR_ANY) to listen on all IP addresses. Can be a hostname.
port
none
Port number on which the listener listens. Legal values are 1 - 65535. On UNIX, creating sockets that listen on ports 1 - 1024 requires superuser privileges. Configuring an SSL listener to listen on port 443 is recommended.
family
inet
(optional) The socket family type. Legal values are inet, inet6, and nca. Use the value inet6 for IPv6 listeners. If this value is inet6, IPv4 addresses are prefixed with ::ffff: in the server log. Specify nca to make use of the Solaris Network Cache and Accelerator.
acceptor-threads
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.
blocking-enabled
false
(optional) Determines whether the listener 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.
security-enabled
false
(optional) Determines whether the listener 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 ssl element.
The Security setting in the init.conf file globally enables or disables SSL by making certificates available to the server instance. Therefore, Security in init.conf must be on or security-enabled in server.xml does not work. For more information, see Chapter 3, "Syntax and Use of init.conf".
default-virtual-server
none
The id attribute of the default virtual server for this particular listener.
server-name
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.
enabled
true
(optional) Determines whether the listener is active. Legal values are on, off, yes, no, 1, 0, true, false.
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.
ssl
Defines SSL (Secure Socket Layer) parameters.
An ssl element is required inside an http-listener element that has its security-enabled attribute set to on.
An ssl element is only allowed inside an http-listener or iiop-listener element.
Subelements
none
Attributes
The following table describes attributes for the ssl element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
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
The following table describes attributes for the mime element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-11 mime attributes
Attribute
Default
Description
id
none
Internal name for the MIME types listing. Used in a virtual-server 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 information about the format of this file, see Chapter 4, "MIME Types".
acl
References an ACL file.
Subelements
none
Attributes
The following table describes attributes for the acl element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
virtual-server-class
Defines a virtual server class.
Subelements
The following table describes subelements for the virtual-server-class element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Attributes
The following table describes attributes for the virtual-server-class element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
virtual-server
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.
When you first install Sun ONE Application Server, a default virtual server is created. (You can also assign a default virtual server to each new http-listener you create.)
Note
Virtual servers are not the same thing as server instances. Each server instance is a completely separate server that contains one or more virtual servers.
Before the Sun ONE Application Server can process a request, it must accept the request via a listener, then direct the request to the correct virtual server. The virtual server is determined as follows:
- If the listener is configured to only a default virtual server, that virtual server is selected.
- If the listener has more than one virtual server configured to it, the request Host header is matched to the hosts attribute of a virtual server. If no Host header is present or no hosts attribute matches, the default virtual server for the listener is selected.
If a virtual server is configured to an SSL listener, its hosts attribute is checked against the subject pattern of the certificate at server startup, and a warning is generated and written to the server log if they don’t match.
Subelements
The following table describes subelements for the virtual-server element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Attributes
The following table describes attributes for the virtual-server element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-16 virtual-server 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.
http-listeners
none
(optional) A comma-separated list of http-listener ids that specify the connection(s) the virtual server uses. Required only for a virtual-server that is not the default-virtual-server of an http-listener.
default-web-module
none
(optional) The default web-module for this virtual server, which responds to all requests that cannot be resolved to other web modules deployed to this virtual server.
If this attribute is empty, the web-module assigned to this virtual server that has an empty context-root attribute is used. If no web-module assigned to this virtual server has an empty context-root, the system default web module is used.
config-file
virtual_server_name-obj.conf
(optional) The file name of the obj.conf file for this virtual server. Can override the value in a virtual-server-class element.
default-object
default
(optional) Tells the server which object loaded from an obj.conf file is the default. Can override the value in a virtual-server-class element.
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 Administration interface assumes the default to be the object named default. Don’t deviate from this convention if you use (or plan to use) the Administration interface.
hosts
none
A comma-separated list of values allowed in the Host request header to select the current virtual server. Each virtual-server that is configured to the same http-listener must have a unique hosts value for that listener.
mime
none
The id of the mime element used by the virtual server.
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.
acls
none
(optional) One or more id attributes of acl elements, separated by commas. Specifies the ACL file(s) used by the virtual server.
accept-language
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. Legal values are on, off, yes, no, 1, 0, true, false. Can override the value in a virtual-server-class element.
log-file
server.log in the directory specified by the log-root attribute of the server element
(optional) Writes this virtual server’s log messages to a log file separate from the server log. The file and directory in which the virtual server log is kept must be writable by whatever user account the server runs as. See the log-service description for details about logs.
Properties
The following table describes properties for the virtual-server element. The left column lists the property name, the middle column indicates the default value if the property is omitted, and the right column describes what the property does.
http-qos
Defines quality of service parameters of an http-service, virtual-server-class, or virtual-server element.
Attributes in the http-service element activate the quality of service features.
For more information, see the Sun ONE Application Server Performance Tuning, Sizing, and Scaling Guide.
Subelements
none
Attributes
The following table describes attributes for the http-qos element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
auth-db
Defines the user database used by the virtual-server; not applicable to J2EE applications.
See "User Database Selection" for more information about how a user database is selected for a given virtual server.
Subelements
none
Attributes
The following table describes attributes for the auth-db element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
iiop-service
Defines the IIOP service.
Subelements
The following table describes subelements for the iiop-service element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-20 iiop-service subelements
Element
Required
Description
only one
Configures the ORB.
zero or one
Defines SSL parameters for the ORB.
zero or more
Defines an IIOP listen socket.
Attributes
none
orb
Configures the ORB.
To enable SSL for outbound connections, include an ssl-client-config subelement in the parent iiop-service element.
Subelements
The following table describes subelements for the orb element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-21 orb subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the orb element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-22 orb attributes
Attribute
Default
Description
message-fragment-size
1024
(optional) GIOPv1.2 messages larger than this number of bytes are fragmented.
steady-thread-pool-size
10
(optional) The minimum number of worker threads in the ORB.
max-thread-pool-size
200
(optional) The maximum number of worker threads in the ORB.
idle-thread-timeout-in-seconds
300
(optional) Idle worker threads are removed from the pool after this amount of time.
max-connections
1024
(optional) The maximum number of incoming connections on all IIOP listeners. Legal values are integers.
log-level
Value of level attribute of log-service element
(optional) Controls the type of messages logged by this element to the server log. For details, see the description of the level attribute of the log-service element.
monitoring-enabled
false
(optional) Determines whether monitoring of the ORB is enabled. Legal values are on, off, yes, no, 1, 0, true, false.
ssl-client-config
Defines SSL parameters for the ORB when it makes outbound SSL connections and behaves as a client.
Subelements
The following table describes subelements for the ssl-client-config element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-23 ssl-client-config subelements
Element
Required
Description
only one
Defines SSL parameters.
Attributes
none
iiop-listener
Defines an IIOP listen socket.
To enable SSL for this listener, include an ssl subelement.
Note
When you create a secure listener through the Administration interface, security is automatically turned on globally in init.conf. When you create a secure listener manually in server.xml, you must manually turn on security by editing the init.conf. file’s Security directive.
Subelements
The following table describes subelements for the iiop-listener element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-24 iiop-listener subelements
Element
Required
Description
zero or one
Defines SSL parameters.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the iiop-listener element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Container ElementsContainer configuration elements are as follows:
web-container
Configures the web container.
Subelements
The following table describes subelements for the web-container element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-26 web-container subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the web-container element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-27 web-container attributes
Attribute
Default
Description
monitoring-enabled
false
(optional) Determines whether monitoring of the web container is enabled. Legal values are on, off, yes, no, 1, 0, true, false.
log-level
Value of level attribute of log-service element
(optional) Controls the type of messages logged by this element to the server log. For details, see the description of the level attribute of the log-service element.
ServletContext.log messages are logged at the INFO level by default.
ejb-container
Configures the EJB container. Stateless session beans are maintained in pools. Stateful session beans have session affinity and are cached. Entity beans associated with a database primary key are also cached. Entity beans not yet associated with a primary key are maintained in pools. Pooled entity beans are used to run ejbCreate() and finder methods.
Subelements
The following table describes subelements for the ejb-container element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-28 ejb-container subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the ejb-container element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-29 ejb-container attributes
Attribute
Default
Description
steady-pool-size
32
(optional) Specifies the initial and minimum number of beans maintained in the pool. Must be 0 or greater and less than max-pool-size.
Bean instances are removed from the pool and returned after use. The pool is replenished or cleaned up periodically to maintain this size.
Applies to stateless session beans and entity beans.
pool-resize-quantity
16
(optional) Specifies the number of beans to be:
Must be 0 or greater and less than max-pool-size. The pool is not resized below the steady-pool-size.
Applies to stateless session beans and entity beans.
max-pool-size
64
(optional) Specifies the maximum number of beans that can be created to satisfy client requests. A value of 0 indicates an unbounded pool.
Applies to stateless session beans and entity beans.
cache-resize-quantity
16
(optional) Specifies the number of beans to be:
Must be greater than 1 and less than max-cache-size.
Applies to stateful session beans and entity beans.
max-cache-size
512
(optional) Specifies the maximum number of beans in the cache. A value of 0 indicates an unbounded cache.
Applies to stateful session beans and entity beans.
pool-idle-timeout-in-seconds
600
(optional) Specifies the maximum time that a bean can remain idle in the pool. After this amount of time, the pool can remove this bean. A value of 0 specifies that idle beans can remain in the pool indefinitely.
Applies to stateless session beans and entity beans.
cache-idle-timeout-in-seconds
600
(optional) Specifies the maximum time that a bean can remain idle in the cache. After this amount of time, the container can passivate this bean. A value of 0 specifies that beans may never become candidates for passivation.
Applies to stateful session beans and entity beans.
removal-timeout-in-seconds
5400
(optional) Specifies the amount of time that a bean can remain passivated before it is removed from the session store. A value of 0 specifies that the container does not remove inactive beans automatically.
If removal-timeout-in-seconds is less than or equal to cache-idle-timeout-in-seconds, beans are removed immediately without being passivated.
The session-store attribute of the server element determines the location of the session store.
Applies to stateful session beans and entity beans.
victim-selection-policy
nru
(optional) Specifies how entity and stateful session beans are selected for passivation. Allowed values are fifo, lru, and nru:
commit-option
B
(optional) Determines which commit option is used for entity beans. Legal values are B or C.
log-level
Value of level attribute of log-service element
(optional) Controls the type of messages logged by this element to the server log. For details, see the description of the level attribute of the log-service element.
monitoring-enabled
false
(optional) Determines whether monitoring of the EJB container is enabled. Legal values are on, off, yes, no, 1, 0, true, false.
mdb-container
Configures the message-driven bean (MDB) container.
Subelements
The following table describes subelements for the mdb-container element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-30 mdb-container subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the mdb-container element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-31 mdb-container attributes
Attribute
Default
Description
steady-pool-size
10
(optional) Specifies the initial and minimum number of beans maintained in the pool.
pool-resize-quantity
2
(optional) Specifies the number of beans to be created if a request arrives when the pool is empty (subject to the max-pool-size limit), or the number of beans to remove if idle for more than idle-timeout-in-seconds.
max-pool-size
60
(optional) Specifies the maximum number of beans that can be created to satisfy client requests.
idle-timeout-in-seconds
600
(optional) Specifies the maximum time that a bean can remain idle in the pool. After this amount of time, the bean is destroyed.
log-level
Value of level attribute of log-service element
(optional) Controls the type of messages logged by this element to the server log. For details, see the description of the level attribute of the log-service element.
monitoring-enabled
false
(optional) Determines whether monitoring of the message-driven bean (MDB) container is enabled. Legal values are on, off, yes, no, 1, 0, true, false.
Properties
The following table describes properties for the mdb-container element. The left column lists the property name, the middle column indicates the default value if the property is omitted, and the right column describes what the property does.
J2EE Service ElementsJ2EE service elements are as follows:
jms-service
Configures the built-in Java Message Service (JMS) that is managed by the Sun ONE Application Server.
Subelements
The following table describes subelements for the jms-service element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-33 jms-service subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the jms-service element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-34 jms-service attributes
Attribute
Default
Description
port
7676
(optional) Specifies the port number used by the JMS provider.
admin-user-name
admin
Specifies the administrator user name for the JMS provider.
admin-password
admin
Specifies the administrator password for the JMS provider.
init-timeout-in-seconds
60
(optional) Specifies the amount of time the server instance waits at startup for the corresponding JMS instance to respond. If there is no response, startup is aborted. If set to 0, the server instance waits indefinitely.
start-args
none
(optional) Specifies the string of arguments supplied for startup of the corresponding JMS instance.
log-level
Value of level attribute of log-service element
(optional) Controls the type of messages logged by this element to the server log. For details, see the description of the level attribute of the log-service element.
enabled
true
(optional) If set to true, the Sun ONE Application Server instance is responsible for starting up and shutting down the JMS provider. If set to false, the Sun ONE Application Server instance does not start up nor shut down the JMS provider (either because the JMS provider is not used or because it is managed independently of the Sun ONE Application Server).
Legal values are on, off, yes, no, 1, 0, true, false.
Properties
The following table describes properties for the jms-service element. The left column lists the property name, the middle column indicates the default value if the property is omitted, and the right column describes what the property does.
log-service
Configures the system logging service, which includes the following log files:
- The server log file stores messages from the default virtual server. Messages from other configured virtual servers also go here, unless the log-file attribute is explicitly specified in the virtual-server-class or virtual-server element. The default name is server.log.
- 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 init.conf and obj.conf files. For more information, see the Sun ONE Application Server Developer’s Guide to NSAPI.
- The transaction log files store transaction messages from the default virtual server. The default name of the directory for these files is tx.
- A virtual server log file stores messages from a virtual-server-class or virtual-server element that has an explicitly specified log-file attribute.
Subelements
The following table describes subelements for the log-service element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-36 log-service subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the log-service element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-37 log-service attributes
Attribute
Default
Description
file
server.log
in the directory specified by the log-root attribute of the server element
(optional) Overrides the name or location of the server log. The file and directory in which the server log is kept must be writable by whatever user account the server runs as.
If you specify an absolute path, this value overrides the log-root attribute of the server element.
If you specify a relative path, it is relative to the log-root attribute of the server element. If no log-root value is specified, it is relative to instance_dir/config.
level
INFO
(optional) Controls the default type of messages logged by other elements to the server log. Many other elements can override this default in their log-level attributes. Allowed values are, from highest to lowest: FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE, ALERT, FATAL.
Each value logs all messages for all lower values; for example, FINEST logs all messages, and FATAL logs only FATAL messages. The default value is SEVERE, which logs all SEVERE, ALERT, and FATAL messages.
log-stdout
true
(optional) If true, redirects stdout output to the server log. Legal values are on, off, yes, no, 1, 0, true, false.
log-stderr
true
(optional) If true, redirects stderr output to the server log. Legal values are on, off, yes, no, 1, 0, true, false.
echo-log-messages-to-stderr
true
(optional) If true, sends log messages to stderr in addition to the server log. Legal values are on, off, yes, no, 1, 0, true, false.
create-console
false
(optional, Windows only) If true, creates a Windows console for stderr output. Legal values are on, off, yes, no, 1, 0, true, false.
log-virtual-server-id
false
(optional) If true, virtual server IDs are displayed in the virtual server logs. This is useful if multiple virtual-server elements share the same log file. Legal values are on, off, yes, no, 1, 0, true, false.
use-system-logging
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.
security-service
Defines parameters and configuration information needed by the J2EE security service.
Subelements
The following table describes subelements for the security-service element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-38 security-service subelements
Element
Required
Description
one or more
Defines a realm for authentication.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the security-service element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-39 security-service attributes
Attribute
Default
Description
default-realm
file
(optional) Specifies the active authentication realm (an auth-realm name attribute) for this server instance.
default-principal
none
(optional) Used as the identity of the default security context when necessary and when no principal is provided. This attribute need not be set for normal server operation.
default-principal-password
none
(optional) The password of the default principal. This attribute need not be set for normal server operation.
anonymous-role
ANYONE
(optional) Used as the name for default, or anonymous, role. The anonymous role is always assigned to all principals. This role value can be used in J2EE deployment descriptors to grant access to anyone.
audit-enabled
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:
log-level
Value of level attribute of log-service element
(optional) Controls the type of messages logged by this element to the server log. For details, see the description of the level attribute of the log-service element.
auth-realm
Defines a realm for authentication.
Authentication realms require provider-specific properties, which vary depending on what a particular implementation needs.
For more information about how to define realms, see the Sun ONE Application Server Developer’s Guide.
Here is an example of the default file realm:
<auth-realm 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"/>
</auth-realm>Which properties an auth-realm element uses depends on the value of the auth-realm 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 auth-realm element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-40 auth-realm subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the auth-realm element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-41 auth-realm 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 with Sun ONE Application Server have required and optional properties. A custom realm may have different properties.
The following table describes properties for the auth-realm element. The left column lists the property name, the middle column indicates the standard realms that use the property, and the right column describes what the property does.
transaction-service
Configures the Java Transaction Service (JTS).
Subelements
The following table describes subelements for the transaction-service element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-43 transaction-service subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the transaction-service element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-44 transaction-service attributes
Attribute
Default
Description
automatic-recovery
false
(optional) If true, the server instance attempts transaction recovery during startup. Legal values are on, off, yes, no, 1, 0, true, false.
timeout-in-seconds
0
(optional) Specifies the amount of time after which the transaction is aborted. If set to 0, the transaction never times out.
tx-log-dir
directory specified by the log-root attribute of the server element
(optional) Overrides the location of the transaction log directory. The directory in which the transaction logs are kept must be writable by whatever user account the server runs as. See the log-service description for details about logs.
heuristic-decision
rollback
(optional) During recovery, if the outcome of a transaction cannot be determined from the logs, this property determines the outcome. Allowed values are rollback and commit.
keypoint-interval
2048
(optional) Specifies the number of transactions between keypoint operations in the log. Keypoint operations reduce the size of the transaction log file by compressing it. A larger value for this attribute (for example, 4096) results in a larger transaction log file, but fewer keypoint operations and potentially better performance. A smaller value (for example, 100) results in smaller log files, but slightly reduced performance due to the greater frequency of keypoint operations.
log-level
Value of level attribute of log-service element
(optional) Controls the type of messages logged by this element to the server log. For details, see the description of the level attribute of the log-service element.
monitoring-enabled
false
(optional) Determines whether monitoring of the JTS is enabled. Legal values are on, off, yes, no, 1, 0, true, false. The default is false.
Properties
The following table describes properties for the transaction-service element. The left column lists the property name, the middle column indicates the default value if the property is omitted, and the right column describes what the property does.
Java Configuration ElementsJava configuration elements are as follows:
java-config
Specifies Java Virtual Machine (JVM) configuration parameters.
Subelements
The following table describes subelements for the java-config element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Attributes
The following table describes attributes for the java-config element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-47 java-config attributes
Attribute
Default
Description
java-home
none
The path to the directory where the JDK is installed.
debug-enabled
false
(optional) If true, the server starts up in debug mode ready for attachment with a JPDA-based debugger. Legal values are on, off, yes, no, 1, 0, true, false.
debug-options
-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n
(optional) Specifies JPDA (Java Platform Debugger Architecture) options. A list of debugging options that you can include is available here:
http://java.sun.com/products/jpda/ doc/conninv.html#Invocation
For more information about debugging, see the Sun ONE Application Server Developer’s Guide.
rmic-options
-iiop -poa -alwaysgenerate -keepgenerated -g
(optional) Specifies options passed to the RMI compiler at application deployment time. The -keepgenerated option saves generated source for stubs and ties.
For more information about the rmic command, see the Sun ONE Application Server Developer’s Guide to Enterprise JavaBeans Technology.
javac-options
-g
(optional) Specifies options passed to the Java compiler at application deployment time.
classpath-prefix
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.
server-classpath
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").
classpath-suffix
none
(optional) Specifies a suffix for the system classpath.
native-library-path-prefix
none
(optional) Specifies a prefix for the native library path.
The native library path is the automatically constructed concatenation of the Sun ONE Application Server installation relative path for its native shared libraries, the standard JRE 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.
native-library-path-suffix
none
(optional) Specifies a suffix for the native library path.
bytecode-preprocessors
(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.
env-classpath-ignored
true
(optional) If false, the CLASSPATH environment variable is read and appended to the Sun ONE Application 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.
profiler
Configures a profiler for use with Sun ONE Application Server. For more information about profilers, see the Sun ONE Application Server Developer’s Guide.
Subelements
The following table describes subelements for the profiler element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-48 profiler subelements
Element
Required
Description
zero or more
Contains profiler-specific JVM command line options.
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the profiler element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
jvm-options
Contains JVM command line options, for example:
<jvm-options>-Xdebug -Xmx128m</jvm-options>
For information about the options you can use, see:
http://java.sun.com/docs/hotspot/VMOptions.html
Subelements
none
Attributes
none
Resource ElementsResource elements are as follows:
resources
Contains configured resources, such as database connections, JavaMail sessions, and so on.
Subelements
The following table describes subelements for the resources element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Attributes
none
custom-resource
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 custom-resource element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-51 custom-resource 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 custom-resource element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
external-jndi-resource
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 external-jndi-resource element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-53 external-jndi-resource 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 external-jndi-resource element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
jdbc-resource
Defines a JDBC (javax.sql.DataSource) resource.
Subelements
The following table describes subelements for the jdbc-resource element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-55 jdbc-resource 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 jdbc-resource element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-56 jdbc-resource attributes
Attribute
Default
Description
jndi-name
none
Specifies the JNDI name for the resource.
pool-name
none
Specifies the name of the associated JDBC connection pool, defined in a jdbc-connection-pool element.
enabled
true
(optional) Determines whether this resource is enabled at runtime. Legal values are on, off, yes, no, 1, 0, true, false.
mail-resource
Defines a JavaMail (javax.mail.Session) resource.
Subelements
The following table describes subelements for the mail-resource element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-57 mail-resource 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 mail-resource element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Properties
You can set properties for the mail-resource element and then get these properties in a JavaMail Session object later. Every property name must start with a mail- prefix. Sun ONE Application Server the changes the dash (-) character to a period (.) in the name of the property and saves the property to the MailConfiguration and JavaMail Session objects. If the name of the property doesn’t start with mail-, the property is ignored.
For example, if you want to define the property mail.password in a JavaMail Session object, first edit server.xml as follows:
...
<mail-resource jndi-name="mail/Session" ...>
<property name="mail-password" value="adminadmin"/>
</mail-resource>
...After you get the JavaMail Session object, you can get the mail.password property to retrieve the value adminadmin, as follows:
String password = session.getProperty("mail.password");
jms-resource
Defines a JMS (Java Message Service) resource.
Subelements
The following table describes subelements for the jms-resource element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-59 jms-resource 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 jms-resource element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Properties
The following table describes properties for the jms-resource element. The left column lists the property name, the middle column indicates the default value if the property is omitted, and the right column describes what the property does.
Table 2-61 jms-resource properties
Property
Default
Description
imqDestinationName
none
Specifies the JMS physical destination name associated with this JMS resource. You must specify this property for jms-resource elements with the res-type of javax.jms.Topic or javax.jms.Queue.
The Sun ONE Message Queue Administrator's Guide shows a default value for this property, but this does not apply in the Sun ONE Application Server environment.
imqBrokerHostName
the same host name as the Sun ONE Application Server instance (localhost)
Specifies the host name where the JMS service (Sun ONE Message Queue broker) is running. For jms-resource elements with the res-type of javax.jms.TopicConnectionFactory or javax.jms.QueueConnectionFactory.
imqBrokerHostPort
the jms-service element’s port attribute
Specifies the port where the JMS service (Sun ONE Message Queue broker) is running. For jms-resource elements with the res-type of javax.jms.TopicConnectionFactory or javax.jms.QueueConnectionFactory.
imqConfiguredClientID
none
Specifies the JMS Client Identifier to be associated with a Connection created using the createQueueConnection and createTopicConnection JMS APIs of the QueueConnectionFactory and TopicConnectionFactory classes, respectively.
For jms-resource elements with the res-type of javax.jms.TopicConnectionFactory or javax.jms.QueueConnectionFactory.
Durable subscription names are unique and only valid within the scope of a client identifier. To create or reactivate a durable subscriber, the connection must have a valid client identifier. The JMS specification ensures that client identifiers are unique and that a given client identifier is allowed to be used by only one active connection at a time.
persistence-manager-factory-resource
Defines a persistence manager factory resource for container-managed persistence (CMP).
Subelements
The following table describes subelements for the persistence-manager-factory-resource element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-62 persistence-manager-factory-resource 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 persistence-manager-factory-resource element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-63 persistence-manager-factory-resource attributes
Attribute
Default
Description
jndi-name
none
Specifies the JNDI name for the resource.
factory-class
com.sun.jdo.spi.persistence.support.sqlstore.impl.PersistenceManagerFactoryImpl
(optional) Specifies the name of the factory class. This attribute supports third party CMP persistence manager factories. Use the name required by the third party CMP implementation. Do not specify this attribute for the built-in CMP implementation.
jdbc-resource-jndi-name
none
(optional) Specifies the jdbc-resource from which database connections are obtained. Must be the jndi-name of an existing jdbc-resource.
enabled
true
(optional) Determines whether this resource is enabled at runtime. Legal values are on, off, yes, no, 1, 0, true, false.
jdbc-connection-pool
Defines the properties that are required for creating a JDBC connection pool.
Tip
You can create a pool definition and then copy, paste, and edit it to configure multiple JDBC data sources.
Subelements
The following table describes subelements for the jdbc-connection-pool element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-64 jdbc-connection-pool 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 jdbc-connection-pool element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-65 jdbc-connection-pool attributes
Attribute
Default
Description
name
none
Specifies the name of the connection pool. A jdbc-resource element’s pool-name attribute refers to this name.
datasource-classname
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.
res-type
javax.sql.DataSource
(optional) Specifies the interface the data source class implements. The value of this attribute can be javax.sql.DataSource or javax.sql.XADataSource. If the value is not one of these interfaces, the default is used. An error occurs if this attribute has a legal value and the indicated interface is not implemented by the data source class.
steady-pool-size
8
(optional) Specifies the initial and minimum number of connections maintained in the pool.
max-pool-size
32
(optional) Specifies the maximum number of connections that can be created to satisfy client requests.
max-wait-time-in-millis
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.
pool-resize-quantity
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.
idle-timeout-in-seconds
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.
transaction-isolation-level
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 is-isolation-level-guaranteed for more details.
is-isolation-level-guaranteed
true
(optional) Applicable only when transaction-isolation-level 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.
is-connection-validation-required
false
(optional) Specifies whether connections have to 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.
connection-validation-method
auto-commit
(optional) Legal values are as follows:
validation-table-name
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 connection-validation-type is set to table.
fail-all-connections
false
(optional) If true, closes all connections in the pool if a single validation check fails. This parameter is mandatory if and only if is-connection-validation-required 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 Application Server, some properties may be necessary for most databases. For details, see Section 5.3 of JDBC 2.0 Standard Extension API.
When properties are specified, they are passed to the vendor’s data source class (specified by the datasource-classname attribute) as is using setName(value) methods.
The user and password properties are used as the default principal if container managed authentication is specified and a default-resource-principal is not found in the application deployment descriptors.
The following table describes some common properties for the jdbc-connection-pool element. The left column lists the property name, and the right column describes what the property does.
Application ElementsApplication elements are as follows:
applications
Contains deployed J2EE applications, J2EE modules, and Lifecycle modules.
Subelements
The following table describes subelements for the applications element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Attributes
The following table describes attributes for the applications element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
lifecycle-module
Specifies a deployed lifecycle module. For more information about lifecycle modules, see the Sun ONE Application Server Developer’s Guide.
Subelements
The following table describes subelements for the lifecycle-module element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-69 lifecycle-module 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 lifecycle-module element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-70 lifecycle-module attributes
Attribute
Default
Description
name
none
The name of the lifecycle module.
class-name
none
The fully qualified name of the lifecycle module’s class file, which must implement the com.sun.appserv.server.LifecycleListener interface.
classpath
value of application-root attribute of server element
(optional) The classpath for the lifecycle module. Specifies where the module is located.
load-order
none
(optional) Determines the order in which lifecycle modules are loaded at startup. Modules with smaller integer values are loaded sooner. Values can range from 101 to the operating system’s MAXINT. Values from 1 to 100 are reserved.
is-failure-fatal
false
(optional) Determines whether the server is shut down if the lifecycle module fails. Legal values are on, off, yes, no, 1, 0, true, false.
enabled
true
(optional) Determines whether the lifecycle module is enabled. Legal values are on, off, yes, no, 1, 0, true, false.
j2ee-application
Specifies a deployed J2EE application.
Subelements
The following table describes subelements for the j2ee-application element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-71 j2ee-application subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the j2ee-application element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
ejb-module
Specifies a deployed EJB module.
Subelements
The following table describes subelements for the ejb-module element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-73 ejb-module subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the ejb-module element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
web-module
Specifies a deployed web module.
Subelements
The following table describes subelements for the web-module element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-75 web-module subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the web-module element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-76 web-module attributes
Attribute
Default
Description
name
none
The name of the web module.
context-root
empty string
The context root (context path without the / in front) at which the web module is installed (see Section 5.4 of the Servlet 2.3 specification).
If this attribute is an empty string, which is the default value, this web module can be the default web module for the virtual-server elements specified in the virtual-servers attribute.
If multiple web modules assigned to a virtual server have an empty context root, one of them is loaded, and the rest generate error messages such as: Virtual server [virtual_server] already has a web module loaded at [/].
location
none
A fully qualified or relative path to the directory to which the contents of the .war file have been extracted. If relative, it is relative to the following directory:
instance_dir/applications/j2ee-modules/
virtual-servers
all virtual servers
(optional) The virtual-server elements to which the web module is deployed.
enabled
true
(optional) Determines whether the web module is enabled. Legal values are on, off, yes, no, 1, 0, true, false.
connector-module
Specifies a deployed connector module.
Subelements
The following table describes subelements for the connector-module element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-77 connector-module subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the connector-module element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
User Database Selection
Note
The user database applies only to the security of the server itself. It is not related to J2EE application and module security.
The auth-db element in server.xml selects a user database for the parent virtual-server element as follows:
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 auth-db element.
- A 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:
- If a virtual-server has no auth-db subelement, user- or group-based ACLs fail.
- When no database attribute is present in a virtual server’s ACL definition, the virtual-server must have an auth-db subelement with an id attribute of default. The database attribute of the auth-db 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 virtual-server element’s hosts attribute that matches the client-supplied Host header. If no hosts attribute matches, the server-name attribute of the parent http-listener 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 auth-db 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 Sun ONE Application Server versions.
The Sun ONE LDAP SchemaYou 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.
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 virtual-server 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 virtual-server element is myserver, the docroot variable is set to the value /export/myserver.
Other Important Variables
The following variables are used in various parts of the Sun ONE Application Server configuration. 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 Application Server Developer’s Guide to NSAPI.
Variable Evaluation
Variables are evaluated when generating specific objsets for individual virtual servers. Evaluation is recursive: variable values can contain other variables. For example:
...
<virtual-server-class>
...
<virtual-server ...>
...
<property name=docroot value="$docrootbase/nonjava/$id" />
</virtual-server>
<virtual-server ...>
...
<property name=docroot value="$docrootbase/java/$id" />
</virtual-server>
...
<property name=docrootbase value="/export" />
</virtual-server-class>
...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 FileWhen you first install the Windows version of Sun ONE Application Server, the server.xml file looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<!-- server_7_0_dtd version: 1.1.2.39 -->
<!DOCTYPE server PUBLIC "-//Sun Microsystems Inc.//DTD Sun ONE Application Server 7.0//EN" "file:///C:/Sun/AppServer7/lib/dtds/sun-server_1_0.dtd">
<server name="server1" log-root="C:/Sun/AppServer7/domains/domain1/server1/logs" application-root="C:/Sun/AppServer7/domains/domain1/server1/applications" session-store="C:/Sun/AppServer7/domains/domain1/server1/session-store">
<http-service qos-enabled="false">
<http-listener id="http-listener-1" address="0.0.0.0" port="1024" acceptor-threads="1" blocking-enabled="false" security-enabled="false" default-virtual-server="server1" server-name="goliath" enabled="true"/>
<mime id="mime1" file="mime.types"/>
<acl id="acl1" file="C:/Sun/AppServer7/domains/domain1/server1/config/generated.server1.acl"/>
<virtual-server-class id="defaultclass" config-file="obj.conf" default-object="default" accept-language="false" enabled="true">
<virtual-server id="server1" http-listeners="http-listener-1" hosts="goliath" mime="mime1" state="on" accept-language="false">
<auth-db id="default" database="default"/>
<property name="dir" value=""/>
<property name="nice" value=""/>
<property name="user" value=""/>
<property name="group" value=""/>
<property name="chroot" value=""/>
<property name="docroot" value="C:/Sun/AppServer7/domains/domain1/server1/docroot"/>
<property name="accesslog" value="C:/Sun/AppServer7/domains/domain1/server1/logs/access"/>
</virtual-server>
</virtual-server-class>
</http-service>
<iiop-service>
<orb message-fragment-size="1024" steady-thread-pool-size="10" max-thread-pool-size="200" idle-thread-timeout-in-seconds="300" max-connections="1024" monitoring-enabled="false"/>
<iiop-listener id="orb-listener-1" address="goliath" port="3700" enabled="true">
</iiop-listener>
</iiop-service>
<web-container monitoring-enabled="false" >
</web-container>
<ejb-container steady-pool-size="32" pool-resize-quantity="16" max-pool-size="64" cache-resize-quantity="32" max-cache-size="512" pool-idle-timeout-in-seconds="600" cache-idle-timeout-in-seconds="600" removal-timeout-in-seconds="5400" victim-selection-policy="nru" commit-option="B" monitoring-enabled="false">
</ejb-container>
<mdb-container steady-pool-size="10" pool-resize-quantity="2" max-pool-size="60" idle-timeout-in-seconds="600" monitoring-enabled="false">
</mdb-container>
<jms-service port="7676" admin-user-name="admin" admin-password="admin" init-timeout-in-seconds="30" enabled="true">
</jms-service>
<log-service file="C:/Sun/AppServer7/domains/domain1/server1/logs/server.log" level="INFO" log-stdout="true" log-stderr="true" echo-log-messages-to-stderr="true" create-console="true" log-virtual-server-id="false" use-system-logging="false">
</log-service>
<security-service default-realm="file" anonymous-role="ANYONE" audit-enabled="false">
<auth-realm name="file" classname="com.iplanet.ias.security.auth.realm.file.FileRealm">
<property name="file" value="C:/Sun/AppServer7/domains/domain1/server1/config/keyfile"/>
<property name="jaas-context" value="fileRealm"/>
</auth-realm>
<auth-realm name="ldap" classname="com.iplanet.ias.security.auth.realm.ldap.LDAPRealm">
<property name="directory" value="ldap://localhost:389"/>
<property name="base-dn" value="o=isp"/>
<property name="jaas-context" value="ldapRealm"/>
</auth-realm>
<auth-realm name="certificate" classname="com.iplanet.ias.security.auth.realm.certificate.CertificateRealm">
</auth-realm>
<!--
<auth-realm name="solaris" classname="com.iplanet.ias.security.auth.realm.solaris.SolarisRealm">
<property name="jaas-context" value="solarisRealm"/>
</auth-realm>
-->
</security-service>
<transaction-service automatic-recovery="false" timeout-in-seconds="0" tx-log-dir="C:/Sun/AppServer7/domains/domain1/server1/logs" heuristic-decision="rollback" keypoint-interval="2048" monitoring-enabled="false">
</transaction-service>
<java-config java-home="C:/Sun/AppServer7/jdk" server-classpath="C:/Sun/AppServer7/lib/appserv-rt.jar;C:/Sun/AppServer7/jdk/lib/ tools.jar;C:/Sun/AppServer7/lib/appserv-ext.jar;C:/Sun/AppServer7/lib/appserv-cmp .jar;C:/Sun/AppServer7/lib/appserv-ideplugin.jar;C:\Sun\AppServer7\imq\lib/imq.ja r;C:\Sun\AppServer7\imq\lib/jaxm-api.jar;C:\Sun\AppServer7\imq\lib/imqadmin.jar;C :\Sun\AppServer7\imq\lib/imqutil.jar;C:/Sun/AppServer7/lib/appserv-admin.jar;C:\S un\AppServer7\share\lib/jaxrpc-impl.jar;C:\Sun\AppServer7\share\lib/jaxrpc-api.ja r;C:\Sun\AppServer7\share\lib/jaxr-impl.jar;C:\Sun\AppServer7\share\lib/jaxr-api. jar;C:\Sun\AppServer7\share\lib/jhall.jar;C:\Sun\AppServer7\share\lib/activation. jar;C:\Sun\AppServer7\share\lib/mail.jar;C:\Sun\AppServer7\share\lib/saaj-api.jar ;C:\Sun\AppServer7\share\lib/saaj-impl.jar;C:\Sun\AppServer7\share\lib/commons-lo gging.jar;C:\Sun\AppServer7\imq\lib/fscontext.jar;C:\Sun\AppServer7\imq\lib/provi derutil.jar;C:/Sun/AppServer7/lib/appserv-jstl.jar" classpath-suffix="C:/Sun/AppServer7/pointbase/client_tools/lib/pbclient42RE.jar" env-classpath-ignored="true" debug-options="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n" debug-enabled="false" javac-options="-g">
<jvm-options>-Dorg.xml.sax.parser=org.xml.sax.helpers.XMLReaderAdapter </jvm-options>
<jvm-options>-Dorg.xml.sax.driver=org.apache.crimson.parser.XMLReaderImpl </jvm-options>
<jvm-options>-Djava.security.policy=C:/Sun/AppServer7/domains/domain1/server1/con fig/server.policy</jvm-options>
<jvm-options>-Djava.security.auth.login.config=C:/Sun/AppServer7/domains/domain1/ server1/config/login.conf</jvm-options>
<jvm-options>-Dcom.sun.jdo.api.persistence.model.multipleClassLoaders=reload </jvm-options>
<jvm-options>-Djava.util.logging.manager=com.iplanet.ias.server.logging.ServerLog Manager</jvm-options>
<jvm-options>-Dcom.sun.aas.configRoot=C:/Sun/AppServer7\config</jvm-options>
<jvm-options>-Dcom.sun.aas.imqLib=C:\Sun\AppServer7\imq\lib</jvm-options>
<jvm-options>-Dcom.sun.aas.imqBin=C:\Sun\AppServer7\imq\bin</jvm-options>
<jvm-options>-Dcom.sun.aas.webServicesLib=C:\Sun\AppServer7\share\lib</jvm-option s>
<jvm-options>-Dsun.rmi.dgc.server.gcInterval=300000</jvm-options>
<jvm-options> -Xrs -Xms128m -Xmx256m </jvm-options>
</java-config>
<resources>
</resources>
<applications dynamic-reload-enabled="false" dynamic-reload-poll-interval-in-seconds="2">
</applications>
</server>
