Chapter 2. Administering JBoss EAP

You must download the JBoss EAP .zip file before you can install JBoss EAP.

You can install the JBoss EAP .zip file by extracting the package contents to your desired file location.

You can run JBoss EAP as a standalone server to manage a single instance of JBoss EAP.

The server starts in a suspended state and does not accept requests until all required services start. After required services start, the server transitions into a normal running state and can start accepting requests.

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

JBoss EAP uses the standalone.xml configuration file by default, but you can start it using a different one.

You can run JBoss EAP in a managed domain operating mode to manage several JBoss EAP instances using a single domain controller.

Servers start in a suspended state and do not accept requests until all required services start. After required services start, the servers transition into a normal running state and start accepting requests.

You must start the domain controller before the servers in any of the server groups in the domain.

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

JBoss EAP uses the host.xml host configuration file by default, but you can start it using a different configuration file.

When setting up a managed domain, you must pass additional arguments into the startup script.

You can stop an interactive instance of a standalone server or a domain controller from the terminal where you started it.

You can connect to the management CLI to shut down a running instance of a standalone server or servers in a managed domain.

When running an instance of JBoss EAP on servers in a managed domain, you must specify the host name to shut down by using the --host argument with the shutdown command.

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

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

If you install JBoss EAP using the graphical installer, the graphical installer creates a management user during the installation process.

You can add a management user for JBoss EAP using the add-user script, which is a utility for adding new users to the properties files for immediate authentication.

You can create users 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.

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:

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.

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 remove applications, configure system settings, and perform other administrative tasks. You can perform operations in batch mode, allowing multiple tasks to be run as a group.

Many common terminal commands are available, such as ls (list), cd (change directory), and pwd (print working directory). The management CLI also supports tab completion.

Start the management CLI

$ EAP_HOME/bin/jboss-cli.sh

Connect to a running server

connect

You can start 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 about using deploy, use the following command:

deploy --help

Quit the management CLI

Use the following command to 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 servers 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)

View subsystem configuration

The following command uses the read-resource-description operation to display a description of a given subsystem configuration that includes whether the resource is required, if property replacement is available, etc:

/subsystem=datasources:read-resource-description(recursive=true)

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

Use the following command 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 remove applications, tune system settings, and make persistent modifications to the server configuration. The management console can also perform administrative tasks, with live notifications when a user makes any changes that require you to restart or reload the server.

In a managed domain, server instances and server groups in the same domain are 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, you can access the management console through a web browser at http://localhost:9990/console/index.html. You must authenticate with a user role 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.

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). These are example configuration files that you can modify using the management CLI when you start JBoss EAP.

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. These are example configuration files that you can modify using the management CLI when you start JBoss EAP.

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

To restore your JBoss EAP server configuration, you must back up your data in the following locations:

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.

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

You can start a server using a snapshot or an automatically-saved version of the configuration.

You can use expressions in JBoss EAP to define replaceable properties in place of literal values in the configuration.

Using property replacement in standalone*.xml or domain.xml configuration files will replace the property with the value found in a system property. System properties are defined in the EAP profile xml file or by typing -D command from the command line terminal.

To determine if property replacement is allowed in a given subsystem, use the following command to display a description of a subsystem configuration:

/subsystem=datasources:read-resource-description(recursive=true)

If the expressions-allowed attribute is set to true, property replacement is allowed.

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 and environment variables. When resolving expressions using environment variables, use the format ${env.LANG}.

The following example 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>

You can use the following command to set the jboss.bind.address parameter when starting EAP as a standalone server:

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

You can nest expressions, 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}}

JBoss EAP evaluates nested expressions recursively, so the inner expression is first evaluated, then the outer expression is evaluated. Expressions can 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.

You might use a nested expression if a datasource definition password is masked, for example. The configuration for the datasource might have the following line:

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

A system property (datasource_name) replaces the value of ds_ExampleDS using a nested expression. The following line is an example configuration for the datasource:

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

Deployment descriptor-based property replacement substitutes properties based on descriptors, so that you can 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.

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.

The spec-descriptor-property-replacement flag controls Jakarta EE descriptor replacement, and JBoss EAP disables it by default. When it’s enabled, you can replace properties in the following deployment descriptors:

You can use the following management CLI command to enable or disable property replacement in Jakarta EE descriptors:

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

The jboss-descriptor-property-replacement flag controls JBoss-specific descriptor replacement, and JBoss EAP enables it by default. When it’s enabled, you can replace properties in the following deployment descriptors:

Use the following management CLI command to enable or disable property replacement in JBoss EAP-specific descriptors:

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

The annotation-property-replacement flag controls property replacement inside of annotations, and it is not enabled by default. When it’s enabled, you can replace properties in the annotation attributes inside of application classes.

Use the following management CLI command to enable or disable property replacement in annotations:

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

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

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

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

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

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

/interface=external:add(nic=eth0)

<interface name="external">
   <nic name="eth0"/>
</interface>

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

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

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

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

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

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

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

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

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

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

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

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

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

<socket-binding-group name="standard-sockets" default-interface="public" port-offset ="${jboss.socket.binding.port-offset:0}">

By default, JBoss EAP is configured to run using IPv4 addresses. The following procedures describe how to configure JBoss EAP to run using IPv6 addresses.

#
# Specify options to pass to the Java VM.
#
if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS="-Xms1303m -Xmx1303m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true"
   JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"
   JAVA_OPTS="$JAVA_OPTS -Djboss.modules.policy-permissions=true"
else
   echo "JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS"
fi

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

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