17.6. Web, HTTP Connectors, and HTTP Clustering

Procedure 17.12. Install the mod_cluster Module

1. Determine your Apache HTTP Server configuration location.

   Your Apache HTTP Server configuration location will be different depending on whether you are using Red Hat Enterprise Linux's Apache HTTP Server, the standalone Apache HTTP Server included as a separate downloadable component with JBoss EAP 6, or the Apache HTTP Server available in JBoss Enterprise Web Server. It is one of the following three options, and is referred to in the rest of this task as HTTPD_HOME.
   • Apache HTTP Server - /etc/httpd/
   • JBoss EAP 6 Apache HTTP Server - This location is chosen by you, based on the requirements of your infrastructure.
   • JBoss Enterprise Web Server Apache HTTP Server - EWS_HOME/httpd/

2. Copy the modules to the Apache HTTP Server modules directory.

   Copy the four modules (the files ending in .so) from the EAP_HOME/modules/system/layers/base/native/lib/httpd/modules directory of the extracted Webserver Natives archive to the HTTPD_MODULES/ directory.

3. For JBoss Enterprise Web Server, disable the mod_proxy_balancer module.

   If you use JBoss Enterprise Web Server, the mod_proxy_balancer module is enabled by default. It is incompatible with mod_cluster. To disable it, edit the HTTPD_CONF/httpd.conf and comment out the following line by placing a # (hash) symbol before the line which loads the module. The line is shown without the comment and then with it, below.

   LoadModule proxy_balancer_module modules/mod_proxy_balancer.so

   # LoadModule proxy_balancer_module modules/mod_proxy_balancer.so

   Save and close the file.

4. Configure the mod_cluster module.

   The Webserver Natives archive contains a sample mod_cluster.conf file (EAP_HOME/modules/system/layers/base/native/etc/httpd/conf). This file can be used as a guide or copied and edited to create a HTTPD_CONF.D/JBoss_HTTP.conf file.

   Note

   Using the name JBoss_HTTP.conf is an arbitrary convention in this document. The configuration file will be loaded, regardless of its name, if it is saved in the conf.d/ directory with the .conf extension.
   Add the following to your configuration file:

   LoadModule slotmem_module modules/mod_slotmem.so
   LoadModule manager_module modules/mod_manager.so
   LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
   LoadModule advertise_module modules/mod_advertise.so
   

   This causes Apache HTTP Server to automatically load the modules that mod_cluster needs in order to function.

5. Create a proxy server listener.

   Continue editing HTTPD_CONF.D/JBoss_HTTP.conf and add the following minimal configuration, replacing the values in capital letters with suitable values for your environment.

   Listen IP_ADDRESS:PORT
   <VirtualHost IP_ADDRESS:PORT>  
   	  <Location />
             Order deny,allow
             Deny from all
             Allow from *.MYDOMAIN.COM
   	  </Location>
   	  
   	  KeepAliveTimeout 60
   	  MaxKeepAliveRequests 0
   	  EnableMCPMReceive
   	  
   	  ManagerBalancerName mycluster
   	  ServerAdvertise On
   	  
   </VirtualHost>

   These directives create a new virtual server which listens on IP_ADDRESS:PORT, allows connections from MYDOMAIN.COM, and advertises itself as a balancer called mycluster. These directives are covered in detail in the documentation for Apache Web Server. To learn more about the ServerAdvertise and EnableMCPMReceive directives, and the implications of server advertisement, see Section 17.6.5, “Configure Server Advertisement Properties for Your mod_cluster-enabled Web Server”.
   Save the file and exit.

6. Restart the Apache HTTP Server.

   The way to restart the Apache HTTP Server depends on whether you are using Red Hat Enterprise Linux's Apache HTTP Server or the Apache HTTP Server included in JBoss Enterprise Web Server. Choose one of the two methods below.

   • Red Hat Enterprise Linux 6 Apache HTTP Server

     Issue the following command:

     [root@host]# service httpd restart

   • JBoss Enterprise Web Server HTTP Server

     JBoss Enterprise Web Server runs on both Red Hat Enterprise Linux and Microsoft Windows Server. The method for restarting the Apache HTTP Server is different for each.

     • Red Hat Enterprise Linux

       In Red Hat Enterprise Linux, JBoss Enterprise Web Server installs its Apache HTTP Server as a service. To restart the Apache HTTP Server, issue the following two commands:

       [root@host ~]# service httpd stop
       [root@host ~]# service httpd start

     • Microsoft Windows Server

       Issue the following commands in a command prompt with administrative privileges:

       C:\> net stop httpd
       C:\> net start httpd

1. Install the mod_cluster-native package using YUM:

   yum install mod_cluster-native
   

2. Apache HTTP Server:
   • If you choose to stay on Apache HTTP Server 2.2.15, you must disable the mod_proxy_balancer module loaded by default by commmenting the LoadModule proxy_balancer_module line in the httpd.conf file.
     Either edit the file manually or use the following command:

     sed -i 's/^LoadModule proxy_balancer_module/#LoadModule proxy_balancer_module/;s/$//' /etc/httpd/conf/httpd.conf
     

   • If you choose to upgrade to Apache HTTP Server 2.2.26, install the latest version using the following command.

     yum install httpd

3. To have the Apache HTTP Server service start at boot, enter the following command:
   • For Red Hat Enterprise Linux 5 and 6:

     service httpd add

   • For Red Hat Enterprise Linux 7:

     systemctl enable httpd22.service

4. Start the mod_cluster balancer with the following command:
   • For Red Hat Enterprise Linux 5 and 6:

     service httpd start

   • For Red Hat Enterprise Linux 7:

     systemctl start httpd22.service

Procedure 17.13. Edit the httpd.conf file and implement the changes

1. Disable the AdvertiseFrequency parameter, if it exists.

   If you have a line like the following in your <VirtualHost> statement, comment it out by putting a # (hash) character before the first character. The value may be different from 5.

   AdvertiseFrequency 5

2. Add the directive to disable server advertisement.

   Add the following directive inside the <VirtualHost> statement, to disable server advertisement.

   ServerAdvertise Off

3. Enable the ability to receive MCPM messages.

   Add the following directive to allow the Web server to receive MCPM messages from the worker nodes.

   EnableMCPMReceive

4. Restart the Web server.

   Restart the Web server by issuing one of the following, depending on whether you use Red Hat Enterprise Linux or Microsoft Windows Server.

   • Red Hat Enterprise Linux

     [root@host ]# service httpd restart

   • Microsoft Windows Server

     net stop Apache2.2
     net start Apache2.2
     

Procedure 17.14. 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 EAP 6 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.

        /host=master/core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="SECRET_VALUE") 
        reload --host=master

        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 password vaults in the Security Architecture and other JBoss EAP security documentation.
     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.

        /host=master/core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="${VAULT::secret::password::SECRET_VALUE}") 
        reload --host=master

        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.

           /host=master/core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="${server.identity.password}") 
           reload --host=master

           You will 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.

Procedure 17.15. Upgrade Process for Clusters - Load Balancing Groups

1. Setup your new cluster using the steps described in the prerequisites.
2. In both ClusterNEW and ClusterOLD, ensure that the configuration option sticky-session is set to true (this option is set to true by default). Enabling this option means that all new requests made to a cluster node in any of the clusters will continue to go to the respective cluster node.

   /profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=sticky-session,value=true)
   

3. Assuming that all the cluster nodes in ClusterOLD are members of ClusterOLD load balancing group. One can set this configuration either via CLI or with an xml configuration (either ha or full-ha profiles in domain mode and either standalone-ha or standalone-full-ha in standalone mode):

   /profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=load-balancing-group,value=ClusterOLD)

   				
   				<subsystem xmlns="urn:jboss:domain:modcluster:1.2">
   					<mod-cluster-config load-balancing-group="ClusterOLD" advertise-socket="modcluster" connector="ajp">
   						<dynamic-load-provider>
   							<load-metric type="busyness"/>
   						</dynamic-load-provider>
          		</mod-cluster-config>
       		</subsystem>
   

4. Add the nodes in ClusterNEW to the mod_cluster configuration individually using the process described here: Section 17.6.6, “Configure a mod_cluster Worker Node”. Additionally use the aforementioned procedure and set their load balancing group to ClusterNEW.
   At this point, one can see an output similar to the undermentioned shortened example on the mod_cluster-manager console:

   				
   				mod_cluster/<version>
   				
       LBGroup ClusterOLD: [Enable Nodes]   [Disable Nodes]   [Stop Nodes]
           Node node-1-jvmroute (ajp://node1.oldcluster.example:8009):
               [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
               Balancer: qacluster, LBGroup: ClusterOLD, Flushpackets: Off, ..., Load: 100
               Virtual Host 1:
                   Contexts:
                       /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]
           
           Node node-2-jvmroute (ajp://node2.oldcluster.example:8009):
               [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
               Balancer: qacluster, LBGroup: ClusterOLD, Flushpackets: Off, ..., Load: 100
               Virtual Host 1:
                   Contexts:
                       /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]
           
           
       LBGroup ClusterNEW: [Enable Nodes]   [Disable Nodes]   [Stop Nodes]
           Node node-3-jvmroute (ajp://node3.newcluster.example:8009):
               [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
               Balancer: qacluster, LBGroup: ClusterNEW, Flushpackets: Off, ..., Load: 100
               Virtual Host 1:
                   Contexts:
                       /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]
           
           Node node-4-jvmroute (ajp://node4.newcluster.example:8009):
               [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
               Balancer: qacluster, LBGroup: ClusterNEW, Flushpackets: Off, ..., Load: 100
               Virtual Host 1:
                   Contexts:
                       /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]
   

5. There are old active sessions within the ClusterOLD group and any new sessions are created either within the ClusterOLD or CLusterNEW group. Next, we want to disable the whole ClusterOLD group, so as we can power down its cluster nodes without causing any error to currently active client's sessions.
   Click on the [Disable Nodes] link for LBGroup ClusterOLD on mod_cluster-manager web console.
   From this point on, only requests belonging to already established sessions will be routed to members of ClusterOLD load balancing group. Any new client's sessions will be created in the ClusterNEW group only. As soon as there are no active sessions within ClusterOLD group, we can safely remove its members.

   Note

   Using [Stop Nodes] would command the load balancer to stop routing any requests to this domain immediately. This will force a failover to another load balancing group which will cause session data loss to clients, provided there is no session replication between ClusterNEW and ClusterOLD.