Configuration Guide

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.

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.

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.

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.

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.

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.

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.

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)

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)

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.

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)

Stop JBoss EAP in a Managed Domain (RPM Installation)

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

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

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:

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:

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

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.

/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 five predefined profiles (default, ha, full, full-ha, load-balancer).

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.

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)

/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

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

/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:

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.

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:

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:

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)

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.

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>

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.

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"}

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

ls /path

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

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

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: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>

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.

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.

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.

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.

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.

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.

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.

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

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>

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.

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.

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:

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>

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.

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>

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:

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

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

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:

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.

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.

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:

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.

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.

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.

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

Add an Application

Deploy an Application to a Server Group

Undeploy an Application from a Server Group

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

This removes the deployment from the content repository.

Disable an Application

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

Replace an Application

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

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.

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

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.

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)

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

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

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

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.

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

Deploy an Application

Undeploy an Application

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.

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.

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>

This ensures that framework.ear is deployed before app.ear.

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.

For full usage details, execute deployment-overlay --help.

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.

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]

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.

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.

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.

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

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"
    }]}
}

attachment display --operation=/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF)

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

attachment save --operation=/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF) --file=/path/to/MANIFEST.MF

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:

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.

For more information, see the Start a Managed Domain and Domain Controller Configuration sections.

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:

For more information, see the Start a Managed Domain and Host Controller Configuration sections.

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.

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.

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.

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:

You must configure one host in the domain as the domain controller.

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.

A host controller must be configured to connect to the domain controller so that the host controller can register itself with the domain.

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.

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.

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.

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

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:

A server group includes the following optional attributes:

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:

A server includes the following optional attributes:

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

The following is an example of how to configure a host controller with multiple options for finding the domain controller.

<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:

In the example above, the first discovery option is the one expected to succeed. The second can be used in failover situations.

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.

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.

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.

<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

This host controller will now act as the domain controller.

You can run multiple host controllers on a single machine by using the jboss.domain.base.dir 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.

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.

Create a Managed Domain on Two Machines

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.

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.

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.

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

/host-exclude=EAP64z:write-attribute(name=active-server-groups,value=[eap6-main-server-group])

A JBoss EAP 7.3 domain controller can manage hosts and servers running from a previous minor release of JBoss EAP.

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.

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

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

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:

In cases where the existing profiles do not provide the necessary capabilities, JBoss EAP also provides the ability to define custom profiles as well.

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.

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)

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 Runtime → Hosts, choosing a host and clicking View, and selecting the JVMs tab.

These settings are stored in the within the <jvm> tag in host.xml.

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 Runtime → Server Groups, choosing a server group and clicking View, and selecting the JVMs tab.

These settings for a server group are stored in domain.xml.

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 Runtime → Hosts, choosing the host, clicking View on the server, and selecting the JVMs tab.

These settings for an individual server are stored in host.xml.

By default, all JBoss EAP log entries are written to the server.log file. The location of this file depends on your operating mode.

This file is often referred to as the server log. For more information, see the Root Logger section.

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.

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

/core-service=management:read-boot-errors

{
    "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"}
        }
        ...
    ]
}

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

The following log files are created for the default logging configurations. The default configuration writes the server log files using periodic log handlers.

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.

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"

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.

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.

Log categories can optionally use the log handlers of the root logger instead of their own handlers.

See Configuring Log Categories for more information.

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.

Log Handler Types

For details on configuring each of these log handlers, see the Configuring Log Handlers section.

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

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.

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.

/subsystem=logging/console-handler=CONSOLE:write-attribute(name=filter-spec, value="substituteAll(\"WFLY\"\,\"YLFW\")")

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.

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 Configuration → Subsystems → Logging → Configuration, clicking View, and selecting Handler → Console Handler.

The main tasks you will perform to configure a console log handler are:

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.

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

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 Configuration → Subsystems → Logging → Configuration, clicking View, and selecting Handler → File Handler.

The main tasks you will perform to configure a file log handler are:

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.

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

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 Configuration → Subsystems → Logging → Configuration, clicking View, and selecting Handler → Periodic Handler.

The main tasks you will perform to configure a periodic log handler are:

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.

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

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 Configuration → Subsystems → Logging → Configuration, clicking View, and selecting Handler → Size Handler.

The main tasks you will perform to configure a size log handler are:

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.

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

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 Configuration → Subsystems → Logging → Configuration, clicking View, and selecting Handler → Periodic Size Handler.

The main tasks you will perform to configure a periodic size log handler are:

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.

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

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 Configuration → Subsystems → Logging → Configuration, clicking View, and selecting Handler → Syslog Handler.

The main tasks you will perform to configure a syslog handler are:

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.

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

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 Configuration → Subsystems → Logging → Configuration, clicking View, and selecting Handler → Socket Handler.

The main tasks you will perform to configure a socket log handler are:

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.

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.

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 Configuration → Subsystems → Logging → Configuration, clicking View, and selecting Handler → Custom Handler.

The main tasks you will perform to configure a custom log handler are: