I already talked about the domain creation in a previous blog, it is nice to start with but of course not enough if you want to understand the domain architecture, its components, and how they are related to each other.

To understand JBoss EAP domain architecture we need to understand all components of the below domain example:

In the previous figure, the light gray boxes represent machines, they could be either physical or virtual machines. Now, let’s try to explain each component:

Host controller

It is a process running on each machine involved in the domain, this process relays configuration information, runtime status, and management commands to EAP server instances on that particular machine, it is the entry point on the machine. The host controller interacts with the domain controller (explained below) to ensure each server instance is configured according to the policies of the domain. On the other hand, a host controller doesn’t perform application servers tasks, this is done exclusively by server instances.

The configuration file for a host controller is host.xml, and can be found under $DOMAIN_HOME/configuration. There are important settings in this file, for example, server configurations.

By default, a host controller instance is named as 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:

<host name="slave1" xmlns="urn:jboss:domain:4.1">

This name will be displayed in the Management Console and CLI.
Be careful, when a host is stopped it doesn’t appear anymore in the Management Console and CLI!

Domain controller

In a managed domain, one of the host controller instances is configured to act as the central management point, so it act as the domain controller. In the previous figure the host managed by the domain controller does not have any server instances. This is a recommended approach, but it is possible because a domain controller is also a host controller so it could directly manage its own server instances.

To denote that a host controller is a domain controller (master host) add the following to its host.xml configuration file between the managenemt and interfaces elements as shown below:

<host name="master" xmlns="urn:jboss:domain:4.1">

In fact, the domain-controller element informs a host controller where to find the domain controller. If a host controller is supposed to be the master for its managed domain, use the local element, if not:

	<remote security-realm="ManagementRealm">
			<static-discovery name="primary"

The master address and port can be set in the host.xml configuration file or passed as parameter to start the slave host and override these values. Please note that at the same location of host.xml two other preconfigured files host-master.xml and host-slave.xml can be found.

The white field next to the host controllers, means that any host controller could be configured as a replacement domain controller in case the original one is unavailable, this can’t be automated and require manual operation and will be detailed and tested in a separated blog. If a domain controller fails, the host controllers simply keep trying to reconnect until the domain controller comes back again. Note that the server instances are NOT affected if a domain controller fails.

Server Group

A server group is a collection of servers that are managed and configured as one. It provide a logical grouping that impacts configuration settings, for example:

  • A profile is assigned to a server group, all server instances in this server group will have the same profile.
  • Applications are deployed and activated only to server groups, applications will be deployed to all server instances in this group.

Server groups are defined in the domain.xml configuration file of the domain controller! A server group require at least a profile and a socket binding group to be created. Then, servers are assigned to the server group inherits its configuration from the server group. For example, if a server group has the default profile, the servers assigned to this server group can’t be clustered because this need the ha or full-ha profiles. On the other hand, you can override some server group configuration for a specific server, for example, jvm parameters.


A server instance runs inside a dedicated Java Virtual Machine (JVM) and runs only application code not management services, I mean comparing to a standalone instance which runs the Management Console and the Management API under the same JVM that runs applications.

In a managed domain, a server instance should be created on one and only one host, and assigned to one and only one server group.

Process controller (not shown in the above schema)

A process running on a host machine that starts host controllers and server instances on that particular machine. In fact, on any one of the machines starting a host controller (with or without domain controller) you should have two processes:
Process Controller

jboss    10281 10200  2 21:47 pts/0    00:00:00 java -D[Process Controller] -server -Xms64m -Xmx512m -XX:MaxMetaspaceSize=256m 
-Djava.net.preferIPv4Stack=true -Djboss.modules.system.pkgs=org.jboss.byteman -Djava.awt.headless=true 
-Dorg.jboss.boot.log.file=/opt/install/master/log/process-controller.log -Dlogging.configuration=file:/opt/install/master/configuration/logging.properties 
-jar /opt/install/eap-7.0.0/jboss-modules.jar -mp /opt/install/eap-7.0.0/modules org.jboss.as.process-controller ..

Host Controller

jboss    10294 10281 18 21:47 pts/0    00:00:04 java -D[Host Controller] -Dorg.jboss.boot.log.file=/opt/install/master/log/host-controller.log 
-Dlogging.configuration=file:/opt/install/master/configuration/logging.properties -server -Xms64m -Xmx512m -XX:MaxMetaspaceSize=256m 
-Djava.net.preferIPv4Stack=true -Djboss.modules.system.pkgs=org.jboss.byteman -Djava.awt.headless=true -jar /opt/install/eap-7.0.0/jboss-modules.jar 
-mp /opt/install/eap-7.0.0/modules org.jboss.as.host-controller ...

CLI and Management Console

The Command Line Interface (CLI) and Management Console are a management tools for a managed domain or standalone server. These tools allow users to connect to the domain controller or a standalone server and execute management operations. I am not going to speak a lot about the management tools, the most important point here is to understand that these tools deal only with the domain controller as shown in the above figure.

Hope that this blog helped you to improve your knowledge on domain architecture in JBoss EAP, in next blogs I will talk more in depth about the domain mode with use cases. Meanwhile, don’t hesitate to ask if you have any question! 😉