Chapter 8. Domain Management

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 Configure the Domain Controller 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 Configure Host Controllers 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:

Configure a Host to Act as the Domain Controller

A host is designated to be the domain controller if it includes the <local/> element in the <domain-controller> declaration.

<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. It is not required to expose an HTTP(S) management interface, but is recommended as it allows access to the management console.

<management-interfaces>
  <native-interface security-realm="ManagementRealm">
    <socket interface="management" port="${jboss.management.native.port:9999}"/>
  </native-interface>
  <http-interface security-realm="ManagementRealm" http-upgrade-enabled="true">
    <socket interface="management" port="${jboss.management.http.port:9990}"/>
  </http-interface>
</management-interfaces>

The EAP_HOME/domain/configuration/host-master.xml file is already preconfigured with these settings to act as the domain controller.

Connect to the Domain Controller

A host controller must be provided with the means to connect to the domain controller so that it can register itself with the domain. This is configured in the <domain-controller> element of the configuration.

<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:9999}"/>
    </discovery-options>
  </remote>
</domain-controller>

The EAP_HOME/domain/configuration/host-slave.xml file is already preconfigured with these settings to connect to the domain controller. You will need to 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.

<host xmlns="urn:jboss:domain:5.0" name="host1">

$ 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

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:9999}"/>
      <static-discovery name="backup" protocol="${jboss.domain.master.protocol:remote}" host="172.16.81.101" port="${jboss.domain.master.port:9999}"/>
    </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.1 domain controller can manage hosts and servers running JBoss EAP 7.0.

Complete the following tasks to successfully manage JBoss EAP 7.0 instances in a JBoss EAP 7.1 managed domain.

Once these tasks are complete, you can manage your JBoss EAP 7.0 servers and configurations from the JBoss EAP 7.1 domain controller using the management CLI. Note that JBoss EAP 7.0 hosts will not be able to take advantage of new JBoss EAP 7.1 features, such as the elytron subsystem.

<servers>
    <server name="server-one" group="eap70-main-server-group"/>
    <server name="server-two" group="eap70-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:9999}"/>
        </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)