JBoss/Wildfly - Domain Mode Master/Slave Set Up & Configuration

JBoss domain mode allows for the centralized management of multiple nodes, which may be physical or virtual machines, each, potentially, running multiple instances of  the JBoss application server, configured to provide different  services.


JBoss domain mode allows for the creation and management of remote and local JBoss instances, the farming of deployments across server groups and centralised configuration of server instances. This post was tested with JBoss 6.4 and Wildfly 7 and 8 versions. It should be pretty much the same for later versions with, perhaps, some minor variations.

JBoss Domain Mode Set up & Configuration

For this exercise assume we have two servers.

Server Management Lan IP User Lan IP
domain master(master)
domain slave (node1)

Default JBoss Domain Configuration Files

JBoss 6.4 and Wildfly 7,8 and 9 come with 4 default configuration files stored under [JBOSS-HOME]/domain/configuration

Configuration File Purpose
domain.xml This file holds the domain configuration such as profiles to apply to server instances, server groups, deployments and management interface access control. It is only used by the domain master.
host.xml This is the default configuration file for the host controller. If no alternative host configuration is specified on the command line this file will be used.
host-slave.xml An example configuration file for a slave host. You can edit this file for the slave host or the host.xml above. If you edit this file you will need to provide it on the command line when running the domain.sh script.
host-master.xml An example configuration file for a master host. You can edit this file for the master host or the host.xml above. If you edit this file you will need to provide it on the command line when running the domain.sh script. The host,xml file is already configured for master mode.


JBoss Training - Domain Set Up & Configuration


The steps required to correctly configure the master and slave hosts are listed below before we delve deeper into each step.

JBoss Domain Master Host

  • Configure the host.xml file for the master host. (Default host.xml is good-to-go),
  • Add a user to the host master user database for use by the slave to authenticate to the master,
  • Start the host master, binding the management interface to a management IP address and bind the remaining services to the user lan accessible address

JBoss Domain Slave Host

  • Configure the host.xml file with the ip address of the master host,
  • Configure the host.xml file with the authentication information for the users added above,
  • Start the slave host with the management interface bound to management IP address and the remaining services to the user lan ip address

JBoss Domain Master Configuration

By default the setting for the domain.xml file, which configures the domain controller process, and the host.xml which configures the host controller process, are good to go for the master host and domain. The parts of the configuration files that are relate to configuring the node as as the domain master are located in the host.xml file and are as follows:

Configure the host.xml file

  • Who is the hosts domain controller? The local host of course <local/>! This can be found by searching the file.

Add User for Slave Host Authentication

  • Next we need to add a user for the slave servers to authenticate to the domain master. If you are using the default file based user and group authentication mechanism this can be done by running "./bin/adduser.sh".
    • You will be prompted for a user name. It is recommended that you use the node name of the salve machine for the user name. This node name is configured in the host.xml file on the slave server,
    • Provide a password when prompted,
    • You will then be asked to make the user a member of any groups. Since you will be only using this user to authenticate the slave leave this empty. Just hit enter.
    • You will be asked to confirm the setting, say "yes"
    • Lastly you will be asked if this account will be used for AS process authentication. Say "yes" here to be provided with the based64 encoded string to use in the slave host.xml file.
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 : node2
Password recommendations are listed below. To modify these restrictions edit the add-user.properties configuration file.
 - The password should not be one of the following restricted values {root, admin, administrator}
 - The password should contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s)
 - The password should be different from the username
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 'node2' for realm 'ManagementRealm'
Is this correct yes/no? yes
Added user 'node2' to file '/home/mark/bin/jboss-eap-6.4/standalone/configuration/mgmt-users.properties'
Added user 'node2' to file '/home/mark/bin/jboss-eap-6.4/domain/configuration/mgmt-users.properties'
Added user 'node2' with groups  to file '/home/mark/bin/jboss-eap-6.4/standalone/configuration/mgmt-groups.properties'
Added user 'node2' with groups  to file '/home/mark/bin/jboss-eap-6.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 EJB calls.
yes/no? yes
To represent the user add the following to the server-identities definition 
<secret value="SkJvc3MgVHJhaW5pbmchIHd3dy5qdW1waW5nYmVhbi5jby56YQo=">

The "secret" is the based64 encoded password that you provied and will be copied to the host.xml file of the slave. The password can be stored in the JBoss vault if required to provide better security for the password. It should be noted the hosts will use PLAIN or DIGEST authentication when communicating with the master. The choice of PLAIN or DIGEST is  based on whether the server has access to the prehashed password or the plain string to perform the hashing. If not then plain authentication will be used. If you have set up your management realm not to use the properties files and use ldap or some other mechanism you will need to create the based64 encoded password yourself.

Domain Slave Configuration

All that needs to be configured on the slave is done in the host.xml file.

Configure host.xml with master host ip address

  • Edit the host.xml file changing the <domain-controller> element as follows: (note the environment variables can be replaced with the management lan ip address of the master or we can provided it on the command line. Below we leave the default configuration which expects the values on the command line.
       <remote host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}" security-realm="ManagementRealm"/>

Alternatively, if you want to use a username that is not the same as the node/host name you can use the following:

        <remote host="YourMasterHostName" port="9999" security-realm="ManagementRealm" username="hostOne"/>

Configure host.xml for the user and secret created on the domain host

  • As mentioned in the domain host configuration the username of the slave is taken from the name="node1" attribute in the <host> document root tag in the host.xml file. So edit the hostname to be the name you provided during user creation. You can use a different username than the name attribute if you so choose but will need to add it to the authentication information below. The first is we need to add the authentication information to the host.xml file on the slaved. The <server-identities> tage is added to the <mangement> entity of the host.xml file.
            <security-realm name="ManagementRealm">
                      <secret value="SkJvc3MgVHJhaW5pbmchIHd3dy5qdW1waW5nYmVhbi5jby56YQo="/>


Start the Servers

Finally start the domain and master servers specifying the management and user lan ip addresses.

Domain Master: ./bin/domain.sh -b -bmanagement

Domain Slave: ./bin/domain.sh -b -bmanagement --management-address


Mark Clarke's picture

The secret used in the above configuration files is  base64 encoded string. There is no separate file in which it is stored. Maybe you are asking about the JBoss vault? The name of the file is determined when you set up the vault. You can find its location by reading the standalone.xml or host.xml config files if I remember correctly.

Hi I'm trying to run Keycloak in domain-clustered mode in my local lan using Two nodes (Linux and by simply putting host-master and host-slave XMLs but failover is not happening. although in logs while boot of servers i can see slave joined the master but when shuttig down the master control doesn't goes to slave. Please help. Keycloak is IDM tool core based on WildFly/Jboss