Chapter 3. JBoss EAP Management

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.

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.

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:

Group information is stored in the following properties files:

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.

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:

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

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

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.

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

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

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:

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

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.

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.

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

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

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.

// 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();

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

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

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

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

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

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.

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.

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:

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:

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:

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)

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:

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.

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

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

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>

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>

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

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.

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.

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.