Configuration Guide

Red Hat JBoss Enterprise Application Platform 7.3

Instructions for setting up and maintaining Red Hat JBoss Enterprise Application Platform, including running applications and services.

Red Hat Customer Content Services

Abstract

The purpose of this guide is to cover many of the configuration tasks needed for setting up and maintaining JBoss EAP as well as running applications and other services on it.

Chapter 1. Introduction

Before using this guide to configure JBoss EAP, it is assumed that the latest version of JBoss EAP has been downloaded and installed. For installation instructions, see the JBoss EAP Installation Guide.

Important

Since the installation location of JBoss EAP will vary between host machines, this guide refers to the installation location as EAP_HOME. The actual location of the JBoss EAP installation should be used instead of EAP_HOME when performing administrative tasks.

Chapter 2. Starting and Stopping JBoss EAP

2.1. Starting JBoss EAP

JBoss EAP is supported on Red Hat Enterprise Linux, Windows Server, and Oracle Solaris, and runs in either a standalone server or managed domain operating mode. The specific command to start JBoss EAP depends on the underlying platform and the desired operating mode.

Servers are initially started in a suspended state and will not accept any requests until all required services have started, at which time the servers are placed into a normal running state and can start accepting requests.

Start JBoss EAP as a Standalone Server

$ EAP_HOME/bin/standalone.sh
Note

For Windows Server, use the EAP_HOME\bin\standalone.bat script.

This startup script uses the EAP_HOME/bin/standalone.conf file, or standalone.conf.bat for Windows Server, to set some default preferences, such as JVM options. You can customize the settings in this file.

JBoss EAP uses the standalone.xml configuration file by default, but can be started using a different one. For details on the available standalone configuration files and how to use them, see the Standalone Server Configuration Files section.

For a complete listing of all available startup script arguments and their purposes, use the --help argument or see the Server Runtime Arguments section.

Start JBoss EAP in a Managed Domain

The domain controller must be started before the servers in any of the server groups in the domain. Use this script to first start the domain controller, and then for each associated host controller.

$ EAP_HOME/bin/domain.sh
Note

For Windows Server, use the EAP_HOME\bin\domain.bat script.

This startup script uses the EAP_HOME/bin/domain.conf file, or domain.conf.bat for Windows Server, to set some default preferences, such as JVM options. You can customize the settings in this file.

JBoss EAP uses the host.xml host configuration file by default, but can be started using a different one. For details on the available managed domain configuration files and how to use them, see the Managed Domain Configuration Files section.

When setting up a managed domain, additional arguments will need to be passed into the startup script. For a complete listing of all available startup script arguments and their purposes, use the --help argument or see the Server Runtime Arguments section.

2.2. Stopping JBoss EAP

The way that you stop JBoss EAP depends on how it was started.

Stop an Interactive Instance of JBoss EAP

Press Ctrl+C in the terminal where JBoss EAP was started.

Stop a Background Instance of JBoss EAP

Use the management CLI to connect to the running instance and shut down the server.

  1. Launch the management CLI.

    $ EAP_HOME/bin/jboss-cli.sh --connect
  2. Issue the shutdown command.

    shutdown
Note

When running in a managed domain, you must specify the host name to shut down by using the --host argument with the shutdown command.

2.3. Running JBoss EAP in Admin-only Mode

JBoss EAP has the ability to be started in admin-only mode. This enables JBoss EAP to run and accept management requests but not start other runtime services or accept end user requests. Admin-only mode is available in both standalone servers as well as managed domains.

Running a Standalone Server in Admin-only Mode

Start the Server in Admin-only Mode

To start a JBoss EAP instance in admin-only mode, use the --start-mode=admin-only runtime argument when starting the JBoss EAP instance.

$ EAP_HOME/bin/standalone.sh --start-mode=admin-only
Check If the Server is Running in Admin-only Mode

Use the following command to check the running mode of the server. The result will be ADMIN_ONLY if the server is running in admin-only mode.

:read-attribute(name=running-mode)
{
  "outcome" => "success",
  "result" => "ADMIN_ONLY"
}
Note

Additionally, you can check the initial running mode in which JBoss EAP was launched by using the following command.

/core-service=server-environment:read-attribute(name=initial-running-mode)
Reload in a Different Mode from the Management CLI

In addition to stopping and starting a JBoss EAP instance with a different runtime switch, the management CLI may also be used to reload it in a different mode.

To reload the server in admin-only mode:

reload --start-mode=admin-only

To reload the server in normal mode:

reload --start-mode=normal

Note that if the server was started in admin-only mode and no --start-mode argument is specified to the reload command, the server will be started in normal mode.

Running a Managed Domain in Admin-only Mode

In a managed domain, if a domain controller is started in admin-only mode, it will not accept incoming connections from slave host controllers.

Start a Host Controller in Admin-only Mode

Pass in the --admin-only runtime argument to start a host controller in admin-only mode.

$ EAP_HOME/bin/domain.sh --admin-only
Check If a Host Controller is Running in Admin-only Mode

Use the following command to check the running mode of a host controller. The result will be ADMIN_ONLY if the host controller is running in admin-only mode.

/host=HOST_NAME:read-attribute(name=running-mode)
{
  "outcome" => "success",
  "result" => "ADMIN_ONLY"
}
Reload in a Different Mode from the Management CLI

In addition to stopping and starting a host controller with a different runtime switch, the management CLI may also be used to reload it in a different mode.

To reload the host controller in admin-only mode:

reload --host=HOST_NAME --admin-only=true

To reload a host controller in normal mode:

reload --host=HOST_NAME --admin-only=false

Note that if the host controller was started in admin-only mode and no --admin-only argument is specified to the reload command, the host controller will be started in normal mode.

2.4. Suspend and Shut Down JBoss EAP Gracefully

JBoss EAP can be suspended or shut down gracefully. This allows active requests to complete normally, without accepting any new requests. A timeout value specifies how long that the suspend or shut down operation will wait for active requests to complete. While the server is suspended, management requests are still processed.

Graceful shutdown is coordinated at a server-wide level, mostly focused on the entry points at which a request enters the server. The following subsystems support graceful shutdown:

Undertow
The undertow subsystem will wait for all requests to finish.
mod_cluster
The modcluster subsystem will notify the load balancer that the server is suspending in the PRE_SUSPEND phase.
EJB
The ejb3 subsystem will wait for all remote EJB requests and MDB message deliveries to finish. Delivery to MDBs is stopped in the PRE_SUSPEND phase. EJB timers are suspended, and missed timers will be activated when the server is resumed.
Transactions

Once suspended, the server will not accept new requests, but in-flight transactions and requests are allowed to continue until they complete or until the timeout period expires. This also applies for web service requests associated with an XTS transaction.

Note

By default, transaction graceful shutdown is disabled for the ejb subsystem. You must enable transaction graceful shutdown if you want the server to wait for EJB-related transactions to complete before suspending. For example:

/subsystem=ejb3:write-attribute(name=enable-graceful-txn-shutdown,value=true)
EE Concurrency

The server will wait for all active jobs to finish. All queued jobs will be skipped. Currently, since EE Concurrency does not have persistence, those queued jobs that were skipped will be lost.

While the server is in a suspended state, scheduled tasks will continue to execute at their scheduled times but will throw a java.lang.IllegalStateException. Once the server is resumed, scheduled tasks will continue to execute normally, and in most cases tasks will not need to be rescheduled.

Batch
The server will stop all running jobs within the timeout period and defer all scheduled jobs.
Note

Graceful shutdown currently will not reject new inbound JMS messages. EE batch jobs and EE concurrency tasks scheduled by in-flight activity are currently allowed to proceed; however, EE concurrency tasks submitted that pass the timeout window currently error when executed.

Requests are tracked by the request-controller subsystem. Without this subsystem, suspend and resume capabilities are limited and the server will not wait for requests to complete before suspending or shutting down; however, if you do not need this capability, the request-controller subsystem can be removed for a small performance improvement.

2.4.1. Suspend Servers

JBoss EAP 7 introduced a suspend mode, which suspends server operations gracefully. This allows all active requests to complete normally, but will not accept any new requests. Once the server has been suspended, it can be shut down, returned back to a running state, or left in a suspended state to perform maintenance.

Note

The management interfaces are not impacted by suspending the server.

The server can be suspended and resumed using the management console or the management CLI.

Check the Server Suspend State

The server suspend state can be viewed using the following management CLI commands. The resulting value will be one of RUNNING, PRE_SUSPEND, SUSPENDING, or SUSPENDED.

  • Check the suspend state for a standalone server.

    :read-attribute(name=suspend-state)
  • Check the suspend state for a server in a managed domain.

    /host=master/server=server-one:read-attribute(name=suspend-state)
Suspend

Use the following management CLI commands to suspend the server, specifying the timeout value, in seconds, for the server to wait for active requests to complete. The default is 0, which will suspend immediately. A value of -1 will cause the server to wait indefinitely for all active requests to complete.

Each example waits up to 60 seconds for requests to complete before suspending.

  • Suspend a standalone server.

    :suspend(suspend-timeout=60)
  • Suspend all servers in a managed domain.

    :suspend-servers(suspend-timeout=60)
  • Suspend a single server in a managed domain.

    /host=master/server-config=server-one:suspend(suspend-timeout=60)
  • Suspend all servers in a server group.

    /server-group=main-server-group:suspend-servers(suspend-timeout=60)
  • Suspend all servers at the host level.

    /host=master:suspend-servers(suspend-timeout=60)
Resume

The resume command returns the server to a normal running state to accept new requests. You can initiate the command at the host, server, server group, or domain level. For example:

:resume
Start a Server in a Suspended State

You can start a server in a suspended state so that no requests are accepted by the server until it is resumed.

  • To start a standalone server in a suspended state, use the --start-mode=suspend runtime argument when starting the JBoss EAP instance.

    $ EAP_HOME/bin/standalone.sh --start-mode=suspend
  • To start a managed domain server in a suspended state, pass the start-mode=suspend argument to the start operation in the management CLI command.

    /host=HOST_NAME/server-config=SERVER_NAME:start(start-mode=suspend)
    Note

    You can also pass the start-mode argument to the reload and restart operations for a server.

  • To start all servers in a managed domain server group in a suspended state, pass the start-mode=suspend argument to the start-servers operation in the management CLI command.

    /server-group=SERVER_GROUP_NAME:start-servers(start-mode=suspend)
    Note

    You can also pass the start-mode argument to the reload-servers and restart-servers operations for a server group.

2.4.2. Shut Down Servers Gracefully Using the Management CLI

A server will be shut down gracefully if an appropriate timeout value is specified when stopping the server. Once the command is issued, the server will be suspended and will wait up to the specified timeout for all requests to finish before shutting down.

Use the following management CLI commands to shut down the server gracefully. Specify the timeout value, in seconds, for the server to wait for active requests to complete. The default is 0, which will shut down the server immediately. A value of -1 will cause the server to wait indefinitely for all active requests to complete before shutting down.

Each example waits up to 60 seconds for requests to complete before shutting down.

  • Shut down a standalone server gracefully.

    shutdown --suspend-timeout=60
  • Stop all servers in a managed domain gracefully.

    :stop-servers(suspend-timeout=60)
  • Stop a single server in a managed domain gracefully.

    /host=master/server-config=server-one:stop(suspend-timeout=60)
  • Stop all servers in a server group gracefully.

    /server-group=main-server-group:stop-servers(suspend-timeout=60)
  • Shutdown the host controller and all the servers it manages.

    /host=master:shutdown(suspend-timeout=60)
    Note

    The suspend-timeout attribute is only applied to the servers managed by the host controller, not the host controller itself.

2.4.3. Shut Down Servers Gracefully Using an OS Signal

A server can be shut down gracefully by sending an OS TERM signal, such as with kill -15 PID. By default, this value is identical to the management CLI’s shutdown --suspend-timeout=0 command, resulting in immediate termination of any currently processing requests. The timeout can be configured by org.wildfly.sigterm.suspend.timeout system property, indicating the maximum number of seconds to wait for requests to complete before the server shuts down. A value of -1 indicates that the server will wait indefinitely.

Important

In a managed domain OS signals should not be used to shut down servers. Instead, servers should be shut down using the management CLI and through the managing Host Controller.

Graceful shutdown using an OS signal will not work if the JVM is configured to disable signal handling, such as if the -Xrs java argument has been passed to the JVM options, or if the signal sent is not one the process can respond to, such as if a KILL signal is sent.

2.5. Starting and Stopping JBoss EAP (RPM Installation)

Starting and stopping JBoss EAP is different for an RPM installation compared to a ZIP or installer installation.

2.5.1. Starting JBoss EAP (RPM Installation)

The command for starting an RPM installation of JBoss EAP depends on which operating mode you want to start, a standalone server or a managed domain, and which Red Hat Enterprise Linux version you are running.

Start JBoss EAP as a Standalone Server (RPM Installation)
  • For Red Hat Enterprise Linux 6:

    $ service eap7-standalone start
  • For Red Hat Enterprise Linux 7 and later:

    $ systemctl start eap7-standalone.service

This will start JBoss EAP using the standalone.xml configuration file by default. You can start JBoss EAP with a different standalone server configuration file by setting a property in the RPM service configuration file. For more information, see the Configure RPM Service Properties section below.

Start JBoss EAP in a Managed Domain (RPM Installation)
  • For Red Hat Enterprise Linux 6:

    $ service eap7-domain start
  • For Red Hat Enterprise Linux 7 and later:

    $ systemctl start eap7-domain.service

This will start JBoss EAP using the host.xml configuration file by default. You can start JBoss EAP with a different managed domain configuration file by setting a property in the RPM service configuration file. For more information, see the Configure RPM Service Properties section below.

Configure RPM Service Properties

This section shows you how to configure the RPM service properties and other startup options for your JBoss EAP installation. Note that it is recommended to back up your configuration files before making modifications.

For a listing of all available startup options for an RPM installation, see the RPM Service Configuration Properties section.

Important

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

  • Specify the server configuration file.

    When starting a standalone server, the standalone.xml file is used by default. When running in a managed domain, the host.xml file is used by default. You can start JBoss EAP with a different configuration file by setting the WILDFLY_SERVER_CONFIG property in the appropriate RPM configuration file, for example, eap7-standalone.conf.

    WILDFLY_SERVER_CONFIG=standalone-full.xml
  • Bind to a specific IP address.

    By default, a JBoss EAP RPM installation binds to 0.0.0.0. You can bind JBoss EAP to a specific IP address by setting the WILDFLY_BIND property in the appropriate RPM configuration file, for example, eap7-standalone.conf.

    WILDFLY_BIND=192.168.0.1
    Note

    If you want to bind the management interfaces to a specific IP address, this can be configured in the JBoss EAP startup configuration file as shown in the next example.

  • Set JVM options or Java properties.

    You can specify JVM options or Java properties to pass into the JBoss EAP startup script by editing the startup configuration file. This file is EAP_HOME/bin/standalone.conf for a standalone server or EAP_HOME/bin/domain.conf for a managed domain. The below example configures the heap size and binds the JBoss EAP management interfaces to an IP address.

    JAVA_OPTS="$JAVA_OPTS -Xms2048m -Xmx2048m"
    JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address.management=192.168.0.1"
    Note

    If required, the JBoss EAP bind address must be configured using the WILDFLY_BIND property and not using the jboss.bind.address standard property here.

Note

If a property has the same name in both the RPM service configuration file, such as /etc/sysconfig/eap7-standalone, and in the JBoss EAP startup configuration file, such as 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.

2.5.2. Stopping JBoss EAP (RPM Installation)

The command for stopping an RPM installation of JBoss EAP depends on which operating mode that was started, a standalone server or a managed domain, and which Red Hat Enterprise Linux version you are running.

Stop JBoss EAP as a Standalone Server (RPM Installation)
  • For Red Hat Enterprise Linux 6:

    $ service eap7-standalone stop
  • For Red Hat Enterprise Linux 7 and later:

    $ systemctl stop eap7-standalone.service
Stop JBoss EAP in a Managed Domain (RPM Installation)
  • For Red Hat Enterprise Linux 6:

    $ service eap7-domain stop
  • For Red Hat Enterprise Linux 7 and later:

    $ systemctl stop eap7-domain.service

For a listing of all available startup options for an RPM installation, see the RPM Service Configuration Files section.

2.6. PowerShell Scripts (Windows Server)

Important

The collection of PowerShell scripts is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

JBoss EAP includes PowerShell script equivalents for most of the JBoss EAP management scripts. This includes a PowerShell script to start JBoss EAP on Microsoft Windows Server.

The JBoss EAP PowerShell scripts are designed to work with PowerShell version 2 and newer running on tested versions of Windows Server.

The JBoss EAP PowerShell scripts are located in EAP_HOME\bin, and are used in mostly the same way as the JBoss EAP batch scripts.

For example, to start a standalone JBoss EAP server with the standalone-full.xml configuration file, use the following PowerShell command:

.\standalone.ps1 "-c=standalone-full.xml"
Note

Arguments of the JBoss EAP PowerShell scripts must be in quotes.

Chapter 3. JBoss EAP Management

JBoss EAP uses a simplified configuration, with one configuration file per standalone server or managed domain. Default configuration for a standalone server is stored in the EAP_HOME/standalone/configuration/standalone.xml file and default configuration for a managed domain is stored in the EAP_HOME/domain/configuration/domain.xml file. Additionally, the default configuration for a host controller is stored in the EAP_HOME/domain/configuration/host.xml file.

JBoss EAP can be configured using the command-line management CLI, web-based management console, Java API, or HTTP API. Changes made using these management interfaces persist automatically, and the XML configuration files are overwritten by the Management API. The management CLI and management console are the preferred methods, and it is not recommended to edit the XML configuration files manually.

3.1. About Subsystems, Extensions, and Profiles

Different aspects of JBoss EAP functionality are configured in different subsystems. For example, application and server logging are configured in the logging subsystem.

An extension is a module that extends the core functionality of the server. Extensions are loaded as they are needed by deployments, and are unloaded when they are no longer needed. See the JBoss EAP Management CLI Guide for how to add and remove extensions.

A subsystem provides configuration options for a particular extension. For more information on the available subsystems, see Overview of JBoss EAP Subsystems.

A collection of subsystem configurations makes up a profile, which is configured to satisfy the needs for the server. A standalone server has a single, unnamed profile. A managed domain can define many profiles for use by server groups in the domain.

Using the Management Console or the Management CLI

Both the management console and the management CLI are valid, supported ways of updating the configuration of a JBoss EAP instance. Deciding between the two is a matter of preference. Those who prefer to use a graphical, web-based interface should use the management console. Those who prefer a command-line interface should use the management CLI.

3.2. Management Users

The default JBoss EAP configuration provides local authentication so that a user can access the management CLI on the local host without requiring authentication.

However, you must add a management user if you want to access the management CLI remotely or use the management console, which is considered remote access even if the traffic originates on the local host. If you attempt to access the management console before adding a management user, you will receive an error message.

If JBoss EAP is installed using the graphical installer, then a management user is created during the installation process.

This guide covers simple user management for JBoss EAP using the add-user script, which is a utility for adding new users to the properties files for out-of-the-box authentication.

For more advanced authentication and authorization options, such as LDAP or Role-Based Access Control (RBAC), see the Core Management Authentication section of the JBoss EAP Security Architecture.

3.2.1. Adding a Management User

  1. Run the add-user utility script and follow the prompts.

    $ EAP_HOME/bin/add-user.sh
    Note

    For Windows Server, use the EAP_HOME\bin\add-user.bat script.

  2. Press ENTER to select the default option a to add a management user.

    This user will be added to the ManagementRealm and will be authorized to perform management operations using the management console or management CLI. The other choice, b, adds a user to the ApplicationRealm, which is used for applications and provides no particular permissions.

  3. Enter the desired username and password. You will be prompted to confirm the password.

    Note

    User names can only contain the following characters, in any number and in any order:

    • Alphanumeric characters (a-z, A-Z, 0-9)
    • Dashes (-), periods (.), commas (,), at sign (@)
    • Backslash (\)
    • Equals (=)

    By default, JBoss EAP allows weak passwords but will issue a warning.

    See Setting Add-User Utility Password Restrictions for details on changing this default behavior.

  4. Enter a comma-separated list of groups to which the user belongs. If you do not want the user to belong to any groups, press ENTER to leave it blank.
  5. Review the information and enter yes to confirm.
  6. Determine whether this user represents a remote JBoss EAP server instance. For a basic management user, enter no.

    One type of user that may need to be added to the ManagementRealm is a user representing another instance of JBoss EAP, which must be able to authenticate to join as a member of a cluster. If this is the case, then answer yes to this prompt and you will be given a hashed secret value representing the user’s password, which will need to be added to a different configuration file.

Users can also be created non-interactively by passing parameters to the add-user script. This approach is not recommended on shared systems, because the passwords will be visible in log and history files. For more information, see Running the Add-User Utility Non-Interactively.

3.2.2. Running the Add-User Utility Non-Interactively

You can run the add-user script non-interactively by passing in arguments on the command line. At a minimum, the username and password must be provided.

Warning

This approach is not recommended on shared systems, because the passwords will be visible in log and history files.

Create a User Belonging to Multiple Groups

The following command adds a management user, mgmtuser1, with the guest and mgmtgroup groups.

$ EAP_HOME/bin/add-user.sh -u 'mgmtuser1' -p 'password1!' -g 'guest,mgmtgroup'
Specify an Alternative Properties File

By default, user and group information created using the add-user script are stored in properties files located in the server configuration directory.

User information is stored in the following properties files:

  • EAP_HOME/standalone/configuration/mgmt-users.properties
  • EAP_HOME/domain/configuration/mgmt-users.properties

Group information is stored in the following properties files:

  • EAP_HOME/standalone/configuration/mgmt-groups.properties
  • EAP_HOME/domain/configuration/mgmt-groups.properties

These default directories and properties file names can be overridden. The following command adds a new user, specifying a different name and location for the user properties files.

$ EAP_HOME/bin/add-user.sh -u 'mgmtuser2' -p 'password1!' -sc '/path/to/standaloneconfig/' -dc '/path/to/domainconfig/' -up 'newname.properties'

The new user was added to the user properties files located at /path/to/standaloneconfig/newname.properties and /path/to/domainconfig/newname.properties. Note that these files must already exist or you will see an error.

For a complete listing of all available add-user arguments and their purposes, use the --help argument or see the Add-User Utility Arguments section.

3.2.3. Add-User Utility Password Restrictions

The password restrictions for the add-user utility script can be configured using the EAP_HOME/bin/add-user.properties file.

Important

The add-user.properties file is an unprotected plain-text file and must be secured to avoid unwarranted access to its contents.

To avoid setting an unintentional password, check that your keyboard’s system keymap is correct. The default system keymap is en-qwerty. If you change this default setting and create a new password, you must check that the password meets the criteria located in the class SimplePasswordStrengthChecker.

By default, JBoss EAP allows weak passwords but issues a warning. To reject passwords that do not meet the minimum requirements specified, set the password.restriction property to REJECT.

The following table describes the additional password requirement settings that can be configured in the EAP_HOME/bin/add-user.properties file:

Table 3.1. Additional Password Requirement Settings

AttributeDescription

minLength

The minimum number of characters for a password. For example, password.restriction.minLength=8 restricts the password to a minimum of eight characters.

strength

Sets the threshold that a password must meet to be valid. Valid threshold entries include:

* VERY_WEAK

* WEAK

* MODERATE

* MEDIUM

* STRONG

* VERY_STRONG

* EXCEPTIONAL

The default value is MODERATE. The threshold values are defined and the default value specified in the class SimplePasswordStrengthChecker.

NOTE: If you do not specify a threshold value, MODERATE becomes the default value. This value is specified in the class SimplePasswordStrengthChecker.

minAlpha

The minimum number of alphabetic characters set for a password. For example, password.restriction.minAlpha=1 restricts a password to include at least one alphabetic character.

minDigit

The minimum number of numeric characters set for a password. For example, password.restriction.minDigit=1 restricts a password to include at least one numerical character.

minSymbol

The minimum number of symbols set for a password. For example, password.restriction.minSymbol=1 restricts a password to include at least one symbol.

forbiddenValue

Restricts a user from setting an easily determined password, such as root. For example, password.restriction.forbidden=root,admin,administrator restricts setting root, admin, or administrator as the password.

mustNotMatchUsername

Restricts the user from setting their user name as the password. For example, password.restriction.mustNotMatchUsername=TRUE restricts the user from setting their user name as the password. This rule is ignored if set to false.

Additional Resources

See the Configuring Basic System Settings guide on the Red Hat Customer Portal.

3.2.4. Updating a Management User

You can update the settings for an existing management user using the add-user utility script by entering the username when prompted.

$ EAP_HOME/bin/add-user.sh

What type of user do you wish to add?
 a) Management User (mgmt-users.properties)
 b) Application User (application-users.properties)
(a): a

Enter the details of the new user to add.
Using realm 'ManagementRealm' as discovered from the existing property files.
Username : test-user
User 'test-user' already exists and is enabled, would you like to...
 a) Update the existing user password and roles
 b) Disable the existing user
 c) Type a new username
(a):

When you enter a username that already exists, you are presented with several options:

  • Type a to update the password for the existing user.
  • Type b to disable the existing user.
  • Type c to enter a new username.
Warning

When updating a user using the add-user script non-interactively, the user is updated automatically with no confirmation prompt.

3.3. Optimizing the JBoss EAP Server Configuration

Once you have installed the JBoss EAP server, and you have created a management user, Red Hat recommends that you optimize your server configuration.

Make sure you review information in the Performance Tuning Guide for information about how to optimize the server configuration to avoid common problems when deploying applications in a production environment. Common optimizations include setting ulimits, enabling garbage collection, creating Java heap dumps, and adjusting the thread pool size.

It is also a good idea to apply any existing patches for your release of the product. Each patch for EAP contains numerous bug fixes. For more information, see Patching JBoss EAP in the Patching and Upgrading Guide for JBoss EAP.

3.4. Management Interfaces

3.4.1. Management CLI

The management command-line interface (CLI) is a command-line administration tool for JBoss EAP.

Use the management CLI to start and stop servers, deploy and undeploy applications, configure system settings, and perform other administrative tasks. Operations can be performed in batch mode, allowing multiple tasks to be run as a group.

Many common terminal commands are available, such as ls, cd, and pwd. The management CLI also supports tab completion.

For detailed information on using the management CLI, including commands and operations, syntax, and running in batch mode, see the JBoss EAP Management CLI Guide.

Launch the Management CLI
$ EAP_HOME/bin/jboss-cli.sh
Note

For Windows Server, use the EAP_HOME\bin\jboss-cli.bat script.

Connect to a Running Server
connect

Or you can launch the management CLI and connect in one step by using the EAP_HOME/bin/jboss-cli.sh --connect command.

Display Help

Use the following command for general help.

help

Use the --help flag on a command to receive instructions on using that specific command. For instance, to receive information on using deploy, the following command is executed.

deploy --help
Quit the Management CLI
quit
View System Settings

The following command uses the read-attribute operation to display whether the example datasource is enabled.

/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
{
    "outcome" => "success",
    "result" => true
}

When running in a managed domain, you must specify which profile to update by preceding the command with /profile=PROFILE_NAME.

/profile=default/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
Update System Settings

The following command uses the write-attribute operation to disable the example datasource.

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled,value=false)
Start Servers

The management CLI can also be used to start and stop servers when running in a managed domain.

/host=HOST_NAME/server-config=server-one:start

3.4.2. Management Console

The management console is a web-based administration tool for JBoss EAP.

Use the management console to start and stop servers, deploy and undeploy applications, tune system settings, and make persistent modifications to the server configuration. The management console also has the ability to perform administrative tasks, with live notifications when any changes performed by the current user require the server instance to be restarted or reloaded.

In a managed domain, server instances and server groups in the same domain can be centrally managed from the management console of the domain controller.

For a JBoss EAP instance running on the local host using the default management port, the management console can be accessed through a web browser at http://localhost:9990/console/index.html. You will need to authenticate with a user that has permissions to access the management console.

The management console provides the following tabs for navigating and managing your JBoss EAP standalone server or managed domain.

Home
Learn how to accomplish several common configuration and management tasks. Take a tour to become familiar with the JBoss EAP management console.
Deployments
Add, remove, and enable deployments. In a managed domain, assign deployments to server groups.
Configuration
Configure available subsystems, which provide capabilities such as web services, messaging, or high availability. In a managed domain, manage the profiles that contain different subsystem configurations.
Runtime
View runtime information, such as server status, JVM usage, and server logs. In a managed domain, manage your hosts, server groups, and servers.
Patching
Apply patches to your JBoss EAP instances.
Access Control
Assign roles to users and groups when using Role-Based Access Control.

3.4.2.1. Updating Attributes in the Management Console

Once you have navigated to the appropriate section of the management console for the resource that you want to modify, you can edit its attributes as long as you have the proper permissions.

  1. Click the Edit link.
  2. Make the desired changes.

    Required fields are marked with an asterisk (*). You can view attribute descriptions by clicking the Help link.

    Note

    Depending on the attribute type, the input field can be a text field, ON/OFF field, or drop down. In some text fields, as you type, values from elsewhere in the configuration may appear as suggestions.

  3. Click Save to save the changes.
  4. If necessary, reload the server for the changes to take effect.

    A popup appears when saving changes that require a reload in order to take effect. To reload a standalone server, click the Reload link in the popup. To reload a server in a managed domain, click the Topology link, select the appropriate server, and click the Reload drop down option.

To view the history of recent configuration actions you have performed, click the notification icon in the top-right of the management console.

3.4.2.2. Enable/Disable Management Console

You can enable or disable the management console by setting the console-enabled boolean attribute of the /core-service=management/management-interface=http-interface resource. For the master host in domain mode, use /host=master/core-service=management/management-interface=http-interface.

For example, to enable:

/core-service=management/management-interface=http-interface:write-attribute(name=console-enabled,value=true)

For example, to disable:

/core-service=management/management-interface=http-interface:write-attribute(name=console-enabled,value=false)

3.4.2.3. Change the Language of the Management Console

By default, the language settings of the management console is English. You can choose to use one of the following languages instead:

  • German (de)
  • Simplified Chinese (zh-Hans)
  • Brazilian Portuguese (pt-BR)
  • French (fr)
  • Spanish (es)
  • Japanese (ja)
To Change the Language of the Management Console
  1. Log in to the management console.
  2. Click the Settings link in the lower-right corner of the management console.
  3. Select the required language from the Locale selection box.
  4. Select Save. A confirmation box informs you that you need to reload the application.
  5. Click Yes. The system refreshes your web browser automatically to use the selected locale.

3.4.2.4. Customizing the Management Console Title

You can customize the management console title so that each of your JBoss EAP instances can be identified at a quick glance.

To customize the management console title:

  1. Log in to the management console.
  2. Click Settings in the lower-right corner of the management console.
  3. In the Settings window, modify the title in the Title field.
  4. Click Save.

    A confirmation box informs you that you must reload the management console.

  5. Click Yes.

    The system refreshes your web browser automatically and the new title is displayed on the tab header.

3.5. Management APIs

3.5.1. HTTP API

The HTTP API endpoint is the entry point for management clients that rely on the HTTP protocol to integrate with the JBoss EAP management layer.

The HTTP API is used by the JBoss EAP management console but offers integration capabilities for other clients as well. By default, the HTTP API is accessible at http://HOST_NAME:9990/management. This URL will display the raw attributes and values exposed to the API.

Read Resources

While you can read, write, or perform other operations using the HTTP POST method, you can perform some read operations using a GET request. The HTTP GET method uses the following URL format.

http://HOST_NAME:9990/management/PATH_TO_RESOURCE?operation=OPERATION&PARAMETER=VALUE

Be sure to replace all of the replaceable values with those that are appropriate for your request. The following values are the available options for the OPERATION replaceable value:

ValueDescription

attribute

Performs the read-attribute operation.

operation-description

Performs the read-operation-description operation.

operation-names

Performs the read-operation-names operation.

resource

Performs the read-resource operation.

resource-description

Performs the read-resource-description operation.

snapshots

Performs the list-snapshots operation.

The following example URLs show how to perform read operations using the HTTP API.

Example: Read All Attributes and Values for a Resource

http://HOST_NAME:9990/management/subsystem/undertow/server/default-server/http-listener/default

This displays all attributes and their values for the default HTTP listener.

Note

The default operation is read-resource.

Example: Read the Value of an Attribute for a Resource

http://HOST_NAME:9990/management/subsystem/datasources/data-source/ExampleDS?operation=attribute&name=enabled

This reads the value of the enabled attribute for the ExampleDS datasource.

Update Resources

You can use the HTTP POST method to update configuration values or perform other operations using the HTTP API. You must provide authentication for these operations.

The following examples show how to update resources using the HTTP API.

Example: Update the Value of an Attribute for a Resource

$ curl --digest http://HOST_NAME:9990/management --header "Content-Type: application/json" -u USERNAME:PASSWORD -d '{"operation":"write-attribute", "address":["subsystem","datasources","data-source","ExampleDS"], "name":"enabled", "value":"false", "json.pretty":"1"}'

This updates the value of the enabled attribute for the ExampleDS datasource to false.

Example: Issue an Operation to the Server

$ curl --digest http://localhost:9990/management --header "Content-Type: application/json" -u USERNAME:PASSWORD -d '{"operation":"reload"}'

This reloads the server.

See Deploying Applications Using the HTTP API for information on how to deploy applications to JBoss EAP using the HTTP API.

3.5.2. Native API

The native API endpoint is the entry point for management clients that rely on the native protocol to integrate with the JBoss EAP management layer. The native API is used by the JBoss EAP management CLI but offers integration capabilities for other clients as well.

The following Java code shows an example of how to execute management operations from Java code using the native API.

Note

You must add the required JBoss EAP libraries, found in the EAP_HOME/bin/client/jboss-cli-client.jar file, to your class path.

Example: Using the Native API to Read Resources

// Create the management client
ModelControllerClient client = ModelControllerClient.Factory.create("localhost", 9990);

// Create the operation request
ModelNode op = new ModelNode();

// Set the operation
op.get("operation").set("read-resource");

// Set the address
ModelNode address = op.get("address");
address.add("subsystem", "undertow");
address.add("server", "default-server");
address.add("http-listener", "default");

// Execute the operation and manipulate the result
ModelNode returnVal = client.execute(op);
System.out.println("Outcome: " + returnVal.get("outcome").toString());
System.out.println("Result: " + returnVal.get("result").toString());

// Close the client
client.close();

3.6. Configuration Data

3.6.1. Standalone Server Configuration Files

The standalone configuration files are located in the EAP_HOME/standalone/configuration/ directory. A separate file exists for each of the five predefined profiles (default, ha, full, full-ha, load-balancer).

Table 3.2. Standalone Configuration Files

Configuration FilePurpose

standalone.xml

This standalone configuration file is the default configuration that is used when you start your standalone server. It contains all information about the server, including subsystems, networking, deployments, socket bindings, and other configurable details. It does not provide the subsystems necessary for messaging or high availability.

standalone-ha.xml

This standalone configuration file includes all of the default subsystems and adds the modcluster and jgroups subsystems for high availability. It does not provide the subsystems necessary for messaging.

standalone-full.xml

This standalone configuration file includes all of the default subsystems and adds the messaging-activemq and iiop-openjdk subsystems. It does not provide the subsystems necessary for high availability.

standalone-full-ha.xml

This standalone configuration file includes support for every possible subsystem, including those for messaging and high availability.

standalone-load-balancer.xml

This standalone configuration file includes the minimum subsystems necessary to use the built-in mod_cluster front-end load balancer to load balance other JBoss EAP instances.

By default, starting JBoss EAP as a standalone server uses the standalone.xml file. To start JBoss EAP with a different configuration, use the --server-config argument. For example,

$ EAP_HOME/bin/standalone.sh --server-config=standalone-full.xml

3.6.2. Managed Domain Configuration Files

The managed domain configuration files are located in the EAP_HOME/domain/configuration/ directory.

Table 3.3. Managed Domain Configuration Files

Configuration FilePurpose

domain.xml

This is the main configuration file for a managed domain. Only the domain master reads this file. This file contains the configurations for all of the profiles (default, ha, full, full-ha, load-balancer).

host.xml

This file includes configuration details specific to a physical host in a managed domain, such as network interfaces, socket bindings, the name of the host, and other host-specific details. The host.xml file includes all of the features of both host-master.xml and host-slave.xml, which are described below.

host-master.xml

This file includes only the configuration details necessary to run a server as the master domain controller.

host-slave.xml

This file includes only the configuration details necessary to run a server as a managed domain host controller.

By default, starting JBoss EAP in a managed domain uses the host.xml file. To start JBoss EAP with a different configuration, use the --host-config argument. For example,

$ EAP_HOME/bin/domain.sh --host-config=host-master.xml

3.6.3. Backing Up Configuration Data

In order to later restore the JBoss EAP server configuration, items in the following locations should be backed up:

  • EAP_HOME/standalone/configuration/

    • Back up the entire directory to save user data, server configuration, and logging settings for standalone servers.
  • EAP_HOME/domain/configuration/

    • Back up the entire directory to save user and profile data, domain and host configuration, and logging settings for managed domains.
  • EAP_HOME/modules/

    • Back up any custom modules.
  • EAP_HOME/welcome-content/

    • Back up any custom welcome content.
  • EAP_HOME/bin/

    • Back up any custom scripts or startup configuration files.

3.6.4. Configuration File Snapshots

To assist in the maintenance and management of the server, JBoss EAP creates a timestamped version of the original configuration file at the time of startup. Any additional configuration changes made by management operations will result in the original file being automatically backed up, and a working copy of the instance being preserved for reference and rollback. Additionally, configuration snapshots can be taken, which are point-in-time copies of the current server configuration. These snapshots can be saved and loaded by an administrator.

The following examples use the standalone.xml file, but the same process applies to the domain.xml and host.xml files.

Take a Snapshot

Use the management CLI to take a snapshot of the current configurations.

:take-snapshot
{
    "outcome" => "success",
    "result" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20151022-133109702standalone.xml"
}
List Snapshots

Use the management CLI to list all snapshots that have been taken.

:list-snapshots
{
    "outcome" => "success",
    "result" => {
        "directory" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot",
        "names" => [
            "20151022-133109702standalone.xml",
            "20151022-132715958standalone.xml"
        ]
    }
}
Delete a Snapshot

Use the management CLI to delete a snapshot.

:delete-snapshot(name=20151022-133109702standalone.xml)
Start the Server with a Snapshot

The server can be started using a snapshot or an automatically-saved version of the configuration.

  1. Navigate to the EAP_HOME/standalone/configuration/standalone_xml_history directory and identify the snapshot or saved configuration file to be loaded.
  2. Start the server and point to the selected configuration file. Pass in the file path relative to the configuration directory, EAP_HOME/standalone/configuration/.

    $ EAP_HOME/bin/standalone.sh --server-config=standalone_xml_history/snapshot/20151022-133109702standalone.xml
Note

When running in a managed domain, use the --host-config argument instead to specify the configuration file.

3.6.5. View Configuration Changes

JBoss EAP 7 provides the ability to track configuration changes made to the running system. This allows administrators to view a history of configuration changes made by other authorized users.

Important

Changes are stored in memory and are not persisted between server restarts. This feature is not a replacement for management audit logging.

You can enable tracking and view configuration changes from either the management CLI or the management console.

Track and View Configuration Changes from the Management CLI

To enable tracking of configuration changes, use the following management CLI command. You can specify how many entries to store using the max-history attribute.

/subsystem=core-management/service=configuration-changes:add(max-history=20)
Note

In a managed domain, configuration changes are tracked at the host level for host and server-related modifications. Enabling configuration changes for a host controller enables it for all of its managed servers. You can track configuration changes per host using the following command.

/host=HOST_NAME/subsystem=core-management/service=configuration-changes:add(max-history=20)

To view the list of most recent configuration changes, use the following management CLI command.

/subsystem=core-management/service=configuration-changes:list-changes
Note

In a managed domain, you can list the configuration changes for a host using the following command.

/host=HOST_NAME/subsystem=core-management/service=configuration-changes:list-changes

You can list the configuration changes that affect a particular server using the following command.

/host=HOST_NAME/server=SERVER_NAME/subsystem=core-management/service=configuration-changes:list-changes

This lists each configuration change made, with the date, origin, outcome, and operation details. For example, the below output from the list-changes command shows configuration changes, with the most recent displayed first.

{
    "outcome" => "success",
    "result" => [
        {
            "operation-date" => "2016-02-12T18:37:00.354Z",
            "access-mechanism" => "NATIVE",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "address" => [],
                "operation" => "reload",
                "operation-headers" => {
                    "caller-type" => "user",
                    "access-mechanism" => "NATIVE"
                }
            }]
        },
        {
            "operation-date" => "2016-02-12T18:34:16.859Z",
            "access-mechanism" => "NATIVE",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "address" => [
                    ("subsystem" => "datasources"),
                    ("data-source" => "ExampleDS")
                ],
                "operation" => "write-attribute",
                "name" => "enabled",
                "value" => false,
                "operation-headers" => {
                    "caller-type" => "user",
                    "access-mechanism" => "NATIVE"
                }
            }]
        },
        {
            "operation-date" => "2016-02-12T18:24:11.670Z",
            "access-mechanism" => "HTTP",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "operation" => "remove",
                "address" => [
                    ("subsystem" => "messaging-activemq"),
                    ("server" => "default"),
                    ("jms-queue" => "ExpiryQueue")
                ],
                "operation-headers" => {"access-mechanism" => "HTTP"}
            }]
        }
    ]
}

This example lists the details of three operations performed that impacted the configuration:

  • Reloading the server from the management CLI.
  • Disabling the ExampleDS datasource from the management CLI.
  • Removing the ExpiryQueue queue from the management console.
Track and View Configuration Changes from the Management Console

To enable tracking of configuration changes from the management console, select to the Runtime tab, navigate to the server or host to track changes for and select Configuration Changes from the drop down. Click Enable Configuration Changes and provide a maximum history value.

The table on this page then lists each configuration change made, with the date, origin, outcome, and operation details.

3.6.6. Property Replacement

JBoss EAP allows you to use expressions to define replaceable properties in place of literal values in the configuration. Expressions use the format ${PARAMETER:DEFAULT_VALUE}. If the specified parameter is set, then the parameter’s value will be used. Otherwise, the default value provided will be used.

The supported sources for resolving expressions are system properties, environment variables, and the vault. For deployments only, the source can be properties listed in a META-INF/jboss.properties file in the deployment archive. For deployment types that support subdeployments, the resolution is scoped to all subdeployments if the properties file is in the outer deployment, for example the EAR. If the properties file is in the subdeployment, then the resolution is scoped just to that subdeployment.

The example below from the standalone.xml configuration file sets the inet-address for the public interface to 127.0.0.1 unless the jboss.bind.address parameter is set.

<interface name="public">
    <inet-address value="${jboss.bind.address:127.0.0.1}"/>
</interface>

The jboss.bind.address parameter can be set when starting EAP as a standalone server with the following command:

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=IP_ADDRESS
Nested Expressions

Expressions can be nested, which allows for more advanced use of expressions in place of fixed values. The format of a nested expression is like that of a normal expression, but one expression is embedded in the other, for example:

${SYSTEM_VALUE_1${SYSTEM_VALUE_2}}

Nested expressions are evaluated recursively, so the inner expression is first evaluated, then the outer expression is evaluated. Expressions may also be recursive, where an expression resolves to another expression, which is then resolved. Nested expressions are permitted anywhere that expressions are permitted, with the exception of management CLI commands.

An example of where a nested expression might be used is if the password used in a datasource definition is masked. The configuration for the datasource might have the following line:

<password>${VAULT::ds_ExampleDS::password::1}</password>

The value of ds_ExampleDS could be replaced with a system property (datasource_name) using a nested expression. The configuration for the datasource could instead have the following line:

<password>${VAULT::${datasource_name}::password::1}</password>

JBoss EAP would first evaluate the expression ${datasource_name}, then input this to the larger expression and evaluate the resulting expression. The advantage of this configuration is that the name of the datasource is abstracted from the fixed configuration.

Descriptor-Based Property Replacement

Application configuration, such as datasource connection parameters, typically varies between development, testing, and production environments. This variance is sometimes accommodated by build system scripts, as the Jakarta EE specification does not contain a method to externalize these configurations. With JBoss EAP, you can use descriptor-based property replacement to manage configuration externally.

Descriptor-based property replacement substitutes properties based on descriptors, allowing you to remove assumptions about the environment from the application and the build chain. Environment-specific configurations can be specified in deployment descriptors rather than annotations or build system scripts. You can provide configuration in files or as parameters at the command line.

There are several flags in the ee subsystem that control whether property replacement is applied.

JBoss-specific descriptor replacement is controlled by the jboss-descriptor-property-replacement flag and is enabled by default. When enabled, properties can be replaced in the following deployment descriptors:

  • jboss-ejb3.xml
  • jboss-app.xml
  • jboss-web.xml
  • *-jms.xml
  • *-ds.xml

The following management CLI command can be used to enable or disable property replacement in JBoss-specific descriptors:

/subsystem=ee:write-attribute(name="jboss-descriptor-property-replacement",value=VALUE)

Jakarta EE descriptor replacement controlled by the spec-descriptor-property-replacement flag and is disabled by default. When enabled, properties can be replaced in the following deployment descriptors:

  • ejb-jar.xml
  • persistence.xml
  • application.xml
  • web.xml

The following management CLI command can be used to enable or disable property replacement in Jakarta EE descriptors:

/subsystem=ee:write-attribute(name="spec-descriptor-property-replacement",value=VALUE)

3.6.7. Using Git to Manage Configuration Data

As of JBoss EAP 7.3, you can use Git to manage and persist your server configuration data, properties files, and deployments. This not only allows you to manage the version history for these files, but it also allows you to share server and application configurations across multiple servers and nodes using one or more Git repositories. This feature only works for standalone servers that use the default configuration directory layout.

You can choose to use configuration data in a local Git repository or you can pull the data from a remote Git repository. The Git repository is configured in the jboss.server.base.dir directory, which is the base directory for standalone server content. Once the jboss.server.base.dir directory is configured to use Git, JBoss EAP automatically commits every update you make to the configuration using the management CLI or management console. Any changes made outside of the server by manually editing the configuration files are not committed or persisted; however, you can use the Git CLI to add and commit manual changes. You can also use the Git CLI to view the commit history, manage branching, and manage the content.

To use this feature, pass one or more of the following arguments on the command line when you start the server.

Table 3.4. Server Startup Arguments for Git Configuration Management

ArgumentDescription

--git-repo

The location of the Git repository that is used to manage and persist server configuration data. This can be local if you want to store it locally, or the URL to a remote repository.

--git-branch

The branch or tag name in the Git repository to use. This argument should name an existing branch or tag name as it will not be created if it does not exist. If you use a tag name, you put the repository in a detached HEAD state, meaning future commits are not attached to any branches. Tag names are read-only and are normally used when you need to replicate a configuration across several nodes.

--git-auth

The URL to an Elytron configuration file that contains the credentials to be used when connecting to a remote Git repository. This argument is required if your remote Git repository requires authentication. Although Git supports SSH authentication, Elytron does not; therefore, it is currently only possible to specify credentials to authenticate with HTTP or HTTPS, not SSH. This argument is not used with a local repository.

Using a Local Git Repository

To use a local Git repository, start the server with the --git-repo=local argument. You can also specify an optional branch or tag name in the remote repository by adding the --git-branch=GIT_BRANCH_NAME argument when you start the server. This argument should name an existing branch or tag name as it will not be created if it does not exist. If you use a tag name, you put the repository in a detached HEAD state, meaning future commits are not attached to any branches.

The following is an example of a command to start the server using the 1.0.x branch of the local repository.

$ EAP_HOME/bin/standalone.sh --git-repo=local --git-branch=1.0.x

If you start the server with the argument to use a local Git repository, JBoss EAP checks whether the jboss.server.base.dir directory is already configured for Git. If not, JBoss EAP creates and initializes the Git repository in the jboss.server.base.dir directory using the existing configuration content. JBoss EAP checks out a branch name passed by the --git-branch argument. If that argument is not passed, it checks out the master branch. After initialization, you should see a .git/ directory and a .gitignore file in the base directory for standalone server content.

Using a Remote Git Repository

To use a remote Git repository, start the server with the --git-repo=REMOTE_REPO argument. The value of the argument can be a URL or a remote alias that you have manually added to the local Git configuration.

You can also specify an optional branch or tag name in the remote repository by adding the --git-branch=GIT_BRANCH_NAME argument when you start the server. This argument should name an existing branch or tag name as it will not be created if it does not exist. If you use a tag name, you put the repository in a detached HEAD state, meaning future commits are not attached to any branches.

If your Git repository requires authentication, you must also add the --git-auth=AUTH_FILE_URL argument when you start the server. This argument should be the URL to an Elytron configuration file containing the credentials required to connect to the Git repository. The following is an example of an Elytron configuration file that can be used for authentication.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <authentication-client xmlns="urn:elytron:client:1.2">
    <authentication-rules>
      <rule use-configuration="test-login">
      </rule>
    </authentication-rules>
    <authentication-configurations>
      <configuration name="test-login">
        <sasl-mechanism-selector selector="BASIC" />
        <set-user-name name="eap-user" />
        <credentials>
          <clear-password password="my_api_key" />
        </credentials>
        <set-mechanism-realm name="testRealm" />
      </configuration>
    </authentication-configurations>
  </authentication-client>
</configuration>
Note

Although Git supports SSH authentication, Elytron does not; therefore, it is currently only possible to specify credentials to authenticate with HTTP or HTTPS, not SSH.

The following is an example of a command to start the server with the full profile, using the 1.0.x branch of the remote eap-configuration repository, and passing the URL to an Elytron configuration file containing authentication credentials.

$ EAP_HOME/bin/standalone.sh --git-repo=https://github.com/MY_GIT_ID/eap-configuration.git --git-branch=1.0.x --git-auth=file:///home/USER_NAME/github-wildfly-config.xml --server-config=standalone-full.xml

If you start the server with the argument to use a remote Git repository, JBoss EAP checks whether the jboss.server.base.dir directory is already configured for Git. If not, JBoss EAP deletes the existing configuration files in the jboss.server.base.dir directory and replaces them with the remote Git configuration data. JBoss EAP checks out a branch name passed by the --git-branch argument. If that argument is not passed, it checks out the master branch. Once this process is complete, you should see a .git/ directory and a .gitignore file in the base directory for standalone server content.

Warning

If you later start the server passing a different --git-repo URL or --git-branch name than was originally used, you will see the error message java.lang.RuntimeException: WFLYSRV0268: Failed to pull the repository GIT_REPO_NAME when you attempt to start the server. This is because JBoss EAP attempts to pull configuration data from a different repository and branch than the one that is currently configured in the jboss.server.base.dir directory and the Git pull results in conflicts.

Publishing Remote Configuration Data When Using Git

You can push your Git repository changes to the remote repository using the management CLI publish-configuration operation. Because JBoss EAP pulls the configuration from the remote Git repository during the boot process when you start the server, this allows you to share the configuration data across multiple servers. You can only use this operation with a remote repository. It does not work for a local repository.

The following management CLI operation publishes the configuration data to the remote eap-configuration repository.

:publish-configuration(location="=https://github.com/MY_GIT_ID/eap-configuration.git")
{"outcome" => "success"}
Using Snapshots with Git

In addition to using the Git commit history to track configuration changes, you can also take snapshots to preserve a configuration at a specific point in time. You can list the snapshots and delete them.

Taking Snapshots When Using Git

Snapshots are stored as tags in Git. You specify the snapshot tag name and commit message as arguments on the take-snapshot operation.

The following management CLI operation takes a snapshot and names the tag "snapshot-01".

:take-snapshot(name="snapshot-01", comment="1st snapshot")
{
    "outcome" => "success",
    "result" => "1st snapshot"
}
Listing Snapshots When Using Git

You can list all of the snapshot tags using the list-snapshots operation.

The following management CLI operation lists the snapshot tags.

:list-snapshots
{
    "outcome" => "success",
    "result" => {
        "directory" => "",
        "names" => [
            "snapshot : 1st snapshot",
            "refs/tags/snapshot-01",
            "snapshot2 : 2nd snapshot",
            "refs/tags/snapshot-02"
        ]
    }
}
Deleting Snapshots When Using Git

You can delete a specific snapshot by passing the tag name on the delete-snapshot operation.

The following management CLI operation deletes the snapshot with the tag name "snapshot-01".

:delete-snapshot(name="snapshot-01")
{"outcome" => "success"}

3.7. File System Paths

JBoss EAP uses logical names for file system paths. Other areas of the configuration can then reference the paths using their logical name, avoiding the need to use absolute paths for each instance and allowing specific host configurations to resolve to universal logical names.

For example, the default logging subsystem configuration declares jboss.server.log.dir as the logical name for the server log directory.

Example: Relative Path Example for the Server Log Directory

<file relative-to="jboss.server.log.dir" path="server.log"/>

JBoss EAP automatically provides a number of standard paths without any need for the user to configure them in a configuration file.

Table 3.5. Standard Paths

PropertyDescription

java.home

The Java installation directory

jboss.controller.temp.dir

A common alias for standalone servers and managed domains. The directory to be used for temporary file storage. Equivalent to jboss.domain.temp.dir in a managed domain, and jboss.server.temp.dir on a standalone server.

jboss.domain.base.dir

The base directory for domain content.

jboss.domain.config.dir

The directory that contains the domain configuration.

jboss.domain.data.dir

The directory that the domain will use for persistent data file storage.

jboss.domain.log.dir

The directory that the domain will use for persistent log file storage.

jboss.domain.temp.dir

The directory that the domain will use for temporary file storage.

jboss.domain.deployment.dir

The directory that the domain will use for storing deployed content.

jboss.domain.servers.dir

The directory that the domain will use for storing outputs of the managed domain instances.

jboss.home.dir

The root directory of the JBoss EAP distribution.

jboss.server.base.dir

The base directory for standalone server content.

jboss.server.config.dir

The directory that contains the standalone server configuration.

jboss.server.data.dir

The directory the standalone server will use for persistent data file storage.

jboss.server.log.dir

The directory the standalone server will use for log file storage.

jboss.server.temp.dir

The directory the standalone server will use for temporary file storage.

jboss.server.deploy.dir

The directory that the standalone server will use for storing deployed content.

user.dir

The user’s current working directory.

user.home

The user home directory.

You can override a standard path or add a custom path.

3.7.1. View File System Paths

Use the following management CLI command to list the file system paths:

ls /path
Note

In a managed domain, you can list the file system paths for a specific server using the following management CLI command:

ls /host=HOST_NAME/server=SERVER_NAME/path

Use the following management CLI command to read the value of a file system path:

/path=PATH_NAME:read-resource
Note

In a managed domain, you can read the value of a file system path for a specific server using the following management CLI command:

/host=HOST_NAME/server=SERVER_NAME/path=PATH_NAME:read-resource

3.7.2. Override a Standard Path

You can override the default locations of the standard paths that begin with jboss.server.* or jboss.domain.*. This can be done in one of two ways:

  • Pass in the command-line argument when you start the server. For example:

    $ EAP_HOME/bin/standalone.sh -Djboss.server.log.dir=/var/log
  • Modify the JAVA_OPTS variable in the server configuration file, either standalone.conf or domain.conf, to contain the new location. For example:

    JAVA_OPTS="$JAVA_OPTS -Djboss.server.log.dir=/var/log"
Overriding a Managed Domain’s Standard Paths

In this example, the objective is to store domain files in the /opt/jboss_eap/domain_data directory, and give each top-level directory a custom name. The default directory grouping, by-server, is used.

  • Log files are to be stored in the all_logs subdirectory
  • Data files are to be stored in the all_data subdirectory
  • Temporary files are to be stored in the all_temp subdirectory
  • Servers' files are to be stored in the all_servers subdirectory

To achieve this configuration, you would override several system properties when starting JBoss EAP.

$ EAP_HOME/bin/domain.sh -Djboss.domain.temp.dir=/opt/jboss_eap/domain_data/all_temp -Djboss.domain.log.dir=/opt/jboss_eap/domain_data/all_logs -Djboss.domain.data.dir=/opt/jboss_eap/domain_data/all_data -Djboss.domain.servers.dir=/opt/jboss_eap/domain_data/all_servers

The resulting path structure will be as follows:

/opt/jboss_eap/domain_data/
               ├── all_data
               ├── all_logs
               ├── all_servers
               │   ├── server-one
               │   │   ├── data
               │   │   ├── log
               │   │   └── tmp
               │   └── server-two
               │       ├── data
               │       ├── log
               │       └── tmp
               └── all_temp

3.7.3. Add a Custom Path

You can add a custom file system path using the management CLI or the management console.

  • From the management CLI, you can add a new path using the following management CLI command.

    /path=my.custom.path:add(path=/my/custom/path)
  • From the management console, you can configure file system paths by navigating to the Configuration tab, selecting Paths, and clicking View. From there, you can add, modify, and remove paths.

You can then use this custom path in your configuration. For example, the below log handler uses a custom path for its relative path.

<subsystem xmlns="urn:jboss:domain:logging:6.0">
  ...
  <periodic-rotating-file-handler name="FILE" autoflush="true">
    <formatter>
      <named-formatter name="PATTERN"/>
    </formatter>
    <file relative-to="my.custom.path" path="server.log"/>
    <suffix value=".yyyy-MM-dd"/>
    <append value="true"/>
  </periodic-rotating-file-handler>
  ...
</subsystem>

3.8. Directory Grouping

In a managed domain, each server’s files are stored in the EAP_HOME/domain directory. You can specify how to organize the subdirectories for servers using the host controller’s directory-grouping attribute. Directories can be grouped either by server or by type. By default, directories are grouped by server.

Directory Grouping by Server

By default, directories are grouped by server. If your administration is server-centric, this configuration is recommended. For example, it allows backups and log file handling to be configured per server instance.

If JBoss EAP is installed using the ZIP installation method, the default directory structure (grouped by server) will be as follows.

EAP_HOME/domain
         └─ servers
            ├── server-one
            │   ├── data
            │   ├── tmp
            │   └── log
            └── server-two
                ├── data
                ├── tmp
                └── log

To group domain directories by server, enter the following management CLI command:

/host=HOST_NAME:write-attribute(name=directory-grouping,value=by-server)

This will update the host controller’s host.xml configuration file:

<servers directory-grouping="by-server">
  <server name="server-one" group="main-server-group"/>
  <server name="server-two" group="main-server-group" auto-start="true">
    <socket-bindings port-offset="150"/>
  </server>
</servers>

Directory Grouping by Type

Instead of grouping directories by server, you can instead group by file type. If your administration is file type-centric, this configuration is recommended. For example, this would allow you to easily back up only data files.

If JBoss EAP is installed using the ZIP installation method and the domain’s files are grouped by type, the directory structure will be as follows.

EAP_HOME/domain
         ├── data
         │   └── servers
         │       ├── server-one
         │       └── server-two
         ├── log
         │   └── servers
         │       ├── server-one
         │       └── server-two
         └── tmp
             └── servers
                 ├── server-one
                 └── server-two

To group domain directories by type, enter the following management CLI command:

/host=HOST_NAME:write-attribute(name=directory-grouping,value=by-type)

This will update the host controller’s host.xml configuration file:

<servers directory-grouping="by-type">
  <server name="server-one" group="main-server-group"/>
  <server name="server-two" group="main-server-group" auto-start="true">
    <socket-bindings port-offset="150"/>
  </server>
</servers>

3.9. System Properties

You can use Java system properties to configure many JBoss EAP options, as well as set any name-value pair for use within the application server.

System properties can be used to override default values in the JBoss EAP configuration. For example, the following XML configuration for the public interface bind address shows that it can be set by the jboss.bind.address system property, but if the system property is not provided, it will default to 127.0.0.1.

<inet-address value="${jboss.bind.address:127.0.0.1}"/>

There are a few ways you can set system properties in JBoss EAP, including:

If you use a JBoss EAP managed domain, system properties can be applied to either the whole domain, a specific server group, a specific host and all its server instances, or just to one specific server instance. As with most other JBoss EAP domain settings, a system property set at a more specific level will override a more abstract one. See the Domain Management chapter for more information.

Passing a System Property to the Startup Script

You can pass a system property to the JBoss EAP startup script by using the -D argument. For example:

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=192.168.1.2

This method of setting the system property is especially useful for JBoss EAP options that need to be set before JBoss EAP starts.

Setting a System Property Using the Management CLI

Using the management CLI, you can set a system property using the following syntax:

/system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE)

For example:

/system-property=jboss.bind.address:add(value=192.168.1.2)

When setting system properties using the management CLI, some JBoss EAP options, including the above example of jboss.bind.address, will only take effect after the next server restart.

For a managed domain, the above example configures a system property for the entire domain, but you can also set or override system properties at more specific levels of the domain configuration.

Setting a System Property Using the Management Console

  • For a standalone JBoss EAP server, you can configure system properties in the management console under the Configuration tab. Select System Properties, and click the View button.
  • For a managed domain:

    • Domain-level system properties can be set in the Configuration tab. Select System Properties, and click the View button.
    • Server group and server-level system properties can be set in the Runtime tab. Select the server group or server you want to configure, click the View button next to the server group or server name, and select the System Properties tab.
    • Host-level system properties can be set in the Runtime tab. Select the host you want to configure, then using the drop-down menu next to the host name, select Properties.

Setting a System Property Using JAVA_OPTS

System properties can also be configured using the JAVA_OPTS environment variable. There are many ways to modify JAVA_OPTS, but JBoss EAP provides a configuration file for setting JAVA_OPTS that is used by the JBoss EAP process.

For a standalone server, this file is EAP_HOME/bin/standalone.conf, or, for a managed domain, it is EAP_HOME/bin/domain.conf. For Microsoft Windows systems these files have a .bat extension.

Note

For an RPM installation, the RPM service configuration file is the preferred location to modify JAVA_OPTS to configure system properties. For more information, see Configure RPM Service Properties.

Add your system property definition to JAVA_OPTS in the relevant configuration file. The examples below demonstrate setting the bind address on a Red Hat Enterprise Linux system.

  • For standalone.conf, add your JAVA_OPTS system property definition at the end of the file. For example:

    ...
    # Set the bind address
    JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address=192.168.1.2"
  • For domain.conf, JAVA_OPTS must be set before the process controller JAVA_OPTS setting. For example:

    ...
    # Set the bind address
    JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address=192.168.1.2"
    
    # The ProcessController process uses its own set of java options
    if [ "x$PROCESS_CONTROLLER_JAVA_OPTS" = "x" ]; then
    ...

3.10. Management Audit Logging

You can enable audit logging for the management interfaces, which will log all operations performed using the management console, management CLI, or custom application that uses the Management API. Audit log entries are stored in JSON format. By default, audit logging is disabled.

You can configure audit logging to output to a file or to a syslog server.

Note

Login and logout events cannot be audited as there is no authenticated session in JBoss EAP. Instead, audit messages are logged when an operation is received from the user.

Standalone Server Audit Logging

Though disabled by default, the default audit logging configuration writes to a file.

<audit-log>
    <formatters>
        <json-formatter name="json-formatter"/>
    </formatters>
    <handlers>
        <file-handler name="file" formatter="json-formatter" path="audit-log.log" relative-to="jboss.server.data.dir"/>
    </handlers>
    <logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="file"/>
        </handlers>
    </logger>
</audit-log>

This configuration can be read using the following management CLI command.

/core-service=management/access=audit:read-resource(recursive=true)

See Enable Audit Logging to enable audit logging for a standalone server.

Managed Domain Audit Logging

Though disabled by default, the default audit logging configuration writes a file for each host and for each server.

<audit-log>
    <formatters>
        <json-formatter name="json-formatter"/>
    </formatters>
    <handlers>
        <file-handler name="host-file" formatter="json-formatter" relative-to="jboss.domain.data.dir" path="audit-log.log"/>
        <file-handler name="server-file" formatter="json-formatter" relative-to="jboss.server.data.dir" path="audit-log.log"/>
    </handlers>
    <logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="host-file"/>
        </handlers>
    </logger>
    <server-logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="server-file"/>
        </handlers>
    </server-logger>
</audit-log>

This configuration can be read using the following management CLI command.

/host=HOST_NAME/core-service=management/access=audit:read-resource(recursive=true)

See Enable Audit Logging to enable audit logging for a managed domain.

3.10.1. Enable Management Audit Logging

JBoss EAP is preconfigured with file handlers for audit logging, though audit logging is disabled by default. The management CLI command to enable audit logging depends on whether you are running as a standalone server or in a managed domain. See Management Audit Logging Attributes for file handler attributes.

The following instructions enable NATIVE and HTTP audit logging. To configure JMX audit logging, see Enable JMX Management Audit Logging.

To set up syslog audit logging, see Send Management Audit Logging to a Syslog Server.

Enable Standalone Server Audit Logging

Audit logging can be enabled using the following command.

/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)

By default, this will write the audit log to EAP_HOME/standalone/data/audit-log.log.

Enable Managed Domain Audit Logging

The default audit logging configuration for a managed domain is preconfigured to write an audit log for each host and each server.

Audit logging for each host can be enabled using the following command.

/host=HOST_NAME/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)

By default, this will write the audit logs to EAP_HOME/domain/data/audit-log.log.

Audit logging for each server can be enabled using the following command.

/host=HOST_NAME/core-service=management/access=audit/server-logger=audit-log:write-attribute(name=enabled,value=true)

By default, this will write the audit logs to EAP_HOME/domain/servers/SERVER_NAME/data/audit-log.log.

3.10.2. Enable JMX Management Audit Logging

JBoss EAP is preconfigured with file handlers for JMX audit logging, though these logs are disabled by default. The management CLI command to enable audit logging depends on whether you are running as a standalone server or a managed domain.

To configure NATIVE or HTTP audit logging, see Enable Management Audit Logging.

Enable Standalone Server JMX Audit Logging

JMX audit logging can be enabled for a standalone server using the following commands.

/subsystem=jmx/configuration=audit-log:add()
/subsystem=jmx/configuration=audit-log/handler=file:add()

This enables JMX audit logging, and then uses the defined file handler to write these logs to EAP_HOME/standalone/data/audit-log.log.

Enable Managed Domain JMX Audit Logging

JMX audit logging can be enabled for each host and profile in a managed domain.

Enable JMX Audit Logging for a Host

  1. Enable audit logging in the host’s jmx subsystem.

    /host=HOST_NAME/subsystem=jmx/configuration=audit-log:add()
  2. Once audit logging for the jmx subsystem has been enabled, a handler can be defined for the host with the following command.

    /host=HOST_NAME/subsystem=jmx/configuration=audit-log/handler=host-file:add()

    By default, this will write the JMX audit logs to EAP_HOME/domain/data/audit-log.log.

Enable JMX Audit Logging for a Profile

  1. Enable audit logging in the profile’s jmx subsystem.

    /profile=PROFILE_NAME/subsystem=jmx/configuration=audit-log:add()
  2. Once audit logging for the jmx subsystem has been enabled, a handler can be defined for the profile with the following command.

    /profile=PROFILE_NAME/subsystem=jmx/configuration=audit-log/handler=server-file:add()

    By default, this will write the JMX audit logs to EAP_HOME/domain/servers/SERVER_NAME/data/audit-log.log.

3.10.3. Send Management Audit Logging to a Syslog Server

A syslog handler specifies the parameters by which audit log entries are sent to a syslog server, specifically the syslog server’s host name and the port on which the syslog server is listening. Sending audit logging to a syslog server provides more security options than logging to a local file or local syslog server. Multiple syslog handlers can be defined and be active at the same time.

By default, audit logging is preconfigured to output to a file when enabled. Use the following steps to set up and enable audit logging to a syslog server. See Management Audit Logging Attributes for syslog handler attributes.

  1. Add a syslog handler.

    Create the syslog handler, specifying the host and port of the syslog server. In a managed domain, you must precede the /core-service commands with /host=HOST_NAME.

    batch
    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME:add(formatter=json-formatter)
    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME/protocol=udp:add(host=HOST_NAME,port=PORT)
    run-batch
    Note

    The parameters to pass in differ depending on the protocol specified.

    To configure the handler to use TLS to communicate securely with the syslog server, you must also configure the authentication, for example:

    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME/protocol=tls/authentication=truststore:add(keystore-path=PATH_TO_TRUSTSTORE,keystore-password=TRUSTSTORE_PASSWORD)
  2. Add a reference to the syslog handler.

    In a managed domain, you must precede this command with /host=HOST_NAME.

    /core-service=management/access=audit/logger=audit-log/handler=SYSLOG_HANDLER_NAME:add
  3. Enable audit logging.

    See Enable Management Audit Logging to enable audit logging.

Important

Enabling audit logging to a syslog server in JBoss EAP will not work unless logging is enabled in the operating system as well.

For more information on rsyslog configurations on Red Hat Enterprise Linux, see the Basic Configuration of Rsyslog section of the System Administrator’s Guide for Red Hat Enterprise Linux at https://access.redhat.com/documentation/en/red-hat-enterprise-linux/.

3.10.4. Read Audit Log Entries

Audit log entries output to files are best viewed with a text viewer, while those output to a syslog server are best viewed using a syslog viewer application.

Note

Using a text editor for viewing log files is not recommended as some may prevent further log entries being written to the log file.

The audit log entries are stored in JSON format. Each log entry begins with an optional timestamp, followed by the fields in the below table.

Table 3.6. Management Audit Log Fields

Field NameDescription

access

This can have one of the following values:

  • NATIVE - The operation came in through the native management interface.
  • HTTP - The operation came in through the domain HTTP interface.
  • JMX - The operation came in through the jmx subsystem.

booting

Has the value true if the operation was executed during the bootup process, or false if it was executed once the server is up and running.

domainUUID

An ID to link together all operations as they are propagated from the domain controller to its servers, slave host controllers, and slave host controller servers.

ops

The operations being executed. This is a list of the operations serialized to JSON. At boot, this is the operations resulting from parsing the XML. Once booted, the list typically contains a single entry.

r/o

Has the value true if the operation does not change the management model, or false if it does.

remote-address

The address of the client executing this operation.

success

Has the value true if the operation was successful, or false if it was rolled back.

type

This can have the value core, meaning it is a management operation, or jmx, meaning it comes from the jmx subsystem.

user

The username of the authenticated user. If the operation occurred using the management CLI on the same machine as the running server, the special user $local is used.

version

The version number of the JBoss EAP instance.

3.11. Server Lifecycle Event Notifications

You can set up notifications for server lifecycle events using the JBoss EAP core-management subsystem or JMX. A change in server runtime configuration state or server running state will trigger a notification.

The server runtime configuration states for JBoss EAP are STARTING, RUNNING, RELOAD_REQUIRED, RESTART_REQUIRED, STOPPING, and STOPPED.

The server running states for JBoss EAP are STARTING, NORMAL, ADMIN_ONLY, PRE_SUSPEND, SUSPENDING, SUSPENDED, STOPPING, and STOPPED.

3.11.1. Monitor Server Lifecycle Events Using the Core Management Subsystem

You can register a listener to the JBoss EAP core-management subsystem to monitor for server lifecycle events. The following steps show how to create and register an example listener that logs the events to a file.

  1. Create the listener.

    Create an implementation of org.wildfly.extension.core.management.client.ProcessStateListener, like the example below.

    Example: Listener Class

    package org.simple.lifecycle.events.listener;
    
    import java.io.File;
    import java.io.FileWriter;
    import java.io.IOException;
    
    import org.wildfly.extension.core.management.client.ProcessStateListener;
    import org.wildfly.extension.core.management.client.ProcessStateListenerInitParameters;
    import org.wildfly.extension.core.management.client.RunningStateChangeEvent;
    import org.wildfly.extension.core.management.client.RuntimeConfigurationStateChangeEvent;
    
    public class SimpleListener implements ProcessStateListener {
    
        private File file;
        private FileWriter fileWriter;
        private ProcessStateListenerInitParameters parameters;
    
        public void init(ProcessStateListenerInitParameters parameters) {
            this.parameters = parameters;
            this.file = new File(parameters.getInitProperties().get("file"));
            try {
                fileWriter = new FileWriter(file, true);
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    
        public void cleanup() {
            try {
                fileWriter.close();
            } catch (IOException e) {
                e.printStackTrace();
            } finally {
                fileWriter = null;
            }
        }
    
        public void runtimeConfigurationStateChanged(RuntimeConfigurationStateChangeEvent evt) {
            try {
                fileWriter.write(String.format("Runtime configuration state change for %s: %s to %s\n", parameters.getProcessType(), evt.getOldState(), evt.getNewState()));
                fileWriter.flush();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    
        public void runningStateChanged(RunningStateChangeEvent evt) {
            try {
                fileWriter.write(String.format("Running state change for %s: %s to %s\n", parameters.getProcessType(), evt.getOldState(), evt.getNewState()));
                fileWriter.flush();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    }

    Note

    Keep the following in mind when implementing the listener.

    • In the event of a server reload, listeners stop listening while the server attempts to stop, and the listeners are reloaded when the server starts. Because of this, implementations must ensure that they can be loaded, initialized, and removed properly several times inside the same JVM.
    • Notifications to the listeners are blocking to allow reactions to server state changes. Implementations must ensure that they do not block or deadlock.
    • Each listener instance is executed in its own thread and the order is not guaranteed.
  2. Compile the class and package it into a JAR.

    Note that to compile, you need to depend on the org.wildfly.core:wildfly-core-management-client Maven module.

  3. Add the JAR as a JBoss EAP module.

    Use the following management CLI command and provide the module name and path to the JAR.

    module add --name=org.simple.lifecycle.events.listener --dependencies=org.wildfly.extension.core-management-client --resources=/path/to/simple-listener-0.0.1-SNAPSHOT.jar
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  4. Register the listener.

    Add the listener to the core-management subsystem using the following management CLI command. Specify the class, module, and file location to log the server lifecycle events.

    /subsystem=core-management/process-state-listener=my-simple-listener:add(class=org.simple.lifecycle.events.listener.SimpleListener, module=org.simple.lifecycle.events.listener,properties={file=/path/to/my-listener-output.txt})

Now, server lifecycle events will be logged to the my-listener-output.txt file based on the SimpleListener class above. For example, issuing a :suspend command in the management CLI will output the following to the my-listener-output.txt file.

Running state change for STANDALONE_SERVER: normal to suspending
Running state change for STANDALONE_SERVER: suspending to suspended

This shows that the running state changed from normal to suspending, and then from suspending to suspended.

3.11.2. Monitor Server Lifecycle Events Using JMX Notifications

You can register a JMX notification listener to monitor for server lifecycle events. The following steps show how to create and add an example listener that logs events to a file.

  1. Create the listener.

    Create an implementation of javax.management.NotificationListener, like the example below.

    Example: Listener Class

    import java.io.BufferedWriter;
    import java.io.IOException;
    import java.nio.charset.StandardCharsets;
    import java.nio.file.Files;
    import java.nio.file.Path;
    import java.nio.file.Paths;
    import java.nio.file.StandardOpenOption;
    
    import javax.management.AttributeChangeNotification;
    import javax.management.Notification;
    import javax.management.NotificationListener;
    
    import org.jboss.logging.Logger;
    
    public class StateNotificationListener implements NotificationListener {
    
      public static final String RUNTIME_CONFIGURATION_FILENAME = "runtime-configuration-notifications.txt";
      public static final String RUNNING_FILENAME = "running-notifications.txt";
      private final Path targetFile;
    
      public StateNotificationListener() {
        this.targetFile = Paths.get("notifications/data").toAbsolutePath();
        init(targetFile);
      }
    
      protected Path getRuntimeConfigurationTargetFile() {
        return this.targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME);
      }
    
      protected Path getRunningConfigurationTargetFile() {
        return this.targetFile.resolve(RUNNING_FILENAME);
      }
    
      protected final void init(Path targetFile) {
        try {
          Files.createDirectories(targetFile);
    
          if (!Files.exists(targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME))) {
            Files.createFile(targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME));
          }
    
          if (!Files.exists(targetFile.resolve(RUNNING_FILENAME))) {
            Files.createFile(targetFile.resolve(RUNNING_FILENAME));
          }
        } catch (IOException ex) {
            Logger.getLogger(StateNotificationListener.class).error("Problem handling JMX Notification", ex);
        }
      }
    
      @Override
      public void handleNotification(Notification notification, Object handback) {
        AttributeChangeNotification attributeChangeNotification = (AttributeChangeNotification) notification;
        if ("RuntimeConfigurationState".equals(attributeChangeNotification.getAttributeName())) {
          writeNotification(attributeChangeNotification, getRuntimeConfigurationTargetFile());
        } else {
          writeNotification(attributeChangeNotification, getRunningConfigurationTargetFile());
        }
      }
    
      private void writeNotification(AttributeChangeNotification notification, Path path) {
        try (BufferedWriter in = Files.newBufferedWriter(path, StandardCharsets.UTF_8, StandardOpenOption.APPEND)) {
          in.write(String.format("%s %s %s %s", notification.getType(), notification.getSequenceNumber(), notification.getSource().toString(), notification.getMessage()));
          in.newLine();
          in.flush();
        } catch (IOException ex) {
          Logger.getLogger(StateNotificationListener.class).error("Problem handling JMX Notification", ex);
        }
      }
    }

  2. Register the notification listener.

    Add the notification listener to the MBeanServer.

    Example: Add a Notification Listener

    MBeanServer server = ManagementFactory.getPlatformMBeanServer();
    server.addNotificationListener(ObjectName.getInstance("jboss.root:type=state"), new StateNotificationListener(), null, null);

  3. Package and deploy to JBoss EAP.

Server lifecycle events are now logged to a file based on the StateNotificationListener class above. For example, issuing a :suspend command in the management CLI outputs the following to the running-notifications.txt file.

jmx.attribute.change 5 jboss.root:type=state The attribute 'RunningState' has changed from 'normal' to 'suspending'
jmx.attribute.change 6 jboss.root:type=state The attribute 'RunningState' has changed from 'suspending' to 'suspended'

This shows that the running state changed from normal to suspending, and then from suspending to suspended.

Chapter 4. Network and Port Configuration

4.1. Interfaces

JBoss EAP references named interfaces throughout the configuration. This allows the configuration to reference individual interface declarations with logical names, rather than requiring the full details of the interface at each use.

This also allows for easier configuration in a managed domain, where network interface details can vary across multiple machines. Each server instance can correspond to a logical name group.

The standalone.xml, domain.xml, and host.xml files all include interface declarations. There are several preconfigured interface names, depending on which default configuration is used. The management interface can be used for all components and services that require the management layer, including the HTTP management endpoint. The public interface can be used for all application-related network communications. The unsecure interface is used for IIOP sockets in the standard configuration. The private interface is used for JGroups sockets in the standard configuration.

4.1.1. Default Interface Configurations

<interfaces>
  <interface name="management">
    <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
  </interface>
  <interface name="public">
    <inet-address value="${jboss.bind.address:127.0.0.1}"/>
  </interface>
  <interface name="private">
    <inet-address value="${jboss.bind.address.private:127.0.0.1}"/>
  </interface>
  <interface name="unsecure">
    <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"/>
  </interface>
</interfaces>

By default, JBoss EAP binds these interfaces to 127.0.0.1, but these values can be overridden at runtime by setting the appropriate property. For example, the inet-address of the public interface can be set when starting JBoss EAP as a standalone server with the following command.

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=IP_ADDRESS

Alternatively, you can use the -b switch on the server start command line. For more information about server start options, see Server Runtime Arguments.

Important

If you modify the default network interfaces or ports that JBoss EAP uses, you must also remember to change any scripts that use the modified interfaces or ports. These include JBoss EAP service scripts, as well as remembering to specify the correct interface and port when accessing the management console or management CLI.

4.1.2. Configuring Interfaces

Network interfaces are declared by specifying a logical name and selection criteria for the physical interface. The selection criteria can reference a wildcard address or specify a set of one or more characteristics that an interface or address must have in order to be a valid match. For a listing of all available interface selection criteria, see the Interface Attributes section.

Interfaces can be configured using the management console or the management CLI. Below are several examples of adding and updating interfaces. The management CLI command is shown first, followed by the corresponding configuration XML.

Add an Interface with a NIC Value

Add a new interface with a NIC value of eth0.

/interface=external:add(nic=eth0)
<interface name="external">
   <nic name="eth0"/>
</interface>
Add an Interface with Several Conditional Values

Add a new interface that matches any interface/address on the correct subnet if it is up, supports multicast, and is not point-to-point.

/interface=default:add(subnet-match=192.168.0.0/16,up=true,multicast=true,not={point-to-point=true})
<interface name="default">
   <subnet-match value="192.168.0.0/16"/>
   <up/>
   <multicast/>
   <not>
      <point-to-point/>
   </not>
</interface>
Update an Interface Attribute

Update the public interface’s default inet-address value, keeping the jboss.bind.address property to allow for this value to be set at runtime.

/interface=public:write-attribute(name=inet-address,value="${jboss.bind.address:192.168.0.0}")
<interface name="public">
    <inet-address value="${jboss.bind.address:192.168.0.0}"/>
</interface>
Add an Interface to a Server in a Managed Domain
/host=HOST_NAME/server-config=SERVER_NAME/interface=INTERFACE_NAME:add(inet-address=127.0.0.1)
<servers>
   <server name="SERVER_NAME" group="main-server-group">
      <interfaces>
         <interface name="INTERFACE_NAME">
            <inet-address value="127.0.0.1"/>
         </interface>
      </interfaces>
   </server>
</servers>

4.2. Socket Bindings

Socket bindings and socket binding groups allow you to define network ports and their relationship to the networking interfaces required for your JBoss EAP configuration. A socket binding is a named configuration for a socket. A socket binding group is a collection of socket binding declarations that are grouped under a logical name.

This allows other sections of the configuration to reference socket bindings by their logical name, rather than requiring the full details of the socket configuration at each use.

The declarations for these named configurations can be found in the standalone.xml and domain.xml configuration files. A standalone server contains only one socket binding group, while a managed domain can contain multiple groups. You can create a socket binding group for each server group in the managed domain, or share a socket binding group between multiple server groups.

The ports JBoss EAP uses by default depend on which socket binding groups are used and the requirements of your individual deployments.

There are three types of socket bindings that can be defined in a socket binding group in the JBoss EAP configuration:

Inbound Socket Bindings

The socket-binding element is used to configure inbound socket bindings for the JBoss EAP server. The default JBoss EAP configurations provide several preconfigured socket-binding elements, for example, for HTTP and HTTPS traffic. Another example can be found in the Broadcast Groups section of Configuring Messaging for JBoss EAP.

Attributes for this element can be found in the Inbound Socket Binding Attributes table.

Remote Outbound Socket Bindings

The remote-destination-outbound-socket-binding element is used to configure outbound socket bindings for destinations that are remote to the JBoss EAP server. The default JBoss EAP configurations provide an example remote destination socket binding that can be used for a mail server. Another example can be found in the Using the Integrated Artemis Resource Adapter for Remote Connections section of Configuring Messaging for JBoss EAP.

Attributes for this element can be found in the Remote Outbound Socket Binding Attributes table.

Local Outbound Socket Bindings

The local-destination-outbound-socket-binding element is used to configure outbound socket bindings for destinations that are local to the JBoss EAP server. This type of socket binding is not expected to be commonly used.

Attributes for this element can be found in the Local Outbound Socket Binding Attributes table.

4.2.1. Management Ports

Management ports were consolidated in JBoss EAP 7. By default, JBoss EAP 7 uses port 9990 for both native management, used by the management CLI, and HTTP management, used by the web-based management console. Port 9999, which was used as the native management port in JBoss EAP 6, is no longer used but can still be enabled if desired.

If HTTPS is enabled for the management console, then port 9993 is used by default.

4.2.2. Default Socket Bindings

JBoss EAP ships with a socket binding group for each of the five predefined profiles (default, ha, full, full-ha, load-balancer).

For detailed information about the default socket bindings, such as default ports and descriptions, see the Default Socket Bindings section.

Important

If you modify the default network interfaces or ports that JBoss EAP uses, you must also remember to change any scripts that use the modified interfaces or ports. These include JBoss EAP service scripts, as well as remembering to specify the correct interface and port when accessing the management console or management CLI.

Standalone Server

When running as a standalone server, only one socket binding group is defined per configuration file. Each standalone configuration file (standalone.xml, standalone-ha.xml, standalone-full.xml, standalone-full-ha.xml, standalone-load-balancer.xml) defines socket bindings for the technologies used by its corresponding profile.

For example, the default standalone configuration file (standalone.xml) specifies the below socket bindings.

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
    <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/>
    <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9993}"/>
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
        <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
</socket-binding-group>
Managed Domain

When running in a managed domain, all socket binding groups are defined in the domain.xml file. There are five predefined socket binding groups:

  • standard-sockets
  • ha-sockets
  • full-sockets
  • full-ha-sockets
  • load-balancer-sockets

Each socket binding group specifies socket bindings for the technologies used by its corresponding profile. For example, the full-ha-sockets socket binding group defines several jgroups socket bindings, which are used by the full-ha profile for high availability.

<socket-binding-groups>
  <socket-binding-group name="standard-sockets" default-interface="public">
    <!-- Needed for server groups using the 'default' profile  -->
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
      <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
  </socket-binding-group>
  <socket-binding-group name="ha-sockets" default-interface="public">
    <!-- Needed for server groups using the 'ha' profile  -->
    ...
  </socket-binding-group>
  <socket-binding-group name="full-sockets" default-interface="public">
    <!-- Needed for server groups using the 'full' profile  -->
    ...
  </socket-binding-group>
  <socket-binding-group name="full-ha-sockets" default-interface="public">
    <!-- Needed for server groups using the 'full-ha' profile  -->
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="iiop" interface="unsecure" port="3528"/>
    <socket-binding name="iiop-ssl" interface="unsecure" port="3529"/>
    <socket-binding name="jgroups-mping" interface="private" port="0" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45700"/>
    <socket-binding name="jgroups-tcp" interface="private" port="7600"/>
    <socket-binding name="jgroups-udp" interface="private" port="55200" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45688"/>
    <socket-binding name="modcluster" port="0" multicast-address="224.0.1.105" multicast-port="23364"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
      <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
  </socket-binding-group>
  <socket-binding-group name="load-balancer-sockets" default-interface="public">
    <!-- Needed for server groups using the 'load-balancer' profile  -->
    ...
  </socket-binding-group>
</socket-binding-groups>
Note

The socket configuration for the management interfaces is defined in the domain controller’s host.xml file.

4.2.3. Configuring Socket Bindings

When defining a socket binding, you can configure the port and interface attributes, as well as multicast settings such as multicast-address and multicast-port. For details on all available socket bindings attributes, see the Socket Binding Attributes section.

Socket bindings can be configured using the management console or the management CLI. The following steps go through adding a socket binding group, adding a socket binding, and configuring socket binding settings using the management CLI.

  1. Add a new socket binding group. Note that this step cannot be performed when running as a standalone server.

    /socket-binding-group=new-sockets:add(default-interface=public)
  2. Add a socket binding.

    /socket-binding-group=new-sockets/socket-binding=new-socket-binding:add(port=1234)
  3. Change the socket binding to use an interface other than the default, which is set by the socket binding group.

    /socket-binding-group=new-sockets/socket-binding=new-socket-binding:write-attribute(name=interface,value=unsecure)

The following example shows how the XML configuration may look after the above steps have been completed.

<socket-binding-groups>
    ...
    <socket-binding-group name="new-sockets" default-interface="public">
        <socket-binding name="new-socket-binding" interface="unsecure" port="1234"/>
    </socket-binding-group>
</socket-binding-groups>

4.2.4. Viewing Socket Bindings and Open Ports for a Server

You can view the socket binding name and the open ports for a server from the management console. The information is visible when the server is in the following states:

  • running
  • reload-required
  • restart-required

To view the socket bindings and the open ports for a server:

  1. Access the management console and navigate to Runtime.
  2. Click the server to view the socket binding name and the open ports in the right pane.

4.2.5. Port Offsets

A port offset is a numeric offset value added to all port values specified in the socket binding group for that server. This allows the server to inherit the port values defined in its socket binding group, with an offset to ensure that it does not conflict with any other servers on the same host. For instance, if the HTTP port of the socket binding group is 8080, and a server uses a port offset of 100, then its HTTP port is 8180.

Below is an example of setting a port offset of 250 for a server in a managed domain using the management CLI.

/host=master/server-config=server-two/:write-attribute(name=socket-binding-port-offset,value=250)

Port offsets can be used for servers in a managed domain and for running multiple standalone servers on the same host.

You can pass in a port offset when starting a standalone server using the jboss.socket.binding.port-offset property.

$ EAP_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=100

4.3. IPv6 Addresses

By default, JBoss EAP is configured to run using IPv4 addresses. The steps below show how to configure JBoss EAP to run using IPv6 addresses.

Configure the JVM Stack for IPv6 Addresses

Update the startup configuration to prefer IPv6 addresses.

  1. Open the startup configuration file.

    • When running as a standalone server, edit the EAP_HOME/bin/standalone.conf file (or standalone.conf.bat for Windows Server).
    • When running in a managed domain, edit the EAP_HOME/bin/domain.conf file (or domain.conf.bat for Windows Server).
  2. Set the java.net.preferIPv4Stack property to false.

    -Djava.net.preferIPv4Stack=false
  3. Append the java.net.preferIPv6Addresses property and set it to true.

    -Djava.net.preferIPv6Addresses=true

The following example shows how the JVM options in the startup configuration file may look after making the above changes.

# Specify options to pass to the Java VM.
#
if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS="-Xms1303m -Xmx1303m -Djava.net.preferIPv4Stack=false"
   JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"
   JAVA_OPTS="$JAVA_OPTS -Djava.net.preferIPv6Addresses=true"
else

Update Interface Declarations for IPv6 Addresses

The default interface values in the configuration can be changed to IPv6 addresses. For example, the below management CLI command sets the management interface to the IPv6 loopback address (::1).

/interface=management:write-attribute(name=inet-address,value="${jboss.bind.address.management:[::1]}")

The following example shows how the XML configuration may look after running the above command.

<interfaces>
    <interface name="management">
        <inet-address value="${jboss.bind.address.management:[::1]}"/>
    </interface>
    ....
</interfaces>

Chapter 5. JBoss EAP Security

JBoss EAP offers the ability to configure security for its own interfaces and services as well as provide security for applications that are running on it.

Chapter 6. JBoss EAP Class Loading

JBoss EAP uses a modular class loading system for controlling the class paths of deployed applications. This system provides more flexibility and control than the traditional system of hierarchical class loaders. Developers have fine-grained control of the classes available to their applications, and can configure a deployment to ignore classes provided by the application server in favor of their own.

The modular class loader separates all Java classes into logical groups called modules. Each module can define dependencies on other modules in order to have the classes from that module added to its own class path. Because each deployed JAR and WAR file is treated as a module, developers can control the contents of their application’s class path by adding module configuration to their application.

6.1. Modules

A module is a logical grouping of classes used for class loading and dependency management. JBoss EAP identifies two different types of modules: static and dynamic. The main difference between the two is how they are packaged.

Static Modules

Static modules are defined in the EAP_HOME/modules/ directory of the application server. Each module exists as a subdirectory, for example, EAP_HOME/modules/com/mysql/. Each module directory then contains a slot subdirectory, which defaults to main and contains the module.xml configuration file and any required JAR files. All the application server-provided APIs are provided as static modules, including the Jakarta EE APIs as well as other APIs.

Example: MySQL JDBC Driver module.xml File

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-8.0.12.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

The module name, com.mysql, must match the directory structure for the module, excluding the slot name, main.

Creating custom static modules can be useful if many applications are deployed on the same server that use the same third-party libraries. Instead of bundling those libraries with each application, a module containing these libraries can be created and installed by an administrator. The applications can then declare an explicit dependency on the custom static modules.

The modules provided in JBoss EAP distributions are located in the system directory within the EAP_HOME/modules directory. This keeps them separate from any modules provided by third parties. Any Red Hat provided products that layer on top of JBoss EAP also install their modules within the system directory.

Users must ensure that custom modules are installed into the EAP_HOME/modules directory, using one directory per module. This ensures that custom versions of modules that already exist in the system directory are loaded instead of the shipped versions. In this way, user-provided modules will take precedence over system modules.

If you use the JBOSS_MODULEPATH environment variable to change the locations in which JBoss EAP searches for modules, then the product will look for a system subdirectory structure within one of the locations specified. A system structure must exist somewhere in the locations specified with JBOSS_MODULEPATH.

Note

Starting with JBoss EAP 7.1, the use of absolute paths in the resource-root path element of the module.xml file is also supported. This way, your resource libraries can be made accessible without needing to move them to the EAP_HOME/modules directory.

Example: Absolute Path in the module.xml File

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="oracle.jdbc">
    <resources>
        <resource-root path="/home/redhat/test.jar"/>
    </resources>
</module>

Dynamic Modules

Dynamic modules are created and loaded by the application server for each JAR or WAR deployment, or for each subdeployment in an EAR. The name of a dynamic module is derived from the name of the deployed archive. Because deployments are loaded as modules, they can configure dependencies and be used as dependencies by other deployments.

Modules are only loaded when required. This usually only occurs when an application is deployed that has explicit or implicit dependencies.

Predefined Modules

Starting with JBoss EAP 7.2, a set of predefined modules is available to you when you use the default module loader. The special module, org.jboss.modules, which includes all of the JBoss Modules API, is always available and is provided by JBoss Modules. The standard Java Platform Module System (JPMS) modules, which are provided in Java 9 and later, are also available by their standard names. When using JDK 8, the JDK 9 modules are emulated by JBoss Modules.

For a list of platform modules available on Java 9 or later, see the appropriate JDK documentation.

For the list the platform modules provided for Java 8, see Platform Modules Provided for Java 8.

6.2. Module Dependencies

A module dependency is a declaration that one module requires the classes of one or more other modules in order to function. When JBoss EAP loads a module, the modular class loader parses the dependencies of that module and adds the classes from each dependency to its class path. If a specified dependency cannot be found, the module will fail to load.

Note

See the Modules section for complete details about modules and the modular class loading system.

Deployed applications, such as a JAR or WAR, are loaded as dynamic modules and make use of dependencies to access the APIs provided by JBoss EAP.

There are two types of dependencies: explicit and implicit.

Explicit Dependencies
Explicit dependencies are declared by the developer in a configuration file. A static module can declare dependencies in its module.xml file. A dynamic module can declare dependencies in the deployment’s MANIFEST.MF or jboss-deployment-structure.xml deployment descriptor.
Implicit Dependencies

Implicit dependencies are added automatically by JBoss EAP when certain conditions or meta-data are found in a deployment. The Jakarta EE APIs supplied with JBoss EAP are examples of modules that are added by detection of implicit dependencies in deployments.

Deployments can also be configured to exclude specific implicit dependencies by using the jboss-deployment-structure.xml deployment descriptor file. This can be useful when an application bundles a specific version of a library that JBoss EAP will attempt to add as an implicit dependency.

Optional Dependencies

Explicit dependencies can be specified as optional. Failure to load an optional dependency will not cause a module to fail to load. However, if the dependency becomes available later it will not be added to the module’s class path. Dependencies must be available when the module is loaded.

Export a Dependency

A module’s class path contains only its own classes and that of its immediate dependencies. A module is not able to access the classes of the dependencies of one of its dependencies. However, a module can specify that an explicit dependency is exported. An exported dependency is provided to any module that depends on the module that exports it.

For example, Module A depends on Module B, and Module B depends on Module C. Module A can access the classes of Module B, and Module B can access the classes of Module C. Module A cannot access the classes of Module C unless:

  • Module A declares an explicit dependency on Module C, or
  • Module B exports its dependency on Module C.

Global Modules

A global module is a module that JBoss EAP provides as a dependency to every application. Any module can be made global by adding it to JBoss EAP’s list of global modules. It does not require changes to the module.

See the Define Global Modules section for details.

6.3. Create a Custom Module

Custom static modules can be added to make resources available for deployments running on JBoss EAP. You can create the module manually or by using the management CLI.

Once you create the module, you must add the module as a dependency if its resources need to be made available to applications.

Create a Custom Module Manually

You can create a custom module manually using the following steps.

  1. Create the appropriate directory structure in the EAP_HOME/modules/ directory.

    Example: Create MySQL JDBC Driver Directory Structure

    $ cd EAP_HOME/modules/
    $ mkdir -p com/mysql/main

  2. Copy the JAR files or other necessary resources to the main/ subdirectory.

    Example: Copy MySQL JDBC Driver JAR

    $ cp /path/to/mysql-connector-java-8.0.12.jar EAP_HOME/modules/com/mysql/main/

  3. Create a module.xml file in the main/ subdirectory, specifying the appropriate resources and dependencies in the file.

    Example: MySQL JDBC Driver module.xml File

    <?xml version="1.0" ?>
    <module xmlns="urn:jboss:module:1.1" name="com.mysql">
      <resources>
        <resource-root path="mysql-connector-java-8.0.12.jar"/>
      </resources>
      <dependencies>
        <module name="javaee.api"/>
        <module name="sun.jdk"/>
        <module name="ibm.jdk"/>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
      </dependencies>
    </module>

Create a Custom Module Using the Management CLI

You can create a custom module using the module add management CLI command.

Important

Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  1. Start the JBoss EAP server.
  2. Launch the management CLI.

    $ EAP_HOME/bin/jboss-cli.sh
  3. Use the module add management CLI command to add the new core module.

    module add --name=MODULE_NAME --resources=PATH_TO_RESOURCE --dependencies=DEPENDENCIES

    Example: Create a MySQL Module

    module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api

    See Module Command Arguments for the available arguments to customize this command, such as providing your own module.xml file, using an external module directory, or specifying an alternative slot for the module. You can also execute module --help for more details on using this command to add and remove modules.

Add the Module as a Dependency

In order for your application to be able to access this module’s resources, you must add the module as a dependency.

  • See the Define Global Modules section for instructions on adding modules as dependencies to all applications.

As an example, the following steps add a JAR file containing several properties files as a module and define a global module, so that an application can then load these properties.

  1. Add the JAR file as a core module.

    module add --name=myprops --resources=/path/to/properties.jar
  2. Define this module as a global module so that it is made available to all deployments.

    /subsystem=ee:list-add(name=global-modules,value={name=myprops})
  3. The application can then retrieve the properties from one of the properties files contained within the JAR.

    Thread.currentThread().getContextClassLoader().getResource("my.properties");

6.4. Remove a Custom Module

Custom static modules can be removed manually or by using the management CLI.

Remove a Custom Module Manually

Before manually removing a module, ensure that it is not required by deployed applications or elsewhere in the server configuration, such as by a datasource.

To remove a custom module, remove the module’s directory under EAP_HOME/modules/, which includes its module.xml file and associated JAR files or other resources. For example, remove the EAP_HOME/modules/com/mysql/main/ directory to remove a custom MySQL JDBC driver module in the main slot.

Remove a Custom Module Using the Management CLI

You can remove a custom module using the module remove management CLI command.

Important

Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  1. Start the JBoss EAP server.
  2. Launch the management CLI.

    $ EAP_HOME/bin/jboss-cli.sh
  3. Use the module remove management CLI command to remove the custom module.

    module remove --name=MODULE_NAME
    • Use the --slot argument if the module to remove is in a slot other than main.

    Example: Remove a MySQL Module

    module remove --name=com.mysql

Execute module --help for more details on using this command to add and remove modules.

6.5. Define Global Modules

A list of global modules can be defined for JBoss EAP, which will add the modules as dependencies to all deployments.

Note

You must know the name of the modules that are to be configured as global modules. For the complete listing of the included modules and whether they are supported, see Red Hat JBoss Enterprise Application Platform 7 Included Modules on the Red Hat Customer Portal. See the Dynamic Module Naming section for naming conventions for modules in deployments.

Use the following management CLI command to define the list of global modules.

/subsystem=ee:write-attribute(name=global-modules,value=[{name=MODULE_NAME_1},{name=MODULE_NAME_2}]

Use the following management CLI command to add a single module to the list of existing global modules.

/subsystem=ee:list-add(name=global-modules,value={name=MODULE_NAME})

Global modules can also be added and removed using the management console by navigating to the EE subsystem from the Configuration tab and selecting the Global Modules section.

If you want a global module to be accessible by external dependencies, you must explicitly make it available. The following options are available to make the services in a global module available externally.

  • Add services="import" to the module in your jboss-deployment-structure.xml
  • Add services="true" to the global module definition.

    /subsystem=ee:write-attribute(name=global-modules,value=[{name=module1,services=true}]

    Or, when adding multiple modules:

    /subsystem=ee:write-attribute(name=global-modules,value=[{name=module1,services=true},{name=module2,services=false}]

    To add a new module to an existing list:

    /subsystem=ee:list-add(name=global-modules,value={name=module1,services=true})
  • When defining the global module using the management console, make sure that the value of the Services property is On.

6.6. Configure Subdeployment Isolation

Each subdeployment in an Enterprise Archive (EAR) is a dynamic module with its own class loader. Subdeployments always have an implicit dependency on the parent module, which gives them access to classes in EAR/lib. By default, a subdeployment can access the resources of other subdeployments within that EAR.

If you do not want a subdeployment to be allowed to access classes belonging to other subdeployments, then strict subdeployment isolation can be enabled in JBoss EAP. This setting will affect all deployments.

Enable Subdeployment Module Isolation for All Deployments

Subdeployment isolation can be enabled or disabled using the management console or the management CLI from the ee subsystem. By default, subdeployment isolation is set to false, which allows the subdeployments to access resources of other subdeployments within an EAR deployment.

Use the following management CLI to enable EAR subdeployment isolation.

/subsystem=ee:write-attribute(name=ear-subdeployments-isolated,value=true)

Subdeployments in an EAR will no longer be able to access resources from other subdeployments.

6.7. Define an External JBoss EAP Module Directory

The default directory for JBoss EAP modules is EAP_HOME/modules. You can specify a different directory for JBoss EAP modules using the JBOSS_MODULEPATH variable. Follow the below steps to set this variable in the JBoss EAP startup configuration file.

Note

You can also set JBOSS_MODULEPATH as an environment variable instead of setting this in the JBoss EAP startup configuration files.

  1. Edit the startup configuration file.

    • When running as a standalone server, edit the EAP_HOME/bin/standalone.conf file, or standalone.conf.bat for Windows Server.
    • When running in a managed domain, edit the EAP_HOME/bin/domain.conf file, or domain.conf.bat for Windows Server.
  2. Set the JBOSS_MODULEPATH variable, for example:

    JBOSS_MODULEPATH="/path/to/modules/directory/"

    To specify a list of directories use a colon (:) to delimit the list of directories.

    Note

    For Windows Server, use the following syntax to set the JBOSS_MODULEPATH variable:

    set "JBOSS_MODULEPATH /path/to/modules/directory/"

    To specify a list of directories use a semicolon (;) to delimit the list of directories.

6.8. Dynamic Module Naming Conventions

JBoss EAP loads all deployments as modules, which are named according to the following conventions.

  • Deployments of WAR and JAR files are named using the following format:

    deployment.DEPLOYMENT_NAME

    For example, inventory.war and store.jar will have the module names of deployment.inventory.war and deployment.store.jar respectively.

  • Subdeployments within an Enterprise Archive (EAR) are named using the following format:

    deployment.EAR_NAME.SUBDEPLOYMENT_NAME

    For example, the subdeployment of reports.war within the enterprise archive accounts.ear will have the module name of deployment.accounts.ear.reports.war.

Chapter 7. Deploying Applications

JBoss EAP features a range of application deployment and configuration options to cater to both administrators and developers. For administrators, the management console and the management CLI offer ideal graphical and command-line interfaces to manage application deployment in a production environment. For developers, the range of application deployment testing options include a configurable file system deployment scanner, the HTTP API, an IDE such as Red Hat CodeReady Studio, and Maven.

When deploying applications, you may want to enable validation for deployment descriptors by setting the org.jboss.metadata.parser.validate system property to true. This can be done one of the following ways:

  • While starting the server.

    $ EAP_HOME/bin/standalone.sh -Dorg.jboss.metadata.parser.validate=true
  • By adding it to the server configuration with the following management CLI command.

    /system-property=org.jboss.metadata.parser.validate:add(value=true)

7.1. Deploying Applications Using the Management CLI

Deploying applications using the management CLI gives you the benefit of a single command-line interface with the ability to create and run deployment scripts. You can use this scripting ability to configure specific application deployment and management scenarios. You can manage the deployments for a single server when running as a standalone server, or an entire network of servers when running in a managed domain.

7.1.1. Deploy an Application to a Standalone Server Using the Management CLI

Deploy an Application

From the management CLI, use the deployment deploy-file command and specify the path to the application deployment.

deployment deploy-file /path/to/test-application.war

A successful deployment does not produce any output to the management CLI, but the server log displays deployment messages.

WFLYSRV0027: Starting deployment of "test-application.war" (runtime-name: "test-application.war")
WFLYUT0021: Registered web context: /test-application
WFLYSRV0010: Deployed "test-application.war" (runtime-name : "test-application.war")

Similarly, you can use the following deployment commands:

  • Use the deployment deploy-cli-archive to deploy the content from a .cli archive file. A CLI deployment archive is a JAR file with the .cli extension. It contains application archives that should be deployed and the CLI script files, deploy.scr and undeploy.scr, containing commands and operations. One script file, deploy.scr, contains the commands and operations that deploy the application archives and set up the environment; the other script file, undeploy.scr, contains the commands to undeploy the application archives and clean up the environment.
  • Use the deployment deploy-url to deploy the content referenced by a URL.

You can also enable the disabled applications using the deployment enable command.

Undeploy an Application

From the management CLI, use the deployment undeploy command and specify the deployment name. This will delete the deployment content from the repository. See Disable an Application for keeping the deployment content when undeploying.

deployment undeploy test-application.war

A successful undeployment does not produce any output to the management CLI, but the server log displays undeployment messages.

WFLYUT0022: Unregistered web context: /test-application
WFLYSRV0028: Stopped deployment test-application.war (runtime-name: test-application.war) in 62ms
WFLYSRV0009: Undeployed "test-application.war" (runtime-name: "test-application.war")

Similarly, you can use the deployment undeploy-cli-archive to undeploy the content from a .cli archive file. You can also undeploy all deployments using a wildcard (*).

deployment undeploy *
Disable an Application

Disable a deployed application without removing the deployment content from the repository.

deployment disable test-application.war

You can use the deployment disable-all command to disable all the deployments.

deployment disable-all
Enable an Application

Enable a disabled deployed application.

deployment enable test-application.war

You can use the deployment enable-all command to enable all the deployments.

deployment enable-all
List Deployments

From the management CLI, use the deployment info command to list deployment information.

deployment info

The output will show details about each deployment, such as the runtime name, status, and whether it is enabled.

NAME                 RUNTIME-NAME         PERSISTENT ENABLED STATUS
helloworld.war       helloworld.war       true       true    OK
test-application.war test-application.war true       true    OK

To display deployment information by name:

deployment info helloworld.war

You can also list all the deployments using the deployment list command.

7.1.2. Deploy an Application in a Managed Domain Using the Management CLI

Deploy an Application

From the management CLI, use the deployment deploy-file command and specify the path to the application deployment. You must also specify the server groups to which the application should be deployed.

  • To deploy the application to all server groups.

    deployment deploy-file /path/to/test-application.war --all-server-groups
  • To deploy the application to specific server groups.

    deployment deploy-file /path/to/test-application.war --server-groups=main-server-group,other-server-group

A successful deployment does not produce any output to the management CLI, but the server log displays deployment messages for each affected server.

[Server:server-one] WFLYSRV0027: Starting deployment of "test-application.war" (runtime-name: "test-application.war")
[Server:server-one] WFLYUT0021: Registered web context: /test-application
[Server:server-one] WFLYSRV0010: Deployed "test-application.war" (runtime-name : "test-application.war")

Similarly, you can use the following deployment commands:

  • Use the deployment deploy-cli-archive command to deploy the content from a .cli archive file. A CLI deployment archive is a JAR file with the .cli extension. It contains application archives that should be deployed and the CLI script files, deploy.scr and undeploy.scr, containing commands and operations. One script file, deploy.scr, contains the commands and operations that deploy the application archives and set up the environment; the other script file, undeploy.scr, contains the commands to undeploy the application archives and clean up the environment.
  • Use the deployment deploy-url command to deploy the content referenced by a URL.

You can also enable the disabled applications using the deployment enable command.

Undeploy an Application

From the management CLI, use the deployment undeploy command and specify the deployment name. You must also specify the server groups from which the application should be undeployed. See Disable an Application for undeploying from specific server groups.

Undeploy the application from all server groups with that deployment.

deployment undeploy test-application.war --all-relevant-server-groups

A successful undeployment does not produce any output to the management CLI, but the server log displays undeployment messages for each affected server.

[Server:server-one] WFLYUT0022: Unregistered web context: /test-application
[Server:server-one] WFLYSRV0028: Stopped deployment test-application.war (runtime-name: test-application.war) in 74ms
[Server:server-one] WFLYSRV0009: Undeployed "test-application.war" (runtime-name: "test-application.war")

Similarly, you can use the deployment undeploy-cli-archive command to undeploy the content from a .cli archive file. You can also undeploy all deployments using a wildcard (*).

deployment undeploy * --all-relevant-server-groups
Disable an Application

Disable a deployed application from specific server groups and retain its content in the repository for other server groups with that deployment.

deployment disable test-application.war --server-groups=other-server-group

You can use the deployment disable-all command to disable all the deployments.

deployment disable-all --server-groups=other-server-group
Enable an Application

Enable a disabled deployed application.

deployment enable test-application.war

You can use the deployment enable-all command to enable all the deployments.

deployment enable-all --server-groups=other-server-group
List Deployments

From the management CLI, use the deployment info command to list deployment information. You can list deployment information by deployment name or by server group.

To display deployment information by name:

deployment info helloworld.war

The output will list the deployment and its state in each server group.

NAME               RUNTIME-NAME
helloworld.war     helloworld.war

SERVER-GROUP       STATE
main-server-group  enabled
other-server-group added

To display deployment information by server group:

deployment info --server-group=other-server-group

The output will list the deployments and their state for the specified server group.

NAME                 RUNTIME-NAME         STATE
helloworld.war       helloworld.war       added
test-application.war test-application.war enabled

You can also list all deployments in the domain using the deployment list command.

7.2. Deploying Applications Using the Management Console

Deploying applications using the management console gives you the benefit of a graphical interface that is easy to use. You can see at a glance which applications are deployed to your server or server groups, and you can enable, disable or remove applications from the content repository as required.

7.2.1. Deploy an Application to a Standalone Server Using the Management Console

Deployments can be viewed and managed from the Deployments tab of the JBoss EAP management console.

Deploy an Application

Click the Add (+) button. You can choose to deploy an application by uploading a deployment, adding an unmanaged deployment, or creating an empty deployment. Deployments are enabled by default.

  • Upload a deployment

    Upload an application that will be copied to the server’s content repository and managed by JBoss EAP.

  • Adding an unmanaged deployment

    Specify the location of a deployment. This deployment will not be copied to the server’s content repository and will not be managed by JBoss EAP.

  • Creating an empty deployment

    Create an empty, exploded deployment. You can add files to the deployment after it has been created.

Undeploy an Application

Select the deployment and choose the Undeploy option. JBoss EAP removes the deployment from the content repository.

Disable an Application

Select the deployment and choose the Disable option to disable the application. This undeploys the deployment, but does not remove it from the content repository.

Replace an Application

Select the deployment and choose the Replace option. Select the new version of the deployment, which must have the same name as the original, and click Finish. This undeploys and removes the original version of the deployment, and then deploys the new version.

7.2.2. Deploy an Application in a Managed Domain Using the Management Console

From the Deployments tab of the JBoss EAP management console, deployments can be viewed and managed by:

  • Content Repository

    All managed and unmanaged deployments are listed in the Content Repository section. Deployments can be added and deployed to server groups here.

  • Server Groups

    Deployments that have been deployed to one or more server groups are listed in the Server Groups section. Deployments can be enabled and added directly to a server group here.

Add an Application
  1. From Content Repository, click the Add button.
  2. Choose to add an application by uploading a deployment or adding an unmanaged deployment.
  3. Follow the prompts to deploy the application.

    Note that a deployment must be deployed to a server group before it can be enabled.

Deploy an Application to a Server Group
  1. From Content Repository, select a deployment and click the Deploy button.
  2. Select one or more server groups to which this deployment should be deployed.
  3. Optionally, select the option to enable the deployment on the selected server groups.
Undeploy an Application from a Server Group
  1. From Server Groups, select the appropriate server group.
  2. Select the desired deployment and click the Undeploy button.

Deployments can also be undeployed from multiple server groups at once by selecting the Undeploy button for the deployment in Content Repository.

Remove an Application
  1. If the deployment is still deployed to any server groups, be sure to undeploy the deployment.
  2. From Content Repository, select the deployment and click the Remove button.

This removes the deployment from the content repository.

Disable an Application
  1. From Server Groups, select the appropriate server group.
  2. Select the desired deployment and click the Disable button.

This undeploys the deployment, but does not remove it from the content repository.

Replace an Application
  1. From Content Repository, select the deployment and click the Replace button.
  2. Select the new version of the deployment, which must have the same name as the original, and click Replace.

This undeploys and removes the original version of the deployment, and then deploys the new version.

7.3. Deploying Applications Using the Deployment Scanner

The deployment scanner monitors the deployment directory for applications to deploy. By default, the deployment scanner scans the EAP_HOME/standalone/deployments/ directory every five seconds for changes. Marker files are used to indicate the status of a deployment and to trigger actions against deployments, such as undeploying or redeploying.

While it is recommended to use the management console or management CLI for application deployment in a production environment, deploying using the deployment scanner is provided for the convenience of developers. This allows users to build and test applications in a manner suited for rapid development cycles. Additionally, the deployment scanner should not be used in conjunction with other deployment methods.

The deployment scanner is only available when running JBoss EAP as a standalone server.

7.3.1. Deploy an Application to a Standalone Server Using the Deployment Scanner

The deployment scanner can be configured to allow or disallow automatic deployment of XML, zipped, and exploded content. If automatic deployment is disabled, you must manually create marker files to trigger deployment actions. For more information about the available marker file types and their purposes, see the Deployment Scanner Marker Files section.

By default, automatic deployment for XML and zipped content is enabled. For details on configuring automatic deployment for each content type, see Configure the Deployment Scanner.

Warning

Deploying using the deployment scanner is provided for the convenience of developers and is not recommended for use in a production environment. It should also not be used in conjunction with other deployment methods.

Deploy an Application

Copy the content to the deployment folder.

$ cp /path/to/test-application.war EAP_HOME/standalone/deployments/

If auto-deployment is enabled, this file will be picked up automatically, deployed, and a .deployed marker file will be created. If auto-deployment is not enabled, then you will need to manually add a .dodeploy marker file to trigger deployment.

$ touch EAP_HOME/standalone/deployments/test-application.war.dodeploy
Undeploy an Application

Trigger an undeployment by removing the .deployed marker file.

$ rm EAP_HOME/standalone/deployments/test-application.war.deployed

If auto-deployment is enabled, you can also remove the test-application.war file, which will trigger the undeployment. Note that this does not apply for exploded deployments.

Redeploy an Application

Create a .dodeploy marker file to initiate redeployment.

$ touch EAP_HOME/standalone/deployments/test-application.war.dodeploy

7.3.2. Configure the Deployment Scanner

The deployment scanner can be configured using the management console or the management CLI. You can configure the deployment scanner’s behavior, such as the scan interval, deployment folder location, and autodeployment of certain application file types. You can also disable the deployment scanner entirely.

For details on all available deployment scanner attributes, see the Deployment Scanner Attributes section.

Use the below management CLI commands to configure the default deployment scanner.

Disable the Deployment Scanner
/subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-enabled,value=false)

This disables the default deployment scanner.

Change the Scan Interval
/subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-interval,value=10000)

This updates the scan interval time from 5000 milliseconds (five seconds) to 10000 milliseconds (ten seconds).

Change the Deployment Folder
/subsystem=deployment-scanner/scanner=default:write-attribute(name=path,value=/path/to/deployments)

This changes the location of the deployment folder from the default location of EAP_HOME/standalone/deployments to /path/to/deployments.

The path value will be treated as an absolute path unless the relative-to attribute is specified, in which case it will be relative to that path.

Enable the Automatic Deployment of Exploded Content
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-exploded,value=true)

This enables the automatic deployment of exploded content, which is disabled by default.

Disable the Automatic Deployment of Zipped Content
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-zipped,value=false)

This disables the automatic deployment of zipped content, which is enabled by default.

Disable the Automatic Deployment of XML Content
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-xml,value=false)

This disables the automatic deployment of XML content, which is enabled by default.

7.3.3. Define a Custom Deployment Scanner

A new deployment scanner can be added using the management CLI or by navigating to the Deployment Scanners subsystem from the Configuration tab in the management console. This will define a new directory to scan for deployments. The default deployment scanner monitors EAP_HOME/standalone/deployments. See Configure the Deployment Scanner for details on configuring an existing deployment scanner.

The following management CLI command adds a new deployment scanner that will check EAP_HOME/standalone/new_deployment_dir every five seconds for deployments.

/subsystem=deployment-scanner/scanner=new-scanner:add(path=new_deployment_dir,relative-to=jboss.server.base.dir,scan-interval=5000)
Note

The specified directory must already exist or this command will fail with an error.

A new deployment scanner has been defined and the specified directory will be monitored for deployments.

7.4. Deploying Applications Using Maven

Deploying applications using Apache Maven allows you to easily incorporate deployment to JBoss EAP into your existing development workflow.

You can use Maven to deploy applications to JBoss EAP using the WildFly Maven Plugin, which provides simple operations to deploy and undeploy applications to the application server.

7.4.1. Deploy an Application to a Standalone Server Using Maven

The following instructions show how to deploy and undeploy the JBoss EAP helloworld quickstart to a standalone server using Maven.

See Using the Quickstart Examples in the JBoss EAP Getting Started Guide for more information on the JBoss EAP quickstarts.

Deploy an Application

Initialize the WildFly Maven Plugin in your Maven pom.xml file. This should already be configured in the JBoss EAP quickstart pom.xml files.

<plugin>
  <groupId>org.wildfly.plugins</groupId>
  <artifactId>wildfly-maven-plugin</artifactId>
  <version>${version.wildfly.maven.plugin}</version>
</plugin>

From the helloworld quickstart directory, execute the following Maven command.

$ mvn clean install wildfly:deploy

After issuing the Maven command to deploy, the terminal window shows the following output indicating a successful deployment.

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.981 s
[INFO] Finished at: 2015-12-23T15:06:13-05:00
[INFO] Final Memory: 21M/231M
[INFO] ------------------------------------------------------------------------

The deployment can also be confirmed by viewing the server log of the active server instance.

WFLYSRV0027: Starting deployment of "helloworld.war" (runtime-name: "helloworld.war")
WFLYUT0021: Registered web context: /helloworld
WFLYSRV0010: Deployed "helloworld.war" (runtime-name : "helloworld.war")
Undeploy an Application

From the helloworld quickstart directory, execute the following Maven command.

$ mvn wildfly:undeploy

After issuing the Maven command to undeploy, the terminal window shows the following output indicating a successful undeployment.

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.237 s
[INFO] Finished at: 2015-12-23T15:09:10-05:00
[INFO] Final Memory: 10M/183M
[INFO] ------------------------------------------------------------------------

The undeployment can also be confirmed by viewing the server log of the active server instance.

WFLYUT0022: Unregistered web context: /helloworld
WFLYSRV0028: Stopped deployment helloworld.war (runtime-name: helloworld.war) in 27ms
WFLYSRV0009: Undeployed "helloworld.war" (runtime-name: "helloworld.war")

7.4.2. Deploy an Application in a Managed Domain Using Maven

The following instructions show how to deploy and undeploy the JBoss EAP helloworld quickstart in a managed domain using Maven.

See Using the Quickstart Examples in the JBoss EAP Getting Started Guide for more information on the JBoss EAP quickstarts.

Deploy an Application

When deploying an application in a managed domain, you must specify the server groups to which the application should be deployed. This is configured in the Maven pom.xml file.

The following configuration in the pom.xml initializes the WildFly Maven Plugin and specifies main-server-group as the server group to which the application should be deployed.

<plugin>
  <groupId>org.wildfly.plugins</groupId>
  <artifactId>wildfly-maven-plugin</artifactId>
  <version>${version.wildfly.maven.plugin}</version>
  <configuration>
    <domain>
      <server-groups>
        <server-group>main-server-group</server-group>
      </server-groups>
    </domain>
  </configuration>
</plugin>

From the helloworld quickstart directory, execute the following Maven command.

$ mvn clean install wildfly:deploy

After issuing the Maven command to deploy, the terminal window shows the following output indicating a successful deployment.

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.005 s
[INFO] Finished at: 2016-09-02T14:36:17-04:00
[INFO] Final Memory: 21M/226M
[INFO] ------------------------------------------------------------------------

The deployment can also be confirmed by viewing the server log of the active server instance.

WFLYSRV0027: Starting deployment of "helloworld.war" (runtime-name: "helloworld.war")
WFLYUT0021: Registered web context: /helloworld
WFLYSRV0010: Deployed "helloworld.war" (runtime-name : "helloworld.war")
Undeploy an Application

From the helloworld quickstart directory, execute the following Maven command.

$ mvn wildfly:undeploy

After issuing the Maven command to undeploy, the terminal window shows the following output indicating a successful undeployment.

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.750 s
[INFO] Finished at: 2016-09-02T14:45:10-04:00
[INFO] Final Memory: 10M/184M
[INFO] ------------------------------------------------------------------------

The undeployment can also be confirmed by viewing the server log of the active server instance.

WFLYUT0022: Unregistered web context: /helloworld
WFLYSRV0028: Stopped deployment helloworld.war (runtime-name: helloworld.war) in 106ms
WFLYSRV0009: Undeployed "helloworld.war" (runtime-name: "helloworld.war")

7.5. Deploying Applications Using the HTTP API

Applications can be deployed to JBoss EAP using the HTTP API with the curl command. For more information on using the HTTP API, see the HTTP API section.

7.5.1. Deploy an Application to a Standalone Server Using the HTTP API

By default, the HTTP API is accessible at http://HOST:PORT/management, for example, http://localhost:9990/management.

Deploy an Application
$ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "add", "address" : {"deployment" : "test-application.war"}, "content" : [{"url" : "file:/path/to/test-application.war"}]},{"operation" : "deploy", "address" : {"deployment" : "test-application.war"}}],"json.pretty":1}'
Undeploy an Application
$ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "undeploy", "address" : {"deployment" : "test-application.war"}},{"operation" : "remove", "address" : {"deployment" : "test-application.war"}}],"json.pretty":1}'

See this Red Hat Knowledgebase article to learn more about programmatically generating the JSON requests.

7.5.2. Deploy an Application in a Managed Domain Using the HTTP API

By default, the HTTP API is accessible at http://HOST:PORT/management, for example, http://localhost:9990/management.

Deploy an Application
  1. Add the deployment to the content repository.

    $ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "add", "address" : {"deployment" : "test-application.war"}, "content" : [{"url" : "file:/path/to/test-application.war"}],"json.pretty":1}'
  2. Add the deployment to the desired server group.

    $ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "add", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'
  3. Deploy the application to the server group.

    $ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "deploy", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'
Undeploy an Application
  1. Remove the deployment from all server groups to which it is assigned.

    $ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "remove", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'
  2. Remove the deployment from the content repository.

    $ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "remove", "address" : {"deployment" : "test-application.war"}, "json.pretty":1}'

7.6. Customizing Deployment Behavior

7.6.1. Define a Custom Directory for Deployment Content

You can define a custom location for JBoss EAP to store deployed content.

Define a Custom Directory for a Standalone Server

By default, deployed content for a standalone server is stored in the EAP_HOME/standalone/data/content directory. This location can be changed by passing in the -Djboss.server.deploy.dir argument when starting the server.

$ EAP_HOME/bin/standalone.sh -Djboss.server.deploy.dir=/path/to/new_deployed_content

The chosen location should be unique among JBoss EAP instances.

Note

The jboss.server.deploy.dir property specifies the directory to be used for storing content that has been deployed using the management console or management CLI. To define a custom deployment directory to be monitored by the deployment scanner, see Configure the Deployment Scanner.

Define a Custom Directory for a Managed Domain

By default, deployed content for a managed domain is stored in the EAP_HOME/domain/data/content directory. This location can be changed by passing in the -Djboss.domain.deployment.dir argument when starting the domain.

$ EAP_HOME/bin/domain.sh -Djboss.domain.deployment.dir=/path/to/new_deployed_content

The chosen location should be unique among JBoss EAP instances.

7.6.2. Control the Order of Deployments

JBoss EAP offers fine-grained control over the order of deployments when the server is started. Strict order of the deployment of applications present in multiple EAR files can be specified along with persistence of the order after a restart.

You can use the jboss-all.xml deployment descriptor to declare dependencies between top-level deployments.

For example, if you have an app.ear that depends on framework.ear being deployed first, then you can create an app.ear/META-INF/jboss-all.xml file as shown below.

<jboss xmlns="urn:jboss:1.0">
  <jboss-deployment-dependencies xmlns="urn:jboss:deployment-dependencies:1.0">
    <dependency name="framework.ear" />
  </jboss-deployment-dependencies>
</jboss>
Note

You can use the deployment’s runtime name as the dependency name in the jboss-all.xml file.

This ensures that framework.ear is deployed before app.ear.

Important

If you create a jboss-all.xml file in app.ear and you do not deploy framework.ear, the server attempts to deploy app.ear and fails.

7.6.3. Override Deployment Content

A deployment overlay can be used to overlay content into an existing deployment without physically modifying the contents of the deployment archive. It allows you to override deployment descriptors, library JAR files, classes, JSP pages, and other files at runtime without rebuilding the archive.

This can be useful if you need to adapt a deployment for different environments that need different configurations or settings. For example, when moving a deployment through the application lifecycle from development, to testing, to stage, and finally into production, you might want to swap deployment descriptors, modify static web resources to change the branding of the application, or even replace JAR libraries with different versions depending on the target environment. It is also a useful feature for installations that need to change a configuration but can not modify or crack an archive due to policy or security restrictions.

When defining a deployment overlay, you specify the file on a file system that will replace the file in the deployment archive. You must also specify which deployments should be affected by the deployment overlay. Any affected deployments must be redeployed in order for the changes to take effect.

Parameters

You can use any of the following parameters to configure your deployment overlay:

  • name:: The name of the deployment overlay.
  • content:: A comma-separated list that maps the file on the file system to the file in the archive that it replaces. The format for each entry is ARCHIVE_PATH=FILESYSTEM_PATH.
  • deployments:: Comma-separated list of deployments to which this overlay is linked.
  • redeploy-affected:: Redeploys all affected deployments.

For full usage details, execute deployment-overlay --help.

Procedure

  1. Use the deployment-overlay add management CLI command to add a deployment overlay:

    deployment-overlay add --name=new-deployment-overlay --content=WEB-INF/web.xml=/path/to/other/web.xml --deployments=test-application.war --redeploy-affected
    Note

    In a managed domain, specify the applicable server groups by using --server-groups or specify all server groups with --all-server-groups.

  2. After you created a deployment overlay, you can add content to an existing overlay, link the overlay to a deployment, or remove the overlay.
  3. Optional: You can specify an overlay configuration to link to an external directory that contains static web resources, such as HTML, images, or videos, in the <overlay> element. The <overlay> element is located in the application jboss-web.xml file. With this configuration, you do not need to repackage the application.

    The following example shows system property substitution in the <overlay> element, where ${example.path.to.overlay} defines the /PATH/TO/STATIC/WEB/CONTENT location.

    Example: <overlay> element in a jboss-web.xml file

    <jboss-web>
            <overlay>${example.path.to.overlay}</overlay>
    </jboss-web>

    You can specify a system property in the <overlay> element if jboss-descriptor-property-replacement is set to true, which is the default value for the descriptor property.

    To configure jboss-descriptor-property-replacement, use the following management CLI command:

    /subsystem=ee:write-attribute(name=jboss-descriptor-property-replacement,value=true)

    This command adds the following XML content to the ee subsystem in the JBoss EAP configuration:

    <subsystem xmlns="urn:jboss:domain:ee:4.0">
        <jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement>
    </subsystem>

7.6.4. Using Rollout Plans

About Rollout Plans

In a managed domain, operations targeted at domain or host level resources can potentially impact multiple servers. Such operations can include a roll out plan detailing the sequence in which the operation would be applied to the servers, as well as the policies for detailing whether the operation could be reverted if it fails to execute successfully on some servers. If no rollout plan is specified, the default rollout plan is used.

Below is an example rollout plan involving five server groups. Operations can be applied to server groups serially, in-series, or concurrently, concurrent-groups. The syntax is described in more detail in Rollout Plan Syntax.

{"my-rollout-plan" => {"rollout-plan" => {
    "in-series" => [
        {"concurrent-groups" => {
            "group-A" => {
                "max-failure-percentage" => "20",
                "rolling-to-servers" => "true"
            },
            "group-B" => undefined
        }},
        {"server-group" => {"group-C" => {
            "rolling-to-servers" => "false",
            "max-failed-servers" => "1"
        }}},
        {"concurrent-groups" => {
            "group-D" => {
                "max-failure-percentage" => "20",
                "rolling-to-servers" => "true"
            },
            "group-E" => undefined
        }}
    ],
    "rollback-across-groups" => "true"
}}}

Looking at the example above, applying the operation to the servers in the domain is done in three phases. If the policy for any server group triggers a rollback of the operation across the server group, all other server groups will be rolled back as well.

  1. Server groups group-A and group-B will have the operation applied concurrently. The operation will be applied to the servers in group-A in series, while all servers in group-B will handle the operation concurrently. If more than 20% of the servers in group-A fail to apply the operation, it will be rolled back across that group. If any servers in group-B fail to apply the operation it will be rolled back across that group.
  2. Once all servers in group-A and group-B are complete, the operation will be applied to the servers in group-C. Those servers will handle the operation concurrently. If more than one server in group-C fails to apply the operation it will be rolled back across that group.
  3. Once all servers in group-C are complete, server groups group-D and group-E will have the operation applied concurrently. The operation will be applied to the servers in group-D in series, while all servers in group-E will handle the operation concurrently. If more than 20% of the servers in group-D fail to apply the operation, it will be rolled back across that group. If any servers in group-E fail to apply the operation it will be rolled back across that group.
Rollout Plan Syntax

You can specify a rollout plan in either of the following ways.

Although each method has a different initial command, both methods use the rollout operation header to define the rollout plan. This uses the following syntax.

rollout (id=PLAN_NAME | SERVER_GROUP_LIST) [rollback-across-groups]
  • PLAN_NAME is the name for the rollout plan that was stored using the rollout-plan command.
  • SERVER_GROUP_LIST is the list of server groups. Use a comma (,) to separate multiple server groups to indicate that operations should be performed on each server group sequentially. Use a caret (^) separator to indicate that operations should be performed on each server group concurrently.

    • For each server group, set any of the following policies in parentheses. Use a comma to separate multiple policies.

      • rolling-to-servers: A boolean that, if set to true, applies the operation to each server in the group in series. If the value is false or not specified, the operation will be applied to the servers in the group concurrently.
      • max-failed-servers: An integer which takes the maximum number of servers in the group that can fail to apply the operation before it should be reverted on all servers in the group. The default value if not specified is 0, meaning that a failure on any server will trigger rollback across the group.
      • max-failure-percentage: An integer between 0 and 100 that represents the maximum percentage of the total number of servers in the group that can fail to apply the operation before it should be reverted on all servers in the group. The default value if not specified is 0, meaning that a failure on any server will trigger rollback across the group.

        Note

        If both max-failed-servers and max-failure-percentage are set to non-zero values, max-failure-percentage takes precedence.

  • rollback-across-groups: A boolean that indicates whether the need to rollback the operation on all the servers in one server group triggers a rollback across all the server groups. This defaults to false.
Deploy Using a Rollout Plan

You can provide the full details of a rollout plan directly to the deploy command by passing the rollout settings into the headers argument. See the Rollout Plan Syntax for more information on the format.

The following management CLI command deploys an application to the main-server-group server group using a deployment plan that specifies rolling-to-servers=true for serial deployment.

deploy /path/to/test-application.war --server-groups=main-server-group --headers={rollout main-server-group(rolling-to-servers=true)}
Deploy Using a Stored Rollout Plan

Since rollout plans can be complex, you have the option to store the details of a rollout plan. This allows you to reference the rollout plan name when you want to use it instead of requiring the full details of the rollout plan each time.

  1. Use the rollout-plan management CLI command to store a rollout plan. See the Rollout Plan Syntax for more information on the format.

    rollout-plan add --name=my-rollout-plan --content={rollout main-server-group(rolling-to-servers=false,max-failed-servers=1),other-server-group(rolling-to-servers=true,max-failure-percentage=20) rollback-across-groups=true}

    This creates the following deployment plan.

    "rollout-plan" => {
        "in-series" => [
            {"server-group" => {"main-server-group" => {
                "rolling-to-servers" => false,
                "max-failed-servers" => 1
            }}},
            {"server-group" => {"other-server-group" => {
                "rolling-to-servers" => true,
                "max-failure-percentage" => 20
            }}}
        ],
        "rollback-across-groups" => true
    }
  2. Specify the stored rollout plan name when deploying the application.

    The following management CLI command deploys an application to all server groups using the my-rollout-plan stored rollout plan.

    deploy /path/to/test-application.war --all-server-groups --headers={rollout id=my-rollout-plan}
Remove a Stored Rollout Plan

You can remove a stored rollout plan using the rollout-plan management CLI command by specifying the name of the rollout plan to remove.

rollout-plan remove --name=my-rollout-plan
Default Rollout Plan

All operations that impact multiple servers will be executed with a rollout plan. If no rollout plan is specified in the operation request, a default rollout plan will be generated. The plan will have the following characteristics.

  • There will only be a single high-level phase. All server groups affected by the operation will have the operation applied concurrently.
  • Within each server group, the operation will be applied to all servers concurrently.
  • Failure on any server in a server group will cause rollback across the group.
  • Failure of any server group will result in rollback of all other server groups.

7.7. Managing Exploded Deployments

Prior to JBoss EAP 7.1, you could only manage exploded deployments by manipulating files on the file system. Starting with JBoss EAP 7.1, you can manage exploded deployments using the management interfaces. This allows you to change the contents of an exploded application without deploying a new version of the application.

Note

Updates to static files in a deployment, such as JavaScript and CSS files, take effect immediately. Changes to other files, such as Java classes, might require an application redeployment for the changes to take effect.

You can either start with an empty deployment or explode an existing archive deployment and then add or remove content.

See Viewing Deployment Content to browse the files in a deployment or read the contents of the files.

Create an Empty Exploded Deployment

You can create an empty exploded deployment to which you can later add content as necessary. Use the following management CLI command to create an empty exploded deployment.

/deployment=DEPLOYMENT_NAME.war:add(content=[{empty=true}])

The empty=true option is required to confirm that you intended to create an empty deployment.

Explode an Existing Archive Deployment

You can explode an existing archive deployment to be able to update its contents. Note that a deployment must be disabled before it can be exploded. Use the following management CLI command to explode a deployment.

/deployment=ARCHIVE_DEPLOYMENT_NAME.ear:explode

You can now add or remove content from this deployment.

Note

You can also explode an existing archive deployment from the management console. From the Deployments tab, select the deployment and select the Explode drop down option.

Add Content to an Exploded Deployment

To add content to a deployment, use the add-content management CLI operation. Provide the path to the location in the deployment where the content should be added, and provide the content to be uploaded. The content to upload can be provided as a local file stream, URL, hash of content that already exists in the JBoss EAP content repository, or a byte array of the content. The following management CLI command uses the input-stream-index option to upload the contents of a local file to the deployment.

/deployment=DEPLOYMENT_NAME.war:add-content(content=[{target-path=/path/to/FILE_IN_DEPLOYMENT, input-stream-index=/path/to/LOCAL_FILE_TO_UPLOAD}]
Note

When adding content to a deployment using the add-content operation, content in the deployment is overwritten by default. You can change this behavior by setting the overwrite option to false.

Remove Content from an Exploded Deployment

To remove content from a deployment, use the remove-content management CLI operation and provide the path of the content in the deployment to remove.

/deployment=DEPLOYMENT_NAME.war:remove-content(paths=[/path/to/FILE_1, /path/to/FILE_2])

7.8. Viewing Deployment Content

You can browse information about files in a managed deployment and read the contents of the files using the JBoss EAP management interfaces.

7.8.1. Browse Files in a Deployment

Use the browse-content operation to view the files and directories in a managed deployment. Provide no arguments to return the entire deployment structure or use the path argument to provide the path to a specific directory.

Note

You can also browse contents of a deployment from the management console by navigating to the Deployments tab, selecting the deployment, and selecting View from the drop down.

/deployment=helloworld.war:browse-content(path=META-INF/)

This displays the files and directories in the META-INF/ directory of the helloworld.war deployment.

{
    "outcome" => "success",
    "result" => [
        {
            "path" => "MANIFEST.MF",
            "directory" => false,
            "file-size" => 827L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/pom.properties",
            "directory" => false,
            "file-size" => 106L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/pom.xml",
            "directory" => false,
            "file-size" => 2713L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/",
            "directory" => true
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/",
            "directory" => true
        },
        {
            "path" => "maven/",
            "directory" => true
        },
        {
            "path" => "INDEX.LIST",
            "directory" => false,
            "file-size" => 251L
        }
    ]
}

You can also specify the following arguments to the browse-content operation.

archive
Whether to only return archive files.
depth
Specify the depth of files to return.

7.8.2. Read Deployment Content

You can read the contents of a file in a managed deployment using the read-content operation. Provide no arguments to return the entire deployment or use the path argument to provide the path to a specific file. For example:

/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF)

This returns a file stream, which can be displayed in the management CLI or saved to the file system.

{
    "outcome" => "success",
    "result" => {"uuid" => "24ba8e06-21bd-4505-b4d4-bdfb16451b95"},
    "response-headers" => {"attached-streams" => [{
        "uuid" => "24ba8e06-21bd-4505-b4d4-bdfb16451b95",
        "mime-type" => "text/plain"
    }]}
}

7.8.2.1. Display the Contents of a File

Use the attachment display command to read the contents of the MANIFEST.MF file.

attachment display --operation=/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF)

This displays the contents of the MANIFEST.MF file from the helloworld.war deployment to the management CLI.

ATTACHMENT 8af87836-2abd-423a-8e44-e731cc57bd80:
Manifest-Version: 1.0
Implementation-Title: Quickstart: helloworld
Implementation-Version: 7.3.0.GA
Java-Version: 1.8.0_131
Built-By: username
Scm-Connection: scm:git:git@github.com:jboss/jboss-parent-pom.git/quic
 kstart-parent/helloworld
Specification-Vendor: JBoss by Red Hat
...

7.8.2.2. Save the Contents of a File

Use the attachment save command to save the contents of the MANIFEST.MF file to the file system.

attachment save --operation=/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF) --file=/path/to/MANIFEST.MF

This saves the MANIFEST.MF file from the helloworld.war deployment to the file system at path/to/MANIFEST.MF. If you do not specify a file path using the --file argument, the file will be named using its unique attachment ID and saved in the working directory of the management CLI, which by default is EAP_HOME/bin/.

Chapter 8. Domain Management

This section discusses concepts and configuration specific to the managed domain operating mode.

For information on securing a managed domain, see the Securing a Managed Domain section of JBoss EAP How to Configure Server Security.

8.1. About Managed Domains

The managed domain operating mode allows for the management of multiple JBoss EAP instances from a single control point.

Centrally-managed JBoss EAP server collections are known as members of a domain. All JBoss EAP instances in a domain share a common management policy.

A domain consists of one domain controller, one or more host controllers, and zero or more server groups per host.

A managed domain.

A domain controller is the central point from which the domain is controlled. It ensures that each server is configured according to the management policy of the domain. The domain controller is also a host controller.

A host controller is a physical or virtual host that interacts with the domain controller to control the lifecycle of the application server instances running on its host and to assist the domain controller to manage them. Each host can contain multiple server groups.

A server group is a set of server instances which have JBoss EAP installed on them and are managed and configured as one. The domain controller manages the configuration of and applications deployed onto server groups. Consequently, each server in a server group shares the same configuration and deployments.

Host controllers are tied to specific physical, or virtual, hosts. You can run multiple host controllers on the same hardware if you use different configurations, ensuring their ports and other resources do not conflict. It is possible for a domain controller, a single host controller, and multiple servers to run within the same JBoss EAP instance, on the same physical system.

8.1.1. About the Domain Controller

A domain controller is the JBoss EAP server instance that acts as a central management point for a domain. One host controller instance is configured to act as a domain controller.

The primary responsibilities of the domain controller are:

  • Maintain the domain’s central management policy.
  • Ensure all host controllers are aware of its current contents.
  • Assist the host controllers in ensuring that all running JBoss EAP server instances are configured in accordance with this policy.

By default, the central management policy is stored in the EAP_HOME/domain/configuration/domain.xml file. This file is required in this directory of the host controller that is set to run as the domain controller.

The domain.xml file contains profile configurations available for use by the servers in the domain. A profile contains the detailed settings of the various subsystems available in that profile. The domain configuration also includes the definition of socket groups and the server group definitions.

Note

It is possible for a JBoss EAP 7 domain controller to administer JBoss EAP 6 hosts and servers, as long as the hosts and servers are running JBoss EAP 6.2 or later. For more information, see Configure a JBoss EAP 7.x Domain Controller to Administer JBoss EAP 6 Instances.

For more information, see the Start a Managed Domain and Domain Controller Configuration sections.

8.1.2. About Host Controllers

The primary responsibility of a host controller is server management. It delegates domain management tasks and is responsible for starting and stopping the individual application server processes that run on its host.

It interacts with the domain controller to help manage the communication between the servers and the domain controller. Multiple host controllers of a domain can interact with only a single domain controller. Hence, all the host controllers and server instances running on a single domain mode have a single domain controller and must belong to the same domain.

By default, each host controller reads its configuration from the EAP_HOME/domain/configuration/host.xml file located in the unzipped JBoss EAP installation file on its host’s file system. The host.xml file contains the following configuration information that is specific to the particular host:

  • The names of the server instances meant to run from this installation.
  • Configurations specific to the local physical installation. For example, named interface definitions declared in domain.xml can be mapped to an actual machine-specific IP address in host.xml. And abstract path names in domain.xml can be mapped to actual file system paths in host.xml.
  • Any of the following configurations:

    • How the host controller contacts the domain controller to register itself and access the domain configuration.
    • How to find and contact a remote domain controller.
    • Whether the host controller is to act as the domain controller

For more information, see the Start a Managed Domain and Host Controller Configuration sections.

8.1.3. About Process Controllers

A process controller is a small, lightweight process that is responsible for spawning the host controller process and monitoring its lifecycle. If the host controller crashes, the process controller will restart it. It also starts server processes as directed by the host controller; however, it will not automatically restart server processes that crash.

The process controller logs to the EAP_HOME/domain/log/process-controller.log file. You can set JVM options for the process controller in the EAP_HOME/bin/domain.conf file using the PROCESS_CONTROLLER_JAVA_OPTS variable.

8.1.4. About Server Groups

A server group is a collection of server instances that are managed and configured as one. In a managed domain, every application server instance belongs to a server group, even if it is the only member. The server instances in a group share the same profile configuration and deployed content.

A domain controller and a host controller enforce the standard configuration on all server instances of every server group in its domain.

A domain can consist of multiple server groups. Different server groups can be configured with different profiles and deployments. For example, a domain can be configured with different server tiers providing different services.

Different server groups can also have the same profile and deployments. This can, for example, allow for rolling application upgrades where the application is upgraded on one server group and then updated on a second server group, avoiding a complete service outage.

For more information, see the Configuring Server Groups section.

8.1.5. About Servers

A server represents an application server instance. In a managed domain, all server instances are members of a server group. The host controller launches each server instance in its own JVM process.

For more information, see the Configuring Servers section.

8.3. Launching a Managed Domain

8.3.1. Start a Managed Domain

Domain and host controllers can be started using the domain.sh or domain.bat script provided with JBoss EAP. For a complete listing of all available startup script arguments and their purposes, use the --help argument or see the Server Runtime Arguments section.

The domain controller must be started before any slave servers in any server groups in the domain. Start the domain controller first, then start any other associated host controllers in the domain.

Start the Domain Controller

Start the domain controller with the host-master.xml configuration file, which is preconfigured for a dedicated domain controller.

$ EAP_HOME/bin/domain.sh --host-config=host-master.xml

Depending on your domain setup, you will need to make additional configurations to allow host controllers to connect. Also see the following example domain setups:

Start a Host Controller

Start the host controller with the host-slave.xml configuration file, which is preconfigured for a slave host controller.

$ EAP_HOME/bin/domain.sh  --host-config=host-slave.xml

Depending on your domain setup, you will need to make additional configurations connect to, and not conflict with, the domain controller. Also see the following example domain setups:

8.3.2. Domain Controller Configuration

You must configure one host in the domain as the domain controller.

Important

It is not supported to configure multiple domain or host controllers on the same machine when using the RPM installation method to install JBoss EAP.

Configure a host as the domain controller by adding the <local/> element in the <domain-controller> declaration. The <domain-controller> should include no other content.

<domain-controller>
  <local/>
</domain-controller>

The host acting as the domain controller must expose a management interface that is accessible to other hosts in the domain. The HTTP interface is the standard management interface.

<management-interfaces>
  <http-interface security-realm="ManagementRealm" http-upgrade-enabled="true">
    <socket interface="management" port="${jboss.management.http.port:9990}"/>
  </http-interface>
</management-interfaces>

The sample minimal domain controller configuration file, EAP_HOME/domain/configuration/host-master.xml, includes these configuration settings.

8.3.3. Host Controller Configuration

A host controller must be configured to connect to the domain controller so that the host controller can register itself with the domain.

Important

It is not supported to configure multiple domain or host controllers on the same machine when using the RPM installation method to install JBoss EAP.

Use the <domain-controller> element of the configuration to configure a connection to the domain controller.

<domain-controller>
  <remote security-realm="ManagementRealm">
    <discovery-options>
      <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9990}"/>
    </discovery-options>
  </remote>
</domain-controller>

The sample minimal host controller configuration file, EAP_HOME/domain/configuration/host-slave.xml, includes the configuration settings to connect to a domain controller. The configuration assumes that you provide the jboss.domain.master.address property when starting the host controller.

$ EAP_HOME/bin/domain.sh --host-config=host-slave.xml -Djboss.domain.master.address=IP_ADDRESS

For more information on domain controller discovery, see the Domain Controller Discovery and Failover section.

Depending on your domain setup, you may also need to provide authentication for the host controller to be authenticated by the domain controller. See Set Up a Managed Domain on Two Machines for details on generating a management user with a secret value and updating the host controller configuration with that value.

8.3.4. Configure the Name of a Host

Every host running in a managed domain must have a unique host name. To ease administration and allow for the use of the same host configuration files on multiple hosts, the server uses the following precedence for determining the host name.

  1. If set, the host element name attribute in the host.xml configuration file.
  2. The value of the jboss.host.name system property.
  3. The value that follows the final period (.) character in the jboss.qualified.host.name system property, or the entire value if there is no final period (.) character.
  4. The value that follows the period (.) character in the HOSTNAME environment variable for POSIX-based operating systems, the COMPUTERNAME environment variable for Microsoft Windows, or the entire value if there is no final period (.) character.

A host controller’s name is configured in the host element at the top of the relevant host.xml configuration file, for example:

<host xmlns="urn:jboss:domain:8.0" name="host1">

Use the following procedure to update the host name using the management CLI.

  1. Start the JBoss EAP host controller.

    $ EAP_HOME/bin/domain.sh --host-config=host-slave.xml
  2. Launch the management CLI, connecting to the domain controller.

    $ EAP_HOME/bin/jboss-cli.sh --connect --controller=DOMAIN_CONTROLLER_IP_ADDRESS
  3. Use the following command to set a new host name.

    /host=EXISTING_HOST_NAME:write-attribute(name=name,value=NEW_HOST_NAME)

    This modifies the host name attribute in the host-slave.xml file as follows:

    <host name="NEW_HOST_NAME" xmlns="urn:jboss:domain:8.0">
  4. Reload the host controller in order for the changes to take effect.

    reload --host=EXISTING_HOST_NAME

If a host controller does not have a name set in the configuration file, you can also pass in the host name at runtime.

$ EAP_HOME/bin/domain.sh --host-config=host-slave.xml  -Djboss.host.name=HOST_NAME

8.4. Managing Servers

8.4.1. Configure Server Groups

The following is an example of a server group definition:

<server-group name="main-server-group" profile="full">
  <jvm name="default">
    <heap size="64m" max-size="512m"/>
  </jvm>
  <socket-binding-group ref="full-sockets"/>
  <deployments>
    <deployment name="test-application.war" runtime-name="test-application.war"/>
    <deployment name="helloworld.war" runtime-name="helloworld.war" enabled="false"/>
  </deployments>
</server-group>

Server groups can be configured using the management CLI or from the management console Runtime tab.

Add a Server Group

The following management CLI command can be used to add a server group.

/server-group=SERVER_GROUP_NAME:add(profile=PROFILE_NAME,socket-binding-group=SOCKET_BINDING_GROUP_NAME)
Update a Server Group

The following management CLI command can be used to update server group attributes.

/server-group=SERVER_GROUP_NAME:write-attribute(name=ATTRIBUTE_NAME,value=VALUE)
Remove a Server Group

The following management CLI command can be used to remove a server group.

/server-group=SERVER_GROUP_NAME:remove
Server Group Attributes

A server group requires the following attributes:

  • name: The server group name.
  • profile: The server group profile name.
  • socket-binding-group: The default socket binding group used for servers in the group. This can be overridden on a per-server basis.

A server group includes the following optional attributes:

  • management-subsystem-endpoint: Set to true to have servers belonging to the server group connect back to the host controller using the endpoint from their remoting subsystem. The remoting subsystem must be present for this to work.
  • socket-binding-default-interface: The socket binding group default interface for this server.
  • socket-binding-port-offset: The default offset to be added to the port values given by the socket binding group.
  • deployments: The deployment content to be deployed on the servers in the group.
  • jvm: The default JVM settings for all servers in the group. The host controller merges these settings with any other configuration provided in host.xml to derive the settings used to launch the server’s JVM.
  • deployment-overlays: Links between a defined deployment overlay and deployments in this server group.
  • system-properties: The system properties to be set on servers in the group.

8.4.2. Configure Servers

The default host.xml configuration file defines three servers:

<servers>
  <server name="server-one" group="main-server-group">
  </server>
  <server name="server-two" group="main-server-group" auto-start="true">
    <socket-bindings port-offset="150"/>
  </server>
  <server name="server-three" group="other-server-group" auto-start="false">
    <socket-bindings port-offset="250"/>
  </server>
</servers>

A server instance named server-one is associated with main-server-group and inherits the subsystem configuration and socket bindings specified by that server group. A server instance named server-two is also associated with main-server-group, but also defines a socket binding port-offset value, so as not to conflict with the port values used by server-one. A server instance named server-three is associated with other-server-group and uses that group’s configurations. It also defines a port-offset value and sets auto-start to false so that this server does not start when the host controller starts.

Servers can be configured using the management CLI or from the management console Runtime tab.

Add a Server

The following management CLI command can be used to add a server.

/host=HOST_NAME/server-config=SERVER_NAME:add(group=SERVER_GROUP_NAME)
Update a Server

The following management CLI command can be used to update server attributes.

/host=HOST_NAME/server-config=SERVER_NAME:write-attribute(name=ATTRIBUTE_NAME,value=VALUE)
Remove a Server

The following management CLI command can be used to remove a server.

/host=HOST_NAME/server-config=SERVER_NAME:remove
Server Attributes

A server requires the following attributes:

  • name: The name of the server.
  • group: The name of a server group from the domain model.

A server includes the following optional attributes:

  • auto-start: Whether or not this server should be started when the host controller starts.
  • socket-binding-group: The socket binding group to which this server belongs.
  • socket-binding-port-offset: An offset to be added to the port values given by the socket binding group for this server.
  • update-auto-start-with-server-status: Update the auto-start attribute with the status of the server.
  • interface: A list of fully-specified named network interfaces available for use on the server.
  • jvm: The JVM settings for this server. If not declared, the settings are inherited from the parent server group or host.
  • path: A list of named file system paths.
  • system-property: A list of system properties to set on this server.

8.4.3. Start and Stop Servers

You can perform operations on servers, such as starting, stopping, and reloading, from the management console by navigating to the Runtime tab and selecting the appropriate host or server group.

See the below commands for performing these operations using the management CLI.

Start Servers

You can start a single server on a particular host.

/host=HOST_NAME/server-config=SERVER_NAME:start

You can start all servers in a specified server group.

/server-group=SERVER_GROUP_NAME:start-servers
Stop Servers

You can stop a single server on a particular host.

/host=HOST_NAME/server-config=SERVER_NAME:stop

You can stop all servers in a specified server group.

/server-group=SERVER_GROUP_NAME:stop-servers
Reload Servers

You can reload a single server on a particular host.

/host=HOST_NAME/server-config=SERVER_NAME:reload

You can reload all servers in a specified server group.

/server-group=SERVER_GROUP_NAME:reload-servers
Kill Servers

You can kill all server processes in a specified server group.

/server-group=SERVER_GROUP_NAME:kill-servers

8.5. Domain Controller Discovery and Failover

When setting up a managed domain, each host controller must be configured with information needed to contact the domain controller. In JBoss EAP, each host controller can be configured with multiple options for finding the domain controller. Host controllers iterate through the list of options until one succeeds.

A backup host controller can be promoted to domain contoller if there is a problem with the primary domain controller. This allows host controllers to automatically fail over to the new domain controller once it has been promoted.

8.5.1. Configure Domain Discovery Options

The following is an example of how to configure a host controller with multiple options for finding the domain controller.

Example: A Host Controller with Multiple Domain Controller Options

<domain-controller>
  <remote security-realm="ManagementRealm">
    <discovery-options>
      <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="172.16.81.100" port="${jboss.domain.master.port:9990}"/>
      <static-discovery name="backup" protocol="${jboss.domain.master.protocol:remote}" host="172.16.81.101" port="${jboss.domain.master.port:9990}"/>
    </discovery-options>
  </remote>
</domain-controller>

A static discovery option includes the following required attributes:

name
The name for this domain controller discovery option.
host
The remote domain controller’s host name.
port
The remote domain controller’s port.

In the example above, the first discovery option is the one expected to succeed. The second can be used in failover situations.

8.5.2. Start a Host Controller with a Cached Domain Configuration

A host controller can be started without a connection to the domain controller by using the --cached-dc option; however, the host controller must have previously cached its domain configuration locally from the domain controller. Starting a host controller with this --cached-dc option will cache the host controller’s domain configuration from the domain controller.

$ EAP_HOME/bin/domain.sh --host-config=host-slave.xml --cached-dc

This creates a domain.cached-remote.xml file in the EAP_HOME/domain/configuration/ directory that contains the information necessary for this host controller to temporarily manage its current servers without a domain controller connection.

Note

By default, using the --cached-dc option only caches configuration used by this host controller, which means that it cannot be promoted to domain controller for the entire domain. See Cache the Domain Configuration for information on caching the entire domain configuration to allow a host controller to act as the domain controller.

If the domain controller is unavailable when starting this host controller with --cached-dc, the host controller will start using the cached configuration saved in the domain.cached-remote.xml file. Note that this file must exist or the host controller will fail to start.

While in this state, the host controller cannot modify the domain configuration, but can launch servers and manage deployments.

Once started with the cached configuration, the host controller will continue to attempt to reconnect to the domain controller. Once the domain controller becomes available, the host controller will automatically reconnect to it and synchronize the domain configuration. Note that some configuration changes may require you to reload the host controller to take effect. A warning will be logged on the host controller if this occurs.

8.5.3. Promote a Host Controller to Act as Domain Controller

You can promote a host controller to act as the domain controller if a problem arises with the primary domain controller. The host controller must first cache the domain configuration locally from the domain controller before it can be promoted.

Cache the Domain Configuration

Use the --backup option for any host controller that you might want to become the domain controller.

$ EAP_HOME/bin/domain.sh --host-config=host-slave.xml --backup

This creates a domain.cached-remote.xml file in the EAP_HOME/domain/configuration/ directory that contains a copy of the entire domain configuration. This configuration will be used if the host controller is reconfigured to act as the domain controller.

Note

The ignore-unused-configuration attribute is used to determine how much configuration to cache for a particular host. A value of true means that only the configuration relevant to this host controller is cached, which would not allow it to take over as domain controller. A value of false means that the entire domain configuration is cached.

The --backup argument defaults this attribute to false to cache the entire domain. However, if you set this attribute in the host.xml file, that value is used.

You can also use the --cached-dc option alone to create a copy of the domain configuration, but must set ignore-unused-configuration to false in the host.xml to cache the entire domain. For example:

<domain-controller>
  <remote username="$local" security-realm="ManagementRealm" ignore-unused-configuration="false">
    <discovery-options>
      ...
    </discovery-options>
  </remote>
</domain-controller>
Promote a Host Controller to Be the Domain Controller
  1. Ensure the original domain controller is stopped.
  2. Use the management CLI to connect to the host controller that is to become the new domain controller.
  3. Execute the following command to configure the host controller to act as the new domain controller.

    /host=backup:write-attribute(name=domain-controller.local, value={})
  4. Execute the following command to reload the host controller.

    reload --host=HOST_NAME

This host controller will now act as the domain controller.

8.6. Managed Domain Setups

8.6.1. Set Up a Managed Domain on a Single Machine

You can run multiple host controllers on a single machine by using the jboss.domain.base.dir property.

Important

It is not supported to configure more than one JBoss EAP host controller as a system service on a single machine.

  1. Copy the EAP_HOME/domain directory for the domain controller.

    $ cp -r EAP_HOME/domain /path/to/domain1
  2. Copy the EAP_HOME/domain directory for a host controller.

    $ cp -r EAP_HOME/domain /path/to/host1
  3. Start the domain controller using /path/to/domain1.

    $ EAP_HOME/bin/domain.sh --host-config=host-master.xml -Djboss.domain.base.dir=/path/to/domain1
  4. Start the host controller using /path/to/host1.

    $ EAP_HOME/bin/domain.sh --host-config=host-slave.xml -Djboss.domain.base.dir=/path/to/host1 -Djboss.domain.master.address=IP_ADDRESS -Djboss.management.http.port=PORT
    Note

    When starting a host controller, you must specify the address of the domain controller using the jboss.domain.master.address property.

    Additionally, since this host controller is running on the same machine as the domain controller, you must change the management interface so that it does not conflict with the domain controller’s management interface. This command sets the jboss.management.http.port property.

Each instance started in this manner will share the rest of the resources in the base installation directory, for example, EAP_HOME/modules/, but use the domain configuration from the directory specified by jboss.domain.base.dir.

8.6.2. Set Up a Managed Domain on Two Machines

Note

You may need to configure your firewall to run this example.

You can create managed domain on two machines, where one machine is a domain controller and the other machine is a host. For more information, see About the Domain Controller.

  • IP1 = IP address of the domain controller (Machine 1)
  • IP2 = IP address of the host (Machine 2)
Create a Managed Domain on Two Machines
  1. On Machine 1

    1. Add a management user so that the host can be authenticated by the domain controller.

      Use the add-user.sh script to add the management user for the host controller, HOST_NAME. Make sure to answer yes to the last prompt and note the secret value provided. This secret value will be used in the host controller configuration, and will appear similar to the line below:

      <secret value="SECRET_VALUE" />
    2. Start the domain controller.

      Specify the host-master.xml configuration file, which is preconfigured for a dedicated domain controller. Also, set the jboss.bind.address.management property to make the domain controller visible to other machines.

      $ EAP_HOME/bin/domain.sh --host-config=host-master.xml -Djboss.bind.address.management=IP1
  2. On Machine 2

    1. Update the host configuration with the user credentials.

      Edit EAP_HOME/domain/configuration/host-slave.xml and set the host name, HOST_NAME, and secret value, SECRET_VALUE.

      <host xmlns="urn:jboss:domain:8.0" name="HOST_NAME">
        <management>
          <security-realms>
            <security-realm name="ManagementRealm">
              <server-identities>
                <secret value="SECRET_VALUE" />
              </server-identities>
              ...
    2. Start the host controller.

      Specify the host-slave.xml configuration file, which is preconfigured for a slave host controller. Also, set the jboss.domain.master.address property to connect to the domain controller and the jboss.bind.address property to set the host controller bind address.

      $ EAP_HOME/bin/domain.sh --host-config=host-slave.xml  -Djboss.domain.master.address=IP1  -Djboss.bind.address=IP2

You can now manage the domain from the management CLI by specifying the domain controller address with the --controller parameter when launching.

$ EAP_HOME/bin/jboss-cli.sh --connect --controller=IP1

Or you can manage the domain from the management console at http://IP1:9990.

8.7. Managing Multiple JBoss EAP Versions

The latest version of JBoss EAP can manage JBoss EAP servers and host that are running an earlier version. See the appropriate section depending on which versions of JBoss EAP you need to manage.

8.7.1. Configure a JBoss EAP 7.x Domain Controller to Administer JBoss EAP 6 Instances

A JBoss EAP 7.1 domain controller can manage hosts and servers running JBoss EAP 6 as long as they are JBoss EAP 6.2 or later.

Note

For a JBoss EAP 7.0 domain controller managing JBoss EAP 7.0 hosts that are on a different patch release, there are no configuration changes needed. However, the JBoss EAP 7.0 domain controller must be running a patch release that is equal to or higher than the versions on the host controllers that it manages.

Complete the following tasks to successfully manage JBoss EAP 6 instances in a JBoss EAP 7 managed domain.

Once these tasks are complete, you can manage your JBoss EAP 6 servers and configurations from the JBoss EAP 7 domain controller using the management CLI. Note that JBoss EAP 6 hosts will not be able to take advantage of new JBoss EAP 7 features, such as batch processing.

Warning

Because the management console is optimized for the latest version of JBoss EAP, you should not use it to update your JBoss EAP 6 hosts, servers, and profiles. Use the management CLI instead when managing your JBoss EAP 6 configurations from a JBoss EAP 7 managed domain.

8.7.1.1. Add the JBoss EAP 6 Configuration to the JBoss EAP 7 Domain Controller

To allow the domain controller to manage your JBoss EAP 6 servers, you must provide the JBoss EAP 6 configuration details in the JBoss EAP 7 domain configuration. You can do this by copying the JBoss EAP 6 profiles, socket binding groups, and server groups to the JBoss EAP 7 domain.xml configuration file.

You will need to rename resources if any conflict with the existing names in the JBoss EAP 7 configuration. There are also some additional adjustments to make to ensure the proper behavior.

The following procedure uses the JBoss EAP 6 default profile, standard-sockets socket binding group, and main-server-group server group.

  1. Edit the JBoss EAP 7 domain.xml configuration file. It is recommended to back up this file before editing.
  2. Copy the applicable JBoss EAP 6 profiles to the JBoss EAP 7 domain.xml file.

    This procedure assumes that the JBoss EAP 6 default profile was copied and renamed to eap6-default.

    JBoss EAP 7 domain.xml

    <profiles>
      ...
      <profile name="eap6-default">
        ...
      </profile>
    </profiles>

  3. Add the necessary extensions used by this profile.

    If your JBoss EAP 6 profile uses subsystems that are no longer present in JBoss EAP 7, you must add the appropriate extensions to the JBoss EAP domain configuration.

    JBoss EAP 7 domain.xml

    <extensions>
      ...
      <extension module="org.jboss.as.configadmin"/>
      <extension module="org.jboss.as.threads"/>
      <extension module="org.jboss.as.web"/>
    <extensions>

  4. Copy the applicable JBoss EAP 6 socket binding groups to the JBoss EAP 7 domain.xml file.

    This procedure assumes that the JBoss EAP 6 standard-sockets socket binding group was copied and renamed to eap6-standard-sockets.

    JBoss EAP 7 domain.xml

    <socket-binding-groups>
      ...
      <socket-binding-group name="eap6-standard-sockets" default-interface="public">
        ...
      </socket-binding-group>
    </socket-binding-groups>

  5. Copy the applicable JBoss EAP 6 server groups to the JBoss EAP 7 domain.xml file.

    This procedure assumes that the JBoss EAP 6 main-server-group server group was copied and renamed to eap6-main-server-group. You must also update this server group to use the JBoss EAP 6 profile, eap6-default, and the JBoss EAP 6 socket binding group, eap6-standard-sockets.

    JBoss EAP 7 domain.xml

    <server-groups>
      ...
      <server-group name="eap6-main-server-group" profile="eap6-default">
        ...
        <socket-binding-group ref="eap6-standard-sockets"/>
      </server-group>
    </server-groups>

8.7.1.2. Update the Behavior for the JBoss EAP 6 Profiles

Additional updates to the profiles used by your JBoss EAP 6 instances are necessary depending on the JBoss EAP version and desired behavior. You may require additional changes depending on the subsystems and configuration that your existing JBoss EAP 6 instances use.

Start the JBoss EAP 7 domain controller and launch its management CLI to perform the following updates. These examples assume that the JBoss EAP 6 profile is eap6-default.

  • Remove the bean-validation subsystem.

    JBoss EAP 7 moved bean validation functionality from the ee subsystem into its own subsystem, bean-validation. If a JBoss EAP 7 domain controller sees a legacy ee subsystem, it adds the new bean-validation subsystem. However, the JBoss EAP 6 hosts will not recognize this subsystem, so it must be removed.

    JBoss EAP 7 Domain Controller CLI

    /profile=eap6-default/subsystem=bean-validation:remove

  • Set CDI 1.0 behavior.

    This is only necessary if you want CDI 1.0 behavior for your JBoss EAP 6 servers, as opposed to behavior of later CDI versions used in JBoss EAP 7. If you want CDI 1.0 behavior, make the following updates to the weld subsystem.

    JBoss EAP 7 Domain Controller CLI

    /profile=eap6-default/subsystem=weld:write-attribute(name=require-bean-descriptor,value=true)
    
    /profile=eap6-default/subsystem=weld:write-attribute(name=non-portable-mode,value=true)

  • Enable datasource statistics for JBoss EAP 6.2.

    This is only necessary if your profile is being used by JBoss EAP 6.2 servers. JBoss EAP 6.3 introduced the statistics-enabled attribute, which defaults to false to not collect statistics; however, the JBoss EAP 6.2 behavior was to collect statistics. If this profile is used by a JBoss EAP 6.2 host and a host running a newer JBoss EAP version, the behavior would be inconsistent between hosts, which is not allowed. Therefore, profiles intended for use by a JBoss EAP 6.2 host should make the following change for their datasources.

    JBoss EAP 7 Domain Controller CLI

    /profile=eap6-default/subsystem=datasources/data-source=ExampleDS:write-attribute(name=statistics-enabled,value=true)

8.7.1.3. Set the Server Group for the JBoss EAP 6 Servers

If you renamed the server groups, you need to update the JBoss EAP 6 host configuration to use the new server groups specified in the JBoss EAP 7 configuration. This example uses the eap6-main-server-group server group specified in the JBoss EAP 7 domain.xml.

JBoss EAP 6 host-slave.xml

<servers>
    <server name="server-one" group="eap6-main-server-group"/>
    <server name="server-two" group="eap6-main-server-group">
        <socket-bindings port-offset="150"/>
    </server>
</servers>

Note

A host cannot use features or configuration settings that were introduced in a newer version of JBoss EAP than the one the host is running.

8.7.1.4. Prevent the JBoss EAP 6 Instances from Receiving JBoss EAP 7 Updates

The domain controller in a managed domain forwards configuration updates to its host controllers. You must use the host-exclude configuration to specify the resources that should be hidden from particular versions. Choose the appropriate preconfigured host-exclude option for your JBoss EAP 6 version: EAP62, EAP63, EAP64, or EAP64z.

The active-server-groups attribute of the host-exclude configuration specifies the list of server groups that are used by a particular version. These server groups and their associated profiles, socket binding groups, and deployment resources will be available to hosts of this version, but all others will be hidden from these hosts.

This example assumes that the version is JBoss EAP 6.4.z and adds the JBoss EAP 6 server group eap6-main-server-group as an active server group.

JBoss EAP 7 Domain Controller CLI

/host-exclude=EAP64z:write-attribute(name=active-server-groups,value=[eap6-main-server-group])

If necessary, you can specify additional socket binding groups used by your servers using the active-socket-binding-groups attribute. This is only required for socket binding groups that are not associated with the server groups specified in active-server-groups.

8.7.2. Configure a JBoss EAP 7.3 Domain Controller to Administer Previous Minor Releases of JBoss EAP

A JBoss EAP 7.3 domain controller can manage hosts and servers running from a previous minor release of JBoss EAP.

Note

For a JBoss EAP 7.3 domain controller managing JBoss EAP 7.2 hosts that are on a different patch release, you do not need to make any configuration changes. However, you must run the JBoss EAP 7.2 domain controller on a patch release that is equal to or higher than the versions on the host controllers that it manages.

Complete the following tasks to successfully manage JBoss EAP 7.2 instances in a JBoss EAP 7.3 managed domain.

After you complete these tasks, you can manage your JBoss EAP 7.2 servers and configurations from the JBoss EAP 7.3 domain controller using the management CLI.

Warning

Because the management console is optimized for the latest version of JBoss EAP, you must use the CLI to manage your JBoss EAP 7.2 configurations from a JBoss EAP 7.3 managed domain. Do not use the management console to update JBoss EAP 7.2 hosts, servers, and profiles.

8.7.2.1. Add the JBoss EAP 7.2 Configuration to the JBoss EAP 7.3 Domain Controller

To enable the domain controller to manage your JBoss EAP 7.2 servers, you must provide the JBoss EAP 7.2 configuration details in the JBoss EAP 7.3 domain configuration. You can do this by copying the JBoss EAP 7.2 profiles, socket binding groups, and server groups to the JBoss EAP 7.3 domain.xml configuration file.

You must rename a resource if its name conflicts with resource names in the JBoss EAP 7.3 configuration.

The following procedure uses the JBoss EAP 7.2 default profile, standard-sockets socket binding group, and main-server-group server group.

Prerequisites

  • You have copied and renamed the JBoss EAP 7.2 default profile to eap72-default.
  • You have copied and renamed the JBoss EAP 7.2 standard-sockets socket binding group to eap72-standard-sockets.
  • You have copied and renamed the JBoss EAP 7.2 main-server-group server group to eap72-main-server-group.

    • You have updated the server group to use the JBoss EAP 7.2 profile, eap72-default, and to use the JBoss EAP 7.2 socket binding group, eap72-standard-sockets.

Procedure

  1. Edit the JBoss EAP 7.3 domain.xml configuration file.

    Important

    Back up the JBoss EAP 7.3 domain.xml configuration file before you edit the file.

  2. Copy the applicable JBoss EAP 7.2 profiles to the JBoss EAP 7.3 domain.xml file. For example:

    <profiles>
      ...
      <profile name="eap72-default">
        ...
      </profile>
    </profiles>
  3. Copy the applicable JBoss EAP 7.2 socket binding groups to the JBoss EAP 7.3 domain.xml file. For example:

    <socket-binding-groups>
      ...
      <socket-binding-group name="eap72-standard-sockets" default-interface="public">
        ...
      </socket-binding-group>
    </socket-binding-groups>
  4. Copy the applicable JBoss EAP 7.2 server groups to the JBoss EAP 7.3 domain.xml file. For example:

    <server-groups>
      ...
      <server-group name="eap72-main-server-group" profile="eap72-default">
        ...
        <socket-binding-group ref="eap72-standard-sockets"/>
      </server-group>
    </server-groups>

8.7.2.2. Set the Server Group for the JBoss EAP7.2 Servers

If you renamed the server groups, you need to update the JBoss EAP 7.2 host configuration to use the new server groups specified in the JBoss EAP 7.3 configuration. This example uses the eap72-main-server-group server group specified in the JBoss EAP 7.3 domain.xml.

JBoss EAP 7.2 host-slave.xml

<servers>
    <server name="server-one" group="eap72-main-server-group"/>
    <server name="server-two" group="eap72-main-server-group">
        <socket-bindings port-offset="150"/>
    </server>
</servers>

Note

A host cannot use features or configuration settings that were introduced in a newer version of JBoss EAP than the one the host is running.

8.7.2.3. Prevent the JBoss EAP 7.2 Instances from Receiving JBoss EAP 7.3 Updates

A managed domain controller forwards configuration updates to its host controllers, so that a JBoss EAP 7.2 host does not receive configuration and resources that are specific to JBoss EAP 7.3. You must configure the JBoss EAP 7.2 host to ignore those resources. You can do this by setting the ignore-unused-configuration attribute on the JBoss EAP 7.2 host.

Note

You can also use the host-exclude configuration to instruct the domain controller to hide certain resources from hosts running certain JBoss EAP versions. For an example of how to use the host-exclude configuration, see Prevent the JBoss EAP 6 Instances from Receiving JBoss EAP 7 Updates. For JBoss EAP 7.2, you use the EAP72 host-exclude option.

Set the ignore-unused-configuration attribute to true in the JBoss EAP 7.2 host controller connection configuration to the remote domain controller.

JBoss EAP 7.2 host-slave.xml

<domain-controller>
    <remote security-realm="ManagementRealm" ignore-unused-configuration="true">
        <discovery-options>
            <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9990}"/>
        </discovery-options>
    </remote>
</domain-controller>

With this setting, only the server groups used by this host, and their associated profiles, socket binding groups, and deployment resources, are made available to the host. All other resources are ignored.

8.8. Managing JBoss EAP Profiles

8.8.1. About Profiles

JBoss EAP uses profiles as a way to organize which subsystems are available to a server. A profile consists of a collection of available subsystems along with each subsystem’s specific configuration. A profile with a large number of subsystems results in a server with a large set of capabilities. A profile with a small, focused set of subsystems will have fewer capabilities but a smaller footprint.

JBoss EAP comes with five predefined profiles that should satisfy most use cases:

default
Includes commonly used subsystems, such as logging, security, datasources, infinispan, webservices, ee, ejb3, transactions, and so on.
ha
Includes the subsystems provided in the default profile with the addition of the jgroups and modcluster subsystems for high availability
full
Includes the subsystems provided in the default profile with the addition of the messaging-activemq and iiop-openjdk subsystems
full-ha
Includes the subsystems provided in the full profile with the addition of the jgroups and modcluster subsystems for high availability
load-balancer
Includes the minimum subsystems necessary to use the built-in mod_cluster front-end load balancer to load balance other JBoss EAP instances.
Note

JBoss EAP offers the ability to disable extensions or unload drivers and other services manually by removing the subsystems from the configuration of existing profiles. However, for most cases this is unnecessary. Since JBoss EAP dynamically loads subsystems as they are needed, if the server or an application never use a subsystem, it will not be loaded.

In cases where the existing profiles do not provide the necessary capabilities, JBoss EAP also provides the ability to define custom profiles as well.

8.8.2. Cloning a Profile

JBoss EAP allows you to create a new profile in a managed domain by cloning an existing profile. This will create a copy of the original profile’s configuration and subsystems.

A profile can be cloned using the management CLI by using the clone operation on the desired profile to clone.

/profile=full-ha:clone(to-profile=cloned-profile)

You can also clone a profile from the management console by selecting the desired profile to clone and clicking Clone.

8.8.3. Creating Hierarchical Profiles

In a managed domain, you can create a hierarchy of profiles. This allows you to create a base profile with common extensions that other profiles can inherit.

The managed domain defines several profiles in domain.xml. If multiple profiles use the same configuration for a particular subsystem, you can configure it in just one place instead of different profiles. The values in parent profiles cannot be overridden.

In addition, each profile must be self-sufficient. If an element or subsystem is referenced, then it must be defined in the profile where it is referenced.

A profile can include other profiles in a hierarchy using the management CLI by using the list-add operation and providing the profile to include.

/profile=new-profile:list-add(name=includes, value=PROFILE_NAME)

Chapter 9. Configuring JVM Settings

Configuration of Java Virtual Machine (JVM) settings is different for a standalone JBoss EAP server, or a JBoss EAP server in a managed domain.

For a standalone JBoss EAP server instance, the server startup processes pass JVM settings to the JBoss EAP server at startup. These can be declared from the command line before launching JBoss EAP, or using the System Properties page under Configuration in the management console.

In a managed domain, JVM settings are declared in the host.xml and domain.xml configuration files, and can be configured at host, server group, or server levels.

Note

System properties must be configured in JAVA_OPTS to be used by JBoss EAP modules (such as the logging manager) during startup.

9.1. Configuring JVM Settings for a Standalone Server

JVM settings for standalone JBoss EAP server instances can be declared at runtime by setting the JAVA_OPTS environment variable before starting the server.

An example of setting the JAVA_OPTS environment variable on Linux is shown below.

$ export JAVA_OPTS="-Xmx1024M"

The same setting can be used in a Microsoft Windows environment:

set JAVA_OPTS="Xmx1024M"

Alternatively, JVM settings can be added to the standalone.conf file, or standalone.conf.bat for Windows Server, in the EAP_HOME/bin folder, which contains examples of options to pass to the JVM.

Warning

Setting the JAVA_OPTS environment variable will override the default values from standalone.conf, which may cause JBoss EAP startup issues.

9.2. Configuring JVM Settings for a Managed Domain

In a JBoss EAP managed domain, you can define JVM settings at multiple levels. You can define custom JVM settings on a particular host, and then apply those settings to server groups, or to individual server instances.

By default, server groups and individual servers will inherit the JVM settings from their parent, but you can choose to override JVM settings at each level.

Note

The JVM settings in domain.conf, or domain.conf.bat for Windows Server, are applied to the Java process of the JBoss EAP host controller, and not the individual JBoss EAP server instances controlled by that host controller.

9.2.1. Defining JVM Settings on a Host Controller

You can define JVM settings on a host controller, and apply those settings to server groups or individual servers. JBoss EAP comes with a default JVM setting, but the following management CLI command demonstrates creating a new JVM setting named production_jvm with some custom JVM settings and options.

/host=HOST_NAME/jvm=production_jvm:add(heap-size=2048m, max-heap-size=2048m, max-permgen-size=512m, stack-size=1024k, jvm-options=["-XX:-UseParallelGC"])

See Managed Domain JVM Configuration Attributes for descriptions of all available options.

You can also create and edit JVM settings in the JBoss EAP management console by navigating to RuntimeHosts, choosing a host and clicking View, and selecting the JVMs tab.

These settings are stored in the within the <jvm> tag in host.xml.

9.2.2. Applying JVM Settings to a Server Group

When creating a server group, you can specify a JVM configuration that all servers in the group will use. The following management CLI commands demonstrate creating a server group name groupA that uses the production_jvm JVM settings that were shown in the previous example.

/server-group=groupA:add(profile=default, socket-binding-group=standard-sockets)
/server-group=groupA/jvm=production_jvm:add

All servers in the server group will inherit JVM settings from production_jvm.

You can also override specific JVM settings at the server group level. For example, to set a different heap size, you can use the following command:

/server-group=groupA/jvm=production_jvm:write-attribute(name=heap-size,value="1024m")

After applying the above command, the server group groupA will inherit the JVM settings from production_jvm, except for the heap size which has an overridden value of 1024m.

See Managed Domain JVM Configuration Attributes for descriptions of all available options.

You can also edit server group JVM settings in the JBoss EAP management console by navigating to RuntimeServer Groups, choosing a server group and clicking View, and selecting the JVMs tab.

These settings for a server group are stored in domain.xml.

9.2.3. Applying JVM Settings to an Individual Server

By default, an individual JBoss EAP server instance will inherit the JVM settings of the server group it belongs to. However, you can choose to override the inherited settings with another complete JVM setting definition from the host controller, or choose to override specific JVM settings.

For example, the following command overrides the JVM definition of the server group in the previous example, and sets the JVM settings for server-one to the default JVM definition:

/host=HOST_NAME/server-config=server-one/jvm=default:add

Also, similar to server groups, you can override specific JVM settings at the server level. For example, to set a different heap size, you can use the following command:

/host=HOST_NAME/server-config=server-one/jvm=default:write-attribute(name=heap-size,value="1024m")

See Managed Domain JVM Configuration Attributes for descriptions of all available options.

You can also edit server JVM settings in the JBoss EAP management console by navigating to RuntimeHosts, choosing the host, clicking View on the server, and selecting the JVMs tab.

These settings for an individual server are stored in host.xml.

9.3. Displaying the JVM Status

You can view the status of JVM resources, such as heap and thread usage, for standalone or managed domain servers from the management console. While statistics are not displayed in real time, you can click Refresh to provide an up-to-date overview of JVM resources.

To display the JVM status for a standalone JBoss EAP server:

  • Navigate to the Runtime tab, select the server, and select Status.

To display the JVM status for a JBoss EAP server in a managed domain:

  • Navigate to RuntimeHosts, select the host and server, and select Status.

This shows the following heap usage information:

Max
The maximum amount of memory that can be used for memory management.
Used
The amount of used memory.
Committed
The amount of memory that is committed for the Java Virtual Machine to use.

Other information, such as JVM uptime and thread usage, is also available.

9.4. Tuning the JVM

For tips on optimizing JVM performance, see the JVM Tuning section of the Performance Tuning Guide.

Chapter 10. Mail Subsystem

10.1. Configuring the Mail Subsystem

The mail subsystem allows you to configure mail sessions in JBoss EAP and then inject those sessions into applications using JNDI. It also supports configuration using the Jakarta EE @MailSessionDefinition and @MailSessionDefinitions annotations.

Configuring SMTP server for use in an application

  1. Configure the SMTP server and the outbound socket binding using the following CLI commands, for example:

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp:add(host=localhost, port=25)
    /subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
    /subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp, username=user, password=pass, tls=true)
  2. Call the configured mail session within an application

    @Resource(lookup="java:jboss/mail/MySession")
    private Session session;

For a full list of the attributes available for configuring mail sessions and servers, see Mail Subsystem Attributes.

10.2. Configuring Custom Transports

When using a standard mail server, such as POP3 or IMAP, the mail server has a set of attributes that can be defined. Some of these attributes are mandatory. The most important of these is the outbound-socket-binding-ref, which is a reference to the outbound mail socket binding and is defined with a host address and port number.

Defining the outbound-socket-binding-ref may not be the most effective solution for users who have their host configuration using multiple hosts for load balancing purposes. Standard Jakarta Mail does not support host configuration using multiple hosts for load balancing. Therefore, users who have this configuration using multiple hosts are required to implement custom mail transports. These custom mail transports do not require the outbound-socket-binding-ref and allow custom host property formats.

You can configure custom mail transports from the management CLI.

  1. Add a new mail session and specify the JNDI name.

    /subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
  2. Add an outbound socket binding and specify the host and port.

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp-binding:add(host=localhost, port=25)
  3. Add an SMTP server and specify the outbound socket binding, username, and password.

    /subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp-binding, username=user, password=pass, tls=true)
Note

You can configure a POP3 or IMAP server using similar steps.

POP3 Server

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-pop3-binding:add(host=localhost, port=110)
/subsystem=mail/mail-session=mySession/server=pop3:add(outbound-socket-binding-ref=my-pop3-binding, username=user, password=pass)

IMAP Server

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-imap-binding:add(host=localhost, port=143)
/subsystem=mail/mail-session=mySession/server=imap:add(outbound-socket-binding-ref=my-imap-binding, username=user, password=pass)

To use a custom server, create a custom mail server without an outbound socket binding. You can specify the host information in the properties definition of the custom mail server. For example:

/subsystem=mail/mail-session=mySession/custom=myCustomServer:add(username=user,password=pass, properties={"host" => "myhost", "my-property" =>"value"})

If you define a custom protocol, any property name that includes a period (.) is considered a fully-qualified name and is passed directly. Any other format, such as my-property, is translated in the following format: mail.server-name.my-property.

The following XML is an example mail configuration that includes custom servers.

<subsystem xmlns="urn:jboss:domain:mail:3.0">
   <mail-session name="default" jndi-name="java:jboss/mail/Default">
        <smtp-server outbound-socket-binding-ref="mail-smtp"/>
   </mail-session>
    <mail-session name="myMail" from="user.name@domain.org" jndi-name="java:/Mail">
        <smtp-server password="password" username="user" tls="true" outbound-socket-binding-ref="mail-smtp"/>
        <pop3-server outbound-socket-binding-ref="mail-pop3"/>
        <imap-server password="password" username="nobody" outbound-socket-binding-ref="mail-imap"/>
    </mail-session>
    <mail-session name="custom" jndi-name="java:jboss/mail/Custom" debug="true">
        <custom-server name="smtp" password="password" username="username">
            <property name="host" value="mail.example.com"/>
        </custom-server>
    </mail-session>
    <mail-session name="custom2" jndi-name="java:jboss/mail/Custom2" debug="true">
        <custom-server name="pop3" outbound-socket-binding-ref="mail-pop3">
            <property name="custom-prop" value="some-custom-prop-value"/>
        </custom-server>
    </mail-session>
</subsystem>

10.3. Use a Credential Store for Passwords

In addition to providing clear-text passwords in the mail subsystem, you can also use a credential store to provide passwords. The elytron subsystem provides the ability to create credential stores to securely house and use your passwords throughout JBoss EAP. You can find more details on creating and using credential stores in the Credential Store section of How to Configure Server Security.

Using a Credential Store Using the Management CLI

/subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp-binding, username=user, credential-reference={store=exampleCS, alias=mail-session-pw}, tls=true)

Note

The following is an example of how to specify a credential-reference attribute that uses a clear-text password.

credential-reference={clear-text="MASK-Ewcyuqd/nP9;A1B2C3D4;351"}

Using a Credential Store Using the Management Console

  1. Access the management console. For more information, see the Management Console.
  2. Navigate to ConfigurationSubsystemsMail.
  3. Select the appropriate mail session and click View.
  4. Select Server and choose the appropriate mail session server. You can configure the credential reference in the Credential Reference tab and edit other attributes in the Attributes tab.

Chapter 11. Logging with JBoss EAP

JBoss EAP provides highly-configurable logging facilities for both its own internal use and for use by deployed applications. The logging subsystem is based on JBoss LogManager and supports several third-party application logging frameworks in addition to JBoss Logging.

11.1. About Server Logging

11.1.1. Server Logging

By default, all JBoss EAP log entries are written to the server.log file. The location of this file depends on your operating mode.

  • Standalone server: EAP_HOME/standalone/log/server.log
  • Managed domain: EAP_HOME/domain/servers/SERVER_NAME/log/server.log

This file is often referred to as the server log. For more information, see the Root Logger section.

11.1.2. Bootup Logging

During bootup, JBoss EAP logs information about the Java environment and the startup of each service. This log can be useful when troubleshooting. By default, all log entries are written to the server log.

Bootup logging configuration is specified in the logging.properties configuration file, which is active until the JBoss EAP logging subsystem is started and takes over. The location of this file depends on your operating mode.

  • Standalone server: EAP_HOME/standalone/configuration/logging.properties
  • Managed domain:

    There is a logging.properties file for the domain controller and for each server.

    • Domain controller: EAP_HOME/domain/configuration/logging.properties
    • Server: EAP_HOME/domain/servers/SERVER_NAME/data/logging.properties
Warning

It is recommended that you do not directly edit the logging.properties file unless you know of a specific use case that requires it. Before doing so, it is recommended that you open a support case from the Red Hat Customer Portal.

Changes made manually to the logging.properties file are overwritten on startup.

11.1.2.1. View Bootup Errors

When troubleshooting JBoss EAP, checking for errors that occurred during bootup should be one of the first steps taken. You can then use the information provided to diagnose and resolve their causes. Open a support case for assistance in troubleshooting bootup errors.

There are two methods of viewing bootup errors, each with its advantages. You can examine the server.log file or read the boot errors using the read-boot-errors management CLI command.

Examine the Server Log File

You can open the server.log file to view any errors that occurred during bootup.

This method allows you to see each error message together with possibly related messages, allowing you to get more information about why an error might have occurred. It also allows you to see error messages in plain text format.

  1. Open the file server.log in a file viewer.
  2. Navigate to the end of the file.
  3. Search backward for the WFLYSRV0049 message identifier, which marks the start of the latest bootup sequence.
  4. Search the log from that point onward for instances of ERROR. Each instance will include a description of the error and list the modules involved.

The following is an example error description from the server.log log file.

2016-03-16 14:32:01,627 ERROR [org.jboss.msc.service.fail] (MSC service thread 1-7) MSC000001: Failed to start service jboss.undertow.listener.default: org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
        at org.wildfly.extension.undertow.ListenerService.start(ListenerService.java:142)
        at org.jboss.msc.service.ServiceControllerImpl$StartTask.startService(ServiceControllerImpl.java:1948)
        at org.jboss.msc.service.ServiceControllerImpl$StartTask.run(ServiceControllerImpl.java:1881)
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
        at java.lang.Thread.run(Thread.java:745)
Caused by: java.net.BindException: Address already in use
        ...
Read the Boot Errors from the Management CLI

You can use the read-boot-errors management CLI command to view errors if a server starts but reported errors during bootup.

This method does not require access to the server’s file system, which is useful for anyone responsible for monitoring for errors who does not have file system access. Since it is a management CLI command, it can be used in a script. For example, you could write a script that starts multiple JBoss EAP instances, then checks for errors that occurred on bootup.

Run the following management CLI command.

/core-service=management:read-boot-errors

Any errors that occurred during bootup will be listed.

{
    "outcome" => "success",
    "result" => [
        {
            "failed-operation" => {
                "operation" => "add",
                "address" => [
                    ("subsystem" => "undertow"),
                    ("server" => "default-server"),
                    ("http-listener" => "default")
                ]
            },
            "failure-description" => "{\"WFLYCTL0080: Failed services\" => {\"jboss.undertow.listener.default\" => \"org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
    Caused by: java.net.BindException: Address already in use\"}}",
            "failed-services" => {"jboss.undertow.listener.default" => "org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
    Caused by: java.net.BindException: Address already in use"}
        }
        ...
    ]
}

11.1.3. Garbage Collection Logging

Garbage collection logging logs all garbage collection activity to plain text log files. These log files can be useful for diagnostic purposes. Garbage collection logging is enabled by default for a JBoss EAP standalone server on all supported configurations except IBM Java development kit.

The location of the garbage collection log is EAP_HOME/standalone/log/gc.log.DIGIT.current. Garbage collection logs are limited to 3 MB each, and up to five files are rotated.

It is strongly recommended to leave garbage collection logging enabled as it can be useful in troubleshooting and should have minimal overhead. However, you can disable garbage collection logging for a standalone server by setting the GC_LOG variable to false before starting the server. For example:

$ export GC_LOG=false
$ EAP_HOME/bin/standalone.sh

11.1.4. Default Log File Locations

The following log files are created for the default logging configurations. The default configuration writes the server log files using periodic log handlers.

Table 11.1. Default Log File for a Standalone Server

Log FileDescription

EAP_HOME/standalone/log/server.log

Contains server log messages, including server startup messages.

EAP_HOME/standalone/log/gc.log.DIGIT.current

Contains garbage collection details.

Table 11.2. Default Log Files for a Managed Domain

Log FileDescription

EAP_HOME/domain/log/host-controller.log

Contains log messages related to the startup of the host controller.

EAP_HOME/domain/log/process-controller.log

Contains log messages related to the startup of the process controller.

EAP_HOME/domain/servers/SERVER_NAME/log/server.log

Contains log messages for the named server, including server startup messages.

11.1.5. Set the Default Locale of the Server

You can configure the default locale for JBoss EAP by setting JVM properties in the appropriate startup configuration file. The startup configuration file is EAP_HOME/bin/standalone.conf for a standalone server or EAP_HOME/bin/domain.conf for a managed domain.

Note

For Windows Server, the JBoss EAP startup configuration files are standalone.conf.bat and domain.conf.bat.

Log messages that have been internationalized and localized will use this default locale. See the JBoss EAP Development Guide for information on creating internationalized log messages.

Set the Language

Specify the language by setting the user.language property using the JAVA_OPTS variable. For example, add the following line to the startup configuration file to set a French locale.

JAVA_OPTS="$JAVA_OPTS -Duser.language=fr"

Log messages that have been internationalized and localized will now output in French.

Set the Language and Country

In addition to the language, it may also be necessary to specify the country by setting the user.country property. For example, add the following line to the startup configuration file to set the Portuguese locale for Brazil.

JAVA_OPTS="$JAVA_OPTS -Duser.language=pt -Duser.country=BR"

Log messages that have been internationalized and localized will now output in Brazilian Portuguese.

Set the Server Locale Using the org.jboss.logging.locale Property

You can configure the org.jboss.logging.locale property to override the locale for messages logged using JBoss Logging, including any messages from JBoss EAP and its owned dependencies. Other dependencies, such as JSF, cannot get an overridden locale.

To start the JBoss EAP server with a different locale than the system default, you can edit EAP_HOME/bin/standalone.conf or the EAP_HOME/bin/domain.conf file, depending on your operating mode, and append the following command to set the JVM parameter for the required locale. The value of the property must be specified in the BCP 47 format. For example, to set Brazilian Portuguese, use pt-BR.

JAVA_OPTS="$JAVA_OPTS -Dorg.jboss.logging.locale=pt-BR"

11.2. Viewing Log Files

Viewing server and application logs is important in order to help diagnose errors, performance problems, and other issues. Some users may prefer to view logs directly on the server file system. For those who do not have direct access to the file system, or who prefer a graphical interface, JBoss EAP allows you to view logs from the management console. You can also view logs using the management CLI.

For a log to be accessible from one of the management interfaces, it must be located in the directory specified by the server’s jboss.server.log.dir property and be defined as a file, periodic rotating, size rotating, or periodic size rotating log handler. RBAC role assignments are also honored, so a user logged in to the management console or CLI can only view logs that they are authorized to access.

View Logs from the Management Console

You can view logs directly from the management console.

  1. Select the Runtime tab and select the appropriate server.
  2. Select Log Files and choose a log file from the list.
  3. Click View to view and search log contents, or choose Download from the drop down to download the log file to your local file system.
Warning

The management console log viewer is not intended to be a text editor replacement for viewing very large log files, for example, greater than 100MB. You will be prompted for confirmation if you attempt to open a log file that is larger than 15MB. Opening a very large file in the management console could crash your browser, so you should always download large log files locally and open them in a text editor.

View Logs from the Management CLI

You can read the contents of log files from the management CLI using the read-log-file command. By default, this displays the last 10 lines of the specified log file.

/subsystem=logging/log-file=LOG_FILE_NAME:read-log-file
Note

In a managed domain, precede this command with /host=HOST_NAME/server=SERVER_NAME.

You can use the following parameters to customize the log output.

encoding
The character encoding used to read the file.
lines
The number of lines to read from the file. A value of -1 will read all log lines. The default is 10.
skip
The number of lines to skip before reading. The default is 0.
tail
Whether to read from the end of the file. Defaults to true.

For example, the following management CLI command reads the first 5 lines from the top of the server.log log file.

/subsystem=logging/log-file=server.log:read-log-file(lines=5,tail=false)

This produces the following output.

{
    "outcome" => "success",
    "result" => [
        "2016-03-24 08:49:26,612 INFO  [org.jboss.modules] (main) JBoss Modules version 1.5.1.Final-redhat-1",
        "2016-03-24 08:49:26,788 INFO  [org.jboss.msc] (main) JBoss MSC version 1.2.6.Final-redhat-1",
        "2016-03-24 08:49:26,863 INFO  [org.jboss.as] (MSC service thread 1-7) WFLYSRV0049: JBoss EAP 7.0.0.GA (WildFly Core 2.0.13.Final-redhat-1) starting",
        "2016-03-24 08:49:27,973 INFO  [org.jboss.as.server] (Controller Boot Thread) WFLYSRV0039: Creating http management service using socket-binding (management-http)",
        "2016-03-24 08:49:27,994 INFO  [org.xnio] (MSC service thread 1-1) XNIO version 3.3.4.Final-redhat-1"
    ]
}

11.3. About the Logging Subsystem

The JBoss EAP logging subsystem is configured using a system of log categories and log handlers. Log categories define what messages to capture. Log handlers define how to deal with those messages, for example, writing to a disk or sending to the console.

Logging profiles allow uniquely-named sets of logging configuration to be created and assigned to applications independent of any other logging configuration. The configuration of logging profiles is almost identical to the main logging subsystem.

11.3.1. Root Logger

The JBoss EAP root logger captures all log messages, of the specified log level or higher, sent to the server that are not captured by a log category.

By default, the root logger is configured to use a console and a periodic log handler. The periodic log handler is configured to write to the server.log file. This file is often referred to as the server log.

See Configuring the Root Logger for more information.

11.3.2. Log Categories

A log category defines a set of log messages to capture and one or more log handlers that will process the messages.

The log messages to capture are defined by the specified Java package of origin and log level. Messages from classes in that package and of that log level or higher are captured by the log category and sent to the specified log handlers.

Note

Although the log category is typically the Java package and class name, it can be any name specified by the Logger.getLogger(LOGGER_NAME) method.

Log categories can optionally use the log handlers of the root logger instead of their own handlers.

See Configuring Log Categories for more information.

11.3.3. Log Handlers

Log handlers define how captured log messages are recorded. The available log handler types are console, file, periodic, size, periodic size, syslog, custom, and async.

Note

A log handler must be added to at least one logger in order to be active.

Log Handler Types
Console
A console log handler writes log messages to either the host operating system’s standard out, stdout, or standard error, stderr, stream. These messages are displayed when JBoss EAP is run from a command line prompt. The messages from a console log handler are not saved unless the operating system is configured to capture the standard out or standard error stream.
File
A file log handler writes log messages to a specified file.
Periodic
A periodic log handler writes log messages to a named file until a specified period of time has elapsed. Once the time period has passed, the file is renamed by appending the specified timestamp and the handler continues to write into a newly created log file with the original name.
Size
A size log handler writes log messages to a named file until the file reaches a specified size. When the file reaches a specified size, it is renamed with a numeric suffix and the handler continues to write into a newly created log file with the original name. Each size log handler must specify the maximum number of files to be kept in this fashion.
Periodic Size

A periodic size log handler writes log messages to a named file until the file reaches the specified size or the specified time period has passed. Then, the file is renamed and the handler continues to write to a newly created log file with the original name.

This is a combination of the periodic and size log handlers and supports their combined attributes.

Syslog
A syslog handler can be used to send messages to a remote logging server. This allows multiple applications to send their log messages to the same server, where they can all be parsed together.
Socket
A socket log handler can be used to send log messages over a socket to a remote logging server. This can be a TCP or UDP socket.
Custom
A custom log handler enables you to configure new types of log handlers that have been implemented. A custom handler must be implemented as a Java class that extends java.util.logging.Handler and be contained in a module. You can also use a Log4J appender as a custom log handler.
Async
An async log handler is a wrapper log handler that provides asynchronous behavior for one or more other log handlers. This is useful for log handlers that may have high latency or other performance problems such as writing a log file to a network file system.

For details on configuring each of these log handlers, see the Configuring Log Handlers section.

11.3.4. Log Levels

A log level is an enumerated value that indicates the nature and severity of a log message. As a developer, you can specify the level of a given log message using the appropriate method of your chosen logging framework to send the message.

JBoss EAP supports all the log levels used by the supported application logging frameworks. The most commonly used log levels from lowest to highest are TRACE, DEBUG, INFO, WARN, ERROR, and FATAL.

Log levels are used by log categories and handlers to limit the messages they are responsible for. Each log level has an assigned numeric value that indicates its order relative to other log levels. Log categories and handlers are assigned a log level, and they only process log messages of that level or higher. For example a log handler with the level of WARN will only record messages of the levels WARN, ERROR, and FATAL.

Supported Log Levels
Log LevelValueDescription

ALL

Integer.MIN_VALUE

Provides all log messages.

FINEST

300

-

FINER

400

-

TRACE

400

TRACE level log messages provide detailed information about the running state of an application and are usually only captured during debugging.

DEBUG

500

DEBUG level log messages indicate the progress of individual requests or application activities and are usually only captured during debugging.

FINE

500

-

CONFIG

700

-

INFO

800

INFO level log messages indicate the overall progress of the application. Often used for application startup, shutdown, and other major lifecycle events.

WARN

900

WARN level log messages indicate a situation that is not in error, but is not considered ideal. WARN log messages can indicate circumstances that could lead to errors in the future.

WARNING

900

-

ERROR

1000

ERROR level log messages indicate an error that has occurred that could prevent the current activity or request from completing but will not prevent the application from running.

SEVERE

1000

-

FATAL

1100

FATAL level log messages indicate events that could cause critical service failure and application shutdown and could cause JBoss EAP to shutdown.

OFF

Integer.MAX_VALUE

Does not display any log message.

Note

ALL is the lowest log level and includes messages of all log levels. This provides the most amount of logging.

FATAL is the highest log level and only includes messages of that level. This provides the least amount of logging.

11.3.5. Log Formatters

Formatters are used to format a log message. A formatter can be assigned to a logging handler using the named-formatter attribute. For more information on logging handler configuration, see Configuring Log Handlers.

The logging subsystem includes four types of formatters:

Pattern Formatter

A pattern formatter is used to format log messages in plain text. In addition to using the formatter as the named-formatter attribute of log handlers, it can also be used as a formatter attribute, without the need to create the formatter resource first. See Format Characters for Pattern Formatter for more information on the pattern syntax.

See Configure a Pattern Formatter for information on how to configure a pattern formatter.

JSON Formatter

A JSON formatter is used to format log messages in JSON.

See Configure a JSON Log Formatter for information on how to configure a JSON formatter.

XML Formatter

The XML log formatter is used to format log messages in XML.

See Configure an XML Log Formatter for information on how to configure an XML log formatter.

Custom Formatter

A custom formatter to be used with handlers. Note that most log records are formatted in the printf format. Formatters may require invocation of the org.jboss.logmanager.ExtLogRecord#getFormattedMessage() for the message to be properly formatted.

See Configure a Custom Log Formatter for information on how to configure a custom log formatter.

11.3.6. Filter Expressions

Filter expressions, configured using the filter-spec attribute, are used to record log messages based on various criteria. Filter checking is always done on a raw unformatted message. You can include a filter for a logger or handler, but the logger filter takes precedence over the filter put on a handler.

Note

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

Table 11.3. Filter Expressions for Logging

Filter ExpressionDescription

accept

Accept all log messages.

deny

Deny all log messages.

not[filter expression]

Returns the inverted value of a single filter expression. For example:

not(match("WFLY"))

all[filter expression]

Returns concatenated value from a comma-separated list of filter expressions. For example:

all(match("WFLY"),match("WELD"))

any[filter expression]

Returns one value from a comma-separated list of filter expressions. For example:

any(match("WFLY"),match("WELD"))

levelChange[level]

Updates the log record with the specified level. For example:

levelChange(WARN)

levels[levels]

Filters log messages with a level listed in the comma-separated list of levels. For example:

levels(DEBUG,INFO,WARN,ERROR)

levelRange[minLevel,maxLevel]

Filters log messages within the specified level range. The [ and ] characters are used to indicate an inclusive level. The ( and ) characters are used to indicate an exclusive level. For example:

  • levelRange[INFO,ERROR]

    • The minimum level must be greater than or equal to INFO and the maximum level must be less than or equal to ERROR.
  • levelRange[DEBUG,ERROR)

    • The minimum level must be greater than or equal to DEBUG and the maximum level must be less than ERROR.

match["pattern"]

Filters log messages using the provided regular expression. For example:

match("WFLY\d+")

substitute["pattern","replacement value"]

A filter that replaces the first match to the pattern (first argument) with the replacement text (second argument). For example:

substitute("WFLY","EAP")

substituteAll["pattern","replacement value"]

A filter which replaces all matches of the pattern (first argument) with the replacement text (second argument). For example:

substituteAll("WFLY","EAP")

Note

When configuring the filter expression using the management CLI, be sure to escape commas and quotation marks in the filter text so that the value is correctly processed as a string. You must precede commas and quotation marks with a backslash (\) and wrap the entire expression in quotation marks. Below is an example that properly escapes substituteAll("WFLY","YLFW").

/subsystem=logging/console-handler=CONSOLE:write-attribute(name=filter-spec, value="substituteAll(\"WFLY\"\,\"YLFW\")")

11.3.7. Implicit Logging Dependencies

By default, the JBoss EAP logging subsystem adds implicit logging API dependencies to deployments. You can control whether these implicit dependencies are added to deployments by using the add-logging-api-dependencies attribute, which is true by default.

Using the management CLI, you can set the add-logging-api-dependencies attribute to false so that the implicit logging API dependencies will not be added to deployments.

/subsystem=logging:write-attribute(name=add-logging-api-dependencies, value=false)

For information on the implicit dependencies for the logging subsystem, see the Implicit Module Dependencies section in the JBoss EAP Development Guide.

11.4. Configuring Log Categories

This section shows you how to configure log categories using the management CLI. You can also configure log categories using the management console by navigating to ConfigurationSubsystemsLoggingConfiguration, clicking View, and selecting Categories.

The main tasks you will perform to configure a log category are:

Important

If you are configuring this log category for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Log Category

The log category name is defined by the Java package of origin. Messages from classes in that package will be captured as long as they adhere to the other settings, for example, the log level.

/subsystem=logging/logger=LOG_CATEGORY:add

Configure Log Category Settings

Depending on your needs, you may need to set one or more of the following log category attributes. For a full list of available log category attributes and their descriptions, see Log Category Attributes.

  • Set the log level.

    Set the appropriate log level for the log category. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=level,value=LEVEL)
  • Set whether this category should use the log handlers of the root logger.

    By default, log categories will use the handlers of the root logger in addition to its own. Set the use-parent-handlers attribute to false if the log category should use only its assigned handlers.

    /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=use-parent-handlers,value=USE_PARENT_HANDLERS)
  • Set the filter expression.

    Set the expression for filtering log messages for the log category. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign a Handler

Assign a log handler to the log category.

/subsystem=logging/logger=LOG_CATEGORY:add-handler(name=LOG_HANDLER_NAME)

Remove a Log Category

A log category can be removed with the remove operation.

/subsystem=logging/logger=LOG_CATEGORY:remove

11.5. Configuring Log Handlers

Log handlers define how captured log messages are recorded. See the appropriate section for configuring the type of log handler that you need.

11.5.1. Configure a Console Log Handler

This section shows you how to configure a console log handler using the management CLI. You can also configure console log handlers using the management console by navigating to ConfigurationSubsystemsLoggingConfiguration, clicking View, and selecting HandlerConsole Handler.

The main tasks you will perform to configure a console log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Console Log Handler
/subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:add
Configure Console Log Handler Settings

Depending on your needs, you may need to set one or more of the following console log handler attributes. For a full list of available console log handler attributes and their descriptions, see Console Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the target.

    Set the target for the handler, which can be one of System.out, System.err, or console. The default is System.out.

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=target,value=TARGET)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set auto flush.

    Set whether to automatically flush after each write. The default value is true.

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Console Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the console log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=CONSOLE_HANDLER_NAME)

The following management CLI command assigns the console log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=CONSOLE_HANDLER_NAME)
Remove a Console Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:remove

11.5.2. Configure a File Log Handler

This section shows you how to configure a file log handler using the management CLI. You can also configure file log handlers using the management console by navigating to ConfigurationSubsystemsLoggingConfiguration, clicking View, and selecting HandlerFile Handler.

The main tasks you will perform to configure a file log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a File Log Handler

When adding a file log handler, you must specify the file path using the file attribute, which is comprised of the path and relative-to attributes. Use the path attribute to set the file path for the log, including the name, for example my-log.log. Optionally, use the relative-to attribute to set that the path is relative to a named path, for example jboss.server.log.dir.

/subsystem=logging/file-handler=FILE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH})
Configure File Log Handler Settings

Depending on your needs, you may need to set one or more of the following file log handler attributes. For a full list of available file log handler attributes and their descriptions, see File Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the append behavior.

    By default, JBoss EAP will append log messages to the same file when the server is restarted. You can set the append attribute to false to have the file overwritten upon server restart.

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set auto flush.

    Set whether to automatically flush after each write. The default value is true.

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the File Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the file log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=FILE_HANDLER_NAME)

The following management CLI command assigns the file log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=FILE_HANDLER_NAME)
Remove a File Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/file-handler=FILE_HANDLER_NAME:remove

11.5.3. Configure a Periodic Rotating Log Handler

This section shows you how to configure a periodic rotating log handler using the management CLI. You can also configure periodic log handlers using the management console by navigating to ConfigurationSubsystemsLoggingConfiguration, clicking View, and selecting HandlerPeriodic Handler.

The main tasks you will perform to configure a periodic log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Periodic Log Handler

When adding a periodic log handler, you must specify the file path using the file attribute, which is comprised of the path and relative-to attributes. Use the path attribute to set the file path for the log, including the name, for example my-log.log. Optionally, use the relative-to attribute to set that the path is relative to a named path, for example jboss.server.log.dir.

You must also set the suffix for rotated logs using the suffix attribute. This must be in a format that can be understood by java.text.SimpleDateFormat, for example .yyyy-MM-dd-HH. The period of the rotation is automatically calculated based on this suffix.

/subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH},suffix=SUFFIX)
Configure Periodic Log Handler Settings

Depending on your needs, you may need to set one or more of the following periodic log handler attributes. For a full list of available periodic log handler attributes and their descriptions, see Periodic Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the append behavior.

    By default, JBoss EAP will append log messages to the same file when the server is restarted. You can set the append attribute to false to have the file overwritten upon server restart.

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set auto flush.

    Set whether to automatically flush after each write. The default value is true.

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Periodic Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the periodic log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=PERIODIC_HANDLER_NAME)

The following management CLI command assigns the periodic log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=PERIODIC_HANDLER_NAME)
Remove a Periodic Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:remove

11.5.4. Configure a Size Rotating Log Handler

This section shows you how to configure a size rotating log handler using the management CLI. You can also configure size log handlers using the management console by navigating to ConfigurationSubsystemsLoggingConfiguration, clicking View, and selecting HandlerSize Handler.

The main tasks you will perform to configure a size log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Size Log Handler

When adding a size log handler, you must specify the file path using the file attribute, which is comprised of the path and relative-to attributes. Use the path attribute to set the file path for the log, including the name, for example my-log.log. Optionally, use the relative-to attribute to set that the path is relative to a named path, for example jboss.server.log.dir.

/subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH})
Configure Size Log Handler Settings

Depending on your needs, you may need to set one or more of the following size log handler attributes. For a full list of available size log handler attributes and their descriptions, see Size Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the suffix for rotated logs.

    Set the suffix string, which is in a format which can be understood by java.text.SimpleDateFormat, for example .yyyy-MM-dd-HH . The period of the rotation is automatically calculated based on this suffix.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=suffix, value=SUFFIX)
  • Set the rotation size.

    Set the maximum size that the file can reach before being rotated. The default is 2m for 2 megabytes.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=rotate-size, value=ROTATE_SIZE)
  • Set the maximum number of backup logs to keep.

    Set the number of backups to keep. The default is 1.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=max-backup-index, value=MAX_BACKUPS)
  • Set whether to rotate the log on boot.

    By default, a new log file is not created on server restart. You can set this to true to rotate the log on server restart.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=rotate-on-boot, value=ROTATE_ON_BOOT)
  • Set the append behavior.

    By default, JBoss EAP will append log messages to the same file when the server is restarted. You can set the append attribute to false to have the file overwritten upon server restart.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set auto flush.

    Set whether to automatically flush after each write. The default value is true.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Size Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the size log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=SIZE_HANDLER_NAME)

The following management CLI command assigns the size log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=SIZE_HANDLER_NAME)
Remove a Size Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:remove

11.5.5. Configure a Periodic Size Rotating Log Handler

This section shows you how to configure a periodic size rotating log handler using the management CLI. You can also configure periodic size log handlers using the management console by navigating to ConfigurationSubsystemsLoggingConfiguration, clicking View, and selecting HandlerPeriodic Size Handler.

The main tasks you will perform to configure a periodic size log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Periodic Size Log Handler

When adding a periodic size log handler, you must specify the file path using the file attribute, which is comprised of the path and relative-to attributes. Use the path attribute to set the file path for the log, including the name, for example my-log.log. Optionally, use the relative-to attribute to set that the path is relative to a named path, for example jboss.server.log.dir.

You must also set the suffix for rotated logs using the suffix attribute. This must be in a format that can be understood by java.text.SimpleDateFormat, for example .yyyy-MM-dd-HH. The period of the rotation is automatically calculated based on this suffix.

/subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH},suffix=SUFFIX)
Configure Periodic Size Log Handler Settings

Depending on your needs, you may need to set one or more of the following periodic size log handler attributes. For a full list of available periodic size log handler attributes and their descriptions, see Periodic Size Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the rotation size.

    Set the maximum size that the file can reach before being rotated. The default is 2m for 2 megabytes.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=rotate-size, value=ROTATE_SIZE)
  • Set the maximum number of backup logs to keep.

    Set the number of backups to keep. The default is 1.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=max-backup-index, value=MAX_BACKUPS)
  • Set whether to rotate the log on boot.

    By default, a new log file is not created on server restart. You can set this to true to rotate the log on server restart.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=rotate-on-boot, value=ROTATE_ON_BOOT)
  • Set the append behavior.

    By default, JBoss EAP will append log messages to the same file when the server is restarted. You can set the append attribute to false to have the file overwritten upon server restart.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set auto flush.

    Set whether to automatically flush after each write. The default value is true.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Periodic Size Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the periodic size log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=PERIODIC_SIZE_HANDLER_NAME)

The following management CLI command assigns the periodic size log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=PERIODIC_SIZE_HANDLER_NAME)
Remove a Periodic Size Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:remove

11.5.6. Configure a Syslog Handler

This section shows you how to configure a syslog handler using the management CLI, which can be used to send messages to a remote logging server that supports the Syslog protocol, either RFC-3164 or RFC-5424. You can also configure syslog handlers using the management console by navigating to ConfigurationSubsystemsLoggingConfiguration, clicking View, and selecting HandlerSyslog Handler.

The main tasks you will perform to configure a syslog handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Syslog Handler
/subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:add
Configure Syslog Handler Settings

Depending on your needs, you may need to set one or more of the following syslog handler attributes. For a full list of available syslog handler attributes and their descriptions, see Syslog Handler Attributes.

  • Set the log level for the handler. The default level is ALL. See Log Levels for all available options.

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the name of the application that is logging. The default name is java.

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=app-name,value=APP_NAME)
  • Set the address of the syslog server. The default address is localhost.

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=server-address,value=SERVER_ADDRESS)
  • Set the port of the syslog server. The default port is 514.

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=port,value=PORT)
  • Set the syslog format, as defined by an RFC specification. The default format is RFC5424.

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=syslog-format,value=SYSLOG_FORMAT)
  • Specify the named-formatter attribute to format the message of the syslog payload.

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=named-formatter, value=FORMATTER_NAME)
Assign the Syslog Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the syslog handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=SYSLOG_HANDLER_NAME)

The following management CLI command assigns the syslog handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=SYSLOG_HANDLER_NAME)
Remove a Syslog Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:remove

11.5.7. Configure a Socket Log Handler

This section shows you how to configure a socket log handler using the management CLI, which can be used to send messages over a socket. This can be a TCP or UDP socket. You can also configure socket log handlers using the management console by navigating to ConfigurationSubsystemsLoggingConfiguration, clicking View, and selecting HandlerSocket Handler.

Note

If the server is started in admin-only mode, log messages are discarded.

The main tasks you will perform to configure a socket log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add the Socket Binding

Define either a remote-destination-outbound-socket-binding or local-destination-outbound-socket-binding as the socket binding to use.

/socket-binding-group=SOCKET_BINDING_GROUP/remote-destination-outbound-socket-binding=SOCKET_BINDING_NAME:add(host=HOST, port=PORT)
Add the Log Formatter

Define a log formatter to use, such as a JSON formatter.

/subsystem=logging/json-formatter=FORMATTER:add
Add the Socket Log Handler

When adding the socket log handler, you must specify the socket binding and formatter to use.

/subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:add(outbound-socket-binding-ref=SOCKET_BINDING_NAME,named-formatter=FORMATTER)
Configure Socket Log Handler Settings

Depending on your needs, you may need to set one or more of the following socket log handler attributes. For a full list of available socket log handler attributes and their descriptions, see Socket Log Handler Attributes.

  • Set the protocol.

    Set the protocol to use. The default is TCP.

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=protocol,value=PROTOCOL)
  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
    Note

    During server startup, log messages handled by a socket log handler are queued until the socket binding is configured and the logging subsystem is initialized. If the log level is set to a low level, such as TRACE or DEBUG, this can result in large memory consumption during startup.

  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set auto flush.

    Set whether to automatically flush after each write. The default value is true.

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Socket Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the socket log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=SOCKET_HANDLER_NAME)

The following management CLI command assigns the socket log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=SOCKET_HANDLER_NAME)
Remove a Socket Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:remove
Send Log Messages Over a Socket Using SSL/TLS

The following steps show an example of how to set up a socket log handler to send log messages over a socket using the SSL_TCP protocol. This example configures a keystore, trust manager, and client SSL context in the elytron subsystem to be used by the socket log handler. Log messages from the root logger are sent over the specified socket, formatted by a JSON formatter.

For more information on configuring Elytron components, see Elytron Subsystem in How to Configure Server Security for JBoss EAP.

  1. Configure the Elytron settings.

    1. Add the keystore.

      /subsystem=elytron/key-store=log-server-ks:add(path=/path/to/keystore.jks, type=JKS, credential-reference={clear-text=mypassword})
    2. Add the trust manager.

      /subsystem=elytron/trust-manager=log-server-tm:add(key-store=log-server-ks)
    3. Add the client SSL context.

      /subsystem=elytron/client-ssl-context=log-server-context:add(trust-manager=log-server-tm, protocols=["TLSv1.2"])
  2. Add the socket binding.

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=log-server:add(host=localhost, port=4560)
  3. Add a JSON formatter.

    /subsystem=logging/json-formatter=json:add
  4. Add the socket log handler.

    /subsystem=logging/socket-handler=log-server-handler:add(named-formatter=json, level=INFO, outbound-socket-binding-ref=log-server, protocol=SSL_TCP, ssl-context=log-server-context)
  5. Assign the log handler to the root logger.

    /subsystem=logging/root-logger=ROOT:add-handler(name=log-server-handler)

11.5.8. Configure a Custom Log Handler

This section shows you how to configure a custom log handler using the management CLI. You can also configure custom log handlers using the management console by navigating to ConfigurationSubsystemsLoggingConfiguration, clicking View, and selecting HandlerCustom Handler.

The main tasks you will perform to configure a custom log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Custom Log Handler

When adding a custom log handler, you must specify the Java class of the handler and the JBoss EAP module in which it is contained. The class must extend java.util.logging.Handler.

Note

You must have already created a module containing the custom logger or this command will fail.

/subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:add(class=CLASS_NAME,module=MODULE_NAME)
Configure Custom Log Handler Settings

Depending on your needs, you may need to set one or more of the following custom log handler attributes. For a full list of available custom log handler attributes and their descriptions, see Custom Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the properties.

    Set the necessary properties for the log handler. The properties must be accessible using a setter method.

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=properties.PROPERTY_NAME,value=PROPERTY_VALUE)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Custom Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the custom log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=CUSTOM_HANDLER_NAME)

The following management CLI command assigns the custom log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=CUSTOM_HANDLER_NAME)
Remove a Custom Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:remove

11.5.9. Configure an Async Log Handler

This section shows you how to configure an async log handler using the management CLI. You can also configure async log handlers using the management console by navigating to ConfigurationSubsystemsLoggingConfiguration, clicking View, and selecting HandlerAsync Handler.

The main tasks you will perform to configure an async log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add an Async Log Handler

When adding an async log handler, you must specify the queue length. This is the maximum number of log requests that can be held in queue.

/subsystem=logging/async-handler=ASYNC_HANDLER_NAME:add(queue-length=QUEUE_LENGTH)
Add a Sub-handler

You can add one or more handlers as sub-handlers for this async log handler. Note that the handlers must already exist in the configuration or this command will fail.

/subsystem=logging/async-handler=ASYNC_HANDLER_NAME:add-handler(name=HANDLER_NAME)
Configure Async Log Handler Settings

Depending on your needs, you may need to set one or more of the following async log handler attributes. For a full list of available async log handler attributes and their descriptions, see Async Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the overflow action.

    Set the action to take when overflowing. The default value is BLOCK, which means that threads will block in the event of a full queue. You can change this value to DISCARD, which means that log messages will be discarded in the event of a full queue.

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=overflow-action,value=OVERFLOW_ACTION)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Async Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the async log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=ASYNC_HANDLER_NAME)

The following management CLI command assigns the async log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=ASYNC_HANDLER_NAME)
Remove an Async Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger.

/subsystem=logging/async-handler=ASYNC_HANDLER_NAME:remove

11.6. Configuring the Root Logger

The root logger captures all log messages, of the specified log level or higher, sent to the server that are not captured by a log category.

This section shows you how to configure the root logger using the management CLI. You can also configure the root logger using the management console by navigating to ConfigurationSubsystemsLoggingConfiguration, clicking View, and selecting Root Logger.

Configure the Root Logger

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

  1. Assign log handlers to the root logger.

    Add a log handler.

    /subsystem=logging/root-logger=ROOT:add-handler(name=LOG_HANDLER_NAME)

    Remove a log handler.

    /subsystem=logging/root-logger=ROOT:remove-handler(name=LOG_HANDLER_NAME)
  2. Set the log level.

    /subsystem=logging/root-logger=ROOT:write-attribute(name=level,value=LEVEL)

For a full list of available root logger attributes and their descriptions, see Root Logger Attributes.

11.7. Configuring Log Formatters

A log formatter defines the appearance of log messages from that handler. The logging subsystem allows you to configure the following types of log formatters:

11.7.1. Configure a Pattern Formatter

You can create a named pattern formatter that can be used across log handlers to format log messages.

Important

If you are configuring this log formatter for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Create a Pattern Formatter

When defining a pattern formatter, you provide a pattern string to use to format log messages. For more information on the pattern syntax, see Format Characters for Pattern Formatter.

/subsystem=logging/pattern-formatter=PATTERN_FORMATTER_NAME:add(pattern=PATTERN)

For example, the default configuration uses the following log formatter string for logging messages to the server log: %d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. This creates log messages formatted like the one below.

2016-03-18 15:49:32,075 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0051: Admin console listening on http://127.0.0.1:9990

You can also define a color map to assign a color to different log levels. The format is a comma-separated list of LEVEL:COLOR.

  • Valid levels: finest, finer, fine, config, trace, debug, info, warning, warn, error, fatal, severe
  • Valid colors: black, green, red, yellow, blue, magenta, cyan, white, brightblack, brightred, brightgreen, brightblue, brightyellow, brightmagenta, brightcyan, brightwhite
/subsystem=logging/pattern-formatter=PATTERN_FORMATTER_NAME:write-attribute(name=color-map,value="LEVEL:COLOR,LEVEL:COLOR")

You can also configure pattern log formatters using the management console:

  1. Open the management console in a browser.
  2. Choose ConfigurationSubsystemsLogging.
  3. Select Configuration and then click View.
  4. Select Formatter and then choose the Pattern Formatter option.

11.7.2. Configure a JSON Log Formatter

You can create a JSON log formatter to format log messages in JSON.

Important

If you are configuring this log formatter for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a JSON Log Formatter
/subsystem=logging/json-formatter=JSON_FORMATTER_NAME:add(pretty-print=true, exception-output-type=formatted)

This creates log messages formatted like the one below.

{
    "timestamp": "2018-10-18T13:53:43.031-04:00",
    "sequence": 62,
    "loggerClassName": "org.jboss.as.server.logging.ServerLogger_$logger",
    "loggerName": "org.jboss.as",
    "level": "INFO",
    "message": "WFLYSRV0025: JBoss EAP 7.3.0.GA (WildFly Core 10.0.0.Final-redhat-20190924) started in 5672ms - Started 495 of 679 services (331 services are lazy, passive or on-demand)",
    "threadName": "Controller Boot Thread",
    "threadId": 22,
    "mdc": {
    },
    "ndc": "",
    "hostName": "localhost.localdomain",
    "processName": "jboss-modules.jar",
    "processId": 7461
}
Add a Logstash JSON log formatter
Note

You can modify the JSON log formatter output keys and add static metadata. The primary purpose of the JSON log formatter is to format log messages in JSON. Logstash consumes this JSON output and searches for the fields, @timestamp and @version. The following example creates a JSON log formatter that formats messages for Logstash.

/subsystem=logging/json-formatter=logstash:add(exception-output-type=formatted, key-overrides=[timestamp="@timestamp"], meta-data=[@version=1])

You can use the JSON formatter attributes as explained below:

  • The key-overrides attribute can be used to override the names of the keys defined.
  • The exceptions can be formatted as objects by setting the exception-output-type attribute to formatted.
  • The exception stack trace can be included by setting the exception-output-type attribute to detailed.
  • The exceptions can be formatted as objects and stack traces can be included by setting the exception-output-type to detailed-and-formatted.
  • The metadata can be added to log records using the meta-data attribute.

For more information on the JSON formatter attributes, see JSON Log Formatter Attributes.

You can also configure JSON log formatters using the management console:

  1. Open the management console in a browser.
  2. Choose ConfigurationSubsystemsLogging.
  3. Select Configuration and then click View.
  4. Select Formatter and then choose the JSON Formatter option.

11.7.3. Configure an XML Log Formatter

You can create an XML log formatter to format log messages in XML.

Important

If you are configuring this log formatter for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add an XML Log Formatter
/subsystem=logging/xml-formatter=XML_FORMATTER_NAME:add(pretty-print=true, exception-output-type=detailed-and-formatted)

This creates log message formatted like the one below.

<record>
    <timestamp>2018-10-18T13:55:53.419-04:00</timestamp>
    <sequence>62</sequence>
    <loggerClassName>org.jboss.as.server.logging.ServerLogger_$logger</loggerClassName>
    <loggerName>org.jboss.as</loggerName>
    <level>INFO</level>
    <message>WFLYSRV0025: JBoss EAP 7.3.0.GA (WildFly Core 10.0.0.Final-redhat-20190924) started in 6271ms - Started 495 of 679 services (331 services are lazy, passive or on-demand)</message>
    <threadName>Controller Boot Thread</threadName>
    <threadId>22</threadId>
    <mdc>
    </mdc>
    <ndc></ndc>
    <hostName>localhost.localdomain</hostName>
    <processName>jboss-modules.jar</processName>
    <processId>7790</processId>
</record>
Add a Key Override XML Log Formatter
/subsystem=logging/xml-formatter=XML_FORMATTER_NAME:add(pretty-print=true, print-namespace=true, namespace-uri="urn:custom:1.0", key-overrides={message=msg, record=logRecord, timestamp=date}, print-details=true)

You can use the XML formatter attributes as explained below:

  • The key-overrides attribute can be used to override the names of the keys defined.
  • The exceptions can be formatted as objects by setting the exception-output-type attribute to formatted.
  • The exception stack trace can be included by setting the exception-output-type attribute to detailed.
  • The exceptions can be formatted as objects and stack traces can be included by setting the exception-output-type to detailed-and-formatted.
  • The metadata can be added to log records using the meta-data attribute.

For more information on the XML formatter attributes, see XML Log Formatter Attributes.

You can also configure XML log formatters using the management console:

  1. Open the management console in a browser.
  2. Choose ConfigurationSubsystemsLogging.
  3. Select Configuration and then click View.
  4. Select Formatter and then choose the XML Formatter option.

11.7.4. Configure a Custom Log Formatter

You can create a custom log formatter that can be used across log handlers to format log messages.

This section shows you how to configure a custom log formatter using the management CLI.

Configure a Custom Log Formatter
Important

If you are configuring this log formatter for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

  1. Add the custom log formatter.

    When adding a custom log formatter, you must specify the Java class of the formatter and the JBoss EAP module in which it is contained. The class must extend java.util.logging.Formatter.

    Note

    You must have already created a module containing the custom formatter or this command will fail.

    /subsystem=logging/custom-formatter=CUSTOM_FORMATTER_NAME:add(class=CLASS_NAME, module=MODULE_NAME)
  2. Set the necessary properties for the log formatter.

    The properties must be accessible using a setter method.

    /subsystem=logging/custom-formatter=CUSTOM_FORMATTER_NAME:write-attribute(name=properties.PROPERTY_NAME,value=PROPERTY_VALUE)
  3. Assign the custom formatter to a log handler.

    The following management CLI command assigns a custom formatter to be used by a periodic rotating file handler.

    /subsystem=logging/periodic-rotating-file-handler=FILE_HANDLER_NAME:write-attribute(name=named-formatter, value=CUSTOM_FORMATTER_NAME)
Example Custom XML Formatter

The following example configures a custom XML formatter. It uses the java.util.logging.XMLFormatter class provided in the org.jboss.logmanager module and assigns it to the console log handler.

/subsystem=logging/custom-formatter=custom-xml-formatter:add(class=java.util.logging.XMLFormatter, module=org.jboss.logmanager)
/subsystem=logging/console-handler=CONSOLE:write-attribute(name=named-formatter, value=custom-xml-formatter)

A log message using this formatter would be formatted as below.

<record>
  <date>2016-03-23T12:58:13</date>
  <millis>1458752293091</millis>
  <sequence>93963</sequence>
  <logger>org.jboss.as</logger>
  <level>INFO</level>
  <class>org.jboss.as.server.BootstrapListener</class>
  <method>logAdminConsole</method>
  <thread>22</thread>
  <message>WFLYSRV0051: Admin console listening on http://%s:%d</message>
  <param>127.0.0.1</param>
  <param>9990</param>
</record>
Configure a Custom Log Formatter Using the Management Console

You can also configure log formatters using the management console.

  1. Open the management console in a browser.
  2. Choose ConfigurationSubsystemsLogging.
  3. Select Configuration and then click View.
  4. Select Formatter and then choose the Custom Formatter option.

11.8. About Application Logging

Logging for applications can be configured using the JBoss EAP logging subsystem or on a per-deployment basis.

See About the Logging Subsystem for using JBoss EAP log categories and handlers for capturing log messages.

For more information on application logging, such as supported application logging frameworks and configuring per-deployment logging, see the Logging chapter in the JBoss EAP Development Guide.

11.8.1. Per-deployment Logging

Per-deployment logging allows a developer to configure the logging configuration for their application in advance. When the application is deployed, logging begins according to the defined configuration. The log files created through this configuration contain information only about the behavior of the application.

Note

If the per-deployment logging configuration is not done, the configuration from logging subsystem is used for all the applications as well as the server.

This approach has advantages and disadvantages over using system-wide logging. An advantage is that the administrator of the JBoss EAP instance does not need to configure any other logging than the server logging. A disadvantage is that the per-deployment logging configuration is read only on server startup, and so cannot be changed at runtime.

For instructions on using per-deployment logging in your applications, see Add Per-deployment Logging to an Application in the JBoss EAP Development Guide.

11.8.1.1. Disable Per-deployment Logging

You can disable per-deployment logging in one of the following ways:

  • Set the use-deployment-logging-config attribute to false.

    The use-deployment-logging-config attribute controls whether or not your deployment is scanned for per-deployment logging. This defaults to true by default. You can set this attribute to false to disable per-deployment logging.

    /subsystem=logging:write-attribute(name=use-deployment-logging-config,value=false)
  • Exclude the logging subsystem using a jboss-deployment-structure.xml file.

    For instructions, see Exclude a Subsystem from a Deployment in the JBoss EAP Development Guide.

11.8.2. Logging Profiles

Logging profiles are independent sets of logging configurations that can be assigned to deployed applications. As with the regular logging subsystem, a logging profile can define handlers, categories, and a root logger, but it cannot refer to configurations in other profiles or the main logging subsystem. The design of logging profiles mimics the logging subsystem for ease of configuration.

Logging profiles allow administrators to create logging configurations that are specific to one or more applications without affecting any other logging configurations. Because each profile is defined in the server configuration, the logging configuration can be changed without requiring that the affected applications be redeployed.

Each logging profile can have:

  • A unique name. This value is required.
  • Any number of log handlers.
  • Any number of log categories.
  • Up to one root logger.

An application can specify a logging profile to use in its MANIFEST.MF file, using the Logging-Profile attribute.

11.8.2.1. Configure a Logging Profile

A logging profile can be configured with log handlers, categories, and a root logger. Configuring a logging profile uses the same syntax as configuring the logging subsystem, except for the following differences:

  • The root configuration path is /subsystem=logging/logging-profile=NAME.
  • A logging profile cannot contain other logging profiles.
  • The logging subsystem has the following attributes that are not available for a logging profile:

    • add-logging-api-dependencies
    • use-deployment-logging-config
Creating and Configuring a Logging Profile

The following procedure uses the management CLI to create a logging profile and set a file handler and logger category. Logging profiles can also be configured using the management console by navigating to ConfigurationSubsystemsLoggingLogging Profiles.

  1. Create the logging profile.

    /subsystem=logging/logging-profile=PROFILE_NAME:add
  2. Create the file handler.

    /subsystem=logging/logging-profile=PROFILE_NAME/file-handler=FILE_HANDLER_NAME:add(file={path=>"LOG_NAME.log", "relative-to"=>"jboss.server.log.dir"})
    /subsystem=logging/logging-profile=PROFILE_NAME/file-handler=FILE_HANDLER_NAME:write-attribute(name="level", value="DEBUG")

    See File Log Handler Attributes for the list of file handler attributes.

  3. Create the logger category.

    /subsystem=logging/logging-profile=PROFILE_NAME/logger=CATEGORY_NAME:add(level=TRACE)

    See Log Category Attributes for the list of log category attributes.

  4. Assign the file handler to the category.

    /subsystem=logging/logging-profile=PROFILE_NAME/logger=CATEGORY_NAME:add-handler(name="FILE_HANDLER_NAME")

You can then set the logging profile to use by an application in its MANIFEST.MF file. For more information, see Specify a Logging Profile in an Application in the JBoss EAP Development Guide.

11.8.2.2. Example Logging Profile Configuration

This example shows the configuration of a logging profile and the application that uses it. It shows the management CLI commands, the resulting XML, and the application’s MANIFEST.MF file.

The example logging profile has the following characteristics:

  • The name is accounts-app-profile.
  • The log category is com.company.accounts.ejbs.
  • The log level TRACE.
  • The log handler is a file handler using the file ejb-trace.log.

Management CLI Session

/subsystem=logging/logging-profile=accounts-app-profile:add

/subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:add(file={path=>"ejb-trace.log", "relative-to"=>"jboss.server.log.dir"})

/subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:write-attribute(name="level", value="DEBUG")

/subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:add(level=TRACE)

/subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:add-handler(name="ejb-trace-file")

XML Configuration

<logging-profiles>
   <logging-profile name="accounts-app-profile">
      <file-handler name="ejb-trace-file">
         <level name="DEBUG"/>
         <file relative-to="jboss.server.log.dir" path="ejb-trace.log"/>
      </file-handler>
      <logger category="com.company.accounts.ejbs">
         <level name="TRACE"/>
         <handlers>
            <handler name="ejb-trace-file"/>
         </handlers>
      </logger>
   </logging-profile>
</logging-profiles>

Application MANIFEST.MF file

Manifest-Version: 1.0
Logging-Profile: accounts-app-profile

11.8.3. Viewing Deployment Logging Configuration

You can obtain information about the logging configuration for a particular deployment using the following management CLI command.

/deployment=DEPLOYMENT_NAME/subsystem=logging/configuration=CONFIG:read-resource

The logging configuration value, CONFIG, for a deployment can be one of three values:

  • default, if the deployment is using the logging subsystem. This will output the logging subsystem configuration.
  • profile-PROFILE_NAME, if the deployment is using a logging profile defined in the logging subsystem. This will output the logging profile configuration.
  • The path to the configuration file being used, for example, myear.ear/META-INF/logging.properties.

For example, the below management CLI command displays the configuration for the MYPROFILE logging profile, which is used by the specified deployment.

/deployment=mydeployment.war/subsystem=logging/configuration=profile-MYPROFILE:read-resource(recursive=true,include-runtime=true)

This will output the following information.

{
    "outcome" => "success",
    "result" => {
        "error-manager" => undefined,
        "filter" => undefined,
        "formatter" => {
            "MYFORMATTER" => {
                "class-name" => "org.jboss.logmanager.formatters.PatternFormatter",
                "module" => undefined,
                "properties" => {"pattern" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n"}
            }
        },
        "handler" => {
            "MYPERIODIC" => {
                "class-name" => "org.jboss.logmanager.handlers.PeriodicRotatingFileHandler",
                "encoding" => undefined,
                "error-manager" => undefined,
                "filter" => undefined,
                "formatter" => "MYFORMATTER",
                "handlers" => [],
                "level" => "ALL",
                "module" => undefined,
                "properties" => {
                    "append" => "true",
                    "autoFlush" => "true",
                    "enabled" => "true",
                    "suffix" => ".yyyy-MM-dd",
                    "fileName" => "EAP_HOME/standalone/log/deployment.log"
                }
            }
        },
        "logger" => {"MYCATEGORY" => {
            "filter" => undefined,
            "handlers" => [],
            "level" => "DEBUG",
            "use-parent-handlers" => true
        }},
        "pojo" => undefined
    }
}

You could also use a recursive read-resource operation to read the logging configuration and other information about a deployment.

/deployment=DEPLOYMENT_NAME/subsystem=logging:read-resource(include-runtime=true, recursive=true)

11.9. Tuning the Logging Subsystem

For tips on monitoring and optimizing performance for the logging subsystem, see the Logging Subsystem Tuning section of the Performance Tuning Guide.

Chapter 12. Datasource Management

12.1. About JBoss EAP Datasources

About JDBC

The JDBC API is the standard that defines how databases are accessed by Java applications. An application configures a datasource that references a JDBC driver. Application code can then be written against the driver, rather than the database. The driver converts the code to the database language. This means that if the correct driver is installed, an application can be used with any supported database.

For more information, see the JDBC 4.0 specification.

Supported Databases

See JBoss EAP supported configurations for the list of JDBC-compliant databases supported by JBoss EAP 7.

Datasource Types

The two general types of resources are referred to as datasources and XA datasources.

Non-XA datasources
Used for applications that do not use transactions, or applications that use transactions with a single database.
XA datasources
Used by applications that use multiple databases or other XA resources as part of one XA transaction. XA datasources introduce additional overhead.

You specify which type of datasource to use when creating the datasource using the JBoss EAP management interfaces.

The ExampleDS datasource

JBoss EAP ships with an example datasource configuration, ExampleDS, which is provided to demonstrate how datasources are defined. This datasource uses an H2 database, which is a lightweight, relational database management system that provides developers with the ability to quickly build applications.

Warning

The ExampleDS datasource and the H2 database should not be used in a production environment. This is a very small, self-contained datasource that supports all of the standards needed for testing and building applications, but is not robust or scalable enough for production use.

12.2. JDBC Drivers

Before defining datasources in JBoss EAP for your applications to use, you must first install the appropriate JDBC driver.

12.2.1. Installing a JDBC Driver as a Core Module

To install a JDBC driver as a core module, you must first add the JDBC driver as a core module and then register the JDBC driver in the datasources subsystem.

12.2.1.1. Add the JDBC Driver as a Core Module

JDBC drivers can be installed as a core module using the management CLI using the following steps.

  1. Download the JDBC driver.

    Download the appropriate JDBC driver from your database vendor. See JDBC Driver Download Locations for standard download locations for JDBC drivers of common databases.

    Make sure to extract the archive if the JDBC driver JAR file is contained within a ZIP or TAR archive.

  2. Start the JBoss EAP server.
  3. Launch the management CLI.

    $ EAP_HOME/bin/jboss-cli.sh
  4. Use the module add management CLI command to add the new core module.

    module add --name=MODULE_NAME --resources=PATH_TO_JDBC_JAR --dependencies=DEPENDENCIES

    For example, the following command adds a MySQL JDBC driver module.

    module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

    Execute module --help for more details on using this command to add and remove modules.

You must next register it as a JDBC driver for it to be referenced by application datasources.

12.2.1.2. Register the JDBC Driver

After the driver has been installed as a core module, you must register it as a JDBC driver using the following management CLI command. When running in a managed domain, be sure to precede this command with /profile=PROFILE_NAME.

/subsystem=datasources/jdbc-driver=DRIVER_NAME:add(driver-name=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xa-datasource-class-name=XA_DATASOURCE_CLASS_NAME, driver-class-name=DRIVER_CLASS_NAME)
Note

The driver-class-name parameter is only required if the JDBC driver jar defines more than one class in its /META-INF/services/java.sql.Driver file.

For example, the /META-INF/services/java.sql.Driver file in the MySQL 5.1.36 JDBC driver JAR defines two classes:

  • com.mysql.cj.jdbc.Driver
  • com.mysql.fabric.jdbc.FabricMySQLDriver

For this case, you would pass in driver-class-name=com.mysql.cj.jdbc.Driver.

For example, the following command registers a MySQL JDBC driver.

/subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)

The JDBC driver is now available to be referenced by application datasources.

12.2.2. Installing a JDBC Driver as a JAR Deployment

JDBC drivers can be installed as a JAR deployment using either the management CLI or the management console. As long as the driver is JDBC 4-compliant, it will automatically be recognized and installed as a JDBC driver upon deployment.

The following steps describe how to install a JDBC driver using the management CLI.

Note

The recommended installation method for JDBC drivers is to install them as a core module.

  1. Download the JDBC driver.

    Download the appropriate JDBC driver from your database vendor. See JDBC Driver Download Locations for standard download locations for JDBC drivers of common databases.

    Make sure to extract the archive if the JDBC driver JAR file is contained within a ZIP or TAR archive.

  2. If the JDBC driver is not JDBC 4-compliant, see the steps to Update a JDBC Driver JAR to be JDBC 4-Compliant.
  3. Deploy the JAR to JBoss EAP.

    deploy PATH_TO_JDBC_JAR
    Note

    In a managed domain, specify the appropriate server groups.

    For example, the following command deploys a MySQL JDBC driver.

    deploy /path/to/mysql-connector-java-8.0.12.jar

    A message will be displayed in the JBoss EAP server log that displays the deployed driver name, which will be used when defining datasources.

    WFLYJCA0018: Started Driver service with driver-name = mysql-connector-java-8.0.12.jar

The JDBC driver is now available to be referenced by application datasources.

Update a JDBC Driver JAR to be JDBC 4-Compliant

If the JDBC driver JAR is not JDBC 4-compliant, it can be made deployable using the following steps.

  1. Create an empty temporary directory.
  2. Create a META-INF subdirectory.
  3. Create a META-INF/services subdirectory.
  4. Create a META-INF/services/java.sql.Driver file and add one line to indicate the fully-qualified class name of the JDBC driver.

    For example, the below line would be added for a MySQL JDBC driver.

    com.mysql.cj.jdbc.Driver
  5. Use the JAR command-line tool to add this new file to the JAR.

    jar \-uf jdbc-driver.jar META-INF/services/java.sql.Driver

12.2.3. JDBC Driver Download Locations

The following table gives the standard download locations for JDBC drivers of common databases used with JBoss EAP.

Note

These links point to third-party websites which are not controlled or actively monitored by Red Hat. For the most up-to-date drivers for your database, check your database vendor’s documentation and website.

Table 12.1. JDBC Driver Download Locations

VendorDownload Location

MySQL

http://www.mysql.com/products/connector/

PostgreSQL

http://jdbc.postgresql.org/

Oracle

http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html

IBM

http://www-01.ibm.com/support/docview.wss?uid=swg21363866

Sybase

The jConnect JDBC driver is part of the SDK for SAP ASE installation. Currently there is not a separate download site for this driver by itself.

Microsoft

http://msdn.microsoft.com/data/jdbc/

12.2.4. Access Vendor-Specific Classes

In some cases, it is necessary for an application to use vendor-specific functionality that is not part of the JDBC API. In these cases, you can access vendor-specific APIs by declaring a dependency in that application.

Warning

This is advanced usage. Only applications that need functionality not found in the JDBC API should implement this procedure.

Important

This process is required when using the reauthentication mechanism, and accessing vendor-specific classes.

You can define a dependency for an application using either the MANIFEST.MF file or a jboss-deployment-structure.xml file.

If you have not yet done so, install a JDBC driver as a core module.

Using the MANIFEST.MF File
  1. Edit the application’s META-INF/MANIFEST.MF file.
  2. Add the Dependencies line and specify the module name.

    For example, the below line declares the com.mysql module as a dependency.

    Dependencies: com.mysql
Using a jboss-deployment-structure.xml File
  1. Create a file called jboss-deployment-structure.xml in the META-INF/ or WEB-INF/ folder of the application.
  2. Specify the module using the dependencies element.

    For example, the following example jboss-deployment-structure.xml file declares the com.mysql module as a dependency.

    <jboss-deployment-structure>
      <deployment>
        <dependencies>
          <module name="com.mysql"/>
        </dependencies>
      </deployment>
    </jboss-deployment-structure>

The example code below accesses the MySQL API.

import java.sql.Connection;
...
Connection c = ds.getConnection();
if (c.isWrapperFor(com.mysql.jdbc.Connection.class)) {
    com.mysql.jdbc.Connection mc = c.unwrap(com.mysql.jdbc.Connection.class);
}
Important

Follow the vendor-specific API guidelines closely, as the connection is being controlled by the IronJacamar container.

12.3. Creating Datasources

Datasources can be created using the management console or the management CLI.

JBoss EAP 7 allows you to use expressions in datasource attribute values, such as the enabled attribute. See the Property Replacement section for details on using expressions in the configuration.

12.3.1. Create a Non-XA Datasource

You can create non-XA datasources using either the management CLI or the management console.

Defining a Non-XA Datasource Using the Management Console
  1. Navigate to ConfigurationSubsystemsDatasources & DriversDatasources.
  2. Click the Add (+) button and choose Add Datasource.
  3. It opens the Add Datasource wizard where you can choose the datasource type and click Next. This creates a template for your database. The following pages of the wizard are prefilled with values specific for the selected datasource. This makes the datasource creation process easy.
  4. You can test your connection on the Test Connection page before finishing the datasource creation process.
  5. Review the details and click Finish to create the datasource.
Defining a Non-XA Datasource Using the Management CLI

Non-XA datasources can be defined using the data-source add management CLI command.

  1. If you have not yet done so, install and register the appropriate JDBC Driver as a Core Module.
  2. Define the datasource using the data-source add command, specifying the appropriate argument values.

    data-source add --name=DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME  --connection-url=CONNECTION_URL
    Note

    In a managed domain, you must specify the --profile=PROFILE_NAME argument.

    See the Datasource Parameters section below for tips on these parameter values.

For detailed examples, see the Example Datasource Configurations for the supported databases.

Datasource Parameters
jndi-name
The JNDI name for the datasource must start with java:/ or java:jboss/. For example, java:jboss/datasources/ExampleDS.
driver-name

The driver name value depends on whether the JDBC driver was installed as a core module or a JAR deployment.

  1. For a core module, the driver name value will be the name given to the JDBC driver when it was registered.
  2. For a JAR deployment, the driver name is the name of the JAR if there is only one class listed in its /META-INF/services/java.sql.Driver file. If there are multiple classes listed, then the value is JAR_NAME + "_" + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION (for example mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1).

    You can also see the driver name listed in the JBoss EAP server log when the JDBC JAR is deployed.

    WFLYJCA0018: Started Driver service with driver-name = mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1
connection-url
For details on the connection URL formats for the supported databases, see the list of Datasource Connection URLs.

For a complete listing of all available datasource attributes, see the Datasource Attributes section.

12.3.2. Create an XA Datasource

You can create XA datasources using either the management CLI or the management console.

Defining an XA Datasource Using the Management Console
  1. Navigate to ConfigurationSubsystemsDatasources & DriversDatasources.
  2. Click the Add (+) button and choose Add XA Datasource.
  3. It opens the Add XA Datasource wizard where you can choose the datasource type and click Next. This creates a template for your database. The following pages of the wizard are prefilled with values specific for the selected datasource. This makes the datasource creation process easy.
  4. You can test your connection on the Test Connection page before finishing the datasource creation process.
  5. Review the details and click Finish to create the datasource.
Defining an XA Datasource Using the Management CLI

XA datasources can be defined using the xa-data-source add management CLI command.

Note

In a managed domain, you will need to specify the profile to use. Depending on the format of the management CLI command, you will either precede the command with /profile=PROFILE_NAME or pass in the --profile=PROFILE_NAME argument.

  1. If you have not yet done so, install and register the appropriate JDBC Driver as a Core Module.
  2. Define the datasource using the xa-data-source add command, specifying the appropriate argument values.

    xa-data-source add --name=XA_DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME --xa-datasource-class=XA_DATASOURCE_CLASS --xa-datasource-properties={"ServerName"=>"HOST_NAME","DatabaseName"=>"DATABASE_NAME"}

    See the Datasource Parameters section below for tips on these parameter values.

  3. Set XA datasource properties.

    At least one XA datasource property is required when defining an XA datasource or you will receive an error when adding the datasource in the previous step. Any properties that were not set when defining the XA datasource can be set individually afterward.

    1. Set the server name.

      /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=ServerName:add(value=HOST_NAME)
    2. Set the database name.

      /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=DatabaseName:add(value=DATABASE_NAME)

For detailed examples, see the Example Datasource Configurations for the supported databases.

Datasource Parameters
jndi-name
The JNDI name for the datasource must start with java:/ or java:jboss/. For example, java:jboss/datasources/ExampleDS.
driver-name

The driver name value depends on whether the JDBC driver was installed as a core module or a JAR deployment.

  1. For a core module, the driver name value will be the name given to the JDBC driver when it was registered.
  2. For a JAR deployment, the driver name is the name of the JAR if there is only one class listed in its /META-INF/services/java.sql.Driver file. If there are multiple classes listed, then the value is JAR_NAME + "_" + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION, for example, mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1.

    You can also see the driver name listed in the JBoss EAP server log when the JDBC JAR is deployed.

    WFLYJCA0018: Started Driver service with driver-name = mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1
xa-datasource-class
Specify the XA datasource class for the JDBC driver’s implementation of the javax.sql.XADataSource class.
xa-datasource-properties
At least one XA datasource property is required when defining an XA datasource or you will receive an error when attempting to add it. Additional properties can also be added to the XA datasource after it has been defined.

For a complete listing of all available datasource attributes, see the Datasource Attributes section.

12.4. Modifying Datasources

Datasources settings can be configured using the management console or the management CLI.

JBoss EAP 7 allows you to use expressions in datasource attribute values, such as the enabled attribute. See the Property Replacement section for details on using expressions in the configuration.

12.4.1. Modify a Non-XA Datasource

Non-XA datasource settings can be updated using the data-source management CLI command. You can also update datasource attributes from the management console by navigating to ConfigurationSubsystemsDatasources & DriversDatasources.

Note

Non-XA datasources can be integrated with JTA transactions. To integrate the datasource with JTA, ensure that the jta parameter is set to true.

Settings for a datasource can be updated by using the following management CLI command.

data-source --name=DATASOURCE_NAME --ATTRIBUTE_NAME=ATTRIBUTE_VALUE
Note

In a managed domain, you must specify the --profile=PROFILE_NAME argument.

A server reload may be required for the changes to take effect.

12.4.2. Modify an XA Datasource

XA datasource settings can be updated using the xa-data-source management CLI command. You can also update datasource attributes from the management console by navigating to ConfigurationSubsystemsDatasources & DriversDatasources.

  • Settings for an XA datasource can be updated by using the following management CLI command.

    xa-data-source --name=XA_DATASOURCE_NAME --ATTRIBUTE_NAME=ATTRIBUTE_VALUE
    Note

    In a managed domain, you must specify the --profile=PROFILE_NAME argument.

  • An XA datasource property can be added using the following management CLI command.

    /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=PROPERTY:add(value=VALUE)
    Note

    In a managed domain, you must precede this command with /profile=PROFILE_NAME.

A server reload may be required for the changes to take effect.

12.5. Removing Datasources

Datasources can be removed using the management console or the management CLI.

12.5.1. Remove a Non-XA Datasource

Non-XA datasources can be removed using the data-source remove management CLI command. You can also use the management console to remove datasources by navigating to ConfigurationSubsystemsDatasources & DriversDatasources.

data-source remove --name=DATASOURCE_NAME
Note

In a managed domain, you must specify the --profile=PROFILE_NAME argument.

The server will require a reload after the datasource is removed.

12.5.2. Remove an XA Datasource

XA datasources can be removed using the xa-data-source remove management CLI command. You can also use the management console to remove datasources by navigating to ConfigurationSubsystemsDatasources & DriversDatasources.

xa-data-source remove --name=XA_DATASOURCE_NAME
Note

In a managed domain, you must specify the --profile=PROFILE_NAME argument.

The server will require a reload after the XA datasource is removed.

12.6. Testing Datasource Connections

You can use the management CLI or management console to test a datasource connection to verify that its settings are correct.

Test a Datasource Connection Using the Management CLI

The following management CLI command can be used to test a datasource’s connection.

/subsystem=datasources/data-source=DATASOURCE_NAME:test-connection-in-pool
Note

In a managed domain, you must precede this command with /host=HOST_NAME/server=SERVER_NAME. If you are testing an XA datasource, replace data-source=DATASOURCE_NAME with xa-data-source=XA_DATASOURCE_NAME.

Test a Datasource Connection Using the Management Console

When using the Add Datasource wizard in the management console, you have the opportunity to test the connection before creating the datasource. On the Test Connection screen of the wizard, click the Test Connection button.

Once a datasource has been added, you can test the connection by navigating to ConfigurationSubsystemsDatasources & DriversDatasources, selecting the datasource, and choosing Test Connection from the drop down.

12.7. Flushing Datasource Connections

You can flush datasource connections using the following management CLI commands.

Note

In a managed domain, you must precede these commands with /host=HOST_NAME/server=SERVER_NAME.

  • Flush all connections in the pool.

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-all-connection-in-pool
  • Gracefully flush all connections in the pool.

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-gracefully-connection-in-pool

    The server will wait until connections become idle before flushing them.

  • Flush all idle connections in the pool.

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-idle-connection-in-pool
  • Flush all invalid connections in the pool.

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-invalid-connection-in-pool

    The server will flush all connections that it determines to be invalid, for example, by the valid-connection-checker-class-name or check-valid-connection-sql validation mechanism discussed in Database Connection Validation.

You can also flush connections using the management console. From the Runtime tab, select the server, select Datasources, choose a datasource, and use the drop down to select the appropriate action.

12.8. XA Datasource Recovery

An XA datasource is a datasource that can participate in an XA global transaction, which is coordinated by the transaction manager and can span multiple resources in a single transaction. If one of the participants fails to commit its changes, the other participants abort the transaction and restore their state as it was before the transaction occurred. This is to maintain consistency and avoid potential data loss or corruption.

XA recovery is the process of ensuring that all resources affected by a transaction are updated or rolled back, even if any of the resources or transaction participants crash or become unavailable. XA recovery happens without user intervention.

Each XA resource needs to have a recovery module associated with its configuration. The recovery module is the code that is executed when recovery is being performed. JBoss EAP automatically registers recovery modules for JDBC XA resources. You can register a custom module with your XA datasource if you wish to implement custom recovery code. The recovery module must extend class com.arjuna.ats.jta.recovery.XAResourceRecovery.

12.8.1. Configuring XA Recovery

For most JDBC resources, the recovery module is automatically associated with the resource. In these cases, you only need to configure the options that allow the recovery module to connect to your resource to perform recovery.

The following table describes the XA datasource parameters specific to XA recovery. Each of these configuration attributes can be set during datasource creation or afterward. You can set them using either the management console or the management CLI. See Modify an XA Datasource for information on configuring XA datasources.

Table 12.2. Datasource Parameters for XA Recovery

AttributeDescription

recovery-username

The user name to use to connect to the resource for recovery. Note that if this is not specified, the datasource security settings will be used.

recovery-password

The password to use to connect to the resource for recovery. Note that if this is not specified, the datasource security settings will be used.

recovery-security-domain

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

recovery-plugin-class-name

If you need to use a custom recovery module, set this attribute to the fully-qualified class name of the module. The module should extend class com.arjuna.ats.jta.recovery.XAResourceRecovery.

recovery-plugin-properties

If you use a custom recovery module which requires properties to be set, set this attribute to the list of comma-separated KEY=VALUE pairs for the properties.

Disable XA Recovery

If multiple XA datasources connect to the same physical database, then XA recovery typically needs to be configured for only one of them.

Use the following management CLI command to disable recovery for an XA datasource:

/subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME:write-attribute(name=no-recovery,value=true)

12.8.2. Vendor-Specific XA Recovery

Vendor-Specific Configuration

Some databases require specific configurations in order to cooperate in XA transactions managed by the JBoss EAP transaction manager. For detailed and up-to-date information, see your database vendor’s documentation.

MySQL
No special configuration is required. For more information, see the MySQL documentation.
PostgreSQL and Postgres Plus Advanced Server
For PostgreSQL to be able to handle XA transactions, change the configuration parameter max_prepared_transactions to a value greater than 0 and equal to or greater than max_connections.
Oracle

Ensure that the Oracle user, USER, has access to the tables needed for recovery.

GRANT SELECT ON sys.dba_pending_transactions TO USER;
GRANT SELECT ON sys.pending_trans$ TO USER;
GRANT SELECT ON sys.dba_2pc_pending TO USER;
GRANT EXECUTE ON sys.dbms_xa TO USER;

If the Oracle user does not have the proper permissions, you may see an error such as the following:

WARN  [com.arjuna.ats.jta.logging.loggerI18N] [com.arjuna.ats.internal.jta.recovery.xarecovery1] Local XARecoveryModule.xaRecovery  got XA exception javax.transaction.xa.XAException, XAException.XAER_RMERR
Microsoft SQL Server
For more information, see the Microsoft SQL Server documentation, including http://msdn.microsoft.com/en-us/library/aa342335.aspx.
IBM DB2
No special configuration is required. For more information, see the IBM DB2 documentation.
Sybase

Sybase expects XA transactions to be enabled on the database. Without correct database configuration, XA transactions will not work. The enable xact coordination parameter enables or disables Adaptive Server transaction coordination services. When this parameter is enabled, Adaptive Server ensures that updates to remote Adaptive Server data commit or roll back with the original transaction.

To enable transaction coordination, use:

sp_configure 'enable xact coordination', 1
MariaDB
No special configuration is required. For more information, see the MariaDB documentation.
Known Issues

These known issues with handling XA transactions are for the specific database and JDBC driver versions supported with JBoss EAP 7. For up-to-date information on the supported databases, see JBoss EAP supported configurations.

MySQL
MySQL is not fully capable of handling XA transactions. If a client is disconnected from MySQL, then all the information about such transactions is lost. See this MySQL bug for more information. Note that this issue was fixed in MySQL 5.7.
PostgreSQL and Postgres Plus Advanced Server

The JDBC driver returns the XAER_RMERR XAException error code when a network failure occurs during the commit phase of two-phase commit (2PC). This error signals an unrecoverable catastrophic event to the transaction manager, but the transaction is left in the in-doubt state on the database side and could be easily corrected after network connection is established again. The correct return code should be XAER_RMFAIL or XAER_RETRY. The incorrect error code causes the transaction to be left in the Heuristic state on the JBoss EAP side and holding locks in the database which requires manual intervention. See this PostgreSQL bug for more information.

If a connection failure happens when the one-phase commit optimization is used, the JDBC driver returns XAER_RMERR, but the XAER_RMFAIL error code should be returned. This could lead to data inconsistency if the database commits data during one-phase commit and the connection goes down at that moment, then the client is informed that transaction was rolled back.

The Postgres Plus JDBC driver returns XIDs for all prepared transactions that exist in the Postgres Plus Server, so there is no way to determine the database to which the XID belongs. If you define more than one data source for the same database in JBoss EAP, an in-doubt transaction recovery attempt could be run under wrong account, which causes the recovery to fail.

Oracle

The JDBC driver returns XIDs belonging to all users on the database instance, when the Recovery Manager calls recovery using datasource configured with some user credentials. The JDBC driver throws the exception ORA-24774: cannot switch to specified transaction because it tries to recover XIDs belonging to other users.

The workaround for this issue is to grant FORCE ANY TRANSACTION privilege to the user whose credentials are used in recovery datasource configuration. More information about configuring the privilege can be found here: http://docs.oracle.com/database/121/ADMIN/ds_txnman.htm#ADMIN12259.

Microsoft SQL Server

The JDBC driver returns the XAER_RMERR XAException error code when a network failure occurs during the commit phase of two-phase commit (2PC). This error signals an unrecoverable catastrophic event to the transaction manager, but the transaction is left in the in-doubt state on the database side and could be easily corrected after network connection is established again. The correct return code should be XAER_RMFAIL or XAER_RETRY. The incorrect error code causes the transaction to be left in the Heuristic state on the JBoss EAP side and holding locks in the database which requires manual intervention. See this Microsoft SQL Server issue report for more information.

If a connection failure happens when the one-phase commit optimization is used, the JDBC driver returns XAER_RMERR, but the XAER_RMFAIL error code should be returned. This could lead to data inconsistency if the database commits data during one-phase commit and the connection goes down at that moment, then the client is informed that transaction was rolled back.

IBM DB2
If a connection failure happens during a one-phase commit, the JDBC driver returns XAER_RETRY, but the XAER_RMFAIL error code should be returned. This could lead to data inconsistency if the database commits data during one-phase commit and the connection goes down at that moment, then the client is informed that transaction was rolled back.
Sybase

The JDBC driver returns the XAER_RMERR XAException error code when a network failure occurs during the commit phase of two-phase commit (2PC). This error signals an unrecoverable catastrophic event to the transaction manager, but the transaction is left in the in-doubt state on the database side and could be easily corrected after network connection is established again. The correct return code should be XAER_RMFAIL or XAER_RETRY. The incorrect error code causes the transaction to be left in the Heuristic state on the JBoss EAP side and holding locks in the database which requires manual intervention.

If a connection failure happens when the one-phase commit optimization is used, the JDBC driver returns XAER_RMERR, but the XAER_RMFAIL error code should be returned. This could lead to data inconsistency if the database commits data during one-phase commit and the connection goes down at that moment, then the client is informed that transaction was rolled back.

If an XA transaction that includes an insert to a Sybase 15.7 or 16 database fails before the Sybase transaction branch is in a prepared state, then repeating the XA transaction and inserting the same record with the same primary key will fail with an error of com.sybase.jdbc4.jdbc.SybSQLException: Attempt to insert duplicate key row. This exception will be thrown until the original unfinished Sybase transaction branch is rolled back.

MariaDB
MariaDB is not fully capable of handling XA transactions. If a client is disconnected from MariaDB, then all the information about such transactions is lost.
MariaDB Galera Cluster
XA transactions are not supported in MariaDB Galera Cluster.

12.9. Database Connection Validation

Database maintenance, network problems, or other outage events may cause JBoss EAP to lose the connection to the database. In order to recover from these situations, you can enable database connection validation for your datasources.

To configure database connection validation, you specify the validation timing method to define when the validation occurs, the validation mechanism to determine how the validation is performed, and the exception sorter to define how exceptions are handled.

  1. Choose one of the validation timing methods.

    validate-on-match

    When the validate-on-match option is set to true, the database connection is validated every time it is checked out from the connection pool using the validation mechanism specified in the next step.

    If a connection is not valid, a warning is written to the log and the next connection in the pool is retrieved. This process continues until a valid connection is found. If you prefer not to cycle through every connection in the pool, you can use the use-fast-fail option. If a valid connection is not found in the pool, a new connection is created. If the connection creation fails, an exception is returned to the requesting application.

    This setting results in the quickest recovery but creates the highest load on the database. However, this is the safest selection if the minimal performance hit is not a concern.

    background-validation

    When the background-validation option is set to true, connections are validated periodically in a background thread prior to use. The frequency of the validation is specified by the background-validation-millis property. The default value of background-validation-millis is 0, meaning that it is disabled.

    When determining the value of the background-validation-millis property, consider the following:

    • This value should not be set to the same value as your idle-timeout-minutes setting.
    • The lower the value, the more frequently the pool is validated and the sooner invalid connections are removed from the pool.
    • Lower values take more database resources. Higher values result in less frequent connection validation checks and use less database resources, but dead connections are undetected for longer periods of time.
    Note

    These options are mutually exclusive. If validate-on-match is set to true, then background-validation must be set to false. If background-validation is set to true, then validate-on-match must be set to false.

  2. Choose one of the validation mechanisms.

    valid-connection-checker-class-name

    Using valid-connection-checker-class-name is the preferred validation mechanism. This specifies a connection checker class that is used to validate connections for the particular database in use. JBoss EAP provides the following connection checkers:

    • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
    check-valid-connection-sql

    Using check-valid-connection-sql, you provide the SQL statement that will be used to validate the connection.

    The following is an example SQL statement that you might use to validate Oracle connections.

    select 1 from dual

    The following is an example SQL statement that you might use to validate MySQL or PostgreSQL connections.

    select 1
  3. Set the exception sorter class name.

    When an exception is marked as fatal, the connection is closed immediately, even if the connection is participating in a transaction. Use the exception sorter class option to properly detect and clean up after fatal connection exceptions. Choose the appropriate JBoss EAP exception sorter for your datasource type.

    • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.informix.InformixExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter

12.10. Datasource Security

Datasource security refers to encrypting or obscuring passwords for datasource connections. These passwords can be stored in plain text in configuration files, but this represents a security risk.

There are several methods you can use for datasource security. Examples of each are included below.

Secure a Datasource Using a Security Domain

Use the following steps to secure a datasource using a security domain:

  1. Create the new security domain.

    /subsystem=security/security-domain=DsRealm:add(cache-type=default)
    /subsystem=security/security-domain=DsRealm/authentication=classic:add(login-modules=[{code=ConfiguredIdentity,flag=required,module-options={userName=sa,
    principal=sa, password=sa}}])

    A security domain for the datasource is defined. The following XML extract is the result of calling CLI commands.

     <security-domain name="DsRealm" cache-type="default">
      <authentication>
        <login-module code="ConfiguredIdentity" flag="required">
          <module-option name="userName" value="sa"/>
          <module-option name="principal" value="sa"/>
          <module-option name="password" value="sa"/>
        </login-module>
      </authentication>
    </security-domain>
  2. Add a new datasource.

    data-source add --name=securityDs
    --jndi-name=java:jboss/datasources/securityDs
    --connection-url=jdbc:h2:mem:test;DB_CLOSE_DELAY=-1 --driver-name=h2
    --new-connection-sql="select current_user()"
  3. Set the security domain on the datasource.

    data-source --name=securityDs --security-domain=DsRealm
  4. Reload the server for the changes to be effective.

    reload
Note

If you are using a security domain with multiple datasources, disable caching on the security domain. This can be accomplished by setting the value of the cache-type attribute to none or by removing the attribute altogether; however, if caching is desired, use a separate security domain for each datasource.

The following XML extract shows the datasource secured with the DsRealm.

<datasources>
  <datasource jndi-name="java:jboss/datasources/securityDs"
    pool-name="securityDs">
    <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
      <driver>h2</driver>
      <new-connection-sql>select current_user()</new-connection-sql>
      <security>
        <security-domain>DsRealm</security-domain>
      </security>
    </datasource>
</datasources>

For more information on using Security Domains, see How to Configure Identity Management.

Secure a Datasource Using a Password Vault

Use the following steps to secure a datasource using a password vault:

  1. Set the password vault for the ExampleDS datasource.

    data-source --name=ExampleDS
    --password=${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}
  2. Reload the server to implement the changes.

    reload

The following XML security element is added to the ExampleDS datasource secured with password vault.

<security>
  <user-name>admin</user-name>
  <password>${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}</password>
</security>

For more information on using the Password Vault, see the Password Vault section in the JBoss EAP How to Configure Server Security guide.

Secure a Datasource Using a Credential Store

You can also use a credential store to provide passwords. The elytron subsystem provides the ability to create credential stores to securely house and use your passwords throughout JBoss EAP. You can find more details on creating and using credential stores in the Credential Store section in the JBoss EAP How to Configure Server Security guide.

Adding a Credential Store Reference to ExampleDS

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=credential-reference,value={store=exampleCS, alias=example-ds-pw})

Secure a Datasource Using an Authentication Context

You can also use an Elytron authentication context to provide usernames and passwords.

Use the following steps to configure and use an authentication context for datasource security.

  1. Remove password and user-name.

    /subsystem=datasources/data-source=ExampleDS:undefine-attribute(name=password)
    /subsystem=datasources/data-source=ExampleDS:undefine-attribute(name=user-name)
  2. Enable Elytron security for the datasource.

    /subsystem=datasources/data-source=ExampleDS:write-attribute(name=elytron-enabled,value=true)
    
    reload
  3. Create an authentication-configuration for your credentials.

    The authentication configuration contains the credentials you want your datasource to use when making a connection. The below example uses a reference to a credential store, but you could also use an Elytron security domain.

    /subsystem=elytron/authentication-configuration=exampleAuthConfig:add(authentication-name=sa,credential-reference={clear-text=sa})
  4. Create an authentication-context.

    /subsystem=elytron/authentication-context=exampleAuthContext:add(match-rules=[{authentication-configuration=exampleAuthConfig}])
  5. Update the datasource to use the authentication context.

    The below example updates ExampleDS to use an authentication context.

    /subsystem=datasources/data-source=ExampleDS:write-attribute(name=authentication-context,value=exampleAuthContext)
    
    reload
    Note

    If authentication-context attribute is not set and elytron-enabled attribute is set to true, JBoss EAP will use the current context for authentication.

Secure a Datasource using Kerberos

To secure a datasource using kerberos authentication, the following configuration is required:

  • Kerberos is configured on the database server.
  • JBoss EAP host server has a keytab entry for the database server.

To secure a datasource using kerberos:

  1. Configure JBoss EAP to use kerberos.

    /system-property=java.security.krb5.conf:add(value="/path/to/krb5.conf")
    /system-property=sun.security.krb5.debug:add(value="false")
    /system-property=sun.security.spnego.debug:add(value="false")

    For debugging, change the values of sun.security.krb5.debug and sun.security.spnego.debug to true. In a production environment, it is recommended to set the values to false.

  2. Configure security.

    You can use legacy security or Elytron security to secure a datasource.

    • To use kerberos with legacy security:

      1. Configure infinispan cache to periodically remove expired tickets from cache.

        batch
        /subsystem=infinispan/cache-container=security:add(default-cache=auth-cache)
        /subsystem=infinispan/cache-container=security/local-cache=auth-cache:add()
        /subsystem=infinispan/cache-container=security/local-cache=auth-cache/expiration=EXPIRATION:add(lifespan=3540000,max-idle=3540000)
        /subsystem=infinispan/cache-container=security/local-cache=auth-cache/memory=object:add(size=1000)
        run-batch

        The following attributes define ticket expiration:

        • lifespan: Interval, in milliseconds, at which new certificates are requested from the KDC. Set the value of the lifespan attribute to be just smaller than the lifespan defined by the KDC.
        • max-idle: Interval, in milliseconds, at which a valid ticket should be removed from the cache, if it unused.
        • max-entries: The maximum number copies of the kerberos tickets to keep in cache. The value corresponds to the number of configured connections in your datasource.
      2. Create a security domain.

        batch
        /subsystem=security/security-domain=KerberosDatabase:add(cache-type=infinispan)
        /subsystem=security/security-domain=KerberosDatabase/authentication=classic:add
        /subsystem=security/security-domain=KerberosDatabase/authentication=classic/login-module="KerberosDatabase-Module":add(code="org.jboss.security.negotiation.KerberosLoginModule",module="org.jboss.security.negotiation",flag=required, module-options={ "debug" => "false", "storeKey" => "false", "useKeyTab" => "true", "keyTab" => "/path/to/eap.keytab", "principal" => "PRINCIPAL@SERVER.COM", "doNotPrompt" => "true", "refreshKrb5Config" => "true", "isInitiator" => "true", "addGSSCredential" => "true", "credentialLifetime" => "-1"})
        run-batch
        • When using Microsoft JDBC driver for SQL server, add attribute and value "wrapGSSCredential" ⇒ "true" in module-options.
        • For debugging, change the value of the debug attribute in module-options to true.
    • To use kerberos with Elytron:

      1. Set up a kerberos factory in Elytron.

        /subsystem=elytron/kerberos-security-factory=krbsf:add(debug=false, principal=PRINCIPAL@SERVER.COM, path=/path/to/keytab, request-lifetime=-1, obtain-kerberos-ticket=true, server=false)
        • For debugging, add attribute and value debug = true.

          For a list of supported attributes, see the Kerberos Security Factory Attributes section in the How to Configure Server Security guide.

      2. Create an authentication configuration to use the kerberos factory.

        /subsystem=elytron/authentication-configuration=kerberos-conf:add(kerberos-security-factory=krbsf)
      3. Create an authentication context.

        /subsystem=elytron/authentication-context=ds-context:add(match-rules=[{authentication-configuration=kerberos-conf}])
  3. Secure the datasource with kerberos.

    • If you use legacy security:

      1. Configure the datasource to use a security domain.

        /subsystem=datasources/data-source=KerberosDS:add(connection-url="URL", min-pool-size=0, max-pool-size=10, jndi-name="java:jboss/datasource/KerberosDS", driver-name=<jdbc-driver>.jar, security-domain=KerberosDatabase, allow-multiple-users=false, pool-prefill=false, pool-use-strict-min=false, idle-timeout-minutes=2)
      2. Configure vendor-specific connection properties.

        /subsystem=datasources/data-source=KerberosDS/connection-properties=<connection-property-name>:add(value="(<kerberos-value>)")

        Example: connection properties for Oracle database.

        /subsystem=datasources/data-source=KerberosDS/connection-properties=oracle.net.authentication_services:add(value="(KERBEROS5)")
    • If you use Elytron:

      1. Configure the datasource to use an authentication context.

        /subsystem=datasources/data-source=KerberosDS:add(connection-url="URL", min-pool-size=0, max-pool-size=10, jndi-name="java:jboss/datasource/KerberosDS", driver-name=<jdbc-driver>.jar, elytron-enabled=true, authentication-context=ds-context, allow-multiple-users=false, pool-prefill=false, pool-use-strict-min=false, idle-timeout-minutes=2)
      2. Configure vendor-specific connection properties.

        /subsystem=datasources/data-source=KerberosDS/connection-properties=<connection-property-name>:add(value="(<kerberos-value>)")

        Example: connection properties for Oracle database

        /subsystem=datasources/data-source=KerberosDS/connection-properties=oracle.net.authentication_services:add(value="(KERBEROS5)")

      When using kerberos authentication, it is recommended to use the following attributes and values for the datasource:

      • pool-prefill=false
      • pool-use-strict-min=false
      • idle-timeout-minutes

    For a list of supported attributes, see Datasource Attributes.

12.11. Datasource Statistics

When statistics collection is enabled for a datasource, you can view runtime statistics for the datasource.

12.11.1. Enabling Datasource Statistics

By default, datasource statistics are not enabled. You can enable datasource statistics collection using the management CLI or the management console.

Enable Datasource Statistics Using the Management CLI

The following management CLI command enables the collection of statistics for the ExampleDS datasource.

Note

In a managed domain, precede this command with /profile=PROFILE_NAME.

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=statistics-enabled,value=true)

Reload the server for the changes to take effect.

Enable Datasource Statistics Using the Management Console

Use the following steps to enable statistics collection for a datasource using the management console.

  1. Navigate to ConfigurationSubsystemsDatasources & DriversDatasources.
  2. Select the datasource and click View.
  3. Click Edit under the Attributes tab.
  4. Set the Statistics Enabled field to ON and click Save. A popup appears indicating that the changes require a reload in order to take effect.
  5. Reload the server.

    • For a standalone server, click the Reload link from the popup to reload the server.
    • For a managed domain, click the Topology link from the popup. From the Topology tab, select the appropriate server and select the Reload drop down option to reload the server.

12.11.2. Viewing Datasource Statistics

You can view runtime statistics for a datasource using the management CLI or management console.

View Datasource Statistics Using the Management CLI

The following management CLI command retrieves the core pool statistics for the ExampleDS datasource.

Note

In a managed domain, precede these commands with /host=HOST_NAME/server=SERVER_NAME.

/subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "ActiveCount" => 1,
        "AvailableCount" => 20,
        "AverageBlockingTime" => 0L,
        "AverageCreationTime" => 122L,
        "AverageGetTime" => 128L,
        "AveragePoolTime" => 0L,
        "AverageUsageTime" => 0L,
        "BlockingFailureCount" => 0,
        "CreatedCount" => 1,
        "DestroyedCount" => 0,
        "IdleCount" => 1,
        ...
}

The following management CLI command retrieves the JDBC statistics for the ExampleDS datasource.

/subsystem=datasources/data-source=ExampleDS/statistics=jdbc:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "PreparedStatementCacheAccessCount" => 0L,
        "PreparedStatementCacheAddCount" => 0L,
        "PreparedStatementCacheCurrentSize" => 0,
        "PreparedStatementCacheDeleteCount" => 0L,
        "PreparedStatementCacheHitCount" => 0L,
        "PreparedStatementCacheMissCount" => 0L,
        "statistics-enabled" => true
    }
}
Note

Since statistics are runtime information, be sure to specify the include-runtime=true argument.

See Datasource Statistics for a detailed list of all available statistics.

View Datasource Statistics Using the Management Console

To view datasource statistics from the management console, navigate to the Datasources subsystem from the Runtime tab, select a datasource, and click View.

See Datasource Statistics for a detailed list of all available statistics.

12.12. Datasource Tuning

For tips on monitoring and optimizing performance for the datasources subsystem, see the Datasource and Resource Adapter Tuning section of the Performance Tuning Guide.

12.13. Capacity Policies

JBoss EAP supports defining capacity polices for Jakarta Connectors deployments, including datasources. Capacity policies define how physical connections for a pool are created, referred to as capacity incrementing, and destroyed, referred to as capacity decrementing. The default policies are set to create one connection per request for capacity incrementing, and destroy all connections when they time out when the idle timeout is scheduled for capacity decrementing.

To configure capacity polices, you need to specify a capacity incrementer class, a capacity decrementer class, or both.

Example: Defining Capacity Policies

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-incrementer-class, value="org.jboss.jca.core.connectionmanager.pool.capacity.SizeIncrementer")

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-decrementer-class, value="org.jboss.jca.core.connectionmanager.pool.capacity.SizeDecrementer")

You can also configure properties on the specified capacity incrementer or decrementer class.

Example: Configuring Properties for Capacity Policies

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-incrementer-properties.size, value=2)

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-decrementer-properties.size, value=2)

MaxPoolSize Incrementer Policy

Class name: org.jboss.jca.core.connectionmanager.pool.capacity.MaxPoolSizeIncrementer

The MaxPoolSize incrementer policy will fill the pool to its max size for each request. This policy is useful when you want to keep the maximum number of connections available all the time.

Size Incrementer Policy

Class name: org.jboss.jca.core.connectionmanager.pool.capacity.SizeIncrementer

The Size incrementer policy will fill the pool by the specified number of connections for each request. This policy is useful when you want to increment with an additional number of connections per request in anticipation that the next request will also need a connection.

Table 12.3. Size policy properties

NameDescription

Size

The number of connections that should be created

Note

This is the default increment policy, and has a size value of 1.

Watermark Incrementer Policy

Class name: org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkIncrementer

The Watermark incrementer policy will fill the pool to the specified number of connections for each request. This policy is useful when you want to keep a specified number of connections in the pool at all time.

Table 12.4. Watermark policy properties

NameDescription

Watermark

The watermark level for the number of connections

MinPoolSize Decrementer Policy

Class name: org.jboss.jca.core.connectionmanager.pool.capacity.MinPoolSizeDecrementer

The MinPoolSize decrementer policy will decrement the pool to its min size for each request. This policy is useful when you want to limit the number of connections after each idle timeout request. The pool will operate in a First In First Out (FIFO) manner.

Size Decrementer Policy

Class name: org.jboss.jca.core.connectionmanager.pool.capacity.SizeDecrementer

The Size decrementer policy will decrement the pool by the specified number of connections for each idle timeout request.

Table 12.5. Size policy properties

NameDescription

Size

The number of connections that should be destroyed

This policy is useful when you want to decrement an additional number of connections per idle timeout request in anticipation that the pool usage will lower over time.

The pool will operate in a First In First Out (FIFO) manner.

TimedOut Decrementer Policy

Class name: org.jboss.jca.core.connectionmanager.pool.capacity.TimedOutDecrementer

The TimedOut decrementer policy will removed all connections that have timed out from the pool for each idle timeout request. The pool will operate in a First In Last Out (FILO) manner.

Note

This policy is the default decrement policy.

TimedOut/FIFO Decrementer Policy

Class name: org.jboss.jca.core.connectionmanager.pool.capacity.TimedOutFIFODecrementer

The TimedOutFIFO decrementer policy will removed all connections that have timed out from the pool for each idle timeout request. The pool will operate in a First In First Out (FIFO) manner.

Watermark Decrementer Policy

Class name: org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkDecrementer

The Watermark decrementer policy will decrement the pool to the specified number of connections for each idle timeout request. This policy is useful when you want to keep a specified number of connections in the pool at all time. The pool will operate in a First In First Out (FIFO) manner.

Table 12.6. Watermark policy properties

NameDescription

Watermark

The watermark level for the number of connections

12.14. Enlistment Tracing

Enlistment traces can be recorded in order to help locate error situations that happen during enlistment of XAResource instances. When enlistment tracing is enabled, the jca subsystem creates an exception object for every pool operation, so that an accurate stack trace can be produced if necessary; however, this does come with performance overhead.

As of JBoss EAP 7.1, enlistment tracing is disabled by default. You can enable the recording of enlistment traces for a datasource using the management CLI by setting the enlistment-trace attribute to true.

Enable enlistment tracing for a non-XA datasource.

data-source --name=DATASOURCE_NAME --enlistment-trace=true

Enable enlistment tracing for an XA datasource.

xa-data-source --name=XA_DATASOURCE_NAME --enlistment-trace=true
Warning

Enabling enlistment tracing can cause a performance impact.

12.15. Example Datasource Configurations

12.15.1. Example MySQL Datasource

This is an example of a MySQL datasource configuration with connection information, basic security, and validation options.

Example: MySQL Datasource Configuration
<datasources>
  <datasource jndi-name="java:jboss/MySqlDS" pool-name="MySqlDS">
    <connection-url>jdbc:mysql://localhost:3306/jbossdb</connection-url>
    <driver>mysql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="mysql" module="com.mysql">
      <driver-class>com.mysql.cj.jdbc.Driver</driver-class>
      <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: MySQL JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-8.0.12.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the MySQL JDBC driver as a core module.

    module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the MySQL JDBC driver.

    /subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)
  3. Add the MySQL datasource.

    data-source add --name=MySqlDS --jndi-name=java:jboss/MySqlDS --driver-name=mysql --connection-url=jdbc:mysql://localhost:3306/jbossdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter

12.15.2. Example MySQL XA Datasource

This is an example of a MySQL XA datasource configuration with XA datasource properties, basic security, and validation options.

Example: MySQL XA Datasource Configuration
<datasources>
  <xa-datasource jndi-name="java:jboss/MySqlXADS" pool-name="MySqlXADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      mysqldb
    </xa-datasource-property>
    <driver>mysql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="mysql" module="com.mysql">
      <driver-class>com.mysql.cj.jdbc.Driver</driver-class>
      <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: MySQL JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-8.0.12.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the MySQL JDBC driver as a core module.

    module add --name=com.mysql --resources=/path/to/mysql-connector-java-8.0.12.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the MySQL JDBC driver.

    /subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)
  3. Add the MySQL XA datasource.

    xa-data-source add --name=MySqlXADS --jndi-name=java:jboss/MySqlXADS --driver-name=mysql --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"mysqldb"}

12.15.3. Example PostgreSQL Datasource

This is an example of a PostgreSQL datasource configuration with connection information, basic security, and validation options.

Example: PostgreSQL Datasource Configuration
<datasources>
  <datasource jndi-name="java:jboss/PostgresDS" pool-name="PostgresDS">
    <connection-url>jdbc:postgresql://localhost:5432/postgresdb</connection-url>
    <driver>postgresql</driver>
    <security>
        <user-name>admin</user-name>
        <password>admin</password>
    </security>
    <validation>
        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/>
        <validate-on-match>true</validate-on-match>
        <background-validation>false</background-validation>
        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="postgresql" module="com.postgresql">
        <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: PostgreSQL JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.postgresql">
  <resources>
    <resource-root path="postgresql-42.x.y.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

In the example above, make sure you replace 42.x.y with your driver version number.

Additional resources

Example Management CLI Commands

You can add the PostgreSQL JDBC driver and the PostgreSQL datasource to your JDBC API with the following CLI commands.

  1. Add the PostgreSQL JDBC driver as a core module.

    module add --name=com.postgresql --resources=/path/to/postgresql-42.x.y.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api

    In the example above, make sure you replace 42.x.y with your driver version number.

    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the PostgreSQL JDBC driver.

    /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=com.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
  3. Add the PostgreSQL datasource.

    data-source add --name=PostgresDS --jndi-name=java:jboss/PostgresDS --driver-name=postgresql --connection-url=jdbc:postgresql://localhost:5432/postgresdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter

12.15.4. Example PostgreSQL XA Datasource

This is an example of a PostgreSQL XA datasource configuration with XA datasource properties, basic security, and validation options.

Example: PostgreSQL XA Datasource Configuration
<datasources>
  <xa-datasource jndi-name="java:jboss/PostgresXADS" pool-name="PostgresXADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="PortNumber">
      5432
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      postgresdb
    </xa-datasource-property>
    <driver>postgresql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="postgresql" module="com.postgresql">
      <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: PostgreSQL JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.postgresql">
  <resources>
    <resource-root path="postgresql-42.x.y.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

In the example above, make sure you replace 42.x.y with your driver version number.

Additional resources

Example Management CLI Commands

You can add the PostgreSQL JDBC driver and the PostgreSQL datasource to your JDBC API with the following CLI commands.

  1. Add the PostgreSQL JDBC driver as a core module.

    module add --name=com.postgresql --resources=/path/to/postgresql-42.x.y.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api

    In the example above, make sure you replace 42.x.y with your driver version number.

    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the PostgreSQL JDBC driver.

    /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=com.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
  3. Add the PostgreSQL XA datasource.

    xa-data-source add --name=PostgresXADS --jndi-name=java:jboss/PostgresXADS --driver-name=postgresql --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter --xa-datasource-properties={"ServerName"=>"localhost","PortNumber"=>"5432","DatabaseName"=>"postgresdb"}

12.15.5. Example Oracle Datasource

This is an example of an Oracle datasource configuration with connection information, basic security, and validation options.

Example: Oracle Datasource Configuration
<datasources>
  <datasource jndi-name="java:jboss/OracleDS" pool-name="OracleDS">
    <connection-url>jdbc:oracle:thin:@localhost:1521:XE</connection-url>
    <driver>oracle</driver>
    <security>
        <user-name>admin</user-name>
        <password>admin</password>
    </security>
    <validation>
        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/>
        <validate-on-match>true</validate-on-match>
        <background-validation>false</background-validation>
        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
        <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: Oracle JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.oracle">
    <resources>
        <resource-root path="ojdbc7.jar"/>
    </resources>
    <dependencies>
      <module name="javaee.api"/>
      <module name="sun.jdk"/>
      <module name="ibm.jdk"/>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
    </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the Oracle JDBC driver as a core module.

    module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the Oracle JDBC driver.

    /subsystem=datasources/jdbc-driver=oracle:add(driver-name=oracle,driver-module-name=com.oracle,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource)
  3. Add the Oracle datasource.

    data-source add --name=OracleDS --jndi-name=java:jboss/OracleDS --driver-name=oracle --connection-url=jdbc:oracle:thin:@localhost:1521:XE --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter

12.15.6. Example Oracle XA Datasource

Important

The following settings must be applied for the user accessing an Oracle XA datasource in order for XA recovery to operate correctly. The value user is the user defined to connect from JBoss EAP to Oracle:

  • GRANT SELECT ON sys.dba_pending_transactions TO user;
  • GRANT SELECT ON sys.pending_trans$ TO user;
  • GRANT SELECT ON sys.dba_2pc_pending TO user;
  • GRANT EXECUTE ON sys.dbms_xa TO user;

This is an example of an Oracle XA datasource configuration with XA datasource properties, basic security, and validation options.

Example: Oracle XA Datasource Configuration
<datasources>
  <xa-datasource jndi-name="java:jboss/OracleXADS" pool-name="OracleXADS">
    <xa-datasource-property name="URL">
      jdbc:oracle:thin:@oracleHostName:1521:orcl
    </xa-datasource-property>
    <driver>oracle</driver>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
      <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: Oracle JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.oracle">
    <resources>
        <resource-root path="ojdbc7.jar"/>
    </resources>
    <dependencies>
      <module name="javaee.api"/>
      <module name="sun.jdk"/>
      <module name="ibm.jdk"/>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
    </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the Oracle JDBC driver as a core module.

    module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the Oracle JDBC driver.

    /subsystem=datasources/jdbc-driver=oracle:add(driver-name=oracle,driver-module-name=com.oracle,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource)
  3. Add the Oracle XA datasource.

    xa-data-source add --name=OracleXADS --jndi-name=java:jboss/OracleXADS --driver-name=oracle --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter --same-rm-override=false --xa-datasource-properties={"URL"=>"jdbc:oracle:thin:@oracleHostName:1521:orcl"}

12.15.7. Example Microsoft SQL Server Datasource

This is an example of a Microsoft SQL Server datasource configuration with connection information, basic security, and validation options.

Example: Microsoft SQL Server Datasource Configuration
<datasources>
  <datasource jndi-name="java:jboss/MSSQLDS" pool-name="MSSQLDS">
    <connection-url>jdbc:sqlserver://localhost:1433;DatabaseName=MyDatabase</connection-url>
    <driver>sqlserver</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="sqlserver" module="com.microsoft">
      <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: Microsoft SQL Server JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.microsoft">
  <resources>
    <resource-root path="sqljdbc42.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
    <module name="javax.xml.bind.api"/>
  </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the Microsoft SQL Server JDBC driver as a core module.

    module add --name=com.microsoft --resources=/path/to/sqljdbc42.jar --dependencies=javax.api,javax.transaction.api,javax.xml.bind.api,javaee.api,sun.jdk,ibm.jdk
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the Microsoft SQL Server JDBC driver.

    /subsystem=datasources/jdbc-driver=sqlserver:add(driver-name=sqlserver,driver-module-name=com.microsoft,driver-xa-datasource-class-name=com.microsoft.sqlserver.jdbc.SQLServerXADataSource)
  3. Add the Microsoft SQL Server datasource.

    data-source add --name=MSSQLDS --jndi-name=java:jboss/MSSQLDS --driver-name=sqlserver --connection-url=jdbc:sqlserver://localhost:1433;DatabaseName=MyDatabase --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter

12.15.8. Example Microsoft SQL Server XA Datasource

This is an example of a Microsoft SQL Server XA datasource configuration with XA datasource properties, basic security, and validation options.

Example: Microsoft SQL Server XA Datasource Configuration
<datasources>
  <xa-datasource jndi-name="java:jboss/MSSQLXADS" pool-name="MSSQLXADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      mssqldb
    </xa-datasource-property>
    <xa-datasource-property name="SelectMethod">
      cursor
    </xa-datasource-property>
    <driver>sqlserver</driver>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="sqlserver" module="com.microsoft">
      <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: Microsoft SQL Server JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.microsoft">
  <resources>
    <resource-root path="sqljdbc42.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
    <module name="javax.xml.bind.api"/>
  </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the Microsoft SQL Server JDBC driver as a core module.

    module add --name=com.microsoft --resources=/path/to/sqljdbc42.jar --dependencies=javax.api,javax.transaction.api,javax.xml.bind.api,javaee.api,sun.jdk,ibm.jdk
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the Microsoft SQL Server JDBC driver.

    /subsystem=datasources/jdbc-driver=sqlserver:add(driver-name=sqlserver,driver-module-name=com.microsoft,driver-xa-datasource-class-name=com.microsoft.sqlserver.jdbc.SQLServerXADataSource)
  3. Add the Microsoft SQL Server XA datasource.

    xa-data-source add --name=MSSQLXADS --jndi-name=java:jboss/MSSQLXADS --driver-name=sqlserver --user-name=admin --password=admin --validate-on-match=true --background-validation=false --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter --same-rm-override=false --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"mssqldb","SelectMethod"=>"cursor"}

12.15.9. Example IBM DB2 Datasource

This is an example of an IBM DB2 datasource configuration with connection information, basic security, and validation options.

Example: IBM DB2 Datasource Configuration
<datasources>
  <datasource jndi-name="java:jboss/DB2DS" pool-name="DB2DS">
    <connection-url>jdbc:db2://localhost:50000/ibmdb2db</connection-url>
    <driver>ibmdb2</driver>
    <pool>
      <min-pool-size>0</min-pool-size>
      <max-pool-size>50</max-pool-size>
    </pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="ibmdb2" module="com.ibm">
        <xa-datasource-class>com.ibm.db2.jcc.DB2XADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: IBM DB2 JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.ibm">
  <resources>
    <resource-root path="db2jcc4.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the IBM DB2 JDBC driver as a core module.

    module add --name=com.ibm --resources=/path/to/db2jcc4.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the IBM DB2 JDBC driver.

    /subsystem=datasources/jdbc-driver=ibmdb2:add(driver-name=ibmdb2,driver-module-name=com.ibm,driver-xa-datasource-class-name=com.ibm.db2.jcc.DB2XADataSource)
  3. Add the IBM DB2 datasource.

    data-source add --name=DB2DS --jndi-name=java:jboss/DB2DS --driver-name=ibmdb2 --connection-url=jdbc:db2://localhost:50000/ibmdb2db --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter --min-pool-size=0 --max-pool-size=50

12.15.10. Example IBM DB2 XA Datasource

This is an example of an IBM DB2 XA datasource configuration with XA datasource properties, basic security, and validation options.

Example: IBM DB2 XA Datasource Configuration
<datasources>
  <xa-datasource jndi-name="java:jboss/DB2XADS" pool-name="DB2XADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      ibmdb2db
    </xa-datasource-property>
    <xa-datasource-property name="PortNumber">
      50000
    </xa-datasource-property>
    <xa-datasource-property name="DriverType">
      4
    </xa-datasource-property>
    <driver>ibmdb2</driver>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <recovery>
      <recover-plugin class-name="org.jboss.jca.core.recovery.ConfigurableRecoveryPlugin">
        <config-property name="EnableIsValid">
          false
        </config-property>
        <config-property name="IsValidOverride">
          false
        </config-property>
        <config-property name="EnableClose">
          false
        </config-property>
      </recover-plugin>
    </recovery>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="ibmdb2" module="com.ibm">
        <xa-datasource-class>com.ibm.db2.jcc.DB2XADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: IBM DB2 JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.ibm">
  <resources>
    <resource-root path="db2jcc4.jar"/>
  </resources>
  <dependencies>
    <module name="javaee.api"/>
    <module name="sun.jdk"/>
    <module name="ibm.jdk"/>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the IBM DB2 JDBC driver as a core module.

    module add --name=com.ibm --resources=/path/to/db2jcc4.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the IBM DB2 JDBC driver.

    /subsystem=datasources/jdbc-driver=ibmdb2:add(driver-name=ibmdb2,driver-module-name=com.ibm,driver-xa-datasource-class-name=com.ibm.db2.jcc.DB2XADataSource)
  3. Add the IBM DB2 XA datasource.

    xa-data-source add --name=DB2XADS --jndi-name=java:jboss/DB2XADS --driver-name=ibmdb2 --user-name=admin --password=admin --validate-on-match=true --background-validation=false --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter --same-rm-override=false --recovery-plugin-class-name=org.jboss.jca.core.recovery.ConfigurableRecoveryPlugin --recovery-plugin-properties={"EnableIsValid"=>"false","IsValidOverride"=>"false","EnableClose"=>"false"} --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"ibmdb2db","PortNumber"=>"50000","DriverType"=>"4"}

12.15.11. Example Sybase Datasource

This is an example of a Sybase datasource configuration with connection information, basic security, and validation options.

Example: Sybase Datasource Configuration
<datasources>
  <datasource jndi-name="java:jboss/SybaseDB" pool-name="SybaseDB">
    <connection-url>jdbc:sybase:Tds:localhost:5000/DATABASE?JCONNECT_VERSION=6</connection-url>
    <driver>sybase</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="sybase" module="com.sybase">
      <xa-datasource-class>com.sybase.jdbc4.jdbc.SybXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: Sybase JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.sybase">
    <resources>
      <resource-root path="jconn4.jar"/>
    </resources>
    <dependencies>
      <module name="javaee.api"/>
      <module name="sun.jdk"/>
      <module name="ibm.jdk"/>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
    </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the Sybase JDBC driver as a core module.

    module add --name=com.sybase --resources=/path/to/jconn4.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

  2. Register the Sybase JDBC driver.

    /subsystem=datasources/jdbc-driver=sybase:add(driver-name=sybase,driver-module-name=com.sybase,driver-xa-datasource-class-name=com.sybase.jdbc4.jdbc.SybXADataSource)
  3. Add the Sybase datasource.

    data-source add --name=SybaseDB --jndi-name=java:jboss/SybaseDB --driver-name=sybase --connection-url=jdbc:sybase:Tds:localhost:5000/DATABASE?JCONNECT_VERSION=6 --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter

12.15.12. Example Sybase XA Datasource

This is an example of a Sybase XA datasource configuration with XA datasource properties, basic security, and validation options.

Example: Sybase XA Datasource Configuration
<datasources>
  <xa-datasource jndi-name="java:jboss/SybaseXADS" pool-name="SybaseXADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      mydatabase
    </xa-datasource-property>
    <xa-datasource-property name="PortNumber">
      4100
    </xa-datasource-property>
    <xa-datasource-property name="NetworkProtocol">
      Tds
    </xa-datasource-property>
    <driver>sybase</driver>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="sybase" module="com.sybase">
      <xa-datasource-class>com.sybase.jdbc4.jdbc.SybXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Example: Sybase JDBC Driver module.xml File
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="com.sybase">
    <resources>
      <resource-root path="jconn4.jar"/>
    </resources>
    <dependencies>
      <module name="javaee.api"/>
      <module name="sun.jdk"/>
      <module name="ibm.jdk"/>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
    </dependencies>
</module>
Example Management CLI Commands

This example configuration can be achieved by using the following management CLI commands.

  1. Add the Sybase JDBC driver as a core module.

    module add --name=com.sybase --resources=/path/to/jconn4.jar --dependencies=javaee.api,sun.jdk,ibm.jdk,javax.api,javax.transaction.api
    Important

    Using the module management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.

    Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    See