<commit_before>[[Domain_Setup]]
= 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. This sections
focuses on the network configuration for the domain and host controller
components. For background information users are encouraged to review
the <<Operating_modes,Operating modes>> and
link:Management_Clients.html#src-557081_ManagementClients-ConfigurationFiles[Configuration
Files] sections.

[[domain-controller-configuration]]
== 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 Addresses

[IMPORTANT]

In this example the domain controller uses 192.168.0.101 and the host
controller 192.168.0.10

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:

[source,xml,options="nowrap"]
----
<domain-controller>
   <local/>
</domain-controller>
----

~(See domain/configuration/host.xml)~

A host acting as the Domain Controller _must_ expose a management
interface on an address accessible to the other hosts in the domain.
Exposing an HTTP(S) management interface is not required, but is
recommended as it allows the Administration Console to work:

[source,xml,options="nowrap"]
----
<management-interfaces>
    <native-interface sasl-authentication-factory="management-sasl-authentication">
        <socket interface="management" port="9999"/>
    </native-interface>
    <http-interface http-authentication-factory="management-http-authentication">
        <http-upgrade enabled="true" sasl-authentication-factory="management-sasl-authentication"/>
        <socket interface="management" port="${jboss.management.http.port:9990}"/>
    </http-interface>
</management-interfaces>
----

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.

[source,xml,options="nowrap"]
----
<interfaces>
   <interface name="management">
       <inet-address value="192.168.0.101"/>
   </interface>
</interfaces>
----

~(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 Domain Controller is configured to require
authentication so a user needs to be added that can be used by the secondary
Host 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 "secondary".

[NOTE]

`add-user` MUST be run on the Domain Controller and NOT the
secondary Host Controller.

[[host-controller-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 "secondary":

[source,xml,options="nowrap"]
----
<host xmlns="urn:jboss:domain:3.0"
     name="secondary">
[...]
</host>
----

~(See domain/configuration/host.xml)~

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

An `authentication-context` needs to be defined in the `elytron` subsystem
to contain the identity of the host controller.

[source,xml,options="nowrap"]
----
<subsystem xmlns="urn:wildfly:elytron:15.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
    <authentication-client>
        <authentication-configuration sasl-mechanism-selector="DIGEST-MD5"
                                      name="hostAuthConfig"
                                      authentication-name="secondary"
                                      realm="ManagementRealm">
            <credential-reference clear-text="host_us3r_password"/>
        </authentication-configuration>
        <authentication-context name="hcAuthContext">
            <match-rule authentication-configuration="hostAuthConfig"/>
        </authentication-context>
    </authentication-client>
....
----

Tell it how to find the Domain Controller, so it can register itself with
the domain:

[source,xml,options="nowrap"]
----
<domain-controller>
   <remote protocol="remote" host="192.168.0.101" port="9999" authentication-context="hcAuthContext"/>
</domain-controller>
----

Since we have also exposed the HTTP management interface we could also
use:

[source,xml,options="nowrap"]
----
<domain-controller>
   <remote protocol="http-remoting" host="192.168.0.101" port="9990" username="slave" authentication-context="hcAuthContext"/>
</domain-controller>
----

~(See domain/configuration/host.xml)~

[TIP]

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.

=== Ignoring domain wide resources

WildFly 10 and later make it easy for secondary Host Controllers to "ignore"
parts of the domain wide configuration. What does the mean and why is it
useful?

One of the responsibilities of the Domain Controller is ensuring that
all running Host Controllers have a consistent local copy of the domain
wide configuration (i.e. those resources whose address does not begin
with `/host=*`, i.e. those that are persisted in `domain.xml`. Having
that local copy allows a user to do the following things:
<commit_msg>[WFLY-16146] Replacements on Domain Setup documentation<commit_after>[[Domain_Setup]]
= 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. This sections
focuses on the network configuration for the domain and host controller
components. For background information users are encouraged to review
the <<Operating_modes,Operating modes>> and
link:Management_Clients.html#src-557081_ManagementClients-ConfigurationFiles[Configuration
Files] sections.

[[domain-controller-configuration]]
== 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 Addresses

[IMPORTANT]

In this example the domain controller uses 192.168.0.101 and the host
controller 192.168.0.10

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:

[source,xml,options="nowrap"]
----
<domain-controller>
   <local/>
</domain-controller>
----

~(See domain/configuration/host.xml)~

A host acting as the Domain Controller _must_ expose a management
interface on an address accessible to the other hosts in the domain.
Exposing an HTTP(S) management interface is not required, but is
recommended as it allows the Administration Console to work:

[source,xml,options="nowrap"]
----
<management-interfaces>
    <native-interface sasl-authentication-factory="management-sasl-authentication">
        <socket interface="management" port="9999"/>
    </native-interface>
    <http-interface http-authentication-factory="management-http-authentication">
        <http-upgrade enabled="true" sasl-authentication-factory="management-sasl-authentication"/>
        <socket interface="management" port="${jboss.management.http.port:9990}"/>
    </http-interface>
</management-interfaces>
----

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.

[source,xml,options="nowrap"]
----
<interfaces>
   <interface name="management">
       <inet-address value="192.168.0.101"/>
   </interface>
</interfaces>
----

~(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 Domain Controller is configured to require
authentication so a user needs to be added that can be used by the secondary
Host 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 "secondary".

[NOTE]

`add-user` MUST be run on the Domain Controller and NOT the
secondary Host Controller.

[[host-controller-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 "secondary":

[source,xml,options="nowrap"]
----
<host xmlns="urn:jboss:domain:3.0"
     name="secondary">
[...]
</host>
----

~(See domain/configuration/host.xml)~

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

An `authentication-context` needs to be defined in the `elytron` subsystem
to contain the identity of the host controller.

[source,xml,options="nowrap"]
----
<subsystem xmlns="urn:wildfly:elytron:15.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
    <authentication-client>
        <authentication-configuration sasl-mechanism-selector="DIGEST-MD5"
                                      name="hostAuthConfig"
                                      authentication-name="secondary"
                                      realm="ManagementRealm">
            <credential-reference clear-text="host_us3r_password"/>
        </authentication-configuration>
        <authentication-context name="hcAuthContext">
            <match-rule authentication-configuration="hostAuthConfig"/>
        </authentication-context>
    </authentication-client>
....
----

Tell it how to find the Domain Controller, so it can register itself with
the domain:

[source,xml,options="nowrap"]
----
<domain-controller>
   <remote protocol="remote" host="192.168.0.101" port="9999" authentication-context="hcAuthContext"/>
</domain-controller>
----

Since we have also exposed the HTTP management interface we could also
use:

[source,xml,options="nowrap"]
----
<domain-controller>
   <remote protocol="http-remoting" host="192.168.0.101" port="9990" username="secondary" authentication-context="hcAuthContext"/>
</domain-controller>
----

~(See domain/configuration/host.xml)~

[TIP]

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.

=== Ignoring domain wide resources

WildFly 10 and later make it easy for secondary Host Controllers to "ignore"
parts of the domain wide configuration. What does the mean and why is it
useful?

One of the responsibilities of the Domain Controller is ensuring that
all running Host Controllers have a consistent local copy of the domain
wide configuration (i.e. those resources whose address does not begin
with `/host=*`, i.e. those that are persisted in `domain.xml`. Having
that local copy allows a user to do the following things:

{'fraction_non_alphanumeric': 0.0878921645908876, 'fraction_numerical': 0.013006463818382469, 'mean_word_length': 4.2145499383477185, 'pattern_counts': {'":': 2, '<': 77, '<?xml version=': 0, '>': 77, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 32}, 'pii_count': 10, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2555260', 'n_tokens_mistral': 3387, 'n_tokens_neox': 3195, 'n_words': 1397}