19.5.6. Configure a mod_cluster Worker Node

Summary

A mod_cluster worker node consists of a JBoss EAP 6 server. This server can be part of a server group in a Managed Domain, or a standalone server. A separate process runs within JBoss EAP 6, which manages all of the nodes of the cluster. This is called the master. For more conceptual information about worker nodes, refer to Section 19.1.4, “Worker Node”. For an overview of web server load balancing, refer to Section 19.1.3, “Overview of HTTP Connectors”.

The load-balancing web server is configured via the mod_cluster subsystem. To configure the mod_cluster subsystem, refer to Configure the mod_cluster Subsystem in the Administration and Configuration Guide.
Worker nodes in a managed domain shares an identical configuration across a server group. Worker nodes running as standalone servers are configured individually. The configuration steps are otherwise identical.

Worker Node Configuration

  • A standalone server must be started with the standalone-ha or standalone-full-ha profile.
  • A server group in a managed domain must use the ha or full-ha profile, and the ha-sockets or full-ha-sockets socket binding group. JBoss EAP 6 ships with a cluster-enabled server group called other-server-group which meets these requirements.

Note

Where Management CLI commands are given, they assume you use a managed domain. If you use a standalone server, remove the /profile=full-ha portion of the commands.

Procedure 19.9. Configure a Worker Node

  1. Configure the network interfaces.

    By default, the network interfaces all default to 127.0.0.1. Every physical host that hosts either a standalone server or one or more servers in a server group needs its interfaces to be configured to use its public IP address, which the other servers can see.
    To change the IP address of a JBoss EAP 6 host, you need to shut it down and edit its configuration file directly. This is because the Management API which drives the Management Console and Management CLI relies on a stable management address.
    Follow these steps to change the IP address on each server in your cluster to the master's public IP address.
    1. Start the JBoss EAP server using the profile described earlier in this topic.
    2. Launch the Management CLI, using the EAP_HOME/bin/jboss-cli.sh command in Linux or the EAP_HOME\bin\jboss-cli.bat command in Microsoft Windows Server. Type connect to connect to the domain controller on the localhost, or connect IP_ADDRESS to connect to a domain controller on a remote server.
    3. Modify the external IP address for the management, public and unsecure interfaces by typing the following commands. Be sure to replace EXTERNAL_IP_ADDRESS in the command with the actual external IP address of the host.
      /interface=management:write-attribute(name=inet-address,value="${jboss.bind.address.management:EXTERNAL_IP_ADDRESS}"
      /interface=public:write-attribute(name=inet-address,value="${jboss.bind.address.public:EXTERNAL_IP_ADDRESS}"
      /interface=unsecure:write-attribute(name=inet-address,value="${jboss.bind.address.unsecure:EXTERNAL_IP_ADDRESS}"
      :reload
      You should see the following result for each command.
       "outcome" => "success"
    4. For hosts that participate in a managed domain but are not the master, you must change the host name from master to a unique name. This name must be unique across slaves and will be used for the slave to identify to the cluster, so make a note of the name you use.
      1. Start the JBoss EAP slave host using the following syntax:
        bin/domain.sh --host-config=HOST_SLAVE_XML_FILE_NAME
        For example:
        bin/domain.sh --host-config=host-slave01.xml
      2. Launch the Management CLI.
      3. Use the following syntax to replace the host name:
        /host=master:write-attribute(name="name",value=UNIQUE_HOST_SLAVE_NAME)
        For example:
        /host=master:write-attribute(name="name",value="host-slave01")
        You should see the following result.
         "outcome" => "success"
        This modifies the XML in the host-slave01.xml file as follows:
        <host name="host-slave01" xmlns="urn:jboss:domain:1.6">
    5. For newly configured hosts that need to join a managed domain, you must remove the local element and add the remote element host attribute that points to the domain controller. This step does not apply for a standalone server.
      1. Start the JBoss EAP slave host using the following syntax:
        bin/domain.sh --host-config=HOST_SLAVE_XML_FILE_NAME
        For example:
        bin/domain.sh --host-config=host-slave01.xml
      2. Launch the Management CLI.
      3. Use the following syntax specify the domain controller:
        /host=UNIQUE_HOST_SLAVE_NAME/:write-remote-domain-controller(host=DOMAIN_CONTROLLER_IP_ADDRESS,port=${jboss.domain.master.port:9999},security-realm="ManagementRealm") 
        For example:
        /host=host-slave01/:write-remote-domain-controller(host="192.168.1.200",port=${jboss.domain.master.port:9999},security-realm="ManagementRealm") 
        You should see the following result.
         "outcome" => "success"
        This modifies the XML in the host-slave01.xml file as follows:
        <domain-controller>
            <remote host="192.168.1.200" port="${jboss.domain.master.port:9999}" security-realm="ManagementRealm"/>
        </domain-controller>
  2. Configure authentication for each slave server.

    Each slave server needs a username and password created in the domain controller's or standalone master's ManagementRealm. On the domain controller or standalone master, run the EAP_HOME/bin/add-user.sh command. Add a user with the same username as the slave, to the ManagementRealm. When asked if this user will need to authenticate to an external JBoss AS instance, answer yes. An example of the input and output of the command is below, for a slave called slave1, with password changeme.
    user:bin user$ ./add-user.sh
    
    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.
    Realm (ManagementRealm) : 
    Username : slave1
    Password : changeme
    Re-enter Password : changeme
    About to add user 'slave1' for realm 'ManagementRealm'
    Is this correct yes/no? yes
    Added user 'slave1' to file '/home/user/jboss-eap-6.0/standalone/configuration/mgmt-users.properties'
    Added user 'slave1' to file '/home/user/jboss-eap-6.0/domain/configuration/mgmt-users.properties'
    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? yes
    To represent the user add the following to the server-identities definition <secret value="Y2hhbmdlbWU=" />
    
  3. Copy the Base64-encoded <secret> element from the add-user.sh output.

    If you plan to specify the Base64-encoded password value for authentication, copy the <secret> element value from the last line of the add-user.sh output as you will need it in the step below.
  4. Modify the slave host's security realm to use the new authentication.

    You can specify the secret value in one of the following ways:
    • Specify the Base64-encoded password value in the server configuration file using the Management CLI.

      1. Launch the Management CLI, using the EAP_HOME/bin/jboss-cli.sh command in Linux or the EAP_HOME\bin\jboss-cli.bat command in Microsoft Windows Server. Type connect to connect to the domain controller on the localhost, or connect IP_ADDRESS to connect to a domain controller on a remote server.
      2. Specify the secret value by typing the following command. Be sure to replace the SECRET_VALUE with the secret value returned from the add-user output from the previous step.
        /core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="SECRET_VALUE") 
        :reload
        You should see the following result for each command.
         "outcome" => "success"
    • Configure the host to get the password from the vault.

      1. Use the vault.sh script to generate a masked password. It will generate a string like the following: VAULT::secret::password::ODVmYmJjNGMtZDU2ZC00YmNlLWE4ODMtZjQ1NWNmNDU4ZDc1TElORV9CUkVBS3ZhdWx0.
        You can find more information on the vault in the Password Vaults for Sensitive Strings section of this guide starting here: Section 11.13.1, “Password Vault System”.
      2. Launch the Management CLI, using the EAP_HOME/bin/jboss-cli.sh command in Linux or the EAP_HOME\bin\jboss-cli.bat command in Microsoft Windows Server. Type connect to connect to the domain controller on the localhost, or connect IP_ADDRESS to connect to a domain controller on a remote server.
      3. Specify the secret value by typing the following command. Be sure to replace the SECRET_VALUE with the masked password generated in the previous step.
        /core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="${VAULT::secret::password::SECRET_VALUE}") 
        :reload
        You should see the following result for each command.
         "outcome" => "success"

        Note

        When creating a password in the vault, it must be specified in plain text, not Base64-encoded.
    • Specify the password as a system property.

      The following examples use server.identity.password as the system property name for the password.
      1. Specify the system property for the password in the server configuration file using the Management CLI.
        1. Launch the Management CLI, using the EAP_HOME/bin/jboss-cli.sh command in Linux or the EAP_HOME\bin\jboss-cli.bat command in Microsoft Windows Server. Type connect to connect to the domain controller on the localhost, or connect IP_ADDRESS to connect to a domain controller on a remote server.
        2. Type the following command to configure the secret identity to use the system property.
          /core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="${server.identity.password}") 
          :reload
          You should see the following result for each command.
           "outcome" => "success"
      2. When you specify the password as a system property, you can configure the host in either of the following ways:
        • Start the server entering the password in plain text as a command line argument, for example:
          -Dserver.identity.password=changeme

          Note

          The password must be entered in plain text and will be visible to anyone who issues a ps -ef command.
        • Place the password in a properties file and pass the properties file URL as a command line argument.
          1. Add the key/value pair to a properties file. For example:
            server.identity.password=changeme
          2. Start the server with the command line arguments
            --properties=URL_TO_PROPERTIES_FILE
            .
  5. Restart the server.

    The slave will now authenticate to the master using its host name as the username and the encrypted string as its password.
Result

Your standalone server, or servers within a server group of a managed domain, are now configured as mod_cluster worker nodes. If you deploy a clustered application, its sessions are replicated to all cluster nodes for failover, and it can accept requests from an external Web server or load balancer. Each node of the cluster discovers the other nodes using automatic discovery, by default.To configure automatic discovery, and the other specific settings of the mod_cluster subsystem, see Section 19.5.2, “Configure the mod_cluster Subsystem”. To configure the Apache HTTP Server,see Section 19.3.5, “Use an External Web Server as the Web Front-end for JBoss EAP 6 Applications”.