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.

A subsystem provides configuration options for a particular extension. 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.

A collection of subsystem configurations makes up a profile, which is configured to satisfy the needs of 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.

For more information on the available subsystems, see Overview of JBoss EAP Subsystems.

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

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.

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

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

Additional password requirements that can be configured in the EAP_HOME/bin/add-user.properties file:

  • Minimum length
  • Minimum alphabetic characters
  • Minimum digits
  • Minimum symbols
  • List of forbidden passwords (such as admin)
  • Whether to allow a password that matches the username

3.3. Management Interfaces

3.3.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 following command for help on a specific command.

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.3.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/App.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.
Access Control
Assign roles to users and groups when using Role-Based Access Control.
Patching
Apply patches to your JBoss EAP instances.
Note

To take a tour of the updated management console, click the Take a Tour link on the management console home page.

To view details about the form fields, click the Need Help? link.

To view the message history of configuration actions you have performed, click the Messages link in the top-right of the management console.

3.3.2.1. Enable/Disable Management Console

You can enable or disable the management console by setting the console-enabled boolean attribute of /core-service=management/management-interface=http-interface resource. For master host in domain mode, /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.3.2.2. 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 Confirm. The system refreshes your web browser automatically to use the selected locale.

3.4. Management APIs

3.4.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.4.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.5. Configuration Data

3.5.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 four predefined profiles (default, ha, full, full-ha).

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

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.5.2. Managed Domain Configuration Files

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

Table 3.2. 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).

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

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

/core-service=management/service=configuration-changes:add(max-history=10)

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

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

This will list 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.

3.5.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 Java 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)

Java 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 Java EE descriptors:

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

3.6. 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.3. Standard Paths

PropertyDescription

java.ext.dirs

The Java development kit extension directory paths.

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.6.1. 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 (standalone.conf or domain.conf). 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.6.2. 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 and selecting Paths. 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:3.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.6.3. 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.7. 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.8. 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.8.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.

To set up syslog audit logging, see Set Up 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.8.2. 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.8.3. 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.4. 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 not.

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.