Red Hat JBoss Enterprise Application Platform Administration I

The settings and configuration of a managed domain are split into two files:

This chapter and the next focus primarily on the host.xml configuration file. The domain.xml configuration file is covered in later chapters.

A host controller instance is named after its machine host name, but this can be overridden by using the name attribute in the <host> top-level element, at the beginning of the host.xml configuration file. For example:

<?xml version="1.0" ?>
<host xmlns="urn:jboss:domain:16.0" name="myprimarycontroller">
...

To denote that a host controller is a domain controller, that is, the primary host controller, add the following configuration to the host.xml configuration file between the <management> and <interfaces> elements:

<?xml version="1.0" ?>
<host xmlns="urn:jboss:domain:16.0" name="myprimarycontroller">
    ...
    </management>

    <domain-controller> 
        <local/> 
    </domain-controller>

    <interfaces>
    ...
    </host>

The HTTP management interface references the management network interface, and it is declared in the host.xml configuration file. For example:

...
    </domain-controller>

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

    <jvm>
...

Notice that host.xml also defines the public network interface. This interface is used by regular user access to applications. Domain controllers are NOT required to define this interface, unless they have server instances of their own.

The management interface also references the ManagementRealm security realm. Security in managed domains are presented later in this book.

When a host controller is not the primary controller, the host.xml file must define the options to discover the primary controller. For example:

...
<domain-controller>
    <remote security-realm="ManagementRealm"> 
        <discovery-options> 
            <static-discovery name="primary" 
                protocol="${jboss.domain.master.protocol:remote+http}"
                host="${jboss.domain.master.address}"
                port="${jboss.domain.master.port:9990}"/>
        </discovery-options>
    </remote>
</domain-controller>
...

In this course only the <static-discovery> mechanism is used. For information about other mechanisms, consult the JBoss EAP product documentation.

In the configuration above, you must define the jboss.domain.master.address system property when starting the host controller. This is demonstrated later in this section.

An alternative is to modify the host.xml configuration file to assign it to the machine name or IP address that the domain controller is running on. For example:

<domain-controller>
    <remote security-realm="ManagementRealm">
        <discovery-options>
            <static-discovery name="primary"
                protocol="${jboss.domain.master.protocol:remote+http}"
                host="${jboss.domain.master.address:172.25.14.9}"  
                port="${jboss.domain.master.port:9990}"/>
        </discovery-options>
    </remote>
</domain-controller>

The previous example illustrates a common practice with JBoss EAP configuration files: to provide attribute values as default values for system properties. The system property allows overriding the attribute by defining the value on the command line.

The following figure shows an example of a managed domain consisting of three hosts, and shows the critical parts of each host.xml host controller configuration file:

Figure 4.3: Sample managed domain

In the previous figure, the server1 machine runs the domain, or primary, controller. The IP address assigned to all domain controller network interfaces is 192.168.0.14 and the management interface is using the 9990 default port. The server2 and server3 machines run secondary host controllers configured to connect to the domain controller running in the server1 machine.

To start a JBoss EAP host controller, use the domain script specific to your platform. The script is found in the /bin directory of your JBoss EAP installation. On Linux and UNIX, the command is:

[user@host ~]$ $JBOSS_HOME/bin/domain.sh

When starting JBoss EAP in managed domain mode, JBoss EAP needs to determine if the instance being started is the domain controller or not. Here is the sequence of events that occurs when the domain start-up script runs:

JBoss EAP management interfaces are secure by default because they only allow accesses from the local machine. To allow remote access to a JBoss EAP domain controller for administrative actions, and also for secondary host controllers to join the domain, the management interface has to be assigned to a different IP address.

Following the example from the previous figure, a domain controller cat start to listen for secondary connections on a private IP address by defining the jboss.bind.address.management system property. For example:

$ ./domain.sh -Djboss.bind.address.management=192.168.0.14

The previous example shows a domain controller whose management network interface is assigned to the 192.168.0.14 IP address.

Continuing with the same example, a slave host controller is started to connect to the master in that address, by defining the jboss.domain.master.address system property, and also to listen for management commands in another private IP address, by defining the jboss.bind.address.management system property.

The following example is used to start the host controller in the server2 machine:

$ ./domain.sh -Djboss.bind.address.management=192.168.0.15 \
-Djboss.domain.master.address=192.168.0.14

In the previous example a secondary host controller starts and tries to connect to a domain controller running on 192.168.0.14 on the 9990 default port. Note that the primary IP address was specified in the command line using a system property. The primary controller management interface TCP port is the default value provided by the host.xml configuration file.

The previous example also shows that the secondary controller accepts management requests from the primary controller on the 192.168.0.15 IP address, specified on the command line. The secondary management interface TCP port is also the default value provided by the host.xml configuration file.

You can use the following complete example to start the host controller in the server3 machine:

$ ./domain.sh -Djboss.bind.address.management=192.168.0.16 \
-Djboss.domain.master.address=192.168.0.14

Most JBoss EAP installations need custom configuration files and want to keep the default configuration files unchanged for future reference. This can be done using a few startup host script command-line options:

For example:

$ ./domain.sh --domain-config=mydomain.xml --host-config=myhost.xml

The files specified by --host-config and --domain-config are supposed to exist in the default location which is the JBOSS_HOME/domain/configuration directory. You can change this path by assigning a new value to the jboss.domain.config.dir system property.

Creating a custom configuration directory for a JBoss EAP host controller normally requires creating custom directories for subsystem data files, logs and other working files. You can use the jboss.domain.base.dir system property to provide an alternative location for the JBOSS_HOME/domain/ directory. The JBOSS_HOME/domain/ directory must contain the configuration, data, and log directories as children.

For example, to start a JBoss EAP host controller using domain configuration files from /usr/local/eap/configuration, use the following command:

$ ./domain.sh -Djboss.domain.base.dir=/usr/local/eap/configuration

You can combine the use of system properties and file name options in a single command:

$ ./domain.sh -Djboss.domain.base.dir=/usr/local/eap/configuration \
--domain-config=mydomain.xml --host-config=myhost.xml

Red Hat recommends to copy the /domain directory from the default installation of JBoss EAP before starting JBoss EAP in a managed domain. This approach separates a specific host controller instance configurations, deployments, log files and temporary directories from the default installation path. This practice provides the following key benefits:

The default host.xml file configures the host controller as a primary controller. It also configures sample server groups and server instances to perform quick tests.

To start additional secondary host controllers in the domain, the default host.xml configuration file has to be changed to replace the <local/> element with a <remote> element as shown before.

For convenience, the JBoss EAP installation also includes two additional sample host controller configuration files:

A JBoss EAP managed domain is a dynamic entity, created by the existence of one or more host controllers running the same domain configuration. Usually, the primary host controller, the domain controller, is started first, and then secondary host controllers are started. Additional host controllers can join the managed domain at any time.

If the domain controller is not available for any reason, host controllers cannot join the managed domain, but existing ones continue to run. Running applications are not affected by domain controller failures; only the administration tasks are affected.

Every host controller can contain a list of host controllers that can act as domain controller. For example:

 <domain-controller>
  <remote security-realm="ManagementRealm">
    <discovery-options>
        <static-discovery name="primary"
         protocol="${jboss.domain.master.protocol:remote+http}"
         host="198.162.0.14"
        />
        <static-discovery name="backup1"
         protocol="${jboss.domain.master.protocol:remote+http}"
         host="198.162.0.15"
        />
         <static-discovery name="backup2"
         protocol="${jboss.domain.master.protocol:remote+http}"
         host="198.162.0.16"
        />
    </discovery-options>
  </remote>
</domain-controller>

A host controller can keep a cache of the managed domain configuration file so that the host can start if the primary controller is unavailable. You can start the secondary controller by using the --backup option. This option creates a local copy of the domain configuration file. For example:

$ ./domain.sh --backup -Djboss.domain.master.address=192.168.0.14

If the secondary controller is unable to contact the primary domain controller to get its configuration when it boots, then --cached-dc option informs the secondary controller to use the configuration local copy that was previously created by using the --backup option. For example:

$ ./domain.sh --cached-dc -Djboss.domain.master.address=192.168.0.14

The --backup and --cached-dc can NOT be used at the same time, so its use as a fail-over mechanism requires manual intervention from the system administrator. Also notice that the --cached-dc option does not make the secondary host controller act as the domain controller: the cached configuration is considered read-only. When a primary controller becomes unavailable you must promote a secondary controller to act as primary controller.

Refer to the references section in this lecture for more information about how to promote a secondary controller.

The JBoss EAP management console is different compared to when running from a standalone server instance. Additional tabs and navigation steps are required to configure the extra elements provided by the managed domain: named profiles, hosts, server groups, and server instances.

The basic navigation is the same, and specific subsystem configuration is also the same. The most visible changes are:

The following figure shows the Topology view in the Runtime tab as it appears after starting the JBoss EAP as managed domain using the default configuration files:

Figure 4.4: Runtime tab from the JBoss EAP management console in managed domain mode

Similar changes also happen in the management CLI as there are objects representing the additional managed domain configuration elements.