Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

Appendix A. Reference Material

A.1. Server Runtime Arguments

The application server startup script accepts arguments and switches at runtime. This allows the server to start under alternative configurations to those defined in the standalone.xml, domain.xml, and host.xml configuration files.

Alternative configurations might include starting the server with an alternative socket bindings set or a secondary configuration.

The available parameters list can be accessed by passing the help switch -h or --help at startup.

Table A.1. Runtime Switches and Arguments

Argument or SwitchOperating ModeDescription

--admin-only

Standalone

Set the server’s running type to ADMIN_ONLY. This will cause it to open administrative interfaces and accept management requests, but not start other runtime services or accept end user requests.

--admin-only

Domain

Set the host controller’s running type to ADMIN_ONLY causing it to open administrative interfaces and accept management requests but not start servers or, if this host controller is the master for the domain, accept incoming connections from slave host controllers.

-b=<value>, -b <value>

Standalone, Domain

Set system property jboss.bind.address, which is used in configuring the bind address for the public interface. This defaults to 127.0.0.1 if no value is specified. See the -b<interface>=<value> entry for setting the bind address for other interfaces.

-b<interface>=<value>

Standalone, Domain

Set system property jboss.bind.address.<interface> to the given value. For example, -bmanagement=IP_ADDRESS

--backup

Domain

Keep a copy of the persistent domain configuration even if this host is not the domain controller.

-c=<config>, -c <config>

Standalone

Name of the server configuration file to use. The default is standalone.xml.

-c=<config>, -c <config>

Domain

Name of the server configuration file to use. The default is domain.xml.

--cached-dc

Domain

If the host is not the domain controller and cannot contact the domain controller at boot, boot using a locally cached copy of the domain configuration.

--debug [<port>]

Standalone

Activate debug mode with an optional argument to specify the port. Only works if the launch script supports it.

-D<name>[=<value>]

Standalone, Domain

Set a system property.

--domain-config=<config>

Domain

Name of the server configuration file to use. The default is domain.xml.

-h, --help

Standalone, Domain

Display the help message and exit.

--host-config=<config>

Domain

Name of the host configuration file to use. The default is host.xml.

--interprocess-hc-address=<address>

Domain

Address on which the host controller should listen for communication from the process controller.

--interprocess-hc-port=<port>

Domain

Port on which the host controller should listen for communication from the process controller.

--master-address=<address>

Domain

Set system property jboss.domain.master.address to the given value. In a default slave host controller config, this is used to configure the address of the master host controller.

--master-port=<port>

Domain

Set system property jboss.domain.master.port to the given value. In a default slave host controller config, this is used to configure the port used for native management communication by the master host controller.

--read-only-server-config=<config>

Standalone

Name of the server configuration file to use. This differs from --server-config and -c in that the original file is never overwritten.

--read-only-domain-config=<config>

Domain

Name of the domain configuration file to use. This differs from --domain-config and -c in that the initial file is never overwritten.

--read-only-host-config=<config>

Domain

Name of the host configuration file to use. This differs from --host-config in that the initial file is never overwritten.

-P=<url>, -P <url>, --properties=<url>

Standalone, Domain

Load system properties from the given URL.

--pc-address=<address>

Domain

Address on which the process controller listens for communication from processes it controls.

--pc-port=<port>

Domain

Port on which the process controller listens for communication from processes it controls.

-S<name>[=<value>]

Standalone

Set a security property.

-secmgr

Standalone, Domain

Runs the server with a security manager installed.

--server-config=<config>

Standalone

Name of the server configuration file to use. The default is standalone.xml.

-u=<value>, -u <value>

Standalone, Domain

Set system property jboss.default.multicast.address, which is used in configuring the multicast address in the socket-binding elements in the configuration files. This defaults to 230.0.0.4 if no value is specified.

-v, -V, --version

Standalone, Domain

Display the application server version and exit.

Warning

The configuration files that ship with JBoss EAP are set up to handle the behavior of the switches, for example, -b and -u. If you change your configuration files to no longer use the system property controlled by the switch, then adding it to the launch command will have no effect.

A.2. RPM Service Configuration Files

The RPM installation of JBoss EAP includes two additional configuration files compared to a ZIP or installer installation. These files are used by the service init script to specify the JBoss EAP launch environment. The location of these service configuration files differ for Red Hat Enterprise Linux 6 and Red Hat Enterprise Linux 7.

Important

For Red Hat Enterprise Linux 7, RPM service configuration files are loaded using systemd, so variable expressions are not expanded.

Table A.2. RPM Configuration Files for Red Hat Enterprise Linux 6

FileDescription

/etc/sysconfig/eap7-standalone

Settings specific to standalone JBoss EAP servers on Red Hat Enterprise Linux 6.

/etc/sysconfig/eap7-domain

Settings specific to JBoss EAP running as a managed domain on Red Hat Enterprise Linux 6.

Table A.3. RPM Configuration Files for Red Hat Enterprise Linux 7

FileDescription

/etc/opt/rh/eap7/wildfly/eap7-standalone.conf

Settings specific to standalone JBoss EAP servers on Red Hat Enterprise Linux 7.

/etc/opt/rh/eap7/wildfly/eap7-domain.conf

Settings specific to JBoss EAP running as a managed domain on Red Hat Enterprise Linux 7.

A.3. RPM Service Configuration Properties

The following table shows a list of available configuration properties for the JBoss EAP RPM service along with their default values.

Note

If a property has the same name in both the RPM service configuration file (for example, /etc/sysconfig/eap7-standalone) and in the JBoss EAP startup configuration file (for example, EAP_HOME/bin/standalone.conf), the value that takes precedence is the one in the JBoss EAP startup configuration file. One such property is JAVA_HOME.

Table A.4. RPM Service Configuration Properties

PropertyDescription

JAVA_HOME

The directory where your Java Runtime Environment is installed.

Default value: /usr/lib/jvm/jre

JAVAPTH

The path where the Java executable files are installed.

Default value: $JAVA_HOME/bin

WILDFLY_STARTUP_WAIT

The number of seconds that the init script will wait until confirming that the server has launched successfully after receiving a start or restart command. This property only applies to Red Hat Enterprise Linux 6.

Default value: 60

WILDFLY_SHUTDOWN_WAIT

The number of seconds that the init script will wait for the server to shutdown before continuing when it receives a stop or restart command. This property only applies to Red Hat Enterprise Linux 6.

Default value: 20

WILDFLY_CONSOLE_LOG

The file that the CONSOLE log handler will be redirected to.

Default value: /var/opt/rh/eap7/log/wildfly/standalone/console.log for a standalone server, or /var/opt/rh/eap7/log/wildfly/domain/console.log for a managed domain.

WILDFLY_SH

The script which is used to launch to JBoss EAP server.

Default value: /opt/rh/eap7/root/usr/share/wildfly/bin/standalone.sh for a standalone server, or /opt/rh/eap7/root/usr/share/wildfly/bin/domain.sh for a managed domain.

WILDFLY_SERVER_CONFIG

The server configuration file to use.

There is no default for this property. Either standalone.xml or domain.xml can be defined at start.

WILDFLY_HOST_CONFIG

For a managed domain, this property allows a user to specify the host configuration file (such as host.xml). It has no value set as the default.

WILDFLY_MODULEPATH

The path of the JBoss EAP module directory.

Default value: /opt/rh/eap7/root/usr/share/wildfly/modules

WILDFLY_BIND

Sets the jboss.bind.address system property, which is used to configure the bind address for the public interface. This defaults to 0.0.0.0 if no value is specified.

A.4. Overview of JBoss EAP Subsystems

The table below gives a brief description of the JBoss EAP subsystems.

Table A.5. JBoss EAP Subsystems

JBoss EAP SubsystemDescription

batch-jberet

Configure an environment for running batch applications and manage batch jobs.

bean-validation

Configure bean validation for validating Java object data.

datasources

Create and configure datasources and manage JDBC database drivers.

deployment-scanner

Configure deployment scanners to monitor particular locations for applications to deploy.

ee

Configure common functionality in the Java EE platform, such as defining global modules, enabling descriptor-based property replacement, and configuring default bindings.

ejb3

Configure Enterprise JavaBeans (EJBs), including session and message-driven beans.

More information for the ejb3 subsystem can be found in Developing EJB Applications for JBoss EAP.

iiop-openjdk

Configure Common Object Request Broker Architecture (CORBA) services for JTS transactions and other ORB services, including security. In JBoss EAP 6, this functionality was contained in the jacorb subsystem.

infinispan

Configure caching functionality for JBoss EAP high availability services.

io

Define workers and buffer pools to be used by other subsystems.

jaxrs

Enable the deployment and functionality of JAX-RS applications.

jca

Configure the general settings for the Java EE Connector Architecture (JCA) container and resource adapter deployments.

jdr

Enable the gathering of diagnostic data to aid in troubleshooting. JBoss EAP subscribers can provide this information to Red Hat when requesting support.

jgroups

Configure the protocol stacks and communication mechanisms for how servers in a cluster talk to each other.

jmx

Configure remote Java Management Extensions (JMX) access.

jpa

Manages the Java Persistence API (JPA) 2.1 container-managed requirements and allows you to deploy persistent unit definitions, annotations, and descriptors.

More information for the jpa subsystem can be found in the JBoss EAP Development Guide.

jsf

Manage JavaServer Faces (JSF) implementations.

jsr77

Provide Java EE management capabilities defined by the JSR-77 specification.

logging

Configure system and application-level logging through a system of log categories and log handlers.

mail

Configure mail server attributes and custom mail transports to create a mail service that allows applications deployed to JBoss EAP to send mail using that service.

messaging-activemq

Configure JMS destinations, connection factories, and other settings for Artemis, the integrated messaging provider. In JBoss EAP 6, messaging functionality was contained in the messaging subsystem.

More information for the messaging-activemq subsystem can be found in Configuring Messaging for JBoss EAP.

modcluster

Configure the server-side mod_cluster worker node.

naming

Bind entries into global JNDI namespaces and configure the remote JNDI interface.

picketlink-federation

Configure PicketLink SAML-based single sign-on (SSO).

More information on the picketlink-federation subsystem can be found in How To Set Up SSO with SAML v2 for JBoss EAP.

picketlink-identity-management

Configure PicketLink identity management services. This subsystem is unsupported.

pojo

Enable deployment of applications containing JBoss Microcontainer services, as supported by previous versions of JBoss EAP.

remoting

Configure settings for inbound and outbound connections for local and remote services.

request-controller

Configure settings to suspend and shut down servers gracefully.

resource-adapters

Configure and maintain resource adapters for communication between Java EE applications and an Enterprise Information System (EIS) using the Java Connector Architecture (JCA) specification.

rts

Unsupported implementation of REST-AT.

sar

Enable deployment of SAR archives containing MBean services, as supported by previous versions of JBoss EAP.

security

Configure application security settings.

More information on the security subsystem can be found in Security Architecture for JBoss EAP.

security-manager

Configure Java security policies to be used by the Java Security Manager.

More information on the security-manager subsystem can be found in How to Configure Server Security for JBoss EAP.

singleton

Define singleton policies to configure the behavior of singleton deployments or to create singleton MSC services.

More information on the singleton subsystem can be found in the JBoss EAP Development Guide.

transactions

Configure transaction manager options, such as timeout values, transaction logging, and whether to use Java Transaction Service (JTS).

undertow

Configure JBoss EAP’s web server and servlet container settings. In JBoss EAP 6, this functionality was contained in the web subsystem.

webservices

Configure published endpoint addresses and endpoint handler chains, as well as the host name, ports, and WSDL address for the web services provider.

More information for the webservices subsystem can be found in Developing Web Services Applications for JBoss EAP.

weld

Configure Contexts and Dependency Injection (CDI) functionality for JBoss EAP.

xts

Configure settings for coordinating web services in a transaction.

A.5. Add-User Utility Arguments

The following table describes the arguments available for the add-user.sh or add-user.bat script, which is a utility for adding new users to the properties file for out-of-the-box authentication.

Table A.6. Add-User Command Arguments

Command Line ArgumentDescription

-a

Create a user in the application realm. If omitted, the default is to create a user in the management realm.

-dc <value>

The domain configuration directory that will contain the properties files. If it is omitted, the default directory is EAP_HOME/domain/configuration/.

-sc <value>

An alternative standalone server configuration directory that will contain the properties files. If omitted, the default directory is EAP_HOME/standalone/configuration/.

-up, --user-properties <value>

The name of the alternative user properties file. It can be an absolute path or it can be a file name used in conjunction with the -sc or -dc argument that specifies the alternative configuration directory.

-g, --group <value>

A comma-separated list of groups to assign to this user.

-gp, --group-properties <value>

The name of the alternative group properties file. It can be an absolute path or it can be a file name used in conjunction with the -sc or -dc argument that specifies the alternative configuration directory.

-p, --password <value>

The password of the user.

-u, --user <value>

The name of the user. Only alphanumeric characters and the following symbols are valid: ,./=@\.

-r, --realm <value>

The name of the realm used to secure the management interfaces. If omitted, the default is ManagementRealm.

-s, --silent

Run the add-user script with no output to the console.

-e, --enable

Enable the user.

-d, --disable

Disable the user.

-cw, --confirm-warning

Automatically confirm warning in interactive mode.

-h, --help

Display usage information for the add-user script.

A.6. Management Audit Logging Attributes

Table A.7. Logger Attributes

AttributeDescription

enabled

Whether audit logging is enabled.

log-boot

Whether operations should be logged on server boot.

log-read-only

Whether operations that do not modify the configuration or any runtime services should be logged.

Table A.8. Log Formatter Attributes

AttributeDescription

compact

If true, it will format the JSON on one line. There may still be values containing new lines, so if having the whole record on one line is important, set escape-new-line or escape-control-characters to true.

date-format

The date format to use as understood by java.text.SimpleDateFormat. This is ignored if include-date is set to false.

date-separator

The separator between the date and the rest of the formatted log message. This is ignored if include-date is set to false.

escape-control-characters

If true, it will escape all control characters (ASCII entries with a decimal value greater than 32) with the ASCII code in octal. For example, a new line becomes #012. If true, this will override escape-new-line=false.

escape-new-line

If true, it will escape all new lines with the ASCII code in octal: #012.

include-date

Whether or not to include the date in the formatted log record.

Table A.9. File Handler Attributes

AttributeDescription

disabled-due-to-failure

Whether this handler has been disabled due to logging failures (read-only).

failure-count

The number of logging failures since the handler was initialized (read-only).

formatter

The JSON formatter used to format the log messages.

max-failure-count

The maximum number of logging failures before disabling this handler.

path

The path of the audit log file.

relative-to

The name of another previously named path, or of one of the standard paths provided by the system. If relative-to is provided, the value of the path attribute is treated as relative to the path specified by this attribute.

Table A.10. Syslog Handler Attributes

AttributeDescription

app-name

The application name to add to the syslog records as defined in section 6.2.5 of RFC-5424. If not specified it will default to the name of the product.

disabled-due-to-failure

Whether this handler has been disabled due to logging failures (read-only).

facility

The facility to use for syslog logging as defined in section 6.2.1 of RFC-5424 and section 4.1.1 of RFC-3164.

failure-count

The number of logging failures since the handler was initialized (read-only).

formatter

The JSON formatter used to format the log messages.

max-failure-count

The maximum number of logging failures before disabling this handler.

max-length

The maximum length in bytes a log message, including the header, is allowed to be. If undefined, it will default to 1024 bytes if the syslog-format is RFC3164, or 2048 bytes if the syslog-format is RFC5424.

protocol

The protocol to use for the syslog handler. Must be one and only one of udp, tcp or tls.

syslog-format

The syslog format: RFC5424 or RFC3164.

truncate

Whether or not a message, including the header, should truncate the message if the length in bytes is greater than the value of the max-length attribute. If set to false, messages will be split and sent with the same header values.

Note

Syslog servers vary in their implementation, so not all settings are applicable to all syslog servers. Testing has been conducted using the rsyslog syslog implementation.

This table lists only the high-level attributes. Each attribute has configuration parameters, and some have child configuration parameters.

A.7. Interface Attributes

Table A.11. Interface Attributes and Values

Interface ElementDescription

any

Element indicating that part of the selection criteria for an interface should be that it meets at least one, but not necessarily all, of the nested set of criteria.

any-address

Empty element indicating that sockets using this interface should be bound to a wildcard address. The IPv6 wildcard address (::) will be used unless the java.net.preferIPv4Stack system property is set to true, in which case the IPv4 wildcard address (0.0.0.0) will be used. If a socket is bound to an IPv6 anylocal address on a dual-stack machine, it can accept both IPv6 and IPv4 traffic; if it is bound to an IPv4 (IPv4-mapped) anylocal address, it can only accept IPv4 traffic.

inet-address

Either an IP address in IPv6 or IPv4 dotted decimal notation, or a host name that can be resolved to an IP address.

link-local-address

Empty element indicating that part of the selection criteria for an interface should be whether or not an address associated with it is link-local.

loopback

Empty element indicating that part of the selection criteria for an interface should be whether or not it is a loopback interface.

loopback-address

A loopback address that may not actually be configured on the machine’s loopback interface. Differs from inet-address type in that the given value will be used even if no NIC can be found that has the IP address associated with it.

multicast

Empty element indicating that part of the selection criteria for an interface should be whether or not it supports multicast.

nic

The name of a network interface (e.g. eth0, eth1, lo).

nic-match

A regular expression against which the names of the network interfaces available on the machine can be matched to find an acceptable interface.

not

Element indicating that part of the selection criteria for an interface should be that it does not meet any of the nested set of criteria.

point-to-point

Empty element indicating that part of the selection criteria for an interface should be whether or not it is a point-to-point interface.

public-address

Empty element indicating that part of the selection criteria for an interface should be whether or not it has a publicly routable address.

site-local-address

Empty element indicating that part of the selection criteria for an interface should be whether or not an address associated with it is site-local.

subnet-match

A network IP address and the number of bits in the address' network prefix, written in slash notation (e.g. 192.168.0.0/16).

up

Empty element indicating that part of the selection criteria for an interface should be whether or not it is currently up.

virtual

Empty element indicating that part of the selection criteria for an interface should be whether or not it is a virtual interface.

A.8. Socket Binding Attributes

Table A.12. Socket Binding Attributes

AttributeDescription

client-mappings

Specifies the client mappings for this socket binding. A client connecting to this socket should use the destination address specified in the mapping that matches its desired outbound interface. This allows for advanced network topologies that use either network address translation, or have bindings on multiple network interfaces to function. Each mapping should be evaluated in declared order, with the first successful match used to determine the destination.

fixed-port

Whether the port value should remain fixed even if numeric offsets are applied to the other sockets in the socket group.

interface

Name of the interface to which the socket should be bound, or, for multicast sockets, the interface on which it should listen. This should be one of the declared interfaces. If not defined, the value of the default-interface attribute from the enclosing socket binding group will be used.

multicast-address

Multicast address on which the socket should receive multicast traffic. If unspecified, the socket will not be configured to receive multicast.

multicast-port

Port on which the socket should receive multicast traffic. Must be configured if 'multicast-address' is configured.

name

The name of the socket. Services needing to access the socket configuration information will find it using this name. This attribute is required.

port

Number of the port to which the socket should be bound. Note that this value can be overridden if servers apply a port-offset to increment or decrement all port values.

A.9. Default Socket Bindings

Table A.13. Default Socket Bindings

NamePortMulticast PortDescriptionSocket Binding Groups

ajp

8009

 

Apache JServ Protocol. Used for HTTP clustering and load balancing.

standard-sockets, ha-sockets, full-sockets, full-ha-sockets

http

8080

 

The default port for deployed web applications.

standard-sockets, ha-sockets, full-sockets, full-ha-sockets

https

8443

 

SSL-encrypted connection between deployed web applications and clients.

standard-sockets, ha-sockets, full-sockets, full-ha-sockets

iiop

3528

 

CORBA services for JTS transactions and other ORB-dependent services.

full-sockets, full-ha-sockets

iiop-ssl

3529

 

SSL-encrypted CORBA services.

full-sockets, full-ha-sockets

jgroups-mping

 

45700

Multicast. Used to discover initial membership in a HA cluster.

ha-sockets, full-ha-sockets

jgroups-tcp

7600

 

Unicast peer discovery in HA clusters using TCP.

ha-sockets, full-ha-sockets

jgroups-tcp-fd

57600

 

Used for HA failure detection over TCP.

ha-sockets, full-ha-sockets

jgroups-udp

55200

45688

Multicast peer discovery in HA clusters using UDP.

ha-sockets, full-ha-sockets

jgroups-udp-fd

54200

 

Used for HA failure detection over UDP.

ha-sockets, full-ha-sockets

management-http

9990

 

Used for HTTP communication with the management layer.

standard-sockets, ha-sockets, full-sockets, full-ha-sockets

management-https

9993

 

Used for HTTPS communication with the management layer.

standard-sockets, ha-sockets, full-sockets, full-ha-sockets

modcluster

 

23364

Multicast port for communication between JBoss EAP and the HTTP load balancer.

ha-sockets, full-ha-sockets

txn-recovery-environment

4712

 

The JTA transaction recovery manager.

standard-sockets, ha-sockets, full-sockets, full-ha-sockets

txn-status-manager

4713

 

The JTA / JTS transaction manager.

standard-sockets, ha-sockets, full-sockets, full-ha-sockets

A.10. Deployment Scanner Marker Files

Marker files are used by the deployment scanner to mark the status of an application within the deployment directory of the JBoss EAP server instance. A marker file has the same name as the deployment, with the file suffix indicating the state of the application’s deployment.

For example, a successful deployment of test-application.war would have a marker file named test-application.war.deployed.

The following table lists the available marker file types and their meanings.

Table A.14. Marker File Types

Filename SuffixOriginDescription

.deployed

System-generated

Indicates that the content has been deployed. The content will be undeployed if this file is deleted.

.dodeploy

User-generated

Indicates that the content should be deployed or redeployed.

.failed

System-generated

Indicates deployment failure. The marker file contains information about the cause of failure. If the marker file is deleted, the content will be eligible for auto-deployment again.

.isdeploying

System-generated

Indicates that the deployment is in progress. This marker file will be deleted upon completion.

.isundeploying

System-generated

Triggered by deleting a .deployed file, this indicates that the content is being undeployed. This marker file will be deleted upon completion.

.pending

System-generated

Indicates that the deployment scanner recognizes the need to deploy content, but an issue is currently preventing auto-deployment (for example, if content is in the process of being copied). This marker serves as a global deployment road-block, meaning that the scanner will not instruct the server to deploy or undeploy any content while this marker file exists.

.skipdeploy

User-generated

Disables auto-deploy of an application while present. Useful as a method of temporarily blocking the auto-deployment of exploded content, preventing the risk of incomplete content edits being pushed. Can be used with zipped content, although the scanner detects in-progress changes to zipped content and waits until completion.

.undeployed

System-generated

Indicates that the content has been undeployed. Deletion of this marker file has no impact to content redeployment.

A.11. Deployment Scanner Attributes

The deployment scanner contains the following configurable attributes.

Table A.15. Deployment Scanner Attributes

NameDefaultDescription

auto-deploy-exploded

false

Allows the automatic deployment of exploded content without requiring a .dodeploy marker file. Recommended for only basic development scenarios to prevent exploded application deployment from occurring during changes by the developer or operating system.

auto-deploy-xml

true

Allows the automatic deployment of XML content without requiring a .dodeploy marker file.

auto-deploy-zipped

true

Allows the automatic deployment of zipped content without requiring a .dodeploy marker file.

deployment-timeout

600

The time value in seconds for the deployment scanner to allow a deployment attempt before being canceled.

path

deployments

The actual file system path to be scanned. Treated as an absolute path, unless the relative-to attribute is specified, in which case the value is treated as relative to that path.

relative-to

jboss.server.base.dir

Reference to a file system path defined as a path in the server configuration.

runtime-failure-causes-rollback

false

Whether a runtime failure of a deployment causes a rollback of the deployment as well as all other (possibly unrelated) deployments as part of the scan operation.

scan-enabled

true

Allows the automatic scanning for applications by scan-interval and at startup.

scan-interval

5000

The time interval in milliseconds that the repository should be scanned for changes. A value of less than 1 causes the scan to occur only at initial startup.

A.12. Mail Subsystem Attributes

The following tables describe the attributes in the mail subsystem for mail sessions and the following mail server types:

Table A.16. Mail Session Attributes

AttributeDescription

debug

Whether to enable JavaMail debugging.

from

The default "from" address to use if not set when sending.

jndi-name

The JNDI name to which the mail session should be bound.

Table A.17. IMAP Mail Server Attributes

AttributeDescription

outbound-socket-binding-ref

Reference to the outbound socket binding for the mail server.

password

The password to authenticate on the server.

ssl

Whether the server requires SSL.

tls

Whether the server requires TLS.

username

The username to authenticate on the server.

Table A.18. POP3 Mail Server Attributes

AttributeDescription

outbound-socket-binding-ref

Reference to the outbound socket binding for the mail server.

password

The password to authenticate on the server.

ssl

Whether the server requires SSL.

tls

Whether the server requires TLS.

username

The username to authenticate on the server.

Table A.19. SMTP Mail Server Attributes

AttributeDescription

outbound-socket-binding-ref

Reference to the outbound socket binding for the mail server.

password

The password to authenticate on the server.

ssl

Whether the server requires SSL.

tls

Whether the server requires TLS.

username

The username to authenticate on the server.

Table A.20. Custom Mail Server Attributes

AttributeDescription

outbound-socket-binding-ref

Reference to the outbound socket binding for the mail server.

password

The password to authenticate on the server.

properties

The JavaMail properties for this server.

ssl

Whether the server requires SSL.

tls

Whether the server requires TLS.

username

The username to authenticate on the server.

A.13. Root Logger Attributes

Table A.21. Root Logger Attributes

AttributeDescription

filter

Defines a simple filter type. Deprecated in favor of filter-spec.

filter-spec

An expression value that defines a filter. The following expression defines a filter that excludes log entries that do not match a pattern: not(match("WFLY.*"))

handlers

A list of log handlers that are used by the root logger.

level

The lowest level of log message that the root logger records.

Note

A filter-spec specified for the root logger is not inherited by other handlers. Instead a filter-spec must be specified per handler.

A.14. Log Category Attributes

Table A.22. Log Category Attributes

AttributeDescription

category

The log category from which log messages will be captured.

filter

Defines a simple filter type. Deprecated in favor of filter-spec.

filter-spec

An expression value that defines a filter. The following expression defines a filter that does not match a pattern: not(match("WFLY.*"))

handlers

A list of log handlers associated with the logger.

level

The lowest level of log message that the log category records.

use-parent-handlers

If set to true, this category will use the log handlers of the root logger in addition to any other assigned handlers.

A.15. Log Handler Attributes

Table A.23. Console Log Handler Attributes

AttributeDescription

autoflush

If set to true, the log messages will be sent to the handlers assigned file immediately upon receipt.

enabled

If set to true, the handler is enabled and functioning as normal. If set to false, the handler is ignored when processing log messages.

encoding

The character encoding scheme to be used for the output.

filter

Defines a simple filter type. Deprecated in favor of filter-spec.

filter-spec

An expression value that defines a filter. The following expression defines a filter that does not match a pattern: not(match("WFLY.*"))

formatter

The log formatter used by this log handler.

level

The lowest level of log message the log handler records.

name

The name of the log handler. Deprecated since the handler’s address contains the name.

named-formatter

The name of the defined formatter to be used on the handler.

target

The system output stream where the output of the log handler goes. This can be System.err or System.out for the system error stream or standard out stream respectively.

Table A.24. File Log Handler Attributes

AttributeDescription

append

If set to true, all messages written by this handler will be appended to the file if it already exists. If set to false, a new file will be created each time the application server launches.

autoflush

If set to true, the log messages will be sent to the handlers assigned file immediately upon receipt.

enabled

If set to true, the handler is enabled and functioning as normal. If set to false, the handler is ignored when processing log messages.

encoding

The character encoding scheme to be used for the output.

file

The object that represents the file where the output of this log handler is written to. It has two configuration properties, relative-to and path.

filter

Defines a simple filter type. Deprecated in favor of filter-spec.

filter-spec

An expression value that defines a filter. The following expression defines a filter that does not match a pattern: not(match("WFLY.*"))

formatter

The log formatter used by this log handler.

level

The lowest level of log message the log handler records.

name

The name of the log handler. Deprecated since the handler’s address contains the name.

named-formatter

The name of the defined formatter to be used on the handler.

Table A.25. Periodic Log Handler Attributes

AttributeDescription

append

If set to true, all messages written by this handler will be appended to the file if it already exists. If set to false, a new file will be created each time the application server launches.

autoflush

If set to true, the log messages will be sent to the handlers assigned file immediately upon receipt.

enabled

If set to true, the handler is enabled and functioning as normal. If set to false, the handler is ignored when processing log messages.

encoding

The character encoding scheme to be used for the output.

file

Object that represents the file to which the output of this log handler is written. It has two configuration properties, relative-to and path.

filter

Defines a simple filter type. Deprecated in favor of filter-spec.

filter-spec

An expression value that defines a filter. The following expression defines a filter that does not match a pattern: not(match("WFLY.*")).

formatter

The log formatter used by this log handler.

level

The lowest level of log message the log handler records.

name

The name of the log handler. Deprecated since the handler’s address contains the name.

named-formatter

The name of the defined formatter to be used on the handler.

suffix

This string is included in the suffix appended to rotated logs. The format of the suffix is a dot (.) followed by a date string which is able to be parsed by the SimpleDateFormat class.

Table A.26. Size Log Handler Attributes

AttributeDescription

append

If set to true, all messages written by this handler will be appended to the file if it already exists. If set to false, a new file will be created each time the application server launches.

autoflush

If set to true the log messages will be sent to the handlers assigned file immediately upon receipt.

enabled

If set to true, the handler is enabled and functioning as normal. If set to false, the handler is ignored when processing log messages.

encoding

The character encoding scheme to be used for the output.

file

Object that represents the file where the output of this log handler is written to. It has two configuration properties, relative-to and path.

filter

Defines a simple filter type. Deprecated in favor of filter-spec.

filter-spec

An expression value that defines a filter. The following expression defines a filter that does not match a pattern: not(match("WFLY.*"))

formatter

The log formatter used by this log handler.

level

The lowest level of log message the log handler records.

max-backup-index

The maximum number of rotated logs that are kept. When this number is reached, the oldest log is reused. The default is 1.

If the suffix attribute is used, the suffix of rotated log files is included in the rotation algorithm. When the log file is rotated, the oldest file whose name starts with name+suffix is deleted, the remaining rotated log files have their numeric suffix incremented and the newly rotated log file is given the numeric suffix 1.

name

The name of the log handler. Deprecated since the handler’s address contains the name.

named-formatter

The name of the defined formatter to be used on the handler.

rotate-on-boot

If set to true, a new log file will be created on server restart. The default is false.

rotate-size

The maximum size that the log file can reach before it is rotated. A single character appended to the number indicates the size units: b for bytes, k for kilobytes, m for megabytes, g for gigabytes. For example, 50m for 50 megabytes.

suffix

This string is included in the suffix appended to rotated logs. The format of the suffix is a dot (.) followed by a date string which is able to be parsed by the SimpleDateFormat class.

Table A.27. Periodic Size Log Handler Attributes

AttributeDescription

append

If set to true, all messages written by this handler will be appended to the file if it already exists. If set to false, a new file will be created each time the application server launches.

autoflush

If set to true, the log messages will be sent to the handlers assigned file immediately upon receipt.

enabled

If set to true, the handler is enabled and functioning as normal. If set to false, the handler is ignored when processing log messages.

encoding

The character encoding scheme to be used for the output.

file

Object that represents the file where the output of this log handler is written to. It has two configuration properties, relative-to and path.

filter-spec

An expression value that defines a filter. The following expression defines a filter that does not match a pattern: not(match("WFLY.*"))

formatter

The log formatter used by this log handler.

level

The lowest level of log message the log handler records.

max-backup-index

The maximum number of rotated logs that are kept. When this number is reached, the oldest log is reused. The default is 1.

If the suffix attribute is used, the suffix of rotated log files is included in the rotation algorithm. When the log file is rotated, the oldest file whose name starts with name+suffix is deleted, the remaining rotated log files have their numeric suffix incremented and the newly rotated log file is given the numeric suffix 1.

name

The name of the log handler. Deprecated since the handler’s address contains the name.

named-formatter

The name of the defined formatter to be used on the handler.

rotate-on-boot

If set to true, a new log file will be created on server restart. The default is false.

rotate-size

The maximum size that the log file can reach before it is rotated. A single character appended to the number indicates the size units: b for bytes, k for kilobytes, m for megabytes, g for gigabytes. For example, 50m for 50 megabytes.

suffix

This string is included in the suffix appended to rotated logs. The format of the suffix is a dot (.) followed by a date string which is able to be parsed by the SimpleDateFormat class.

Table A.28. Syslog Handler Attributes

AttributeDescription

app-name

The app name used when formatting the message in RFC5424 format. By default the app name is java.

enabled

If set to true, the handler is enabled and functioning as normal. If set to false, the handler is ignored when processing log messages.

facility

The facility as defined by RFC-5424 and RFC-3164.

hostname

The name of the host from which the messages are being sent. For example, the name of the host the application server is running on.

level

The lowest level of log message the log handler records.

port

The port on which the syslog server is listening.

server-address

The address of the syslog server.

syslog-format

Formats the log message according to the RFC specification.

Table A.29. Custom Log Handler Attributes

AttributeDescription

class

The logging handler class to be used.

enabled

If set to true, the handler is enabled and functioning as normal. If set to false, the handler is ignored when processing log messages.

encoding

The character encoding scheme to be used for the output.

filter

Defines a simple filter type. Deprecated in favor of filter-spec.

filter-spec

An expression value that defines a filter. The following expression defines a filter that does not match a pattern: not(match("WFLY.*"))

formatter

The log formatter used by this log handler.

level

The lowest level of log message the log handler records.

module

The module one which the logging handler depends.

name

The name of the log handler. Deprecated since the handler’s address contains the name.

named-formatter

The name of the defined formatter to be used on the handler.

properties

The properties used for the logging handler.

Table A.30. Async Log Handler Attributes

AttributeDescription

enabled

If set to true, the handler is enabled and functioning as normal. If set to false, the handler is ignored when processing log messages.

filter

Defines a simple filter type. Deprecated in favor of filter-spec.

filter-spec

An expression value that defines a filter. The following expression defines a filter that does not match a pattern: not(match("WFLY.*"))

level

The lowest level of log message the log handler records.

name

The name of the log handler. Deprecated since the handler’s address contains the name.

overflow-action

How this handler responds when its queue length is exceeded. This can be set to BLOCK or DISCARD. BLOCK makes the logging application wait until there is available space in the queue. This is the same behavior as an non-async log handler. DISCARD allows the logging application to continue but the log message is deleted.

queue-length

Maximum number of log messages that will be held by this handler while waiting for sub-handlers to respond.

subhandlers

The list of log handlers to which this async handler passes its log messages.

A.16. Datasource Connection URLs

Table A.31. Datasource Connection URLs

DatasourceConnection URL

IBM DB2

jdbc:db2://SERVER_NAME:PORT/DATABASE_NAME

MariaDB

jdbc:mariadb://SERVER_NAME:PORT/DATABASE_NAME

Microsoft SQL Server

jdbc:sqlserver://SERVER_NAME:PORT;DatabaseName=DATABASE_NAME

MySQL

jdbc:mysql://SERVER_NAME:PORT/DATABASE_NAME

Oracle

jdbc:oracle:thin:@SERVER_NAME:PORT:ORACLE_SID

PostgreSQL

jdbc:postgresql://SERVER_NAME:PORT/DATABASE_NAME

Sybase

jdbc:sybase:Tds:SERVER_NAME:PORT/DATABASE_NAME

A.17. Datasource Parameters

Table A.32. Datasource Parameters

ParameterDatasource TypeDescription

allocation-retry

Non-XA, XA

The number of times that allocating a connection should be tried before throwing an exception. The default is 0, so an exception is thrown upon the first failure.

allocation-retry-wait-millis

Non-XA, XA

The amount of time, in milliseconds, to wait between retrying to allocate a connection. The default is 5000 ms.

allow-multiple-users

Non-XA, XA

Whether multiple users will access the datasource through the getConnection(user, password) method and if the internal pool type accounts for this behavior.

background-validation

Non-XA, XA

Whether connections should be validated on a background thread versus being validated prior to use. Background validation is typically not to be used with validate-on-match or there will be redundant checks. With background validation, there is an opportunity for a connection to go bad between the time of the validations can and being handed to the client, so the application must account for this possibility.

background-validation-millis

Non-XA, XA

The frequency, in milliseconds, that background validation will run.

blocking-timeout-wait-millis

Non-XA, XA

The maximum time, in milliseconds, to block while waiting for a connection before throwing an exception. Note that this blocks only while waiting for locking a connection, and will never throw an exception if creating a new connection takes an inordinately long time.

capacity-decrementer-class

Non-XA, XA

Class defining the policy for decrementing connections in the pool.

capacity-decrementer-properties

Non-XA, XA

Properties to be injected in the class defining the policy for decrementing connections in the pool.

capacity-incrementer-class

Non-XA, XA

Class defining the policy for incrementing connections in the pool.

capacity-incrementer-properties

Non-XA, XA

Properties to be injected in the class defining the policy for incrementing connections in the pool.

check-valid-connection-sql

Non-XA, XA

An SQL statement to check validity of a pool connection. This may be called when a managed connection is obtained from the pool.

connectable

Non-XA, XA

Enable the use of CMR, which means that a local resource can reliably participate in an XA transaction.

connection-listener-class

Non-XA, XA

Specifies class name extending org.jboss.jca.adapters.jdbc.spi.listener.ConnectionListener. This class listens for connection activation and passivation in order to perform actions before the connection is returned to the application or to the pool. The specified class must be bundled together with the JDBC driver in one module using two resource jars (Install a JDBC Driver as a Core Module), or in separate global module (Define Global Modules).

connection-listener-property

Non-XA, XA

Properties to be injected into the class specified in the connection-listener-class. The properties injected are compliant with the JavaBeans conventions. For example, if you specify a property named foo, then the connection listener class needs to have a method setFoo that accepts String as argument.

connection-properties

Non-XA Only

Arbitrary string name/value pair connection properties to pass to the Driver.connect(url, props) method.

connection-url

Non-XA Only

The JDBC driver connection URL.

datasource-class

Non-XA Only

The fully-qualified name of the JDBC datasource class.

driver-class

Non-XA Only

The fully-qualified name of the JDBC driver class.

driver-name

Non-XA, XA

Defines the JDBC driver the datasource should use. It is a symbolic name matching the name of installed driver. If the driver is deployed as JAR, the name is the name of the deployment.

enabled

Non-XA, XA

Whether the datasource should be enabled.

enlistment-trace

Non-XA, XA

Whether enlistment traces should be recorded.

exception-sorter-class-name

Non-XA, XA

An instance of org.jboss.jca.adapters.jdbc.ExceptionSorter that provides a method to validate if an exception should broadcast an error.

exception-sorter-properties

Non-XA, XA

The exception sorter properties.

flush-strategy

Non-XA, XA

Specifies how the pool should be flushed in case of an error. Valid values are:

FailingConnectionOnly
Only the failing connection is removed. This is the default setting.
InvalidIdleConnections
The failing connection and idle connections that share the same credentials and are returned as invalid by the ValidatingManagedConnectionFactory.getInvalidConnections(…​) method are removed.
IdleConnections
The failing connection and idle connections that share the same credentials are removed.
Gracefully
The failing connection and idle connections that share the same credentials are removed. Active connections that share the same credentials are destroyed upon return to the pool.
EntirePool
The failing connection and idle and active connections that share the same credentials are removed. This setting is not recommended for production systems.
AllInvalidIdleConnections
The failing connection and idle connections that are returned as invalid by the ValidatingManagedConnectionFactory.getInvalidConnections(…​) method are removed.
AllIdleConnections
The failing connection and all idle connections are removed.
AllGracefully
The failing connection and all idle connections are removed. Active connections are destroyed upon return to the pool.
AllConnections
The failing connection and all idle and active connections are removed. This setting is not recommended for production systems.

idle-timeout-minutes

Non-XA, XA

The maximum time, in minutes, a connection may be idle before being closed. If not specified, the default is 30 minutes. The actual maximum time also depends on the IdleRemover scan time, which is half of the smallest idle-timeout-minutes value of any pool.

initial-pool-size

Non-XA, XA

The initial number of connections a pool should hold.

interleaving

XA Only

Whether to enable interleaving for XA connections.

jndi-name

Non-XA, XA

The unique JNDI name for the datasource.

jta

Non-XA Only

Enable JTA integration.

max-pool-size

Non-XA, XA

The maximum number of connections that a pool can hold.

mcp

Non-XA, XA

The ManagedConnectionPool implementation. For example, org.jboss.jca.core.connectionmanager.pool.mcp.SemaphoreArrayListManagedConnectionPool

min-pool-size

Non-XA, XA

The minimum number of connections that a pool can hold.

new-connection-sql

Non-XA, XA

An SQL statement to execute whenever a connection is added to the connection pool.

no-recovery

XA Only

Whether the connection pool should be excluded from recovery.

no-tx-separate-pool

XA Only

Whether to create a separate sub-pool for each context. This may be required for some Oracle datasources, which may not allow XA connections to be used both inside and outside of a JTA transaction. Using this option will cause your total pool size to be twice the max-pool-size, because two actual pools will be created.

pad-xid

XA Only

Whether to pad the Xid.

password

Non-XA, XA

The password to use when creating a new connection.

pool-fair

Non-XA, XA

Defines if pool should be fair. This setting is part of a Semaphore class used to manage the connection pools in JCA, which provides a performance benefit in some use cases where the order of leasing connections is not required.

pool-prefill

Non-XA, XA

Whether the pool should be prefilled.

pool-use-strict-min

Non-XA, XA

Whether min-pool-size should be considered strictly.

prepared-statements-cache-size

Non-XA, XA

The number of prepared statements per connection in a Least Recently Used (LRU) cache.

query-timeout

Non-XA, XA

The timeout for queries, in seconds. The default is no timeout.

reauth-plugin-class-name

Non-XA, XA

The fully-qualified class name of the reauthentication plugin implementation to reauthenticate physical connections.

reauth-plugin-properties

Non-XA, XA

The properties for the reauthentication plugin.

recovery-password

XA Only

The password to use to connect to the resource for recovery.

recovery-plugin-class-name

XA Only

The fully-qualified class name of the recovery plugin implementation.

recovery-plugin-properties

XA Only

The properties for the recovery plugin.

recovery-security-domain

XA Only

The security domain to use to connect to the resource for recovery.

recovery-username

XA Only

The user name to use to connect to the resource for recovery.

same-rm-override

XA Only

Whether the javax.transaction.xa.XAResource.isSameRM(XAResource) class returns true or false.

security-domain

Non-XA, XA

The name of a JAAS security-manager which handles authentication. This name correlates to the application-policy/name attribute of the JAAS login configuration.

set-tx-query-timeout

Non-XA, XA

Whether to set the query timeout based on the time remaining until transaction timeout. Any configured query timeout will be used if no transaction exists.

share-prepared-statements

Non-XA, XA

Whether JBoss EAP should cache, instead of close or terminate, the underlying physical statement when the wrapper supplied to the application is closed by application code. The default is false.

spy

Non-XA, XA

Enable spy functionality on the JDBC layer. This logs all JDBC traffic to the datasource. Note that the logging category jboss.jdbc.spy must also be set to the log level DEBUG in the logging subsystem.

stale-connection-checker-class-name

Non-XA, XA

An instance of org.jboss.jca.adapters.jdbc.StaleConnectionChecker that provides an isStaleConnection(SQLException) method. If this method returns true, then the exception is wrapped in an org.jboss.jca.adapters.jdbc.StaleConnectionException.

stale-connection-checker-properties

Non-XA, XA

The stale connection checker properties.

statistics-enabled

Non-XA, XA

Whether runtime statistics are enabled. The default is false.

track-statements

Non-XA, XA

Whether to check for unclosed statements when a connection is returned to a pool and a statement is returned to the prepared statement cache. If false, statements are not tracked. Valid values:

  • true: Statements and result sets are tracked, and a warning is issued if they are not closed.
  • false: Neither statements or result sets are tracked.
  • nowarn: Statements are tracked but no warning is issued (default).

tracking

Non-XA, XA

Whether to track connection handles across transaction boundaries.

transaction-isolation

Non-XA, XA

The java.sql.Connection transaction isolation level. Valid values:

  • TRANSACTION_READ_UNCOMMITTED
  • TRANSACTION_READ_COMMITTED
  • TRANSACTION_REPEATABLE_READ
  • TRANSACTION_SERIALIZABLE
  • TRANSACTION_NONE

url-delimiter

Non-XA, XA

The delimiter for URLs in connection-url for High Availability (HA) datasources.

url-property

XA Only

The property for the URL property in the xa-datasource-property values.

url-selector-strategy-class-name

Non-XA, XA

A class that implements org.jboss.jca.adapters.jdbc.URLSelectorStrategy.

use-ccm

Non-XA, XA

Enable the cached connection manager.

use-fast-fail

Non-XA, XA

If true, fail a connection allocation on the first attempt if the connection is invalid. If false, keep trying until the pool is exhausted.

use-java-context

Non-XA, XA

Whether to bind the datasource into global JNDI.

use-try-lock

Non-XA, XA

A timeout value for internal locks. This attempts to obtain the lock for the configured number of seconds, before timing out, rather than failing immediately if the lock is unavailable. Uses tryLock() instead of lock().

user-name

Non-XA, XA

The user name to use when creating a new connection.

valid-connection-checker-class-name

Non-XA, XA

An implementation of org.jboss.jca.adaptors.jdbc.ValidConnectionChecker which provides a SQLException.isValidConnection(Connection e) method to validate a connection. An exception means the connection is destroyed. This overrides the parameter check-valid-connection-sql if it is present.

valid-connection-checker-properties

Non-XA, XA

The valid connection checker properties.

validate-on-match

Non-XA, XA

Whether connection validation is performed when a connection factory attempts to match a managed connection. This should be used when a client must have a connection validated prior to use. Validate-on-match is typically not to be used with background-validation or there will be redundant checks.

wrap-xa-resource

XA Only

Whether to wrap the XAResource in an org.jboss.tm.XAResourceWrapper instance.

xa-datasource-class

XA Only

The fully-qualified name of the javax.sql.XADataSource implementation class.

xa-datasource-properties

XA Only

String name/value pair of XA datasource properties.

xa-resource-timeout

XA Only

If non-zero, this value is passed to the XAResource.setTransactionTimeout method.

A.18. Datasource Statistics

Table A.33. Core Pool Statistics

NameDescription

ActiveCount

The number of active connections. Each of the connections is either in use by an application or available in the pool.

AvailableCount

The number of available connections in the pool.

AverageBlockingTime

The average time spent blocking on obtaining an exclusive lock on the pool. This value is in milliseconds.

AverageCreationTime

The average time spent creating a connection. This value is in milliseconds.

AverageGetTime

The average time spent obtaining a connection.

AverageUsageTime

The average time spent using a connection.

BlockingFailureCount

The number of failures trying to obtain a connection.

CreatedCount

The number of connections created.

DestroyedCount

The number of connections destroyed.

IdleCount

The number of connections that are currently idle.

InUseCount

The number of connections currently in use.

MaxCreationTime

The maximum time it took to create a connection. This value is in milliseconds.

MaxGetTime

The maximum time for obtaining a connection.

MaxPoolTime

The maximum time for a connection in the pool.

MaxUsageTime

The maximum time using a connection.

MaxUsedCount

The maximum number of connections used.

MaxWaitCount

The maximum number of requests waiting for a connection at the same time.

MaxWaitTime

The maximum time spent waiting for an exclusive lock on the pool.

TimedOut

The number of timed out connections.

TotalBlockingTime

The total time spent waiting for an exclusive lock on the pool. This value is in milliseconds.

TotalCreationTime

The total time spent creating connections. This value is in milliseconds.

TotalGetTime

The total time spent obtaining connections.

TotalPoolTime

The total time spent by connections in the pool.

TotalUsageTime

The total time spent using connections.

WaitCount

The number of requests that had to wait to obtain a connection.

XACommitAverageTime

The average time for an XAResource commit invocation.

XACommitCount

The number of XAResource commit invocations.

XACommitMaxTime

The maximum time for an XAResource commit invocation.

XACommitTotalTime

The total time for all XAResource commit invocations.

XAEndAverageTime

The average time for an XAResource end invocation.

XAEndCount

The number of XAResource end invocations.

XAEndMaxTime

The maximum time for an XAResource end invocation.

XAEndTotalTime

The total time for all XAResource end invocations.

XAForgetAverageTime

The average time for an XAResource forget invocation.

XAForgetCount

The number of XAResource forget invocations.

XAForgetMaxTime

The maximum time for an XAResource forget invocation.

XAForgetTotalTime

The total time for all XAResource forget invocations.

XAPrepareAverageTime

The average time for an XAResource prepare invocation.

XAPrepareCount

The number of XAResource prepare invocations.

XAPrepareMaxTime

The maximum time for an XAResource prepare invocation.

XAPrepareTotalTime

The total time for all XAResource prepare invocations.

XARecoverAverageTime

The average time for an XAResource recover invocation.

XARecoverCount

The number of XAResource recover invocations.

XARecoverMaxTime

The maximum time for an XAResource recover invocation.

XARecoverTotalTime

The total time for all XAResource recover invocations.

XARollbackAverageTime

The average time for an XAResource rollback invocation.

XARollbackCount

The number of XAResource rollback invocations.

XARollbackMaxTime

The maximum time for an XAResource rollback invocation.

XARollbackTotalTime

The total time for all XAResource rollback invocations.

XAStartAverageTime

The average time for an XAResource start invocation.

XAStartCount

The number of XAResource start invocations.

XAStartMaxTime

The maximum time for an XAResource start invocation.

XAStartTotalTime

The total time for all XAResource start invocations.

Table A.34. JDBC Statistics

NameDescription

PreparedStatementCacheAccessCount

The number of times that the statement cache was accessed.

PreparedStatementCacheAddCount

The number of statements added to the statement cache.

PreparedStatementCacheCurrentSize

The number of prepared and callable statements currently cached in the statement cache.

PreparedStatementCacheDeleteCount

The number of statements discarded from the cache.

PreparedStatementCacheHitCount

The number of times that statements from the cache were used.

PreparedStatementCacheMissCount

The number of times that a statement request could not be satisfied with a statement from the cache.

A.19. Transaction Manager Configuration Options

Table A.35. Transactions Subsystem Attributes

AttributeDescription

default-timeout

The default transaction timeout. This defaults to 300 seconds. You can override this programmatically, on a per-transaction basis.

enable-statistics

Deprecated in favor of statistics-enabled.

enable-tsm-status

Whether to enable the transaction status manager (TSM) service, which is used for out-of-process recovery. This option is not supported, as running an out-of-process recovery manager to contact the ActionStatusService from a different process, instead of in memory, is not supported.

hornetq-store-enable-async-io

Deprecated in favor of journal-store-enable-async-io.

jdbc-action-store-drop-table

Whether JDBC action store should drop tables. The default is false.

jdbc-action-store-table-prefix

Optional prefix for table used to write transaction logs in configured JDBC action store.

jdbc-communication-store-drop-table

Whether JDBC communication store should drop tables. The default is false.

jdbc-communication-store-table-prefix

Optional prefix for table used to write transaction logs in configured JDBC communication store.

jdbc-state-store-drop-table

Whether JDBC state store should drop tables. The default is false.

jdbc-state-store-table-prefix

Optional prefix for table used to write transaction logs in configured JDBC state store.

jdbc-store-datasource

JNDI name of non-XA datasource used. Datasource should be defined in the datasources subsystem.

journal-store-enable-async-io

Whether AsyncIO should be enabled for the journal store or not. Defaults to false. The server should be restarted for this setting to take effect.

jts

Whether to use Java Transaction Service (JTS) transactions. Defaults to false, which uses JTA transactions only.

node-identifier

The node identifier for the transaction manager. If this option is not set, you will see a warning upon server startup. This option is required in the following situations:

  • For JTS to JTS communications
  • When two transaction managers access shared resource managers
  • When two transaction managers access shared object stores

The node-identifier must be unique for each transaction manager as it is required to enforce data integrity during recovery. The node-identifier must also be unique for JTA because multiple nodes may interact with the same resource manager or share a transaction object store.

object-store-path

A relative or absolute file system path where the transaction manager object store stores data. By default relative to the object-store-relative-to parameter’s value. If object-store-relative-to is set to an empty string, this value is treated as an absolute path.

object-store-relative-to

References a global path configuration in the domain model. The default value is the data directory for JBoss EAP, which is the value of the property jboss.server.data.dir, and defaults to EAP_HOME/domain/data/ for a managed domain, or EAP_HOME/standalone/data/ for a standalone server instance. The value of the object store object-store-path transaction manager attribute is relative to this path. Set this attribute to an empty string to have object-store-path be treated as an absolute path.

process-id-socket-binding

The name of the socket binding configuration to use if the transaction manager should use a socket-based process ID. Will be undefined if process-id-uuid is true; otherwise must be set.

process-id-socket-max-ports

The transaction manager creates a unique identifier for each transaction log. Two different mechanisms are provided for generating unique identifiers: a socket-based mechanism and a mechanism based on the process identifier of the process.

In the case of the socket-based identifier, a socket is opened and its port number is used for the identifier. If the port is already in use, the next port is probed, until a free one is found. The process-id-socket-max-ports represents the maximum number of sockets the transaction manager will try before failing. The default value is 10.

process-id-uuid

Set to true to use the process identifier to create a unique identifier for each transaction. Otherwise, the socket-based mechanism is used. Defaults to true. See process-id-socket-max-ports for more information. To enable process-id-socket-binding, set process-id-uuid to false.

recovery-listener

Whether or not the transaction recovery process should listen on a network socket. Defaults to false.

socket-binding

Specifies the name of the socket binding used by the transaction periodic recovery listener when recovery-listener is set to true.

statistics-enabled

Whether statistics should be enabled. The default is false.

status-socket-binding

Specifies the socket binding to use for the transaction status manager. This configuration option is not supported.

use-hornetq-store

Deprecated in favor of use-journal-store.

use-jdbc-store

Use the JDBC store for writing transaction logs. Set to true to enable and to false to use the default log store type.

use-journal-store

Use Apache ActiveMQ Artemis journaled storage mechanisms instead of file-based storage for the transaction logs. This is disabled by default, but can improve I/O performance. It is not recommended for JTS transactions on separate transaction managers. When changing this option, the server has to be restarted using the shutdown command for the change to take effect.

Table A.36. Log Store Attributes

AttributeDescription

expose-all-logs

Whether to expose all logs. The default is false, meaning that only a subset of transaction logs is exposed.

type

Specifies the implementation type of the logging store. The default is default.

Table A.37. Commit Markable Resource Attributes

AttributeDescription

batch-size

The batch size for this CMR resource. The default is 100.

immediate-cleanup

Whether to perform immediate cleanup for this CMR resource. The default is true.

jndi-name

The JNDI name of this CMR resource.

name

The table name for storing XIDs. The default is xids.

A.20. IIOP Subsystem Attributes

Table A.38. IIOP Subsystem Attributes

AttributeDescription

add-component-via-interceptor

Indicates whether SSL components should be added by an IOR interceptor.

auth-method

The authentication method. Valid values are none and username_password.

caller-propagation

Indicates whether the caller identity should be propagated in the SAS context. Valid values are none and supported.

client-requires

Value that indicates the client SSL required parameters. Valid values are None, ServerAuth, ClientAuth, and MutualAuth.

client-supports

Value that indicates the client SSL supported parameters. Valid values are None, ServerAuth, ClientAuth, and MutualAuth.

confidentiality

Indicates whether the transport must require confidentiality protection or not. Valid values are none, supported, and required.

detect-misordering

Indicates whether the transport must require misordering detection or not. Valid values are none, supported, and required.

detect-replay

Indicates whether the transport must require replay detection or not. Valid values are none, supported, and required.

export-corbaloc

Indicates whether the root context should be exported as corbaloc::address:port/NameService.

giop-version

The GIOP version to be used.

high-water-mark

TCP connection cache parameter. Each time the number of connections exceeds this value, the ORB tries to reclaim connections. The number of reclaimed connections is specified by the number-to-reclaim property. If this property is not set, then the OpenJDK ORB default is used.

integrity

Indicates whether the transport must require integrity protection or not. Valid values are none, supported, and required.

number-to-reclaim

TCP connection cache parameter. Each time the number of connections exceeds the high-water-mark property, then the ORB tries to reclaim connections. The number of reclaimed connections is specified by this property. If it is not set, then the OpenJDK ORB default is used.

persistent-server-id

Persistent ID of the server. Persistent object references are valid across many activations of the server and they identify it using this property. As a result of that, many activations of the same server should have this property set to the same value, and different server instances running on the same host should have different server IDs.

properties

A list of generic key/value properties.

realm

The authentication service realm name.

required

Indicates whether authentication is required.

root-context

The naming service root context.

security

Indicates whether the security interceptors are to be installed. Valid values are client, identity, and none.

security-domain

The name of the security domain that holds the key and trust stores that will be used to establish SSL connections.

server-requires

Value that indicates the server SSL required parameters. Valid values are None, ServerAuth, ClientAuth, and MutualAuth.

server-supports

Value that indicates the server SSL supported parameters. Valid values are None, ServerAuth, ClientAuth, and MutualAuth.

socket-binding

The name of the socket binding configuration that specifies the ORB port.

ssl-socket-binding

The name of the socket binding configuration that specifies the ORB SSL port.

support-ssl

Indicates whether SSL is supported.

transactions

Indicates whether the transactions interceptors are to be installed or not. Valid values are full, spec, and none. A value of full enables JTS while a value of spec enables a non-JTS spec-compliant mode that rejects incoming transaction contexts.

trust-in-client

Indicates if the transport must require trust in client to be established. Valid values are none, supported, and required.

trust-in-target

Indicates if the transport must require trust in target to be established. Valid values are none and supported.

A.21. Resource Adapter Attributes

The following tables describe the resource adapter attributes.

Table A.39. Main Attributes

AttributeDescription

archive

The resource adapter archive.

beanvalidationgroups

The bean validation groups that should be used.

bootstrap-context

The unique name of the bootstrap context that should be used.

config-properties

Custom defined config properties.

module

The module from which the resource adapter will be loaded.

statistics-enabled

Whether runtime statistics are enabled or not.

transaction-support

The transaction support level of the resource adapter.

wm-security

Toggle on/off wm.security for this resource adapter. In case of false, all wm-security-* parameters are ignored, even the defaults.

wm-security-default-groups

A default groups list that should be added to the used Subject instance.

wm-security-default-principal

A default principal name that should be added to the used Subject instance.

wm-security-domain

The name of the security domain that should be used.

wm-security-mapping-groups

List of groups mappings.

wm-security-mapping-required

Defines if a mapping is required for security credentials.

wm-security-mapping-users

List of user mappings.

Table A.40. admin-objects Attributes

AttributeDescription

class-name

The fully qualified class name of an administration object.

enabled

Specifies if the administration object should be enabled.

jndi-name

The JNDI name for the administration object.

use-java-context

Setting this to false will bind the object into global JNDI.

Table A.41. connection-definitions Attributes

AttributeDescription

allocation-retry

Indicates the number of times that allocating a connection should be tried before throwing an exception.

allocation-retry-wait-millis

The amount of time, in milliseconds, to wait between retrying to allocate a connection.

background-validation

Specifies that connections should be validated on a background thread versus being validated prior to use. Changing this value requires a server restart.

background-validation-millis

The amount of time, in milliseconds, that background validation will run. Changing this value requires a server restart.

blocking-timeout-wait-millis

The maximum time, in milliseconds, to block while waiting for a connection before throwing an exception. Note that this blocks only while waiting for locking a connection, and will never throw an exception if creating a new connection takes an inordinately long time.

capacity-decrementer-class

Class defining the policy for decrementing connections in the pool.

capacity-decrementer-properties

Properties to inject in class defining the policy for decrementing connections in the pool.

capacity-incrementer-class

Class defining the policy for incrementing connections in the pool.

capacity-incrementer-properties

Properties to inject in class defining the policy for incrementing connections in the pool.

class-name

The fully qualified class name of a managed connection factory or admin object.

connectable

Enable the use of CMR. This feature means that a local resource can reliably participate in an XA transaction.

enabled

Specifies if the resource adapter should be enabled.

enlistment

Specifies if lazy enlistment should be used if supported by the resource adapter.

enlistment-trace

Specifies if JBoss EAP/IronJacamar should record enlistment traces.

flush-strategy

Specifies how the pool should be flushed in case of an error. Valid values are:

FailingConnectionOnly
Only the failing connection is removed. This is the default setting.
InvalidIdleConnections
The failing connection and idle connections that share the same credentials and are returned as invalid by the ValidatingManagedConnectionFactory.getInvalidConnections(…​) method are removed.
IdleConnections
The failing connection and idle connections that share the same credentials are removed.
Gracefully
The failing connection and idle connections that share the same credentials are removed. Active connections that share the same credentials are destroyed upon return to the pool.
EntirePool
The failing connection and idle and active connections that share the same credentials are removed. This setting is not recommended for production systems.
AllInvalidIdleConnections
The failing connection and idle connections that are returned as invalid by the ValidatingManagedConnectionFactory.getInvalidConnections(…​) method are removed.
AllIdleConnections
The failing connection and all idle connections are removed.
AllGracefully
The failing connection and all idle connections are removed. Active connections are destroyed upon return to the pool.
AllConnections
The failing connection and all idle and active connections are removed. This setting is not recommended for production systems.

idle-timeout-minutes

The maximum time, in minutes, a connection may be idle before being closed. The actual maximum time depends also on the IdleRemover scan time, which is half of the smallest idle-timeout-minutes value of any pool. Changing this value requires a server restart.

initial-pool-size

The initial number of connections a pool should hold.

interleaving

Specifies whether to enable interleaving for XA connections.

jndi-name

The JNDI name for the connection factory.

max-pool-size

The maximum number of connections for a pool. No more connections will be created in each sub-pool.

mcp

The ManagedConnectionPool implementation. For example: org.jboss.jca.core.connectionmanager.pool.mcp.SemaphoreArrayListManagedConnectionPool.

min-pool-size

The minimum number of connections for a pool.

no-recovery

Specifies if the connection pool should be excluded from recovery.

no-tx-separate-pool

Oracle does not like XA connections getting used both inside and outside a JTA transaction. To workaround the problem you can create separate sub-pools for the different contexts.

pad-xid

Specifies whether the Xid should be padded.

pool-fair

Specifies if pool use should be fair.

pool-prefill

Specifies if the pool should be prefilled. Changing this value requires a server restart.

pool-use-strict-min

Specifies if the min-pool-size should be considered strict.

recovery-password

The password used for recovery.

recovery-plugin-class-name

The fully qualified class name of the recovery plugin implementation.

recovery-plugin-properties

The properties for the recovery plugin.

recovery-security-domain

The security domain used for recovery.

recovery-username

The user name used for recovery.

same-rm-override

Unconditionally set whether javax.transaction.xa.XAResource.isSameRM(XAResource) returns true or false.

security-application

Indicates that application-supplied parameters, such as from getConnection(user, pw), are used to distinguish connections in the pool.

security-domain

The security domain which defines the javax.security.auth.Subject that is used to distinguish connections in the pool.

security-domain-and-application

Indicates that either application-supplied parameters, such as from getConnection(user, pw), or Subject (from security domain), are used to distinguish connections in the pool.

sharable

Enable the use of sharable connections, which allows lazy association to be enabled if supported.

tracking

Specifies if IronJacamar should track connection handles across transaction boundaries.

use-ccm

Enable the use of a cached connection manager.

use-fast-fail

Whether to fail a connection allocation on the first try if it is invalid (true), or keep trying until the pool is exhausted of all potential connections (false).

use-java-context

Setting this to false will bind the object into global JNDI.

validate-on-match

Specifies if connection validation should be done when a connection factory attempts to match a managed connection. This is typically exclusive to the use of background validation.

wrap-xa-resource

Specifies whether XAResource instances should be wrapped in an org.jboss.tm.XAResourceWrapper instance.

xa-resource-timeout

The value is passed to XAResource.setTransactionTimeout(), in seconds. The default is 0.

The resource adapter schema can be found at EAP_HOME/docs/schema/wildfly-resource-adapters_4_0.xsd.

A.22. Resource Adapter Statistics

Table A.42. Resource Adapter Statistics

NameDescription

ActiveCount

The number of active connections. Each of the connections is either in use by an application or available in the pool

AvailableCount

The number of available connections in the pool.

AverageBlockingTime

The average time spent blocking on obtaining an exclusive lock on the pool. The value is in milliseconds.

AverageCreationTime

The average time spent creating a connection. The value is in milliseconds.

CreatedCount

The number of connections created.

DestroyedCount

The number of connections destroyed.

InUseCount

The number of connections currently in use.

MaxCreationTime

The maximum time it took to create a connection. The value is in milliseconds.

MaxUsedCount

The maximum number of connections used.

MaxWaitCount

The maximum number of requests waiting for a connection at the same time.

MaxWaitTime

The maximum time spent waiting for an exclusive lock on the pool.

TimedOut

The number of timed out connections.

TotalBlockingTime

The total time spent waiting for an exclusive lock on the pool. The value is in milliseconds.

TotalCreationTime

The total time spent creating connections. The value is in milliseconds.

WaitCount

The number of requests that had to wait for a connection.

A.23. Undertow Subsystem Attributes

Table A.43. undertow Attributes

AttributeDefaultDescription

default-security-domain

other

The default security domain used by web deployments.

default-server

default-server

The default server to use for deployments.

default-servlet-container

default

The default servlet container to use for deployments.

default-virtual-host

default-host

The default virtual host to use for deployments.

instance-id

${jboss.node.name}

The cluster instance ID.

statistics-enabled

false

Whether statistics are enabled.

Buffer Cache Attributes

Table A.44. buffer-cache Attributes

AttributeDefaultDescription

buffer-size

1024

The size of the buffers. Smaller buffers allow space to be utilized more effectively.

buffers-per-region

1024

The numbers of buffers per region.

max-regions

10

The maximum number of regions. This controls the maximum amount of memory that can be used for caching.

Servlet Container Attributes

The servlet container component has the following structure:

servlet-container Attributes

Table A.45. servlet-container Attributes

AttributeDefaultDescription

allow-non-standard-wrappers

false

Whether request and response wrappers that do not extend the standard wrapper classes can be used.

default-buffer-cache

default

The buffer cache to use for caching static resources.

default-encoding

 

Default encoding to use for all deployed applications.

default-session-timeout

30

The default session timeout in minutes for all applications deployed in the container.

directory-listing

 

If directory listing should be enabled for default servlets.

disable-caching-for-secured-pages

true

Whether to set headers to disable caching for secured paged. Disabling this can cause security problems, as sensitive pages may be cached by an intermediary.

eager-filter-initialization

false

Whether to call filter init() on deployment start rather than when first requested.

ignore-flush

false

Ignore flushes on the servlet output stream. In most cases these just hurt performance for no good reason.

max-sessions

 

The maximum number of sessions that can be active at one time.

proactive-authentication

false

Whether proactive authentication should be used. If this is true, a user will always be authenticated if credentials are present.

session-id-length

30

The length of the generated session ID. Longer session ID’s are more secure.

stack-trace-on-error

local-only

If an error page with the stack trace should be generated on error. Values are all, none and local-only.

use-listener-encoding

false

Use encoding defined on listener.

mime-mapping Attributes

Table A.46. mime-mapping Attributes

AttributeDefaultDescription

value

 

The mime type for this mapping.

welcome-file Attributes

Defines a welcome file and has no options.

crawler-session-management Attributes

Configures special session handling for crawler bots.

Note

When using the management CLI to manage the crawler-session-management element, it is available under settings in the servlet-container element. For example:

/subsystem=undertow/servlet-container=default/setting=crawler-session-management:add
/subsystem=undertow/servlet-container=default/setting=crawler-session-management:read-resource

Table A.47. crawler-session-management Attributes

AttributeDefaultDescription

session-timeout

 

The session timeout in seconds for sessions that are owned by crawlers.

user-agents

 

Regular expression that is used to match the user agent of a crawler.

jsp Attributes
Note

When using the management CLI to manage the jsp element, it is available under settings in the servlet-container element. For example:

/subsystem=undertow/servlet-container=default/setting=jsp:read-resource

Table A.48. jsp Attributes

AttributeDefaultDescription

check-interval

0

Check interval for JSP updates using a background thread.

development

false

Enable development mode which enables reloading JSP on-the-fly.

disabled

false

Enable the JSP container.

display-source-fragment

true

When a runtime error occurs, attempts to display corresponding JSP source fragment.

dump-smap

false

Write SMAP data to a file.

error-on-use-bean-invalid-class-attribute

false

Enable errors when using a bad class in useBean.

generate-strings-as-char-arrays

false

Generate String constants as char arrays.

java-encoding

UTF8

Specify the encoding used for Java sources.

keep-generated

true

Keep the generated servlets.

mapped-file

true

Map to the JSP source.

modification-test-interval

4

Minimum amount of time between two tests for updates, in seconds.

optimize-scriptlets

false

If JSP scriptlets should be optimized to remove string concatenation.

recompile-on-fail

false

Retry failed JSP compilations on each request.

scratch-dir

 

Specify a different work directory.

smap

true

Enable SMAP.

source-vm

1.8

Source VM level for compilation.

tag-pooling

true

Enable tag pooling.

target-vm

1.8

Target VM level for compilation.

trim-spaces

false

Trim some spaces from the generated servlet.

x-powered-by

true

Enable advertising the JSP engine in x-powered-by.

persistent-sessions Attributes
Note

When using the management CLI to manage the persistent-sessions element, it is available under settings in the servlet-container element. For example:

/subsystem=undertow/servlet-container=default/setting=persistent-sessions:add
/subsystem=undertow/servlet-container=default/setting=persistent-sessions:read-resource

Table A.49. persistent-sessions Attributes

AttributeDefaultDescription

path

 

The path to the persistent session data directory. If this is null, sessions will be stored in memory.

relative-to

 

The directory the path is relative to.

Note

When using the management CLI to manage the session-cookie element, it is available under settings in the servlet-container element. For example:

/subsystem=undertow/servlet-container=default/setting=session-cookie:add
/subsystem=undertow/servlet-container=default/setting=session-cookie:read-resource

Table A.50. session-cookie Attributes

AttributeDefaultDescription

comment

 

Cookie comment.

domain

 

Cookie domain.

http-only

 

Whether the cookie is http-only.

max-age

 

Maximum age of the cookie.

name

 

Name of the cookie.

secure

 

Whether the cookie is secure.

websockets Attributes
Note

When using the management CLI to manage the websockets element, it is available under settings in the servlet-container element. For example:

/subsystem=undertow/servlet-container=default/setting=websockets:read-resource

Table A.51. websockets Attributes

AttributeDefaultDescription

buffer-pool

default

The buffer pool to use for websocket deployments.

dispatch-to-worker

true

Whether callbacks should be dispatched to a worker thread. If this is false, then they will be run in the IO thread, which is faster however care must be taken not to perform blocking operations.

worker

default

The worker to use for websocket deployments.

Filter Attributes

custom-filter Filters

Table A.52. custom-filter Attributes

AttributeDefaultDescription

class-name

 

Class name of HttpHandler.

module

 

Module name where class can be loaded from.

parameters

 

Filter parameters.

error-page Filters

The error pages

Table A.53. error-page Attributes

AttributeDefaultDescription

code

 

Error page code.

path

 

Error page path.

expression-filter Filters

A filter parsed from the Undertow expression language.

Table A.54. expression-filter Attributes

AttributeDefaultDescription

expression

 

The expression that defines the filter.

module

 

Module to use to load the filter definitions.

gzip Filters

Defines the gzip filter and has no attributes.

mod-cluster Filters

The mod-cluster filter component has the following structure:

Table A.55. mod-cluster Attributes

AttributeDefaultDescription

advertise-frequency

10000

The frequency in milliseconds that mod_cluster advertises itself on the network.

advertise-path

/

The path that mod_cluster is registered under.

advertise-protocol

http

The protocol that is in use.

advertise-socket-binding

 

The multicast group that is used to advertise.

broken-node-timeout

60000

The amount of time that must elapse before a broken node is removed from the table.

cached-connections-per-thread

5

The number of connections that will be kept alive indefinitely.

connection-idle-timeout

60

The amount of time a connection can be idle before it will be closed. Connections will not time out once the pool size is down to the configured minimum, which is configured by cached-connections-per-thread.

connections-per-thread

10

The number of connections that will be maintained to back-end servers, per IO thread.

enable-http2

false

Whether the load balancer should attempt to upgrade back-end connections to HTTP/2. If HTTP/2 is not supported, HTTP or HTTPS will be used as normal.

health-check-interval

10000

The frequency of health check pings to back-end nodes.

management-access-predicate

 

A predicate that is applied to incoming requests to determine if they can perform mod cluster management commands. Provides additional security on top of what is provided by limiting management to requests that originate from the management-socket-binding.

management-socket-binding

 

The socket binding of the mod_cluster management port. When using mod_cluster two HTTP listeners should be defined, a public one to handle requests, and one bound to the internal network to handle mod cluster commands. This socket binding should correspond to the internal listener, and should not be publicly accessible.

max-request-time

-1

The maximum amount of time that a request to a back-end node can take before it is killed.

request-queue-size

10

The number of requests that can be queued if the connection pool is full before requests are rejected with a 503.

security-key

 

The security key that is used for the mod_cluster group. All members must use the same security key.

security-realm

 

The security realm that provides the SSL configuration.

use-alias

false

Whether an alias check is performed.

worker

default

The XNIO worker that is used to send the advertise notifications.

Table A.56. balancer Attributes

AttributeDefaultDescription

max-attempts

 

The number of attempts to send the request to a back-end server.

sticky-session

 

If sticky sessions are enabled.

sticky-session-cookie

 

The session cookie name.

sticky-session-force

 

If this is true, then an error will be returned if the request cannot be routed to the sticky node, otherwise it will be routed to another node.

sticky-session-path

 

The path of the sticky session cookie.

sticky-session-remove

 

Remove the session cookie if the request cannot be routed to the correct host.

wait-worker

 

The number of seconds to wait for an available worker.

load-balancing-group Attributes

Defines a load balancing group and has no options.

Table A.57. node Attributes

AttributeDefaultDescription

aliases

 

The nodes aliases.

cache-connections

 

The number of connections to keep alive indefinitely.

elected

 

The elected count.

flush-packets

 

If received data should be immediately flushed.

load

 

The current load of this node.

load-balancing-group

 

The load balancing group this node belongs to.

max-connections

 

The maximum number of connections per IO thread.

open-connections

 

The current number of open connections.

ping

 

The nodes ping.

queue-new-requests

 

If a request is received and there is no worker immediately available should it be queued.

read

 

The number of bytes read from the node.

request-queue-size

 

The size of the request queue.

status

 

The current status of this node.

timeout

 

The request timeout.

ttl

 

The time connections will stay alive with no requests before being closed, if the number of connections is larger than cache-connections.

uri

 

The URI that the load balancer uses to connect to the node.

written

 

The number of bytes transferred to the node.

Table A.58. context Attributes

AttributeDefaultDescription

requests

 

The number of requests against this context.

status

 

The status of this context.

request-limit Filters

Table A.59. request-limit Attributes

AttributeDefaultDescription

max-concurrent-requests

 

Maximum number of concurrent requests.

queue-size

 

Number of requests to queue before they start being rejected.

response-header Filters

Response header filter allows you to add custom headers.

Table A.60. response-header Attributes

AttributeDefaultDescription

header-name

 

The header name.

header-value

 

The header value.

rewrite Filters

Table A.61. rewrite Attributes

AttributeDefaultDescription

redirect

false

Whether a redirect will be done instead of a rewrite.

target

 

The expression that defines the target. If you are redirecting to a constant target put single quotes around the value.

Handler Attributes

file Attributes

Table A.62. file Attributes

AttributeDefaultDescription

cache-buffer-size

1024

Size of the buffers.

cache-buffers

1024

Number of buffers.

case-sensitive

true

Whether to use case-sensitive file handling. Note that setting this to false for case insensitivity will only work if the underlying file system is case insensitive.

directory-listing

false

Whether to enable directory listing.

follow-symlink

false

Whether to enable following symbolic links.

path

 

Path on the file system from where file handler will serve resources.

safe-symlink-paths

 

Paths that are safe to be targets of symbolic links.

Using WebDAV for Static Resources

Previous versions of JBoss EAP allowed for using WebDAV with the web subsystem, by way of the WebdavServlet, to host static resources and enable additional HTTP methods for accessing and manipulating those files. In JBoss EAP 7, the undertow subsystem does provide a mechanism for serving static files using a file handler, but the undertow subsystem does not support WebDAV. If you want to use WebDAV with JBoss EAP 7, you can write a custom WebDAV servlet.

reverse-proxy attributes

The reverse-proxy handler component has the following structure:

Table A.63. reverse-proxy Attributes

AttributeDefaultDescription

cached-connections-per-thread

5

The number of connections that will be kept alive indefinitely.

connection-idle-timeout

60

The amount of time a connection can be idle before it will be closed. Connections will not time out once the pool size is down to the configured minimum (as configured by cached-connections-per-thread).

connections-per-thread

10

The number of connections that will be maintained to back-end servers, per IO thread.

max-request-time

-1

The maximum time that a proxy request can be active for, before being killed. Defaults to unlimited.

problem-server-retry

30

Time in seconds to wait before attempting to reconnect to a server that is down.

request-queue-size

10

The number of requests that can be queued if the connection pool is full before requests are rejected with a 503.

session-cookie-names

JSESSIONID

Comma-separated list of session cookie names. Generally this will just be JSESSIONID.

Table A.64. host Attributes

AttributeDefaultDescription

instance-id

 

The instance ID, or JVM route, that will be used to enable sticky sessions.

outbound-socket-binding

 

Outbound socket binding for this host.

path

/

Optional path if host is using non root resource.

scheme

http

The kind of scheme that is used.

security-realm

 

The security realm that provides the SSL configuration for the connection to the host.

Server Attributes

The server component has the following structure:

server Attributes

Table A.65. server Attributes

AttributeDefaultDescription

default-host

default-host

The server’s default virtual host.

servlet-container

default

The server’s default servlet container.

http-listener Attributes

Table A.66. http-listener Attributes

AttributeDefaultDescription

allow-encoded-slash

false

If a request comes in with encoded characters, for example %2F, whether these will be decoded.

allow-equals-in-cookie-value

false

Whether to allow non-escaped equals characters in unquoted cookie values. Unquoted cookie values may not contain equals characters. If present the value ends before the equals sign. The remainder of the cookie value will be dropped.

always-set-keep-alive

true

Whether a Connection: keep-alive header will be added to responses, even when it is not strictly required by the specification.

buffer-pipelined-data

false

Whether to buffer pipelined requests.

buffer-pool

default

The listener’s buffer pool.

certificate-forwarding

false

Whether certificate forwarding should be enabled. If this is enabled then the listener will take the certificate from the SSL_CLIENT_CERT attribute. This should only be enabled if behind a proxy, and the proxy is configured to always set these headers.

decode-url

true

Whether the parser will decode the URL and query parameters using the selected character encoding (UTF-8 by default). If this is false they will not be decoded. This will allow a later handler to decode them into whatever charset is desired.

disallowed-methods

["TRACE"]

A comma-separated list of HTTP methods that are not allowed.

enable-http2

false

Whether to enable HTTP/2 support for this listener.

enabled

true

Whether the listener is enabled.

http2-enable-push

true

Whether server push is enabled for this connection.

http2-header-table-size

 

The size of the header table used for HPACK compression, in bytes. This amount of memory will be allocated per connection for compression. Larger values use more memory but may give better compression.

http2-initial-window-size

 

The flow control window size that controls how quickly the client can send data to the server.

http2-max-concurrent-streams

 

The maximum number of HTTP/2 streams that can be active at any time on a single connection.

http2-max-frame-size

 

The maximum HTTP/2 frame size.

http2-max-header-list-size

 

The maximum size of request headers the server is prepared to accept.

max-buffered-request-size

16384

Maximum size of a buffered request, in bytesRequests are not usually buffered, the most common case is when performing SSL renegotiation for a POST request, and the post data must be fully buffered in order to perform the renegotiation.

max-connections

 

The maximum number of concurrent connections.

max-cookies

200

The maximum number of cookies that will be parsed. This is used to protect against hash vulnerabilities.

max-header-size

1048576

The maximum size in bytes of a HTTP request header.

max-headers

200

The maximum number of headers that will be parsed. This is used to protect against hash vulnerabilities.

max-parameters

1000

The maximum number of parameters that will be parsed. This is used to protect against hash vulnerabilities. This applies to both query parameters, and to POST data, but is not cumulative. For example, you can potentially have max parameters * 2 total parameters).

max-post-size

10485760

The maximum size of a post that will be accepted.

no-request-timeout

60000

The length of time in milliseconds that the connection can be idle before it is closed by the container.

proxy-address-forwarding

false

Whether to enable x-forwarded-host and similar headers and set a remote IP address and host name.

read-timeout

 

Configure a read timeout for a socket, in milliseconds. If the given amount of time elapses without a successful read taking place, the socket’s next read will throw a {@link ReadTimeoutException}.

receive-buffer

 

The receive buffer size.

record-request-start-time

false

Whether to record the request start time, to allow for request time to be logged. This has a small but measurable performance impact.

redirect-socket

 

If this listener is supporting non-SSL requests, and a request is received for which a matching requires SSL transport, whether to automatically redirect the request to the socket binding port specified here.

request-parse-timeout

 

The maximum amount of time in milliseconds that can be spent parsing the request.

resolve-peer-address

false

Enables host DNS lookup.

send-buffer

 

The send buffer size.

socket-binding

 

The listener’s socket binding

tcp-backlog

 

Configure a server with the specified backlog.

tcp-keep-alive

 

Configure a channel to send TCP keep-alive messages in an implementation-dependent manner.

url-charset

UTF-8

URL charset.

worker

default

The listener’s XNIO worker.

write-timeout

 

Configure a write timeout for a socket, in milliseconds. If the given amount of time elapses without a successful write taking place, the socket’s next write will throw a {@link WriteTimeoutException}.

The following attributes are read-only and only available when statistics are enabled for the undertow subsystem:

Table A.67. http-listener Metric Attributes

AttributeDefaultDescription

bytes-received

 

The number of bytes that have been received by this listener.

bytes-sent

 

The number of bytes that have been sent out on this listener.

error-count

 

The number of 500 responses that have been sent by this listener.

max-processing-time

 

The maximum processing time taken by a request on this listener.

processing-time

 

The total processing time of all requests handed by this listener.

request-count

 

The number of requests this listener has served.

https-listener Attributes

Table A.68. https-listener Attributes

AttributeDefaultDescription

allow-encoded-slash

false

If a request comes in with encoded characters, for example %2F, whether these will be decoded.

allow-equals-in-cookie-value

false

Whether to allow non-escaped equals characters in unquoted cookie values. Unquoted cookie values may not contain equals characters. If present the value ends before the equals sign. The remainder of the cookie value will be dropped.

always-set-keep-alive

true

Whether a Connection: keep-alive header will be added to responses, even when it is not strictly required by the specification.

buffer-pipelined-data

false

Whether to buffer pipelined requests.

buffer-pool

default

The listener’s buffer pool.

decode-url

true

Whether the parser will decode the URL and query parameters using the selected character encoding (UTF-8 by default). If this is false they will not be decoded. This will allow a later handler to decode them into whatever charset is desired.

disallowed-methods

["TRACE"]

A comma-separated list of HTTP methods that are not allowed.

enable-http2

false

Enables HTTP/2 support for this listener.

enable-spdy

false

Enables SPDY support for this listener.

enabled

true

If the listener is enabled.

enabled-cipher-suites

 

Configures Enabled SSL ciphers.

enabled-protocols

 

Configures SSL protocols.

http2-enable-push

true

If server push is enabled for this connection.

http2-header-table-size

 

The size of the header table used for HPACK compression, in bytes. This amount of memory will be allocated per connection for compression. Larger values use more memory but may give better compression.

http2-initial-window-size

 

The flow control window size that controls how quickly the client can send data to the server.

http2-max-concurrent-streams

 

The maximum number of HTTP/2 streams that can be active at any time on a single connection.

http2-max-frame-size

 

The maximum HTTP/2 frame size.

http2-max-header-list-size

 

The maximum size of request headers the server is prepared to accept.

max-buffered-request-size

16384

Maximum size of a buffered request, in bytesRequests are not usually buffered, the most common case is when performing SSL renegotiation for a POST request, and the post data must be fully buffered in order to perform the renegotiation.

max-connections

 

The maximum number of concurrent connections.

max-cookies

100

The maximum number of cookies that will be parsed. This is used to protect against hash vulnerabilities.

max-header-size

1048576

The maximum size in bytes of a HTTP request header.

max-headers

200

The maximum number of headers that will be parsed. This is used to protect against hash vulnerabilities..

max-parameters

1000

The maximum number of parameters that will be parsed. This is used to protect against hash vulnerabilities. This applies to both query parameters, and to POST data, but is not cumulative. For example, you can potentially have max parameters * 2 total parameters.

max-post-size

10485760

The maximum size of a post that will be accepted.

no-request-timeout

60000

The length of time in milliseconds that the connection can be idle before it is closed by the container.

read-timeout

 

Configure a read timeout for a socket, in milliseconds. If the given amount of time elapses without a successful read taking place, the socket’s next read will throw a {@link ReadTimeoutException}.

receive-buffer

 

The receive buffer size.

record-request-start-time

false

Whether to record the request start time, to allow for request time to be logged. This has a small but measurable performance impact.

request-parse-timeout

 

The maximum amount of time in milliseconds that can be spent parsing the request.

resolve-peer-address

false

Enables host DNS lookup.

security-realm

 

The listener’s security realm.

send-buffer

 

The send buffer size.

socket-binding

 

The listener’s socket binding.

ssl-session-cache-size

 

The maximum number of active SSL sessions.

ssl-session-timeout

 

The timeout for SSL sessions, in seconds.

tcp-backlog

 

Configure a server with the specified backlog.

tcp-keep-alive

 

Configure a channel to send TCP keep-alive messages in an implementation-dependent manner.

url-charset

UTF-8

URL charset.

verify-client

NOT_REQUESTED

The desired SSL client authentication mode for SSL channels.

worker

default

The listener’s XNIO worker.

write-timeout

 

Configure a write timeout for a socket, in milliseconds. If the given amount of time elapses without a successful write taking place, the socket’s next write will throw a {@link WriteTimeoutException}.

The following attributes are read-only and only available when statistics are enabled for the undertow subsystem:

Table A.69. https-listener Metric Attributes

AttributeDefaultDescription

bytes-received

 

The number of bytes that have been received by this listener.

bytes-sent

 

The number of bytes that have been sent out on this listener.

error-count

 

The number of 500 responses that have been sent by this listener.

max-processing-time

 

The maximum processing time taken by a request on this listener.

processing-time

 

The total processing time of all requests handed by this listener.

request-count

 

The number of requests this listener has served.

ajp-listener Attributes

Table A.70. ajp-listener Attributes

AttributeDefaultDescription

allow-encoded-slash

false

If a request comes in with encoded characters, for example %2F, whether these will be decoded.

allow-equals-in-cookie-value

false

Whether to allow non-escaped equals characters in unquoted cookie values. Unquoted cookie values may not contain equals characters. If present the value ends before the equals sign. The remainder of the cookie value will be dropped.

always-set-keep-alive

true

Whether a Connection: keep-alive header will be added to responses, even when it is not strictly required by the specification.

buffer-pipelined-data

false

Whether to buffer pipelined requests.

buffer-pool

default

The AJP listener’s buffer pool.

decode-url

true

If this is true then the parser will decode the URL and query parameters using the selected character encoding (UTF-8 by default). If this is false they will not be decoded. This will allow a later handler to decode them into whatever charset is desired.

disallowed-methods

["TRACE"]

A comma-separated list of HTTP methods that are not allowed.

enabled

true

If the listener is enabled.

max-ajp-packet-size

 

The maximum supported size of AJP packets. If this is modified it has be increased on the load balancer and the back-end server.

max-buffered-request-size

16384

Maximum size of a buffered request, in bytesRequests are not usually buffered, the most common case is when performing SSL renegotiation for a POST request, and the post data must be fully buffered in order to perform the renegotiation.

max-connections

 

The maximum number of concurrent connections.

max-cookies

200

The maximum number of cookies that will be parsed. This is used to protect against hash vulnerabilities.

max-header-size

1048576

The maximum size in bytes of a HTTP request header.

max-headers

200

The maximum number of headers that will be parsed. This is used to protect against hash vulnerabilities.

max-parameters

100

The maximum number of parameters that will be parsed. This is used to protect against hash vulnerabilities. This applies to both query parameters, and to POST data, but is not cumulative. For example, you can potentially have max parameters * 2 total parameters.

max-post-size

10485760

The maximum size of a post that will be accepted

no-request-timeout

60000

The length of time in milliseconds that the connection can be idle before it is closed by the container.

read-timeout

 

Configure a read timeout for a socket, in milliseconds. If the given amount of time elapses without a successful read taking place, the socket’s next read will throw a {@link ReadTimeoutException}.

receive-buffer

 

The receive buffer size.

record-request-start-time

false

Whether to record the request start time, to allow for request time to be logged. This has a small but measurable performance impact.

redirect-socket

 

If this listener is supporting non-SSL requests, and a request is received for which a matching requires SSL transport, whether to automatically redirect the request to the socket binding port specified here.

request-parse-timeout

 

The maximum amount of time in milliseconds that can be spent parsing the request.

resolve-peer-address

false

Enables host DNS lookup.

scheme

 

The listener scheme, can be HTTP or HTTPS. By default the scheme will be taken from the incoming AJP request.

send-buffer

 

The send buffer size.

socket-binding

 

The AJP listener’s socket binding.

tcp-backlog

 

Configure a server with the specified backlog.

tcp-keep-alive

 

Configure a channel to send TCP keep-alive messages in an implementation-dependent manner.

url-charset

UTF-8

URL charset.

worker

default

The listener’s XNIO worker.

write-timeout

 

Configure a write timeout for a socket, in milliseconds. If the given amount of time elapses without a successful write taking place, the socket’s next write will throw a {@link WriteTimeoutException}.

The following attributes are read-only and only available when statistics are enabled for the undertow subsystem:

Table A.71. ajp-listener Metric Attributes

AttributeDefaultDescription

bytes-received

 

The number of bytes that have been received by this listener.

bytes-sent

 

The number of bytes that have been sent out on this listener.

error-count

 

The number of 500 responses that have been sent by this listener.

max-processing-time

 

The maximum processing time taken by a request on this listener.

processing-time

 

The total processing time of all requests handed by this listener.

request-count

 

The number of requests this listener has served.

host Attributes

Table A.72. host Attributes

AttributeDefaultDescription

alias

 

Comma-separated list of aliases for the host.

default-response-code

404

If set, this will be response code sent back in case requested context does not exist on server.

default-web-module

ROOT.war

Default web module.

disable-console-redirect

false

if set to true, /console redirect wont be enabled for this host.

filter-ref Attributes

Table A.73. filter-ref Attributes

AttributeDefaultDescription

predicate

 

Predicates provide a simple way of making a true/false decision based on an exchange. Many handlers have a requirement that they be applied conditionally, and predicates provide a general way to specify a condition.

priority

1

Defines filter order. It should be set to 1 or more. A higher number instructs the server to be included earlier in the handler chain than others under the same context.

access-log Attributes
Note

When using the management CLI to manage the access-log element, it is available under settings in the host element. For example:

/subsystem=undertow/server=default-server/host=default-host/setting=access-log:add
/subsystem=undertow/server=default-server/host=default-host/setting=access-log:read-resource

Table A.74. access-log Attributes

AttributeDefaultDescription

directory

${jboss.server.log.dir}

The directory in which to save logs.

extended

false

Whether the log uses the extended log file format.

pattern

common

The access log pattern.

predicate

 

Predicate that determines if the request should be logged.

prefix

access_log.

Prefix for the log file name.

relative-to

 

The directory the path is relative to.

rotate

true

Whether to rotate the access log every day.

suffix

log

Suffix for the log file name.

use-server-log

false

Whether the log should be written to the server log, rather than a separate file.

worker

default

Name of the worker to use for logging.

single-sign-on Attributes
Note

When using the management CLI to manage the single-sign-on element, it is available under settings in the host element. For example:

/subsystem=undertow/server=default-server/host=default-host/setting=single-sign-on:add
/subsystem=undertow/server=default-server/host=default-host/setting=single-sign-on:read-resource
Important

While distributed single sign-on is no different from an application perspective from previous versions of JBoss EAP, in JBoss EAP 7 the caching and distribution of authentication information is handled differently. For JBoss EAP 7, when running the HA profile, by default each host will have its own Infinispan cache which will store the relevant session and SSO cookie information. This cache is based on the default cache of the web cache container. JBoss EAP will also handle propagating information between all hosts' individual caches.

Table A.75. single-sign-on Attributes

AttributeDefaultDescription

cookie-name

JSESSIONIDSSO

Name of the cookie.

domain

 

The cookie domain that will be used.

http-only

false

Set cookie httpOnly attribute.

path

/

Cookie path.

secure

false

Set cookie secure attribute.

location Attributes

Table A.76. location Attributes

AttributeDefaultDescription

handler

 

Default handler for this location.

A.24. Default Behavior of HTTP Methods

Compared to the web subsystem in previous JBoss EAP releases, the undertow subsystem in JBoss EAP 7.0 has different default behaviors of HTTP methods. The following table outlines the default behaviors in JBoss EAP 7.0.

Table A.77. HTTP Method Default Behavior

HTTP MethodJSPServletStatic HTML

GET

OK

Depends on its implementation

OK

POST

OK

Depends on its implementation

NOT_ALLOWED

HEAD

OK

Depends on its implementation

OK

PUT

NOT_ALLOWED

Depends on its implementation

NOT_ALLOWED

TRACE

NOT_ALLOWED

NOT_ALLOWED

NOT_ALLOWED

DELETE

NOT_ALLOWED

Depends on its implementation

NOT_ALLOWED

OPTIONS

NOT_ALLOWED

Depends on its implementation

OK

A.25. IO Subsystem Attributes

Table A.78. worker Attributes

AttributeDefaultDescription

io-threads

 

Number of IO threads to use.

stack-size

0

Size of the stack.

task-keepalive

60

Keepalive time for a task. This attribute should not be used as it is currently ignored.

task-max-threads

 

Maximum number of threads for a task.

Table A.79. buffer-pool Attributes

AttributeDefaultDescription

buffer-size

 

Size of the buffer.

buffers-per-slice

 

How many buffers per slice.

direct-buffers

 

Does the buffer pool use direct buffers.

A.26. Remoting Subsystem Attributes

Table A.80. remoting Attributes

AttributeDefaultDescription

worker-read-threads

1

The number of read threads to create for the remoting worker.

worker-task-core-threads

4

The number of core threads for the remoting worker task thread pool.

worker-task-keepalive

60

The number of milliseconds to keep non-core remoting worker task threads alive.

worker-task-limit

16384

The maximum number of remoting worker tasks to allow before rejecting.

worker-task-max-threads

16

The maximum number of threads for the remoting worker task thread pool.

worker-write-threads

1

The number of write threads to create for the remoting worker.

Important

The above attributes of the remoting element are deprecated. These attributes should now be configured using the io subsystem.

Table A.81. endpoint Attributes

AttributeDefaultDescription

auth-realm

 

The authentication realm to use if no authentication CallbackHandler is specified.

authentication-retries

3

Specify the number of times a client is allowed to retry authentication before closing the connection.

authorize-id

 

The SASL authorization ID. Used as authentication user name to use if no authentication CallbackHandler is specified and the selected SASL mechanism demands a user name.

buffer-region-size

 

The size of allocated buffer regions.

heartbeat-interval

2147483647

The interval to use for connection heartbeat, in milliseconds. If the connection is idle in the outbound direction for this amount of time, a ping message will be sent, which will trigger a corresponding reply message.

max-inbound-channels

40

The maximum number of concurrent inbound messages on a channel.

max-inbound-message-size

9223372036854775807

The maximum inbound message size to be allowed. Messages exceeding this size will cause an exception to be thrown on the reading side as well as the writing side.

max-inbound-messages

80

The maximum number of inbound channels to support for a connection.

max-outbound-channels

40

The maximum number of concurrent outbound messages on a channel.

max-outbound-message-size

9223372036854775807

The maximum outbound message size to send. No messages larger than this well be transmitted; attempting to do so will cause an exception on the writing side.

max-outbound-messages

65535

The maximum number of outbound channels to support for a connection.

receive-buffer-size

8192

The size of the largest buffer that this endpoint will accept over a connection.

receive-window-size

131072

The maximum window size of the receive direction for connection channels, in bytes.

sasl-protocol

remoting

Where a SaslServer or SaslClient are created by default the protocol specified is remoting, this can be used to override this.

send-buffer-size

8192

The size of the largest buffer that this endpoint will transmit over a connection.

server-name

 

The server side of the connection passes it’s name to the client in the initial greeting, by default the name is automatically discovered from the local address of the connection or it can be overridden using this.

transmit-window-size

131072

The maximum window size of the transmit direction for connection channels, in bytes.

worker

default

Worker to use

Note

When using the management CLI to update the endpoint element, it is available under configuration in the remoting element e.g.: /subsystem=remoting/configuration=endpoint/.

Connector Attributes

The connector component has the following structure:

Table A.82. connector Attributes

AttributeDefaultDescription

authentication-provider

 

The authentication-provider element contains the name of the authentication provider to use for incoming connections.

sasl-protocol

remote

The protocol to pass into the SASL mechanisms used for authentication.

security-realm

 

The associated security realm to use for authentication for this connector.

server-name

 

The server name to send in the initial message exchange and for SASL based authentication.

socket-binding

 

The name (or names) of the socket binding(s) to attach to.

Table A.83. property Attributes

AttributeDefaultDescription

value

 

The property value.

Security Attributes

The security component allows you to configure the security for the connector, but contains no direct configuration attributes. It can be configured using its nested components, such as sasl.

Table A.84. sasl Attributes

AttributeDefaultDescription

include-mechanisms

 

The optional nested include-mechanisms element contains a whitelist of allowed SASL mechanism names. No mechanisms will be allowed which are not present in this list.

qop

 

The optional nested qop element contains a list of quality-of-protection values, in decreasing order of preference.

reuse-session

false

The optional nested reuse-session boolean element specifies whether or not the server should attempt to reuse previously authenticated session information. The mechanism may or may not support such reuse, and other factors may also prevent it.

server-auth

false

The optional nested server-auth boolean element specifies whether the server should authenticate to the client. Not all mechanisms may support this setting.

strength

 

The optional nested "strength" element contains a list of cipher strength values, in decreasing order of preference.

sasl-policy Attributes

The sasl-policy component allows you to specify an optional policy to use to narrow down the available set of mechanisms, but contains no direct configuration attributes. It can be configured using its nested components, such as policy.

Table A.85. policy Attributes

AttributeDefaultDescription

forward-secrecy

true

The optional nested forward-secrecy element contains a boolean value which specifies whether mechanisms that implement forward secrecy between sessions are required. Forward secrecy means that breaking into one session will not automatically provide information for breaking into future sessions.

no-active

true

The optional nested no-active element contains a boolean value which specifies whether mechanisms susceptible to active (non-dictionary) attacks are not permitted. false to permit, true to deny.

no-anonymous

true

The optional nested no-anonymous element contains a boolean value which specifies whether mechanisms that accept anonymous login are permitted. false to permit, true to deny.

no-dictionary

true

The optional nested no-dictionary element contains a boolean value which specifies whether mechanisms susceptible to passive dictionary attacks are permitted. false to permit, true to deny.

no-plain-text

true

The optional nested no-plain-text element contains a boolean value which specifies whether mechanisms susceptible to simple plain passive attacks (e.g., PLAIN) are not permitted. false to permit, true to deny.

pass-credentials

true

The optional nested pass-credentials element contains a boolean value which specifies whether mechanisms that pass client credentials are required.

HTTP Connector Attributes

The http-connector component has the following structure:

Table A.86. http-connector Attributes

AttributeDefaultDescription

authentication-provider

 

The authentication-provider element contains the name of the authentication provider to use for incoming connections.

connector-ref

 

The name (or names) of a connector in the undertow subsystem to connect to.

sasl-protocol

remote

The protocol to pass into the SASL mechanisms used for authentication.

security-realm

 

The associated security realm to use for authentication for this connector.

server-name

 

The server name to send in the initial message exchange and for SASL based authentication.

Outbound Connection Attributes

The outbound-connection component has the following structure:

Table A.87. outbound-connection Attributes

AttributeDefaultDescription

uri

 

The connection URI for the outbound connection.

Table A.88. property Attributes

AttributeDefaultDescription

value

 

The property value.

Note

The above property attributes are related to the XNIO Options that will be used during the connection creation.

Remote Outbound Connection

The remote-outbound-connection component has the following structure:

Table A.89. remote-outbound-connection Attributes

AttributeDefaultDescription

outbound-socket-binding-ref

 

Name of the outbound-socket-binding which will be used to determine the destination address and port for the connection.

protocol

http-remoting

The protocol to use for the remote connection. Defaults to http-remoting.

security-realm

 

Reference to the security realm to use to obtain the password and SSL configuration.

username

 

The user name to use when authenticating against the remote server.

Local Outbound Connection Attributes

The local-outbound-connection component has the following structure:

Table A.90. local-outbound-connection Attributes

AttributeDefaultDescription

outbound-socket-binding-ref

 

Name of the outbound-socket-binding which will be used to determine the destination address and port for the connection.

A.27. Apache HTTP Server mod_cluster Directives

The mod_cluster connector is an Apache HTTP Server-based load balancer. It uses a communication channel to forward requests from the Apache HTTP Server to one of a set of application server nodes. The following directives can be set to configure mod_cluster.

Note

There is no need to use ProxyPass directives because mod_cluster automatically configures the URLs that must be forwarded to Apache HTTP Server.

Table A.91. mod_cluster Directives

DirectiveDescriptionValues

CreateBalancers

Defines how the balancers are created in the Apache HTTP Server VirtualHosts. This allows directives like: ProxyPass /balancer://mycluster1/.

  • 0: Create all VirtualHosts defined in Apache HTTP Server
  • 1: Do not create balancers (at least one ProxyPass or ProxyMatch is required to define the balancer names)
  • 2: Create only the main server (default)

UseAlias

Check that the alias corresponds to the server name.

  • 0: Ignore aliases (default)
  • 1: Check aliases

LBstatusRecalTime

Time interval in seconds for load-balancing logic to recalculate the status of a node.

Default: 5 seconds

WaitBeforeRemove

Time in seconds before a removed node is forgotten by httpd.

Default: 10 seconds

ProxyPassMatch/ProxyPass

ProxyPassMatch and ProxyPass are mod_proxy directives which, when using ! (instead of the back-end URL), prevent reverse-proxy in the path. This is used to allow Apache HTTP Server to serve static content. For example: ProxyPassMatch ^(/.*\.gif)$ ! This example allows the Apache HTTP Server to serve the .gif files directly.

 
Note

Due to performance optimizations for sessions in JBoss EAP 7, configuring hot-standby nodes is not supported.

mod_manager

The context of a mod_manager directive is VirtualHost in all cases, except when mentioned otherwise. server config context implies that the directive must be outside a VirtualHost configuration. If not, an error message is displayed and the Apache HTTP Server does not start.

Table A.92. mod_manager Directives

DirectiveDescriptionValues

EnableMCPMReceive

Allow the VirtualHost to receive the MCPM from the nodes. Include EnableMCPMReceive in the Apache HTTP Server configuration to allow mod_cluster to work. Save it in the VirtualHost where you configure advertising.

 

MemManagerFile

The base name for the names that mod_manager uses to store configuration, generate keys for shared memory or locked files. This must be an absolute path name; the directories are created if needed. It is recommended that these files are placed on a local drive and not an NFS share. Context: server config

$server_root/logs/

Maxcontext

The maximum number of contexts supported by mod_cluster. Context: server config

Default: 100

Maxnode

The maximum number of nodes supported by mod_cluster. Context: server config

Default: 20

Maxhost

The maximum number of hosts (aliases) supported by mod_cluster. It also includes the maximum number of balancers. Context: server config

Default: 20

Maxsessionid

The number of active sessionid stored to provide the number of active sessions in the mod_cluster-manager handler. A session is inactive when mod_cluster does not receive any information from the session within 5 minutes. Context: server config. This field is for demonstration and debugging purposes only.

0: the logic is not activated.

MaxMCMPMaxMessSize

The maximum size of MCMP messages from other Max directives

Calculated from other Max directives. Min: 1024

ManagerBalancerName

The name of balancer to use when the JBoss EAP instance does not provide a balancer name.

mycluster

PersistSlots

Tells mod_slotmem to persist nodes, aliases and contexts in files. Context: server config

Off

CheckNonce

Switch check of nonce when using mod_cluster-manager handler.

on/off Default: on - Nonce checked

AllowDisplay

Switch additional display on mod_cluster-manager main page.

on/off Default: off - only version is displayed

AllowCmd

Allow commands using mod_cluster-manager URL.

on/off Default: on - Commands allowed

ReduceDisplay

Reduce the information displayed on the main mod_cluster-manager page, so that more nodes can be displayed on the page.

on/off Default: off - full information is displayed

SetHandler mod_cluster-manager

Displays information about the node that mod_cluster sees from the cluster. The information includes generic information and additionally counts the number of active sessions.

<Location /mod_cluster-manager>
  SetHandler mod_cluster-manager
  Require ip 127.0.0.1
</Location>

on/off Default: off

Note

When accessing the location defined in httpd.conf:

  • Transferred: Corresponds to the POST data sent to the back-end server.
  • Connected: Corresponds to the number of requests that have been processed when the mod_cluster status page was requested.
  • Num_sessions: Corresponds to the number of sessions mod_cluster report as active (on which there was a request within the past 5 minutes). This field is not present when Maxsessionid is zero and is for demonstration and debugging purposes only.

A.28. ModCluster Subsystem Attributes

The modcluster subsystem has the following structure:

Table A.93. mod-cluster-config Configuration Options

AttributeDefaultDescription

advertise

true

Whether or not advertising is enabled.

advertise-security-key

 

String containing the security key for the Advertise logic.

advertise-socket

 

Name of Socket binding to use for the Advertise socket.

auto-enable-contexts

true

If set to false, contexts are registered with the reverse proxy as disabled. You can enable the context using the enable-context operation or by using the mod_cluster_manager console.

balancer

 

The name of the balancer on the reverse proxy to register with. If not set, the value is configured on the Apache HTTP Server side with the ManagerBalancerName directive, which defaults to mycluster.

connector

 

The name of Undertow listener that mod_cluster reverse proxy will connect to.

excluded-contexts

 

A list of contexts to exclude from registration with the reverse proxies. If no host is indicated, the host is assumed to be localhost. ROOT indicates the root context of the web application.

flush-packets

false

Whether or not to enable packet flushing to the web server.

flush-wait

-1

Time to wait before flushing packets in httpd. Max value is 2,147,483,647.

load-balancing-group

 

If set, requests are sent to the specified load balancing group on the load balancer.

max-attempts

1

The number of times the reverse proxy will attempt to send a given request to a worker before giving up.

node-timeout

-1

Timeout, in seconds, for proxy connections to a worker. This is the time that mod_cluster will wait for the back-end response before returning an error. If the node-timeout attribute is undefined, the httpd ProxyTimeout directive is used. If ProxyTimeout is undefined, the httpd Timeout directive is used, which defaults to 300 seconds.

ping

10

Time, in seconds, in which to wait for a pong answer to a ping.

proxies

 

List of proxies for mod_cluster to register with defined by outbound-socket-binding in socket-binding-group.

proxy-list

 

List of proxies. The format is HOST_NAME:PORT, separated with commas. Deprecated in favor of proxies.

proxy-url

/

Base URL for MCMP requests.

session-draining-strategy

DEFAULT

Session draining strategy used during undeployment of a web application. Valid values are DEFAULT, ALWAYS, or NEVER.

DEFAULT
Drain sessions before web application undeploy only if the web application is non-distributable.
ALWAYS
Always drain sessions before web application undeploy, even for distributable web applications.
NEVER
Do not drain sessions before web application undeploy.

simple-load-provider

 

A simple load provider to use if no dynamic load provider is present. It assigns each cluster member a load factor of 1, and distributes work evenly without applying a load balancing algorithm.

smax

-1

Soft maximum idle connection count in httpd.

socket-timeout

20

Number of seconds to wait for a response from an httpd proxy to MCMP commands before timing out, and flagging the proxy as in error.

status-interval

10

Number of seconds a STATUS message is sent from the application server to the reverse proxy. Allowed values are between 1 and 2,147,483,647.

sticky-session

true

Whether subsequent requests for a given session should be routed to the same node, if possible.

sticky-session-force

false

Whether the reverse proxy should return an error in the event that the balancer is unable to route a request to the node to which it is stuck. This setting is ignored if sticky sessions are disabled.

sticky-session-remove

false

Remove session information on failover.

stop-context-timeout

10

The maximum time, in seconds, to wait for a context to process pending requests, for a distributable context, or to destroy active sessions, for a non-distributable context.

ttl

-1

Time to live, in seconds, for idle connections above smax. Allowed values are between -1 and 2,147,483,647.

worker-timeout

-1

Timeout to wait in httpd for an available worker to process the requests. Allowed values are between -1 and 2,147,483,647.

Table A.94. dynamic-load-provider Configuration Options

AttributeDefaultDescription

decay

2

Decay.

history

9

History.

Table A.95. custom-load-metric Attribute Options

AttributeDefaultDescription

capacity

1.0

Capacity of the metric.

class

 

Class name of the custom metric.

property

 

Properties for the metric.

weight

1

Weight of the metric.

Table A.96. load-metric Attribute Options

AttributeDefaultDescription

capacity

1.0

Capacity of the metric.

property

 

Properties for the metric.

type

 

Type of the metric.

weight

1

Weight of the metric.

Table A.97. ssl Attribute Options

AttributeDefaultDescription

ca-certificate-file

 

Certificate authority.

ca-revocation-url

 

Certificate authority revocation list.

certificate-key-file

${user.home}/.keystore

Key file for the certificate.

cipher-suite

 

The allowed cipher suite.

key-alias

 

The key alias.

password

changeit

Password.

protocol

TLS

The SSL protocols that are enabled.

A.29. mod_jk Worker Properties

The workers.properties file defines the behavior of the workers to which mod_jk passes client requests. The workers.properties file defines where the different application servers are located and the way the workload should be balanced across them.

The general structure of a property is worker.WORKER_NAME.DIRECTIVE. The WORKER_NAME is a unique name that must match the instance-id configured in the JBoss EAP undertow subsystem. The DIRECTIVE is the setting to be applied to the worker.

Configuration Reference for Apache mod_jk Load Balancers

Templates specify default per-load-balancer settings. You can override the template within the load-balancer settings itself.

Table A.98. Global properties

PropertyDescription

worker.list

A comma separated list of worker names that will be used by mod_jk.

Table A.99. Mandatory Directives

PropertyDescription

type

The type of worker. The default type is ajp13. Other possible values are ajp14, lb, status. For more information on these directives, see the Apache Tomcat Connectors Reference at https://tomcat.apache.org/connectors-doc/reference/workers.html.

Table A.100. Load Balancing Directives

PropertyDescription

balance_workers

Specifies the worker nodes that the load balancer must manage. You can use the directive multiple times for the same load balancer. It consists of a comma-separated list of worker node names.

sticky_session

Specifies whether requests from the same session are always routed to the same worker. The default is 1, meaning that sticky sessions are enabled. To disable sticky sessions, set it to 0. Sticky sessions should usually be enabled, unless all of your requests are truly stateless.

Table A.101. Connection Directives

PropertyDescription

host

The host name or IP address of the back-end server. The back-end server must support the ajp protocol stack. The default value is localhost.

port

The port number of the back-end server instance listening for defined protocol requests. The default value is 8009, which is the default listening port for AJP13 workers. The default value for AJP14 workers is 8011.

ping_mode

The conditions under which connections are probed for network status. The probe uses an empty AJP13 packet for CPing, and expects a CPong in response. Specify the conditions by using a combination of directive flags. The flags are not separated by a comma or any white-space. The ping_mode can be any combination of C, P, I, and A.

  • C - Connect. Probe the connection one time after connecting to the server. Specify the timeout using the value of connect_timeout. Otherwise, the value of ping_timeout is used.
  • P - Prepost. Probe the connection before sending each request to the server. Specify the timeout using the prepost_timeout directive. Otherwise, the value of ping_timeout is used.
  • I - Interval. Probe the connection at an interval specified by connection_ping_interval, if present. Otherwise, the value of ping_timeout is used.
  • A - All. A shortcut for CPI, which specifies that all connection probes are used.

ping_timeout, connect_timeout, prepost_timeout, connection_ping_interval

The timeout values for the connection probe settings above. The value is specified in milliseconds, and the default value for ping_timeout is 10000.

lbfactor

Specifies the load-balancing factor for an individual back-end server instance. This is useful to give a more powerful server more of the workload. To give a worker 3 times the default load, set this to 3: worker.my_worker.lbfactor=3

The example below demonstrates load balancing with sticky sessions between two worker nodes (node1 and node2) listening on port 8009.

Example workers.properties File

# Define list of workers that will be used for mapping requests
worker.list=loadbalancer,status

# Define Node1
# modify the host as your host IP or DNS name.
worker.node1.port=8009
worker.node1.host=node1.mydomain.com
worker.node1.type=ajp13
worker.node1.ping_mode=A
worker.node1.lbfactor=1

# Define Node2
# modify the host as your host IP or DNS name.
worker.node2.port=8009
worker.node2.host= node2.mydomain.com
worker.node2.type=ajp13
worker.node2.ping_mode=A
worker.node2.lbfactor=1

# Load-balancing behavior
worker.loadbalancer.type=lb
worker.loadbalancer.balance_workers=node1,node2
worker.loadbalancer.sticky_session=1

# Status worker for managing load balancer
worker.status.type=status

Further configuration details for Apache mod_jk are out of the scope of this document and can be found in the Apache documentation.

A.30. Security Manager Subsystem Attributes

The security-manager subsystem itself does not have configurable attributes, but it has one child resource with configurable attributes: deployment-permissions=default.

Table A.102. default Configuration Options

AttributeDefaultDescription

maximum-permissions

 

The maximum set of permissions that can be granted to a deployment or jars.

minimum-permissions

 

The minimum set of permissions to be granted to a deployment or jars.





Revised on 2018-02-08 10:15:47 EST