Red Hat JBoss Enterprise Application Platform Administration I

You configure the host controllers in the JBOSS_HOME/domain/configuration/host.xml file.

A host.xml file has the following general structure, as defined by the XML schema in the JBOSS_HOME/docs/schema/wildfly-config_16_0.xsd file:

<host name="my-controller-name" xmlns="urn:jboss:domain:16.0">
    <extensions>
    ... host controller extensions
    </extensions>
    <system-properties>
    ... for defining system properties
    </system-properties>
    <paths>
    ... for defining filesystem paths
    </paths>
    <vault>
    ... for storing encrypted passwords
    </vault>
    <management>
    ... the management interfaces and their security settings appear here
    </management>
    <domain-controller>
    ... the settings for how to connect to the Domain Controller
    </domain-controller>
    <interfaces>
    ... interfaces are defined here
    </interfaces>
    <jvms>
    ... JVMs are defined here
    </jvms>
    <servers>
    ... servers are defined here
    </servers>
    <profile>
    ... subsystems configurations for host controller extensions
    </profile>
</host>

Most of the elements are optional and might not be seen in the default host controller configuration files. The only mandatory elements are: <management>, <domain-controller> and the <host> top-level element.

The following are very high-level explanations about each element. Their use and syntax are explained in more detail later in this book.

Elements found in standalone.xml for standalone server operating mode usually have the same meaning and syntax in host.xml for managed domain operating mode. Some elements, such as <system-properties>, or <jvms>, can be configured in different places in the host.xml and domain.xml files. The reason behind this apparent repetition is to enable you to override values for these elements at different levels: domain-wide, host, server group, or server instance.

A host configuration usually defines multiple servers, inside the <server> element.

The <server> and <jvm> configurations are the same for primary and secondary host controllers.

The following is a partial sample of a host.xml configuration file:

<host name="myhost" xmlns="urn:jboss:domain:16.0"> 
    ...
    <jvms> 
        <jvm name="default">
            <heap size="64m" max-size="128m"/>
        </jvm>
        <jvm name="myhost-jvm">
            <heap size="512m" max-size="1024m"/>
        </jvm>
    </jvms>
    <servers> 
        <server name="server1" group="group1">  
            <jvm name="default"/> 
        </server>
        <server name="server2" group="group2"> 
            <jvm name="myhost-jvm"/> 
            <socket-bindings port-offset="200"/> 
        </server>
    </servers>
</host>

The previous sample host controller configuration defines two server instances. Thus, the host runs four operating system processes, each one with its own JVM: the process controller, the host controller, and the two server instances.

The essential parts for a secondary host controller configuration were already presented by this book, but a complete walk through of a configuration has not yet been performed. The following walk through highlights the differences between primary and secondary host controller settings.

The host controller instance uses the machine host name by default. You can change the controller name by using the name attribute in the <host> top-level element. For example:

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

To denote that a host controller is secondary, specify where the primary controller can be found:

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

Details about the previous settings were already explained; review the previous section for more information.

A secondary host controller has to declare a management interface the same way a primary controller has to. For example:

...output omitted...
</extensions>

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

Remember that all administrative operations are performed on the domain controller.

The management interface for a secondary host controller references the management network interface, again in the same way as a primary controller does:

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

For a secondary host controller, the public network interface is required, as it is supposed to have server instances.

Only the domain controller should contact a secondary management interface.

You must define two system properties to start a secondary host controller:

Either those variables are defined in the domain.sh script command line or their values are inserted directly in the host.xml secondary controller configuration file.

Assuming the primary controller management interface IP address is 192.168.0.14, and the secondary management interface IP address is 192.168.1.25, the following command starts the host controller as secondary:

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

The previous example assumes the management interface TCP port was left as the 9990 default value for both the primary and the secondary.

You can define multiple primary controllers in the same secondary host controller configuration. For example:

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

The secondary host controller using the previous example configuration tries to connect to each domain controller in the order they appear, and registers to the first one that replies. The names primary and backup have no special meaning.

If the primary domain controller is unavailable, the backup domain controller has to be manually stopped and promoted to be a domain controller. If the host controller started with the --backup option then it should already have a complete, current domain.xml configuration file and can take the domain controller role.

The promotion of a secondary host controller to the domain controller role is a manual process. The sample configuration above just shows a way to NOT require changing each other secondary host controller configuration to point to the new primary.

A host controller connected to a domain controller has access to all configuration used by all profiles. An external host controller can connect to a managed domain and get these configurations from the domain controller if no authentication is required. To avoid this scenario, JBoss EAP requires that a host controller must authenticate to the domain controller to be part of the managed domain. This authentication requires:

[host@user ~]$ $JBOSS_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 : mydomainsecondary1
Password :
Re-enter Password :
What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[  ]:
About to add user 'mydomainsecondary1' for realm 'ManagementRealm'
Is this correct yes/no? yes
Added user 'mydomainsecondary1' to file '/opt/jboss-eap-7.4/standalone/configuration/mgmt-users.properties'
Added user 'mydomainsecondary1' to file '/opt/jboss-eap-7.4/domain/configuration/mgmt-users.properties'
Added user 'mydomainsecondary1' with groups  to file '/opt/jboss-eap-7.4/standalone/configuration/mgmt-groups.properties'
Added user 'mydomainsecondary1' with groups  to file '/opt/jboss-eap-7.4/domain/configuration/mgmt-groups.properties'
Is this new user going to be used for one AS process to connect to another AS process?
e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server Jakarta Enterprise Beans calls.
yes/no? yes
To represent the user add the following to the server-identities definition <secret value="cmVkaGF0MTIz" />

<?xml version='1.0' encoding='UTF-8'?>

<host xmlns="urn:jboss:domain:16.0">
  <extensions>
...output omitted...
  <management>
      <security-realms>
          <security-realm name="ManagementRealm">
              <server-identities>
                  <secret value="cmVkaGF0MTIz"/>
              </server-identities>
...output omitted...

<?xml version='1.0' encoding='UTF-8'?>

<host xmlns="urn:jboss:domain:16.0">
...output omitted...
  <domain-controller>
     <remote security-realm="ManagementRealm" username="mydomainsecondary1">
         <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>
...output omitted...

Note that in the above example, you can also change the name of the secondary controller in the root XML element that defines its name. For example:

<?xml version='1.0' encoding='UTF-8'?>

<host xmlns="urn:jboss:domain:16.0" name="mydomainsecondary1">
...output omitted...