Chapter 7. Configuring JBoss EAP managed domains

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 and switches section.

The domain controller must be started before any secondary servers in any server groups in the domain. Start the domain controller first, then start any other associated host controllers in the domain.

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.

The sample minimal domain controller configuration file, EAP_HOME/domain/configuration/host-primary.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.

The sample minimal host controller configuration file, EAP_HOME/domain/configuration/host-secondary.xml, includes the configuration settings to connect to a domain controller. The configuration assumes that you provide the jboss.domain.primary.address property when starting the host controller.

$ EAP_HOME/bin/domain.sh --host-config=host-secondary.xml -Djboss.domain.primary.address=<ip_address>

Depending on your domain setup, you may also need to provide authentication for the host controller to be authenticated by the domain controller. See Setting 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:default:20.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-secondary.xml  -Djboss.host.name=<host_name>

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

<domain-controller>
  <remote>
    <discovery-options>
      <static-discovery name="primary" protocol="${jboss.domain.primary.protocol:remote}" host="172.16.81.100" port="${jboss.domain.primary.port:9990}"/>
      <static-discovery name="backup" protocol="${jboss.domain.primary.protocol:remote}" host="172.16.81.101" port="${jboss.domain.primary.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-secondary.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.

To allow the domain controller to manage your JBoss EAP 7.4 servers, you must provide the JBoss EAP 7.4 configuration details in the JBoss EAP 8.0 domain configuration. You can do this by copying the JBoss EAP 7.4 profiles, socket binding groups, and server groups to the JBoss EAP 8.0 domain.xml configuration file.

You will need to rename resources if there is any conflict between the existing names in the JBoss EAP 7.4 configuration. There are also some additional adjustments to make to ensure the proper behavior.

The following procedure uses the JBoss EAP 7.4 default profile, standard-sockets socket binding group, and main-server-group server group.

Additional updates to the profiles used by your JBoss EAP 7.4 instances are necessary depending on the JBoss EAP version and desired behavior. You may require additional changes depending on the subsystems and configuration that your existing JBoss EAP 7.4 instances use. The following procedure assumes that the JBoss EAP 7.4 profile is eap74-default.

If you renamed the server groups, you need to update the JBoss EAP 7.4 host configuration to use the new server groups specified in the JBoss EAP 8.0 configuration. This example uses the eap74-main-server-group server group specified in the JBoss EAP 8.0 domain.xml configuration file.

The domain controller in a managed domain forwards configuration updates to its host controllers. You must use the host-exclude configuration to specify the resources that should be hidden from particular versions. Choose the appropriate preconfigured host-exclude option for your JBoss EAP 7.4 version: EAP74.

The active-server-groups attribute of the host-exclude configuration specifies the list of server groups that are used by a particular version. These server groups and their associated profiles, socket binding groups, and deployment resources will be available to hosts of this version, but all others will be hidden from these hosts.

This example assumes that the version is JBoss EAP 7.4 and adds the JBoss EAP 7.4 server group eap74-main-server-group as an active server group.

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

If necessary, you can specify additional socket binding groups used by your servers using the active-socket-binding-groups attribute. This is only required for socket binding groups that are not associated with the server groups specified in active-server-groups.

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:

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.

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