19.3.4. mod_cluster Configuration on httpd


mod_cluster is an httpd-based load balancer. It uses a communication channel to forward requests from httpd to one of a set of application server nodes. The following derivatives can be set to configure mod_cluster on httpd.


There is no need to use ProxyPass directives because mod_cluster automatically configures the URLs that must be forwarded to JBossWEB.

Table 19.2. mod_cluster Derivatives

Derivative Description Values
CreateBalancers Defines how the balancers are created in the httpd VirtualHosts. This allows directives like: ProxyPass /balancer://mycluster1/.
0: Create all VirtualHosts defined in httpd
1: Do not create balancers (at least one ProxyPass or ProxyMatch is required to define the balancer names)
2: Create only the main server
Default: 2
While using the value 1, do not forget to configure the balancer in the ProxyPass directive, because the default is an empty stickysession and nofailover=Off and the values received via the MCMP CONFIG message are ignored.
UseAlias Check that the alias corresponds to the server name.
0: Ignore aliases
1: Check aliases
Default: 0
LBstatusRecalTime Time interval in seconds for loadbalancing logic to recalculate the status of a node.
Default: 5 seconds
WaitForRemove Time in seconds before a removed node is forgotten by httpd.
Default: 10 seconds
ProxyPassMatch and ProxyPass are mod_proxy directives which, when using ! (instead of the back-end url), prevent reverse-proxy in the path. This is used to allow httpd to serve static information like images. For example,
ProxyPassMatch ^(/.*\.gif)$ !
The above example allows httpd to serve the .gif files directly.
A hot-standby node in the mod_cluster logic is the last resort node to which all requests are routed if all other nodes are down. This is similar to the hot-standby logic in mod_proxy.
To configure a hot-standby node, replace the dynamic-load-provider in mod_cluster subsystem with a simple-load-provider with factor set to 0, for example:
<subsystem xmlns="urn:jboss:domain:modcluster:1.2">
    <mod-cluster-config advertise-socket="modcluster" connector="ajp">
-        <dynamic-load-provider>
-            <load-metric type="busyness"/>
-        </dynamic-load-provider>
+        <simple-load-provider factor="0"/>

In mod_cluster-manager console, the node is displayed with OK status and Load: 0. For more information, refer Apache mod_cluster-manager Application section in the JBoss Enterprise Application Platform Development Guide.
For instance, if there are three nodes:
  • Node A, Load: 10
  • Node B, Load: 10
  • Node C, Load: 0
The load will be balanced between nodes A and B. If both the nodes are unavailable, node C will take the load.

The context of a mod_manager directive is VirtualHost in all cases, except when mentioned otherwise. server config context implies that the directive must be outside a VirtualHost configuration. If not, an error message is displayed and httpd does not start.

Table 19.3. mod_manager Derivatives

Derivative Description Values
EnableMCPMReceive Allow the VirtualHost to receive the MCPM from the nodes. Include EnableMCPMReceive in the httpd configuration to allow mod_cluster to work. Save it in the VirtualHost where you configure advertise.
The base name for the names that mod_manager uses to store configuration, generate keys for shared memory or locked files. This must be an absolute path name; the directories are created if needed. It is recommended that these files are placed on a local drive and not an NFS share.
Context: server config
Maxcontext The maximum number of contexts supported by mod_cluster
Context: server config
Default: 100
Maxnode The maximum number of nodes supported by mod_cluster.
Context: server config
Default: 20
Maxhost The maximum number of hosts (aliases) supported by mod_cluster. It also includes the maximum number of balancers.
Context: server config
Default: 20
The number of active sessionid stored to provide the number of active sessions in the mod_cluster-manager handler. A session is inactive when mod_cluster does not receive any information from the session within 5 minutes.
Context: server config
This field is for demonstration and debugging purposes only.
0: the logic is not activated.
MaxMCMPMaxMessSize The maximum size of MCMP messages from other Max directives Calculated from other Max directives. Min: 1024
ManagerBalancerName The name of balancer to use when the JBoss AS/JBossWeb/Tomcat does not provide a balancer name.
PersistSlots Tells mod_slotmem to persist nodes, aliases and contexts in files.
Context: server config
CheckNonce Switch check of nonce when using mod_cluster-manager handler.
Default: on - Nonce checked
AllowDisplay Switch additional display on mod_cluster-manager main page.
Default: off - only version is displayed
AllowCmd Allow commands using mod_cluster-manager URL.
Default: on - Commands allowed
ReduceDisplay Reduce the information displayed on the main mod_cluster-manager page, so that more number of nodes can be displayed on the page.
Default: off - full information is displayed
SetHandler mod_cluster-manager
Displays information about the node that mod_cluster sees from the cluster. The information includes generic information and additionally counts the number of active sessions.
							<Location /mod_cluster-manager>
							SetHandler mod_cluster-manager
							Order deny,allow
							Allow from

Default: off


When accessing the location defined in httpd.conf:
Transferred: Corresponds to the POST data send to the back-end server.
Connected: Corresponds to the number of requests that have been processed when the mod_cluster status page was requested.
Num_sessions: Corresponds to the number of sessions mod_cluster report as active (on which there was a request during the past 5 minutes). That field is not present when Maxsessionid is zero. This field is for demonstration and debugging purposes only.