Red Hat Training

A Red Hat training course is available for Red Hat JBoss Web Server

3.2. Configure Load Balancing Using Apache HTTP Server and mod_cluster

In Red Hat JBoss Web Server 2.1 and higher, mod_cluster is configured correctly for Apache HTTP Server by default. To set a custom configuration, see Section 3.2.1, “Configure a Basic Proxy Server”.
For more information on configuring a Tomcat worker node with mod_cluster, see Section, “Configuring a Tomcat Worker Node”.


Red Hat customers can also use the Load Balancer Configuration Tool on the Red Hat Customer Portal to quickly generate optimal configuration templates for mod_cluster, as well as Tomcat worker nodes.
When using this tool for JBoss Web Server 3, ensure you select 2.4.x as the Apache version, and select Tomcat as the back end configuration.

3.2.1. Configure a Basic Proxy Server Basic Proxy Configuration Overview

Proxy server configuration consists of one mandatory and one optional step:
  1. Configure a Proxy Server listener to receive worker node connection requests and worker node feedback.
  2. Optional: Disable server advertisement.
Server Advertisement

The proxy server advertises itself using UDP multicast. When UDP multicast is available between the proxy server and the worker nodes, Server Advertisement adds worker nodes without further configuration required on the proxy server, and minimal configuration on the worker nodes.

If UDP multicast is not available or undesirable, configure the worker nodes with a static list of proxy servers, as detailed in Section, “Configuring a Worker Node with a Static Proxy List”. In either case, the proxy server does not need to be configured with a list of worker nodes. Configure a Load-balancing Proxy Using mod_cluster


  • Install JBoss Web Server, and configure the mod_cluster modules for your installation. See the JBoss Web Server Installation Guide for details.

Procedure 3.1. Configure a Load-balancing Proxy Using mod_cluster

  1. Create a Listen Directive for the Proxy Server

    Edit your mod_cluster configuration file (usually JWS_HOME/httpd/conf.d/mod_cluster.conf), and add the following:
    Where IP_ADDRESS is the address of the server network interface to communicate with the worker nodes, and PORT_NUMBER is the port on that interface to listen on.


    The port must be open for incoming TCP connections.

    Example 3.1. Example Listen Directive

  2. Create a Virtual Host

    Add the following to your mod_cluster configuration file:
       <Directory />
          Require ip IP_ADDRESS
       KeepAliveTimeout 60
       MaxKeepAliveRequests 0
       ManagerBalancerName mycluster
       AdvertiseFrequency 5
       EnableMCPMReceive On
    Where IP_ADDRESS and PORT_NUMBER are the values from the Listen directive.
  3. Optional: Disable Server Advertisement

    The AdvertiseFrequency directive makes the server to periodically send server advertisement messages via UDP multicast. By default, this occurs every 5 seconds.
    These server advertisement messages contain the IP_ADDRESS and PORT_NUMBER specified in the VirtualHost definition. Worker nodes configured to respond to server advertisements use this information to register themselves with the proxy server.
    To disable server advertisement, add the following directive to the VirtualHost definition:
    ServerAdvertise Off
    If server advertisements are disabled, or UDP multicast is not available on the network between the proxy server and the worker nodes, configure worker nodes with a static list of proxy servers. See Section, “Configuring a Worker Node with a Static Proxy List”.
  4. Optional: Configure Apache HTTP Server Logging

    You can configure the Apache HTTP Server that is doing the load balancing to log which worker node handled a request. This may be useful when troubleshooting your load balancer.
    To enable this for mod_cluster, you can add the following to your Apache HTTP Server LogFormat directive(s):
    The name of the balancer that served the request.
    The name of the worker node that served the request.
    For more information on Apache HTTP Server logging (including log rotation), see
  5. Stop and Start the JBoss Web Server Apache Service

    See the JBoss Web Server Installation Guide for detailed instructions.

3.2.2. Configuring Worker Nodes Configuring a Tomcat Worker Node

Follow this procedure to install mod_cluster on a Red Hat JBoss Web Server node, and configure it for non-clustered operation.


JBoss Web Server Tomcat worker nodes only support a subset of mod_cluster functionality.

Supported Worker Node types

  • Red Hat JBoss Web Server Tomcat service

mod_cluster JBoss Web Server Node Limitations

  • Non-clustered mode only.
  • Only one load metric can be used at a time when calculating the load balance factor.

Procedure 3.2. Configure a Tomcat Worker Node

  1. Add a Listener to Tomcat

    Add the following Listener element beneath the other Listener elements in JWS_HOME/tomcat<VERSION>/conf/server.xml.
    <Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="true" stickySession="true" stickySessionForce="false" stickySessionRemove="true" />
  2. Give the Worker a Unique Identity

    Edit JWS_HOME/tomcat<VERSION>/conf/server.xml and add the jvmRoute attribute and value to the Engine element, as shown below:
    <Engine name="Catalina" defaultHost="localhost" jvmRoute="worker01">
  3. Configure STATUS MCMP Message Frequency

    Tomcat worker nodes periodically send status messages containing their current load status to the Apache HTTP Server balancer. The default frequency of these messages is 10 seconds. If you have hundreds of worker nodes, the STATUS MCMP Messages can increase traffic congestion on your Apache HTTP Server network.
    You can configure the MCMP message frequency by modifying the org.jboss.modcluster.container.catalina.status-frequency Java property. By default, the property accepts values in seconds*10. For example, setting the property to 1 means 10 seconds. The example below demonstrates the frequency set to 60 seconds.
  4. Optional Step: Configure Firewall for Proxy Server Advertisements

    A proxy server using mod_cluster can advertise itself via UDP multicast. Most operating system firewalls block this by default. To enable server advertising and receive these multicast messages, open port 23364 for UDP connections on the worker node's firewall.
    • For Red Hat Enterprise Linux 6

      /sbin/iptables -A INPUT -m state --state NEW -m udp -p udp --dport
       23364 -j ACCEPT 
      -m comment -comment "receive mod_cluster proxy server advertisements"
      If Automatic Proxy Discovery is not used, configure worker nodes with a static list of proxies. In this case you can safely ignore the following warning message:
      [warning] mod_advertise: ServerAdvertise Address or Port not defined, Advertise disabled!!!
    • For Red Hat Enterprise Linux 7

      firewall-cmd --permanent --zone=public --add-port=23364/udp
    • For Microsoft Windows, using PowerShell

      Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall firewall add rule name="UDP Port 23364" dir=in  action=allow protocol=UDP localport=23364"'
      Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall firewall add rule name="UDP Port 23364" dir=out action=allow protocol=UDP localport=23364"' Configuring a Worker Node with a Static Proxy List

Server advertisement allows worker nodes to dynamically discover and register themselves with proxy servers. If UDP broadcast is not available or server advertisement is disabled, then worker nodes must be configured with a static list of proxy server addresses and ports.
Use the following procedure to configure a Red Hat JBoss Web Server worker node to operate with a static list of proxy servers.

Procedure 3.3. Configure JBoss Web Server Worker Node with a Static Proxy List

  1. Define a mod_cluster listener, and Disable Dynamic Proxy Discovery

    Edit JWS_HOME/tomcat<VERSION>/conf/server.xml, and add a <Listener> element to the server.xml file. Set the advertise property of the ModClusterListener to false. For example:
    <Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="false" stickySession="true" stickySessionForce="false" stickySessionRemove="true"/>
  2. Create a static proxy server list

    Add a comma separated list of proxies in the form of IP_ADDRESS:PORT as the proxyList property. For example:

    Example 3.2. Example Static Proxy List

    <Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="false" stickySession="true" stickySessionForce="false" stickySessionRemove="true" proxyList=","/>