Sun GlassFish Enterprise Server v3 Domain File Format Reference

S

security-map

Maps the principal received during servlet or EJB authentication to the credentials accepted by the EIS. This mapping is optional. It is possible to map multiple Enterprise Server principals to the same back-end principal.

This is different from a work-security-map, which maps a principal associated with an incoming work instance to a principal in the Enterprise Server's security domain.

Superelements

connector-connection-pool

Subelements

The following table describes subelements for the security-map element.

Table 1–145 security-map Subelements


Element	Required	Description
principal	one or more	Contains the principal of the servlet or EJB client.
user-group	one or more	Contains the group to which the principal belongs.
backend-principal	only one	Specifies the user name and password required by the EIS.

Attributes

The following table describes attributes for the security-map element.

Table 1–146 security-map Attributes


Attribute	Default	Description
`name`	none	Specifies a name for the security mapping.

security-service

Defines parameters and configuration information needed by the Java EE security service. For SSL configuration, see ssl. For connector module security, see security-map.

Superelements

config

Subelements

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

Table 1–147 security-service Subelements


Element	Required	Description
auth-realm	one or more	Defines a realm for authentication.
jacc-provider	one or more	Specifies a Java Authorization Contract for Containers (JACC) provider for pluggable authorization.
audit-module	zero or more	Specifies an optional plug-in module that implements audit capabilities.
message-security-config	zero or more	Specifies configurations for message security providers.
property	zero or more	Specifies a property or a variable.

Attributes

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

Table 1–148 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`	`attribute is deprecated`	(optional) Deprecated. Do not use.
`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
`jacc`	`default`	(optional) Specifies the name of the jacc-provider element to use for setting up the JACC infrastructure. Do not change the default value unless you are adding a custom JACC provider.
`audit-modules`	`default`	(optional) Specifies a space-separated list of audit provider modules used by the audit subsystem. The default value refers to the internal log-based audit module.
`activate-default-principal-to-role-mapping`	`false`	(optional) Applies a default principal for role mapping to any application that does not have an application-specific mapping defined. Every role is mapped to an instance of a `java.security.Principal` implementation class defined by `mapped-principal-class`. This class has the same name as the role.
`mapped-principal-class`	none	(optional) Customizes the `java.security.Principal` implementation class used when `activate-default-principal-to-role-mapping` is set to `true`.

selection-key-handler

Configures a selection key handler.

Superelements

transports

Subelements

none

Attributes

The following table describes attributes for the selection-key-handler element.

Table 1–149 selection-key-handler Attributes


Attribute	Default	Description
`name`	none	Specifies a unique name for the selection key handler.
`classname`	none	Specifies the class name of the selection key handler implementation.

server

Defines a server instance, which is a Java EE compliant container. One server instance is specially designated as a domain administration server (DAS). The admin-service subelement of the config element referenced by a server's config-ref attribute determines whether the server is the DAS.

Note –

Server instances are not the same thing as virtual servers. Each server instance is a completely separate server that contains one or more virtual servers.

Superelements

servers

Subelements

The following table describes subelements for the server element.

Table 1–150 server Subelements


Element	Required	Description
application-ref	zero or more	References an application or module deployed to the server instance.
resource-ref	zero or more	References a resource deployed to the server instance.
system-property	zero or more	Specifies a system property.
property	zero or more	Specifies a property or a variable.

Attributes

The following table describes attributes for the server element.

Table 1–151 server Attributes


Attribute	Default	Description
`name`	none	Specifies the name of the server instance.
`config-ref`	default config element’s `name`, `server-config`	(optional) References the `name` of the config used by the server instance.

servers

Contains server instances.

Superelements

domain

Subelements

The following table describes subelements for the servers element.

Table 1–152 servers Subelements


Element	Required	Description
server	only one	Defines a server instance.

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.

Superelements

web-container

Subelements

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

Table 1–153 session-config Subelements


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

session-manager

Specifies session manager information.

Note –

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

Superelements

session-config

Subelements

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

Table 1–154 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.

session-properties

Specifies session properties.

Superelements

session-config

Subelements

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

Table 1–155 session-properties Subelements


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

Attributes

Table 1–156 session-properties Attributes


Attribute	Default	Description
`timeout-in-seconds`	`1800`	(optional) 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 `timeout-in-seconds` value. If neither `session-timeout` nor `timeout-in-seconds` is specified, the `timeout-in-seconds` default is used. Note that the `session-timeout` element in `web.xml` is specified in minutes, not seconds.

Properties

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

Table 1–157 session-properties Properties


Property	Default	Description
`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^TM (JSP^TM) page.
`idLengthBytes`	`128`	Specifies the number of bytes in this web module’s session ID.

ssl

Defines SSL (Secure Socket Layer) parameters.

An ssl element is required inside an http-listener or iiop-listener element that has its security-enabled attribute set to on.

The grandparent http-service element has properties that configure global SSL settings.

Superelements

protocol, http-listener, iiop-listener, jmx-connector, ssl-client-config

Subelements

none

Attributes

The following table describes attributes for the ssl element.

Table 1–158 ssl Attributes


Attribute	Default	Description
`cert-nickname`	`s1as`	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 `+SSL_RSA_WITH_RC4_128_MD5` . Allowed values are `SSL_RSA_WITH_RC4_128_MD5`, `SSL_RSA_WITH_3DES_EDE_CBC_SHA`, `SSL_RSA_WITH_DES_CBC_SHA`, `SSL_RSA_EXPORT_WITH_RC4_40_MD5`, `SSL_RSA_WITH_NULL_MD5`, `SSL_RSA_WITH_RC4_128_SHA`, and `SSL_RSA_WITH_NULL_SHA`. Values available in previous releases are supported for backward compatibility.
`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 theSun GlassFish Enterprise Server v3 Administration Guide.
`client-auth-enabled`	`false`	(optional) Determines whether SSL3 client authentication is performed on every request, independent of ACL-based access control.
`crl-file`	none	(optional) Specifies the location of the Certificate Revocation List (CRL) file to consult during SSL client authentication. This can be an absolute or relative file path. If relative, it is resolved against `domain-dir`. If unspecified, CRL checking is disabled.
`trust-algorithm`	none	(optional) Specifies the name of the trust management algorithm (for example, `PKIX`) to use for certification path validation.
`trust-max-cert-length`	`5`	(optional) Specifies the maximum number of non-self-issued intermediate certificates that can exist in a certification path. This property is considered only if `trustAlgorithm` is set to `PKIX`. A value of zero implies that the path can only contain a single certificate. A value of `-1` implies that the path length is unconstrained (there is no maximum). Setting a value less than `-1` causes an exception to be thrown.
`key-store`	none	(optional) Specifies a key store.
`trust-store`	none	(optional) Specifies a trust store.

ssl-client-config

Defines SSL parameters for the ORB when it makes outbound SSL connections and behaves as a client.

Superelements

iiop-service

Subelements

The following table describes subelements for the ssl-client-config element.

Table 1–159 ssl-client-config Subelements


Element	Required	Description
ssl	only one	Defines SSL parameters.

store-properties

Specifies session persistence (storage) properties.

Superelements

session-manager

Subelements

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

Table 1–160 store-properties Subelements


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

Attributes

Table 1–161 store-properties Attributes


Attribute	Default	Description
`directory`	`domain-dir/generated/jsp/j2ee-apps/appname/appname_war`	(optional) 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.
`reap-interval-in-seconds`	`60`	(optional) Not implemented. Use the `reap-interval-in-seconds` attribute of the manager-properties element instead.

system-applications

Contains system applications. Do not delete or edit these applications.

Superelements

domain

Subelements

The following table describes subelements for the system-applications element.

Table 1–162 system-applications Subelements


Element	Required	Description
application	zero or more	Specifies an application.

system-property

Specifies a system property. A system property defines a common value for a setting at one of these levels, from highest to lowest: domain, server, or config. A value set at a higher level can be overridden at a lower level. Some system properties are predefined; see system-property. You can also create system properties using this element.

The following example shows the use of a predefined system property:

<log-service file="${com.sun.aas.instanceRoot}/logs/server.log">
    <module-log-levels admin=INFO .../>
</log-service>

The following example shows the creation and use of a system property:

<config name="config1">
    ...
    <http-service>
        ...
        <http-listener id="ls1" host="0.0.0.0" port="${ls1-port}"/>
        ...
    </http-service>
    ...
    <system-property name="ls1-port" value="8080"/>
</config>

Superelements

config, domain, server

Subelements

none

Attributes

The following table describes attributes for the system-property element.

Table 1–163 system-property Attributes


Attribute	Default	Description
`name`	none	Specifies the name of the system property.
`value`	none	Specifies the value of the system property.
`description`	none	(optional) Specifies a text description of this element.

Properties

The following table lists predefined system properties.

Table 1–164 Predefined System Properties


Property	Default	Description
`com.sun.aas.installRoot`	depends on operating system	Specifies the directory where the Enterprise Server is installed.
`com.sun.aas.instanceRoot`	depends on operating system	Specifies the top level directory for a server instance.
`com.sun.aas.hostName`	none	Specifies the name of the host (machine).
`com.sun.aas.javaRoot`	depends on operating system	Specifies the installation directory for the Java runtime.
`com.sun.aas.imqLib`	depends on operating system	Specifies the library directory for the Sun GlassFish Message Queue software.
`com.sun.aas.configName`	`server-config`	Specifies the name of the config used by a server instance.
`com.sun.aas.instanceName`	`server1`	Specifies the name of the server instance. This property is not used in the default configuration, but can be used to customize configuration.
`com.sun.aas.domainName`	`domain1`	Specifies the name of the domain. This property is not used in the default configuration, but can be used to customize configuration.
`com.sun.aas.derbyRoot`	`as-install/javadb`	Specifies the directory where Java DB is installed.