C2B2 logo icon

JBoss EAP 6 Domain Mode

Mike Croft considers the issues surrounding any decision between domain and standalone mode

When Red Hat redesigned JBoss 5, one of the key things they did was to combine all the configuration from separate files within their own modules to a single XML file. When you start JBoss by calling standalone.sh, that single XML file holds all the configuration it uses, which makes it much easier to track down any misconfiguration.

Clustering in standalone mode is very straightforward; simply edit the JGroups subsystem in the appropriate configuration file (standalone-ha or standalone-full-ha) as Andy Overton has outlined in his previous blog. Providing they both have the same configuration, the servers will discover each other and you're done. The downside comes when you have large clusters to manage and need to make the same configuration change in many places!

In domain mode, however, things are a little different.

There are two XML configuration files to think about in domain mode, rather than one. Since domain mode is all about easing the task of management of multiple servers, that's the motivation behind the difference in configuration. The domain.xml file is the one which contains configuration for every server instance in the domain, which may contain many clusters (or server groups), and the host.xml is different for each physical host (which may contain many server instances).

It may help to think about how these are organised by looking at how they are used in JBoss.

What happens when a JBoss server starts in domain mode?

JBoss goes through a few steps to load the right configuration. There are three components at work: the process controller, the host controller and the domain controller.

The process controller is responsible for starting other processes and monitoring them. The host controller is responsible for managing configuration on the physical host and making sure the correct server instances are started by the process controller and the domain controller is responsible for holding the domain configuration.

When JBoss is started in domain mode, by calling either domain.bat or domain.sh, the following steps are performed:

  1. The Process Controller (PC) is started in its own JVM
  2. The PC starts the Host Controller (HC) in a separate JVM
  3. The HC parses the host.xml to see if this host is the Domain Controller (DC)
    • If this host is the DC:
      • The local domain.xml and local host.xml settings are combined to make a single configuration for the machine.
    • If this host is not the DC:
      • The HC tries to connect to the DC and combines the remote domain.xml with the local host.xml to make a single configuration for the machine.
  4. Each server instance defined in the host.xml (if any) is started in its own JVM.

So where do I make my configuration changes?

Depending on the scope of the change, you will make it in one of three places: the domain level, the server group (cluster) level or at the server instance level.

Two of these levels are configured in the domain.xml: the domain level (separated into profiles) and the server group level. Server instances are configured in the host.xml on the physical machine where they will be running.

In standalone mode, several configuration files are provided to give different combinations of features. To make use of HA features, you just need to specify one of the configuration files with HA in the name.

In domain mode, a similar concept is carried over, but taken further with the concept of profiles. The domain.xml file has several profiles (default, ha, full, full-ha) which mirror the standalone config files. Within a profile you can configure subsystems, like data sources or infinispan cache containers.

Server Groups
Server groups are exactly what they sound like; logical groupings of server instances which allow you to apply all the settings in a certain profile to all the server instances within that group as shown in the example below, which applies the settings contained in the profile named "full" to all servers in the group "main-server-group":




Within a server group configuration, JVM settings can be configured (as above). These JVM settings will be applied as a default to all the server instances within "main-server-group".

Server Instances
At the bottom of the host.xml file is where all the servers which will run on the physical machine are configured. Every server listed will run on the machine where that XML file is located, so it would not be unusual for each physical machine to have a different host.xml file, even if the only difference is the logical name of the server (e.g. "server-one").

Also at the end of the host.xml file, just above the tag is another place to further configure the JVM:



In this example, the name of the JVM is "default", the same as referenced in the server group "main-server-group" detailed above. Because there are two named JVM configurations with the same name, the order of precedence decides which values are applied. The JVM configuration in the of the domain.xml is applied first. This is then overridden by the values set in in the host.xml file, so that all server instances on a host can be affected by certain values.

Finally, these settings can be overridden again within any tag, as seen below in "server-one":



So the applicable JVM settings are different for "server-one" and "server-two", even though they are in the same server group and on the same machine. They will both have the permgen settings of 256m from the domain.xml. Both will then have the "-server" JVM option added and the heap size overridden to reduce the max heap size from the tag in the host.xml.

"server-one" then has its heap size overridden to increase the heap size and the max heap size.

Since all three server instances are running on the same machine, each has a port offset which adds the given number to the default ports to avoid conflicts.

Decisions, decisions

There are a lot of things to consider when deciding between domain and standalone mode, but all of the questions are around your own personal needs, not limitations of software. Domain mode and standalone mode are both equally capable, but designed to solve different problems. Hopefully this post has given you the information you need to make that decision more easily.