Previous Contents Index Next |
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Administrator's Configuration File Reference

> ## Chapter 2
> Server Configuration Files

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

> This chapter describes server.xml and sun-server_1_1.dtd in these sections:

> - The sun-server_1_1.dtd File
> - Elements in the server.xml File
> - General Elements
> - Listener Service Elements
> - Container Elements
> - Availability Elements
> - J2EE Service Elements
> - Java Configuration Elements
> - Resource Elements
> - Application Elements
> - User Database Selection
> - The Sun Java System LDAP Schema
> - Variables
> - Sample server.xml File

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

> ##

> The sun-server_1_1.dtd File

> The sun-server_1_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-server_1_1.dtd file is located in the install_dir/lib/dtds directory.

> Note | Do not edit the sun-server_1_1.dtd file; its contents change only with new versions of Sun Java System Application Server.

> Note | The sun-server_1_1.dtd interface is Unstable. An unstable interface may be experimental or transitional, and hence may change incompatibly, be removed, or be replaced by a more stable interface in the next release.

> For general information about DTD files and XML, see the XML specification at:

> http://www.w3.org/TR/REC-xml

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

> - Subelements
> - Data
> - Attributes

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

> Table 2-1 Requirement Rules and Subelement Suffixes

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

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

> ### Data

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

> <!ELEMENT element-name (#PCDATA)>

> For example:

> <!ELEMENT description (#PCDATA)>

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

> <description>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 Java System 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 File

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

> - General Elements
> - Listener Service Elements
> - Container Elements
> - J2EE Service Elements
> - Java Configuration Elements
> - Resource Elements
> - Application Elements

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

> For an alphabetical listing of elements in server.xml, see Appendix B, "Alphabetical List of Server Configuration Elements."

> ##

> General Elements

> General elements are as follows:

> - server
> - property
> - description
> - admin-service
> - server-instance

> ### server

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

> ##### Subelements

> The following table describes subelements for the server element.

> Table 2-2 server Subelements

> Element | Required | Description
> --- | --- | ---
> http-service | only one | Defines the HTTP service.
> iiop-service | only one | Defines the IIOP service.
> admin-service | zero or one | Not implemented.
> web-container | only one | Configures the web container.
> ejb-container | only one | Configures the Enterprise JavaBeans™ (EJB™) container.
> mdb-container | only one | Configures the message-driven bean (MDB) container.
> jms-service | only one | Configures the Java™ Message Service (JMS) provider.
> log-service | only one | Configures the system logging service.
> security-service | only one | Defines information needed by the J2EE security service.
> transaction-service | only one | Configures the transaction service.
> java-config | only one | Contains the Java™ Virtual Machine (JVM™) configuration.
> resources | only one | Contains configured resources.
> applications | only one | Contains deployed J2EE applications, J2EE modules, and lifecycle modules.
> availability-service | zero or one | Enables high-availability features.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the server element.

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

> - Optional with respect to Sun Java System Application Server
> - Needed by a system or object that Sun Java System Application Server doesn’t have knowledge of, such as an LDAP server or a Java class

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

> Table 2-4 property Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.

> ##### Attributes

> The following table describes attributes for the property element.

> Table 2-5 property Attributes

> Attribute | Default | Description
> --- | --- | ---
> name | none | Specifies the name of the property or variable.
> value | none | Specifies the value of the property or variable.

> ### description

> Contains a text description of the parent element.

> ##### Subelements

> none

> ##### Attributes

> none

> ### 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 Elements

> Listener service elements are as follows:

> - http-service
> - http-listener
> - ssl
> - mime
> - acl
> - virtual-server-class
> - virtual-server
> - http-qos
> - auth-db
> - iiop-service
> - iiop-listener
> - orb

> ### http-service

> Defines the HTTP service.

> For more information about the quality of service features defined in this element’s attributes, see the Sun Java System Application Server Performance Tuning Guide.

> ##### Subelements

> The following table describes subelements for the http-service element.

> Table 2-6 http-service Subelements

> Element | Required | Description
> --- | --- | ---
> http-listener | zero or more | Defines an HTTP listen socket.
> mime | zero or more | Defines MIME types.
> acl | zero or more | References an ACL file.
> virtual-server-class | zero or more | Defines a virtual server class.
> http-qos | zero or one | Defines quality of service parameters.
> property | zero or more | Specifies a property or a variable.

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

> Table 2-7 http-service Attributes

> Attribute | Default | Description
> --- | --- | ---
> qos-metrics-interval-in-seconds | 30 | (optional) Specifies the interval during which traffic is measured.
> qos-recompute-time-interval-in-millis | 100 | (optional) Specifies the period in which the bandwidth gets recomputed for all server entities.
> qos-enabled | true | (optional) Enables quality of service features, which let you set limits on server entities or view server statistics for bandwidth and connections.

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

> Table 2-8 http-listener Subelements

> Element | Required | Description
> --- | --- | ---
> ssl | zero or one | Defines SSL parameters.

> ##### Attributes

> The following table describes attributes for the http-listener element.

> 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 standard.
> 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, typically 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.
> security-enabled | false | (optional) Determines whether the listener runs SSL. 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.

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

> Table 2-10 ssl Attributes

> Attribute | Default | Description
> --- | --- | ---
> cert-nickname | none | The nickname of the server certificate in the certificate database or the PKCS#11 token. In the certificate, the name format is tokenname:nickname. Including the tokenname: part of the name in this attribute is optional.
> ssl2-enabled | false | (optional) Determines whether SSL2 is enabled. If both SSL2 and SSL3 are enabled for a virtual server, the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption.
> ssl2-ciphers | none | (optional) A comma-separated list of the SSL2 ciphers used, with the prefix + to enable or - to disable, for example +rc4. Allowed values are rc4, rc4export, rc2, rc2export, idea, des, desede3.
> ssl3-enabled | true | (optional) Determines whether SSL3 is enabled. The default is true. If both SSL2 and SSL3 are enabled for a virtual server, the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption.
> ssl3-tls-ciphers | none | (optional) A comma-separated list of the SSL3 ciphers used, with the prefix + to enable or - to disable, for example +rsa_des_sha. Allowed SSL3 values are rsa_rc4_128_md5, rsa_3des_sha, rsa_des_sha, rsa_rc4_40_md5, rsa_rc2_40_md5, rsa_null_md5. Allowed TLS values are rsa_des_56_sha, rsa_rc4_56_sha.
> tls-enabled | true | (optional) Determines whether TLS is enabled.
> tls-rollback-enabled | true | (optional) Determines whether TLS rollback is enabled. TLS rollback should be enabled for Microsoft Internet Explorer 5.0 and 5.5. For more information, see the Sun Java System Application Server Administrator’s Guide.
> client-auth-enabled | false | (optional) Determines whether SSL3 client authentication is performed on every request, independent of ACL-based access control.

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

> Note | The mime.types interface is Unstable. An unstable interface may be experimental or transitional, and hence may change incompatibly, be removed, or be replaced by a more stable interface in the next release.

> ##### Subelements

> none

> ##### Attributes

> The following table describes attributes for the mime element.

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

> Note | The ACL file interface is Unstable. An unstable interface may be experimental or transitional, and hence may change incompatibly, be removed, or be replaced by a more stable interface in the next release.

> ##### Subelements

> none

> ##### Attributes

> The following table describes attributes for the acl element.

> Table 2-12 acl Attributes

> Attribute | Default | Description
> --- | --- | ---
> id | none | Internal name for the ACL file listing. Used in a virtual-server element to define the ACL file used by the virtual server. An ACL file listing name cannot begin with a number.
> file | none | An ACL file. Each ACL file must have a unique name. For information about the format of an ACL file, see the Sun Java System Application Server Administrator’s Guide to Security.

> ### virtual-server-class

> Defines a virtual server class.

> ##### Subelements

> The following table describes subelements for the virtual-server-class element.

> Table 2-13 virtual-server-class Subelements

> Element | Required | Description
> --- | --- | ---
> virtual-server | zero or more | Defines a virtual server.
> http-qos | zero or one | Defines quality of service parameters.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the virtual-server-class element.

> Table 2-14 virtual-server-class Attributes

> Attribute | Default | Description
> --- | --- | ---
> id | none | Virtual server class ID. This is a unique ID that allows lookup of a specific virtual server class. A virtual server class ID cannot begin with a number.
> config-file | none | (optional) The file name of the obj.conf file for this class of virtual servers. Can be overridden in a virtual-server element.
> default-object | default | (optional) Tells the server which object loaded from an obj.conf file is the default. Can be overridden in a virtual-server 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 virtual server class. 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.
> 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 true only if the server supports multiple languages. Can be overridden in a virtual-server element. Can be overridden in a virtual-server element.
> enabled | true | (optional) Determines whether the virtual server class is active.

> ### 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 Java System 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 Java System 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.

> Table 2-15 virtual-server Subelements

> Element | Required | Description
> --- | --- | ---
> http-qos | zero or one | Defines quality of service parameters.
> auth-db | zero or more | Defines the user database for the virtual server; not applicable to J2EE applications.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the virtual-server element.

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

> Table 2-17 virtual-server Properties

> Property | Default | Description
> --- | --- | ---
> sso-enabled | true | If true, single sign-on is enabled for web applications on this virtual server that are configured for the same realm. If false, single sign-on is disabled for this virtual server, and users must authenticate separately to every application on the virtual server.
> sso-max-inactive-seconds | 300 | Specifies the time after which a user’s single sign-on record becomes eligible for purging if no client activity is received. Since single sign-on applies across several applications on the same virtual server, access to any of the applications keeps the single sign-on record active. Higher values provide longer single sign-on persistence for the users at the expense of more memory use on the server.
> sso-reap-interval-seconds | 60 | Specifies the interval between purges of expired single sign-on records.

> ### 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 Java System Application Server Performance Tuning Guide.

> ##### Subelements

> none

> ##### Attributes

> The following table describes attributes for the http-qos element.

> Table 2-18 http-qos Attributes

> Attribute | Default | Description
> --- | --- | ---
> bandwidth-limit | none | (required if enforce-bandwidth-limit is true) The maximum bandwidth limit for the server, virtual-server-class, or virtual-server in bytes per second.
> enforce-bandwidth-limit | false | (optional) Specifies whether the bandwidth limit should be enforced or not.
> connection-limit | none | (required if enforce-connection-limit is true) The maximum number of concurrent connections for the server, virtual-server-class, or virtual-server.
> enforce-connection-limit | false | (optional) Specifies whether the connection limit should be enforced or not.

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

> Note | The user database applies only to the security of the server itself. It is not related to J2EE application and module security. For more information, see the Sun Java System Application Server Administrator’s Guide to Security.

> ##### Subelements

> none

> ##### Attributes

> The following table describes attributes for the auth-db element.

> Table 2-19 auth-db 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 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 virtual-server.

> ### iiop-service

> Defines the IIOP service.

> ##### Subelements

> The following table describes subelements for the iiop-service element.

> Table 2-20 iiop-service Subelements

> Element | Required | Description
> --- | --- | ---
> orb | only one | Configures the ORB.
> ssl-client-config | zero or one | Defines SSL parameters for the ORB.
> iiop-listener | 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.

> Table 2-21 orb Subelements

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the orb element.

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

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

> Table 2-23 ssl-client-config Subelements

> Element | Required | Description
> --- | --- | ---
> ssl | 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.

> Table 2-24 iiop-listener Subelements

> Element | Required | Description
> --- | --- | ---
> ssl | zero or one | Defines SSL parameters.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the iiop-listener element.

> Table 2-25 iiop-listener Attributes

> Attribute | Default | Description
> --- | --- | ---
> id | none | The listener name. An iiop-listener name cannot begin with a number.
> address | none | IP address of the listener. Can be in dotted-pair or IPv6 notation or just a name.
> port | 3700 (for the first server instance) | (optional) Port number to create the listener on. Legal values are 1 - 65535. On UNIX, creating sockets that listen on ports 1 - 1024 requires superuser privileges.
> enabled | true | (optional) Determines whether the listener is active.

> ##

> Container Elements

> Container configuration elements are as follows:

> - web-container
> - ejb-container
> - mdb-container

> ### web-container

> Configures the web container.

> ##### Subelements

> The following table describes subelements for the web-container element.

> Table 2-26 web-container Subelements

> Element | Required | Description
> --- | --- | ---
> session-config | zero or one | Specifies session configuration information for the web container.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the web-container element.

> Table 2-27 web-container Attributes

> Attribute | Default | Description
> --- | --- | ---
> monitoring-enabled | false | (optional) Determines whether monitoring of the web container is enabled.
> 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.
> availability-enabled | Value of same attribute in availability-service element | (optional) Determines whether availability is enabled at the web container level. For more information about availability levels, see the availability-service element description.

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

> Table 2-28 ejb-container Subelements

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the ejb-container element.

> 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: created if a request arrives when the pool has no available beans (subject to the max-pool-size limit) removed when the pool-idle-timeout-in-seconds timer expires and a cleaner thread removes any unused instances 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: created if a request arrives when the pool has no available beans (subject to the max-cache-size limit) passivated when the cache-idle-timeout-in-seconds timer expires and a cleaner thread removes any unused instances, or when the cache size exceeds max-cache-size. 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: fifo selects the oldest instance. lru selects the least recently accessed instance. nru selects a not recently used instance.
> 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.
> availability-enabled | Value of same attribute in availability-service element | (optional) Determines whether availability is enabled at the EJB container level. For more information about availability levels, see the availability-service element description.

> ### mdb-container

> Configures the message-driven bean (MDB) container.

> ##### Subelements

> The following table describes subelements for the mdb-container element.

> Table 2-30 mdb-container Subelements

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the mdb-container element.

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

> ##### Properties

> The following table describes properties for the mdb-container element.

> Table 2-32 mdb-container Properties

> Property | Default | Description
> --- | --- | ---
> cmt-max-runtime-exceptions | 1 | Specifies the maximum number of RuntimeException occurrences allowed from a message-driven bean’s onMessage() method when container-managed transactions are used. Deprecated.
> reconnect-enabled | true | If true, the MDB container automatically tries to reconnect to the JMS provider when the connection is broken. When the connection is broken, depending on the message processing stage, the onMessage() method may not be able to complete successfully or the transaction may be rolled back due to a JMS exception. When the MDB container reestablishes the connection, JMS message redelivery semantics apply.
> reconnect-delay-in-seconds | 60 | Specifies the delay between reconnect attempts.
> reconnect-max-retries | 60 | Specifies the maximum number of reconnect attempts.

> ##

> Availability Elements

> Availability elements are as follows:

> - availability-service
> - persistence-store
> - session-config
> - session-manager
> - manager-properties
> - store-properties
> - session-properties

> ### availability-service

> Enables high-availability features such as HTTP session and stateful session bean state persistence to the Sun Java System high-availability database (HADB). Also determines whether single sign-on, if configured, is highly available.

> ##### Subelements

> The following table describes subelements for the availability-service element.

> Table 2-33 availability-service Subelements

> Element | Required | Description
> --- | --- | ---
> iiop-cluster | zero or one | Defines IIOP endpoints of application server instances forming a cluster.
> persistence-store | zero or one | Configures the HADB.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the availability-service element.

> Table 2-34 availability-service Attributes

> Attribute | Default | Description
> --- | --- | ---
> availability-enabled | false | (optional) If set to true, high-availability features apply to all applications deployed to the server instance that do not have availability disabled. You should set the same availability value for all instances in a cluster to ensure consistent behavior.

> Availability can be enabled or disabled at the following levels:

> 1. The server instance (attribute of availability-service)
> 2. The EJB or web container (attribute of ejb-container or web-container)
> 3. The application (attribute of j2ee-application)
> 4. The EJB or web module (attribute of ejb-module or web-module)

> For availability to be enabled at a given level, it must be enabled at all higher levels as well. For example, to enable availability at the application level, you must also enable it at the server instance and container levels.

> The default for a given level is the setting at the next level up. For example, if availability is enabled at the EJB and web container level, it is enabled by default at the application level. Availability is disabled by default at the server instance level.

> Note | Setting availability-enabled to true at all levels is not sufficient for configuring session persistence. You must also configure this element’s subelements and session-config and its subelements.

> If availability is disabled, there is no high availability for HTTP session persistence. In other words, persistence-type=memory.

> If availability is enabled, high availability for HTTP session persistence is enabled for all applications by default. If no further configuration exists either in the server.xml or sun-web.xml file, the default session persistence configuration is as follows:

> persistence-type=ha

> persistenceFrequency=time-based

> persistenceScope=session

> You can override this default configuration for all applications in server.xml by setting the various session-config subelements. You can override this default configuration for a specific application in sun-web.xml. For details, see the Sun Java System Application Server Developer’s Guide to Web Applications.

> ### iiop-cluster

> Defines IIOP endpoints of application server instances forming a cluster.

> ##### Subelements

> The following table describes subelements for the iiop-cluster element.

> Table 2-35 iiop-cluster Subelements

> Element | Required | Description
> --- | --- | ---
> iiop-server-instance | zero or more | Defines a server instance in the cluster.

> ##### Attributes

> none

> ### iiop-server-instance

> Defines a server instance in the cluster.

> ##### Subelements

> The following table describes subelements for the iiop-server-instance element.

> Table 2-36 iiop-server-instance Subelements

> Element | Required | Description
> --- | --- | ---
> iiop-endpoint | zero or more | Defines IIOP endpoints of the server instance.

> ##### Attributes

> The following table describes attributes for the iiop-server-instance element.

> Table 2-37 iiop-server-instance Attributes

> Attribute | Default | Description
> --- | --- | ---
> name | none | Specifies the name of the server instance.

> ### iiop-endpoint

> Defines IIOP endpoints of the server instance.

> ##### Subelements

> none

> ##### Attributes

> The following table describes attributes for the iiop-endpoint element.

> Table 2-38 iiop-endpoint Attributes

> Attribute | Default | Description
> --- | --- | ---
> id | none | Specifies a unique identifier for this endpoint.
> host | none | Specifies an IP address or host name for this endpoint.
> port | 3600 | (optional) Specifies the port number at which the endpoint listens for IIOP requests.

> ### persistence-store

> Configures the Sun Java System high-availability database (HADB).

> ##### Subelements

> The following table describes subelements for the persistence-store element.

> Table 2-39 persistence-store Subelements

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> none

> ##### Properties

> The following table describes properties for the persistence-store element.

> Table 2-40 persistence-store Properties

> Property | Default Value | Description
> --- | --- | ---
> store-pool-jndi-name | jdbc/hastore | Specifies the jndi-name of the jdbc-resource used for connections to the HADB for session persistence. For more information about setting up a connection pool and JDBC resource for the HADB, see the Sun Java System Application Server Installation Guide and the Sun Java System Application Server Administrator’s Guide.

> ### session-config

> Specifies session configuration information for the entire web container. Individual web applications can override these settings using the corresponding elements in their sun-web.xml files.

> ##### Subelements

> The following table describes subelements for the session-config element.

> Table 2-41 session-config Subelements

> Element | Required | Description
> --- | --- | ---
> session-manager | zero or one | Specifies session manager configuration information.
> session-properties | zero or one | Specifies session properties.

> ##### Attributes

> none

> ### session-manager

> Specifies session manager information.

> Note | The session manager interface is Unstable. An unstable interface may be experimental or transitional, and hence may change incompatibly, be removed, or be replaced by a more stable interface in the next release.

> ##### Subelements

> The following table describes subelements for the session-manager element.

> Table 2-42 session-manager Subelements

> Element | Required | Description
> --- | --- | ---
> manager-properties | zero or one | Specifies session manager properties.
> store-properties | zero or one | Specifies session persistence (storage) properties.

> ##### Attributes

> The following table describes attributes for the session-manager element.

> Table 2-43 session-manager Attributes

> Attribute | Default Value | Description
> --- | --- | ---
> persistence-type | memory | (optional) Specifies the session persistence mechanism. Allowed values are memory, file, and ha. For production environments that require session persistence, use ha. The custom value is not implemented and should not be used.

> Note | Setting the web container’s persistence-type to ha is not sufficient for configuring session persistence. You must also enable the availability-service. For more information about session persistence, see the Sun Java System Application Server Developer’s Guide to Web Applications.

> ### manager-properties

> Specifies session manager properties.

> ##### Subelements

> The following table describes subelements for the manager-properties element.

> Table 2-44 manager-properties Subelements

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property, which has a name and a value.

> ##### Attributes

> none

> ##### Properties

> The following table describes properties for the manager-properties element.

> Table 2-45 manager-properties Properties

> Property Name | Default Value | Description
> --- | --- | ---
> reapIntervalSeconds | 60 | Specifies the number of seconds between checks for expired sessions. If the persistence-type attribute of the session-manager element is file or ha, sessions are passivated if maxSessions has been exceeded. If persistenceFrequency is set to time-based, active sessions are stored at this interval. You should set this value lower than the frequency at which session data changes. For example, this value should be as low as possible (1 second) for a hit counter servlet on a frequently accessed website, or you could lose the last few hits each time you restart the server.
> maxSessions | -1 | Specifies the maximum number of sessions that can be in cache, or -1 for no limit. After this, an attempt to create a new session causes an IllegalStateException to be thrown. If the persistence-type attribute of the session-manager element is file or ha, the session manager passivates sessions to the persistent store when this maximum is reached.
> sessionFilename | none; state is not preserved across restarts | Specifies the absolute or relative path to the directory in which the session state is preserved between application restarts, if preserving the state is possible. A relative path is relative to the temporary directory for this web application. Applicable only if the persistence-type attribute of the session-manager element is memory.
> persistenceFrequency | web-method | Specifies how often the session state is stored. Allowed values are as follows: web-method - The session state is stored at the end of each web request prior to sending a response back to the client. This mode provides the best guarantee that the session state is fully updated in case of failure. time-based - The session state is stored in the background at the frequency set by reapIntervalSeconds. This mode provides less of a guarantee that the session state is fully updated. However, it can provide a significant performance improvement because the state is not stored after each request. Applicable only if the persistence-type attribute of the session-manager element is ha.

> ### store-properties

> Specifies session persistence (storage) properties.

> ##### Subelements

> The following table describes subelements for the store-properties element.

> Table 2-46 store-properties Subelements

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property, which has a name and a value.

> ##### Attributes

> none

> ##### Properties

> The following table describes properties for the store-properties element.

> Table 2-47 store-properties Properties

> Property Name | Default Value | Description
> --- | --- | ---
> directory | instance_dir/generated/jsp/j2ee-apps/appname/appname_war | Specifies the absolute or relative pathname of the directory into which individual session files are written. A relative path is relative to the temporary work directory for this web application. Applicable only if the persistence-type attribute of the session-manager element is file.
> persistenceScope | session | Specifies how much of the session state is stored. Allowed values are as follows: session - The entire session state is stored every time. This mode provides the best guarantee that your session data is correctly stored for any distributable web application. modified-session - The entire session state is stored if it has been modified. A session is considered to have been modified if HttpSession.setAttribute() or HttpSession.removeAttribute() was called. You must guarantee that setAttribute() is called every time an attribute is changed. This is not a J2EE specification requirement, but it is required for this mode to work properly. modified-attribute - Only modified session attributes are stored. For this mode to work properly, you must follow some guidelines, which are explained immediately following this table. Applicable only if the persistence-type attribute of the session-manager element is ha.

> If the persistenceScope store property is set to modified-attribute, your web application must follow these guidelines:

> - Call setAttribute() every time you modify the session state.
> - Make sure there are no cross-references between attributes. The object graph under each distinct attribute key is serialized and stored separately. If there are any object cross references between the objects under each separate key, they are not serialized and deserialized correctly.
> - Distribute the session state across multiple attributes, or at least between a read-only attribute and a modifiable attribute.

> Note | The session persistence scope modified-attribute is not certified as a full production quality feature. You should evaluate the performance and stability of the web container under expected peak load with this persistence scope. If exceptions are logged or response time is too high, do not use this persistence scope for your production environment. Use session or modified-session instead.

> ### session-properties

> Specifies session properties.

> ##### Subelements

> The following table describes subelements for the session-properties element.

> Table 2-48 session-properties Subelements

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property, which has a name and a value.

> ##### Attributes

> none

> ##### Properties

> The following table describes properties for the session-properties element.

> Table 2-49 session-properties Properties

> Property Name | Default Value | Description
> --- | --- | ---
> timeoutSeconds | 600 | Specifies the default maximum inactive interval (in seconds) for all sessions created in this web module. If set to 0 or less, sessions in this web module never expire. If a session-timeout element is specified in the web.xml file, the session-timeout value overrides any timeoutSeconds value. If neither session-timeout nor timeoutSeconds is specified, the timeoutSeconds default is used. Note that the session-timeout element in web.xml is specified in minutes, not seconds.
> enableCookies | true | Uses cookies for session tracking if set to true.
> enableURLRewriting | true | Enables URL rewriting. This provides session tracking via URL rewriting when the browser does not accept cookies. You must also use an encodeURL or encodeRedirectURL call in the servlet or JavaServer Pages™ (JSP™) page.
> idLengthBytes | 128 | Specifies the number of bytes in this web module’s session ID.

> ##

> J2EE Service Elements

> J2EE service elements are as follows:

> - jms-service
> - log-service
> - security-service
> - auth-realm
> - transaction-service

> ### jms-service

> Configures the built-in Java Message Service (JMS) that is managed by the Sun Java System Application Server.

> ##### Subelements

> The following table describes subelements for the jms-service element.

> Table 2-50 jms-service Subelements

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the jms-service element.

> Table 2-51 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 Java System Application Server instance is responsible for starting up and shutting down the JMS provider. If set to false, the Sun Java System 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 Java System Application Server).

> ##### Properties

> The following table describes properties for the jms-service element.

> Table 2-52 jms-service Properties

> Property | Default | Description
> --- | --- | ---
> instance-name | domain_instance | Specifies the full Sun Java™ System Message Queue broker instance name, which by default is a concatenation of the domain and server instance names. For example: domain1_server1.
> instance-name-suffix | none | Specifies a suffix to add to the full Sun Java System Message Queue broker instance name. The suffix is separated from the instance name by an underscore character (_). For example, if the instance name is domain1_server1, appending the suffix xyz changes the instance name to domain1_server1_xyz.
> append-version | false | If true, appends the major and minor version numbers, preceded by underscore characters (_), to the full Sun Java System Message Queue broker instance name. For example, if the instance name is domain1_server1, appending the version numbers changes the instance name to domain1_server1_7_0.

> ### 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 Java System 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.

> Table 2-53 log-service Subelements

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the log-service element.

> Table 2-54 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.
> log-stderr | true | (optional) If true, redirects stderr output to the server log.
> echo-log-messages-to-stderr | true | (optional) If true, sends log messages to stderr in addition to the server log.
> 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.
> use-system-logging | false | (optional) If true, uses the UNIX syslog service to produce and manage logs.

> ### security-service

> Defines parameters and configuration information needed by the J2EE security service.

> ##### Subelements

> The following table describes subelements for the security-service element.

> Table 2-55 security-service Subelements

> Element | Required | Description
> --- | --- | ---
> auth-realm | one or more | Defines a realm for authentication.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the security-service element.

> Table 2-56 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. Audit information consists of: Authentication success and failure events Servlet and EJB access grants and denials
> 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 Java System 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.

> Table 2-57 auth-realm Subelements

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the auth-realm element.

> Table 2-58 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 Java System Application Server have required and optional properties. A custom realm may have different properties.

> The following table describes properties for the auth-realm element.

> Table 2-59 auth-realm Properties

> Property | Realms | Description
> --- | --- | ---
> jaas-context | file, ldap, solaris | Specifies the JAAS (Java Authentication and Authorization Service) context.
> file | file | Specifies the file that stores user names. The default is instance_dir/config/keyfile.
> assign-groups | certificate | (optional) If this property is set, its value is taken to be a comma-separated list of group names. All clients who present valid certificates are assigned membership to these groups for the purposes of authorization decisions in the web and EJB containers.
> directory | ldap | Specifies the LDAP URL to your server.
> base-dn | ldap | Specifies the LDAP base DN for the location of user data. This base DN can be at any level above the user data, since a tree scope search is performed. The smaller the search tree, the better the performance.
> search-filter | ldap | (optional) Specifies the search filter to use to find the user. The default is uid=%s (%s expands to the subject name).
> group-base-dn | ldap | (optional) Specifies the base DN for the location of groups data. By default it is same as the base-dn, but it can be tuned if necessary.
> group-search-filter | ldap | (optional) Specifies the search filter to find group memberships for the user. The default is uniquemember=%d (%d expands to the user element DN).
> group-target | ldap | (optional) Specifies the LDAP attribute name that contains group name entries. The default is CN.
> search-bind-dn | ldap | (optional) Specifies an optional DN used to authenticate to the directory for performing the search-filter lookup. Only required for directories that do not allow anonymous search.
> search-bind-password | ldap | (optional) Specifies the LDAP password for the DN given in search-bind-dn.

> ### transaction-service

> Configures the Java Transaction Service (JTS).

> ##### Subelements

> The following table describes subelements for the transaction-service element.

> Table 2-60 transaction-service Subelements

> Element | Required | Description
> --- | --- | ---
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the transaction-service element.

> Table 2-61 transaction-service Attributes

> Attribute | Default | Description
> --- | --- | ---
> automatic-recovery | false | (optional) If true, the server instance attempts transaction recovery during startup.
> 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.

> ##### Properties

> The following table describes properties for the transaction-service element.

> Table 2-62 transaction-service Properties

> Property | Default | Description
> --- | --- | ---
> oracle-xa-recovery-workaround | false | If true, the Oracle XA Resource workaround is used in transaction recovery.
> sybase-xa-recovery-workaround | false | If true, the Sybase XA Resource workaround is used in transaction recovery.
> disable-distributed-transaction-logging | false | If true, disables transaction logging, which may improve performance. If the automatic-recovery attribute is set to true, this property is ignored.
> xaresource-txn-timeout | specific to the XAResource used | Changes the XAResource timeout. In some cases, the XAResource default timeout can cause transactions to be aborted, so it is desirable to change it.

> ##

> Java Configuration Elements

> Java configuration elements are as follows:

> - java-config
> - profiler
> - jvm-options

> ### java-config

> Specifies Java Virtual Machine (JVM) configuration parameters.

> ##### Subelements

> The following table describes subelements for the java-config element.

> Table 2-63 java-config Subelements

> Element | Required | Description
> --- | --- | ---
> profiler | zero or one | Configures a profiler for use with Sun Java System Application Server.
> jvm-options | zero or more | Contains JVM command line options.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the java-config element.

> Table 2-64 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.
> 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/conn inv.html#Invocation For more information about debugging, see the Sun Java System 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 Java System 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 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 Java System 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.

> ### profiler

> Configures a profiler for use with Sun Java System Application Server. For more information about profilers, see the Sun Java System Application Server Developer’s Guide.

> ##### Subelements

> The following table describes subelements for the profiler element.

> Table 2-65 profiler Subelements

> Element | Required | Description
> --- | --- | ---
> jvm-options | zero or more | Contains profiler-specific JVM command line options.
> property | zero or more | Specifies a property or a variable.

> Note | Subelements of a profiler element can occur in any order.

> ##### Attributes

> The following table describes attributes for the profiler element.

> Table 2-66 profiler Attributes

> Attribute | Default | Description
> --- | --- | ---
> name | none | Specifies the name of the profiler.
> classpath | none | (optional) Specifies the classpath for the profiler.
> native-library-path | none | (optional) Specifies the native library path for the profiler.
> enabled | true | (optional) Determines whether the profiler is enabled.

> ### 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 Elements

> Resource elements are as follows:

> - resources
> - custom-resource
> - external-jndi-resource
> - jdbc-resource
> - mail-resource
> - jms-resource
> - persistence-manager-factory-resource
> - jdbc-connection-pool

> ### resources

> Contains configured resources, such as database connections, JavaMail™ sessions, and so on.

> Note | You must specify a Java Naming and Directory Interface™ (JNDI) name for each resource. To avoid collisions with names of other enterprise resources in JNDI, and to avoid portability problems, all names in a Sun Java System Application Server application should begin with the string java:comp/env.

> ##### Subelements

> The following table describes subelements for the resources element.

> Table 2-67 resources Subelements

> Element | Required | Description
> --- | --- | ---
> custom-resource | zero or more | Defines a custom resource.
> external-jndi-resource | zero or more | Defines a resource that resides in an external JNDI repository.
> jdbc-resource | zero or more | Defines a JDBC (Java Database Connectivity) resource.
> mail-resource | zero or more | Defines a JavaMail resource.
> jms-resource | zero or more | Defines a JMS resource.
> persistence-manager-factory-resource | zero or more | Defines a persistence manager factory resource for CMP.
> jdbc-connection-pool | zero or more | Defines the properties that are required for creating a JDBC connection pool.

> Note | Subelements of a resources element can occur in any order.

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

> Table 2-68 custom-resource Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the custom-resource element.

> Table 2-69 custom-resource Attributes

> Attribute | Default | Description
> --- | --- | ---
> jndi-name | none | Specifies the JNDI name for the resource.
> res-type | none | Specifies the fully qualified type of the resource.
> factory-class | none | Specifies the fully qualified name of the user-written factory class, which implements javax.naming.spi.ObjectFactory.
> enabled | true | (optional) Determines whether this resource is enabled at runtime.

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

> Table 2-70 external-jndi-resource Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the external-jndi-resource element.

> Table 2-71 external-jndi-resource Attributes

> Attribute | Default | Description
> --- | --- | ---
> jndi-name | none | Specifies the JNDI name for the resource.
> jndi-lookup-name | none | Specifies the JNDI lookup name for the resource.
> res-type | none | Specifies the fully qualified type of the resource.
> factory-class | none | Specifies the fully qualified name of the factory class, which implements javax.naming.spi.InitialContextFactory. For more information about JNDI, see the Sun Java System Application Server Developer’s Guide to J2EE Services and APIs.
> enabled | true | (optional) Determines whether this resource is enabled at runtime.

> ### jdbc-resource

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

> ##### Subelements

> The following table describes subelements for the jdbc-resource element.

> Table 2-72 jdbc-resource Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the jdbc-resource element.

> Table 2-73 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.

> ### mail-resource

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

> ##### Subelements

> The following table describes subelements for the mail-resource element.

> Table 2-74 mail-resource Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the mail-resource element.

> Table 2-75 mail-resource Attributes

> Attribute | Default | Description
> --- | --- | ---
> jndi-name | none | Specifies the JNDI name for the resource.
> store-protocol | imap | (optional) Specifies the storage protocol service, which connects to a mail server, retrieves messages, and saves messages in folder(s). Example values are imap and pop3.
> store-protocol-class | com.sun.mail.imap.IMAPStore | (optional) Specifies the service provider implementation class for storage.
> transport-protocol | smtp | (optional) Specifies the transport protocol service, which sends messages.
> transport-protocol-class | com.sun.mail.smtp.SMTPTransport | (optional) Specifies the service provider implementation class for transport.
> host | none | The mail server host name.
> user | none | The mail server user name.
> from | none | The e-mail address the mail server uses to indicate the message sender.
> debug | false | (optional) Determines whether debugging for this resource is enabled.
> enabled | true | (optional) Determines whether this resource is enabled at runtime.

> ##### 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 Java System 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.

> Table 2-76 jms-resource Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the jms-resource element.

> Table 2-77 jms-resource Attributes

> Attribute | Default | Description
> --- | --- | ---
> jndi-name | none | Specifies the JNDI name for the resource.
> res-type | none | Specifies the fully qualified type of the resource, which is one of the following: javax.jms.Topic javax.jms.Queue javax.jms.TopicConnectionFactory javax.jms.QueueConnectionFactory
> enabled | true | (optional) Determines whether this resource is enabled at runtime.

> ##### Properties

> The following table describes the most commonly used JMS properties for the jms-resource element. For a complete list of the available properties (called administered object attributes in Sun Java System Message Queue), see the Sun Java System Message Queue Administration Guide.

> Table 2-78 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 Java System Message Queue Administrator's Guide shows a default value for this property, but this does not apply in the Sun Java System Application Server environment.
> imqBrokerHostName | the same host name as the Sun Java System Application Server instance (localhost) | Specifies the host name where the JMS service (Sun Java System 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 Java System 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.

> Table 2-79 persistence-manager-factory-resource Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the persistence-manager-factory-resource element.

> Table 2-80 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.

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

> Table 2-81 jdbc-connection-pool Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the jdbc-connection-pool element.

> Table 2-82 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.
> connection-validation-method | auto-commit | (optional) Legal values are as follows: auto-commit (default), which uses Connection.setAutoCommit(Connection.getAutoCommit()) meta-data, which uses Connection.getMetaData() table, which performs a query on a table specified in the validation-table-name attribute
> 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.

> ##### Properties

> Most JDBC 2.0 drivers allow use of standard property lists to specify the user, password, and other resource configuration information. Although properties are optional with respect to Sun Java System 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.

> Table 2-83 jdbc-connection-pool Properties

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

> ##

> Application Elements

> Application elements are as follows:

> - applications
> - lifecycle-module
> - j2ee-application
> - web-module
> - ejb-module
> - connector-module

> ### applications

> Contains deployed J2EE applications, J2EE modules, and Lifecycle modules.

> ##### Subelements

> The following table describes subelements for the applications element.

> Table 2-84 applications Subelements

> Element | Required | Description
> --- | --- | ---
> lifecycle-module | zero or more | Specifies a deployed lifecycle module.
> j2ee-application | zero or more | Specifies a deployed J2EE application.
> ejb-module | zero or more | Specifies a deployed EJB module.
> web-module | zero or more | Specifies a deployed web module.
> connector-module | zero or more | Specifies a deployed connector module.

> Note | Subelements of an applications element can occur in any order.

> ##### Attributes

> The following table describes attributes for the applications element.

> Table 2-85 applications Attributes

> Attribute | Default | Description
> --- | --- | ---
> dynamic-reload-enabled | false | (optional) Specifies whether dynamic reloading is enabled. This attribute should be set to true in a development environment and false in a production environment.
> dynamic-reload-poll-interval-in-seconds | 2 | (optional) Specifies the interval at which applications and modules are checked for code changes and dynamically reloaded.

> ### lifecycle-module

> Specifies a deployed lifecycle module. For more information about lifecycle modules, see the Sun Java System Application Server Developer’s Guide.

> ##### Subelements

> The following table describes subelements for the lifecycle-module element.

> Table 2-86 lifecycle-module Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.
> property | zero or more | Specifies a property or a variable.

> ##### Attributes

> The following table describes attributes for the lifecycle-module element.

> Table 2-87 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.
> enabled | true | (optional) Determines whether the lifecycle module is enabled.

> ### j2ee-application

> Specifies a deployed J2EE application.

> ##### Subelements

> The following table describes subelements for the j2ee-application element.

> Table 2-88 j2ee-application Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.

> ##### Attributes

> The following table describes attributes for the j2ee-application element.

> Table 2-89 j2ee-application Attributes

> Attribute | Default | Description
> --- | --- | ---
> name | none | The name of the application.
> location | none | The location of the application in the Sun Java System Application Server file system.
> virtual-servers | all virtual servers | (optional) The virtual servers to which the web modules within this application are deployed.
> enabled | true | (optional) Determines whether the application is enabled.
> availability-enabled | Value of same attribute in web-container and ejb-container elements | (optional) Determines whether availability is enabled at the application level. For more information about availability levels, see the availability-service element description.

> ### ejb-module

> Specifies a deployed EJB module.

> ##### Subelements

> The following table describes subelements for the ejb-module element.

> Table 2-90 ejb-module Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.

> ##### Attributes

> The following table describes attributes for the ejb-module element.

> Table 2-91 ejb-module Attributes

> Attribute | Default | Description
> --- | --- | ---
> name | none | The name of the EJB module.
> location | none | The location of the EJB module in the Sun Java System Application Server file system.
> enabled | true | (optional) Determines whether the EJB module is enabled.
> availability-enabled | Value of same attribute in ejb-container and j2ee-application elements | (optional) Determines whether availability is enabled at the EJB module level. For more information about availability levels, see the availability-service element description.

> ### web-module

> Specifies a deployed web module.

> ##### Subelements

> The following table describes subelements for the web-module element.

> Table 2-92 web-module Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.

> ##### Attributes

> The following table describes attributes for the web-module element.

> Table 2-93 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 Java™ 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 [/]. If you are setting up load balancing, web module context roots must be unique within a cluster. See the Sun Java System Application Server Administrator’s Guide for more information about load balancing.
> 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.
> availability-enabled | Value of same attribute in web-container and j2ee-application elements | (optional) Determines whether availability is enabled at the web module level. For more information about availability levels, see the availability-service element description.

> ### connector-module

> Specifies a deployed connector module.

> ##### Subelements

> The following table describes subelements for the connector-module element.

> Table 2-94 connector-module Subelements

> Element | Required | Description
> --- | --- | ---
> description | zero or one | Contains a text description of this element.

> ##### Attributes

> The following table describes attributes for the connector-module element.

> Table 2-95 connector-module Attributes

> Attribute | Default | Description
> --- | --- | ---
> name | none | The name of the connector module.
> location | none | The location of the connector module in the Sun Java System Application Server file system.
> enabled | true | (optional) Determines whether the connector module is enabled.

> ##

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

> - The auth-db element’s id attribute maps to an ACL file’s database attribute.
> - The auth-db element’s database attribute maps to a dbswitch.conf entry.

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

> Note | The dbswitch.conf interface is Unstable. An unstable interface may be experimental or transitional, and hence may change incompatibly, be removed, or be replaced by a more stable interface in the next release.

> 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 Java System 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 Application Server versions.

> ##

> The Sun Java System LDAP Schema

> You can use the dcsuffix attribute in the dbswitch.conf file if your LDAP database meets the requirements outlined in this section.

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

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

> The directory tree may be single rooted, (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). The cn should contain name initial sn. The RDN of the user entry should 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.

> ##

> Variables

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

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

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

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

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

> Note | A variable must be defined in the server.xml file at the http-service, virtual-server-class, or virtual-server level. You should define variables with default values at the http-service or virtual-server-class level and override them at the virtual-server level.

> ### 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 Java System 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.

> Table 2-96 General Variables

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

> #### send-cgi Variables

> The following table lists server.xml variables used by the send-cgi function in the obj.conf file.

> Table 2-97 send-cgi Variables

> Variable | Description
> --- | ---
> user | The value of the user CGI parameter.
> group | The value of the group CGI parameter.
> chroot | The value of the chroot CGI parameter.
> dir | The value of the dir CGI parameter.
> nice | The value of the nice CGI parameter.

> For more information about the send-cgi function, see the Sun Java System 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 File

> When you first install Sun Java System 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 Java System Application Server 7.0//EN" "file:///C:/Sun/AppServer7/lib/dtds/sun-server_1_1.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.ja r;C:/Sun/AppServer7/lib/appserv-ext.jar;C:/Sun/AppServer7/lib/appserv-cmp.jar;C:/Sun/AppS erver7/lib/appserv-ideplugin.jar;C:\Sun\AppServer7\imq\lib/imq.jar;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:\Sun\AppServer7\share\lib/jaxrpc-impl.jar; C:\Sun\AppServer7\share\lib/jaxrpc-api.jar;C:\Sun\AppServer7\share\lib/jaxr-impl.jar;C:\S un\AppServer7\share\lib/jaxr-api.jar;C:\Sun\AppServer7\share\lib/jhall.jar;C:\Sun\AppServ er7\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/c ommons-logging.jar;C:\Sun\AppServer7\imq\lib/fscontext.jar;C:\Sun\AppServer7\imq\lib/prov iderutil.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/config/serv er.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.ServerLogManager< /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-options>

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

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.