JBoss Community Archive (Read Only)

WildFly 8

Domain Setup

To run a group of servers as a managed domain you need to configure both the domain controller and each host that joins the domain. The following steps focus on the  network configuration for the domain and host controller components.

Domain Controller Configuration

The domain controller is the central government for a managed domain. A domain controller configuration requires two steps:

  • A host needs to be configured to act as the Domain Controller for the whole domain

  • The host must expose an addressable management interface binding for the managed hosts to communicate with it

Example IP Adresses

In this example the domain controller uses and the host controller

Configuring a host to act as the Domain Controller is done through the domain-controller declaration in host.xml. If it includes the <local/> element, then this host will become the domain controller:


(See domain/configuration/host.xml)

A host acting as the Domain Controller must expose a native (i.e. non-HTTP) management interface on an address accessible to the other hosts in the domain. Also exposing an HTTP management interface is not required, but is recommended as it allows the Administration Console to work:

  <native-interface security-realm="ManagementRealm">
    <socket interface="management" port="${jboss.management.native.port:9999}"/>
  <http-interface security-realm="ManagementRealm">
    <socket interface="management" port="${jboss.management.http.port:9990}"/>

The interface attributes above refer to a named interface declaration later in the host.xml file. This interface declaration will be used to resolve a corresponding network interface. 

   <interface name="management">
       <inet-address value=""/>

(See domain/configuration/host.xml)

Please consult the chapter "Interface Configuration" for a more detailed explanation on how to configure network interfaces.

Next by default the master domain controller is configured to require authentication so a user needs to be added that can be used by the slave domain controller to connect.

Make use of the add-user utility to add a new user, for this example I am adding a new user called slave.

add-user MUST be run on the master domain controller and NOT the slave.

When you reach the final question of the interactive flow answer y or yes to indicate that the new user will be used for a process e.g.

Is this new user going to be used for one AS process to connect to another AS process e.g. slave domain controller?
yes/no? y
To represent the user add the following to the server-identities definition <secret value="cE3EBEkE=" />

Make a note of the XML Element output as that is going to be required within the slave configuration.

Host Controller Configuration

Once the domain controller is configured correctly you can proceed with any host that should join the domain. The host controller configuration requires three steps:

  • The logical host name (within the domain) needs to be distinct

  • The host controller needs to know the domain controller IP address

Provide a distinct, logical name for the host. In the following example we simply name it "slave":

<host xmlns="urn:jboss:domain:1.0"

(See domain/configuration/host.xml)

If the name attribute is not set, the default name for the host will be the value of the HOSTNAME or COMPUTERNAME environment variable, one of which will be set on most operating systems. If neither is set the name will be the value of InetAddress.getLocalHost().getHostName().

A security realm needs to be defined to hold the identity of the slave, as it is performing a specific purpose I would suggest a new realm is defined although it is possible to combine this with an existing realm.

<security-realm name="SlaveRealm">
    <secret value="cE3EBEkE=" />

The <secret /> element here is the one output from add-user previously. To create the <secret /> element yourself the value needs to be the password encoded using Base64.

Tell it how to find the domain controller so it can register itself with the domain:

   <remote host="" port="9999" username="slave" security-realm="SlaveRealm"/>

(See domain/configuration/host.xml)

The username attribute here is optional, if it is omitted then the name of the host will be used instead, in this example that was already set to name.

The name of each host needs to be unique when registering with the domain controller, however the username does not - using the username attribute allows the same account to be used by multiple hosts if this makes sense in your environment.

The <remote /> element is also associated with the security realm SlaveRealm, this is how it picks up the password from the <secret /> element.

Server groups

The domain controller defines one or more server groups and associates each of these with a profile and a socket binding group, and also :

    <server-group name="main-server-group" profile="default">
        <jvm name="default">
           <heap size="64m" max-size="512m"/>
           <permgen size="128m" max-size="128m"/>
        <socket-binding-group ref="standard-sockets"/>
    <server-group name="other-server-group" profile="bigger">
        <jvm name="default">
            <heap size="64m" max-size="512m"/>
        <socket-binding-group ref="bigger-sockets"/>

(See domain/configuration/domain.xml)

The domain controller also defines the socket binding groups and the profiles. The socket binding groups define the default socket bindings that are used:

    <socket-binding-group name="standard-sockets" default-interface="public">
        <socket-binding name="http" port="8080"/>
    <socket-binding-group name="bigger-sockets" include="standard-sockets" default-interface="public">
        <socket-binding name="unique-to-bigger" port="8123"/>

(See domain/configuration/domain.xml)
In this example the bigger-sockets group includes all the socket bindings defined in the standard-sockets groups and then defines an extra socket binding of its own.

A profile is a collection of subsystems, and these subsystems are what implement the functionality people expect of an application server.

    <profile name="default">
        <subsystem xmlns="urn:jboss:domain:web:1.0">
            <connector name="http" scheme="http" protocol="HTTP/1.1" socket-binding="http"/>
        <\!-\- The rest of the subsystems here \-->
    <profile name="bigger">
        <subsystem xmlns="urn:jboss:domain:web:1.0">
            <connector name="http" scheme="http" protocol="HTTP/1.1" socket-binding="http"/>
        <\!-\- The same subsystems as defined by 'default' here \-->
        <subsystem xmlns="urn:jboss:domain:fictional-example:1.0">
            <socket-to-use name="unique-to-bigger"/>

(See domain/configuration/domain.xml)
Here we have two profiles. The bigger profile contains all the same subsystems as the default profile (athough the parameters for the various subsystems could be different in each profile), and adds the fictional-example subsystem which references the unique-to-bigger socket binding.


The host controller defines one or more servers:

    <server name="server-one" group="main-server-group">
        <\!-\- server-one inherits the default socket-group declared in the server-group \-->
        <jvm name="default"/>

    <server name="server-two" group="main-server-group" auto-start="true">
        <socket-binding-group ref="standard-sockets" port-offset="150"/>
        <jvm name="default">
            <heap size="64m" max-size="256m"/>

    <server name="server-three" group="other-server-group" auto-start="false">
        <socket-binding-group ref="bigger-sockets" port-offset="250"/>

(See domain/configuration/host.xml)

server-one and server-two both are associated with main-server-group so that means they both run the subsystems defined by the default profile, and have the socket bindings defined by the standard-sockets socket binding group. Since all the servers defined by a host will be run on the same physical host we would get port conflicts unless we used <socket-binding-group ref="standard-sockets" port-offset="150"/> for server-two. This means that server-two will use the socket bindings defined by standard-sockets but it will add 150 to each port number defined, so the value used for http will be 8230 for server-two.

server-three will not be started due to its auto-start="false". The default value if no auto-start is given is true so both server-one and server-two will be started when the host controller is started. server-three belongs to other-server-group, so if its auto-start were changed to true it would start up using the subsystems from the bigger profile, and it would use the bigger-sockets socket binding group.


The host controller contains the main jvm definitions with arguments:

    <jvm name="default">
        <heap size="64m" max-size="128m"/>

(See domain/configuration/host.xml)
From the preceeding examples we can see that we also had a jvm reference at server group level in the domain controller. The jvm's name must match one of the definitions in the host controller. The values supplied at domain controller and host controller level are combined, with the host controller taking precedence if the same parameter is given in both places.

Finally, as seen, we can also override the jvm at server level. Again, the jvm's name must match one of the definitions in the host controller. The values are combined with the ones coming in from domain controller and host controller level, this time the server definition takes precedence if the same parameter is given in all places.

Following these rules the jvm parameters to start each server would be


JVM parameters


-XX:PermSize=128m -XX:MaxPermSize=128m -Xms64m -Xmx128m


-XX:PermSize=128m -XX:MaxPermSize=128m -Xms64m -Xmx256m


-Xms64m -Xmx128m

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 13:46:30 UTC, last content change 2012-05-18 18:05:41 UTC.