Clustering with JBoss mod_cluster

User Rating: 5 / 5

Star ActiveStar ActiveStar ActiveStar ActiveStar Active
Mod cluster is an http based load balancer which greatly simplify the setup of an http cluster. It ships as a set of modules which need to be installed on the httpd server and a Service Archive Library (.sar) which needs to be deployed on JBoss AS (It is built-in in JBoss AS 6/7).


Compared with the former mod_jk, the new mod_cluster has the great advantage to accept a dynamic configuration of httpd workers. This can be done through an advertise mechanism where all httpd workers communicate lifecycle events (like startup or shutdown) thus leveraging dynamic configuration of nodes.

The following picture describes an high level view of the communication between the httpd server and a set of JBoss nodes:

jboss cluster clustering

As you can see, mod_cluster issues requests to mod_proxy_ajp which forwards the AJP request to the target node of the cluster. The cluster of JBoss nodes communicates the cluster view to mod_cluster.
However note that AJP is optional: Unlike mod_jk, mod_cluster can forward connections to application server nodes using also HTTP or HTTPS. Refer to the documentation for additional information about it.

Installing mod_cluster

The installation of mod_cluster is slightly different depending on the release of the application server. If you are running JBoss AS 5.1.0 you need to execute all the steps listed in this tutorial. If you are running JBoss AS 6 or 7 you need just to execute steps 2 (Install Binaries) and 4 (Update Apache configuration).

At first move to the Download page and download the following items:

1) Download the Java Bundle package which contains the Service Archive (.sar) to be deployed on JBoss
2) Download the binaries for your platform which contains a built-in httpd server and its modules (including mod_cluster).

1. Installing Java Bundles

From the bundle tar.gz, copy the file mod-cluster.sar in the "deploy/cluster"  folder of your "all" configuration:

jboss clustering cluster

2. Installing Mod_cluster Binaries

 You have to copy the following modules to your Apache Web server installation:
The modules can be extracted from the archive The modules need to be copied in the APACHE_HOME/modules dir.

3. Update JBoss AS Configuration

Now open the file server.xml which contains the embedded Web Server configuration and is located in the deploy/jbossweb.sar/ folder and add the following line at the same level of other Listeners:

<Listener className="org.jboss.web.tomcat.service.deployers.MicrocontainerIntegrationLifecycleListener"            delegateBeanName="ModClusterService"/>
In the same file, a few lines after, add the jvmRoute in the Engine element:

<Engine name="jboss.web" defaultHost="localhost"  jvmRoute="node01"> 

Next file we need to modify is jboss-beans.xml which is located in the deploy/jbossweb.sar/META-INF folder. There we need to state that the WebServer depends on the Mod Cluster Service.

just add the following dependency to the WebServer bean (approx line 16)

4. Update Apache Web Server configuration

Provided that you have copied all modules in the previous step, all you have to do is loading the modules in the httpd memory and configure a VirtualHost for handling requests to JBoss cluster.

In order to enable mod_cluster, the following modules need to be enabled:
LoadModule proxy_module /modules/
LoadModule proxy_ajp_module /modules/
LoadModule slotmem_module /modules/
LoadModule manager_module /modules/
LoadModule proxy_cluster_module /modules/
LoadModule advertise_module /modules/
Then, add this configuration to the bottom of your Apache's httpd.conf file:

    <Directory />     
       Order deny,allow     
       Deny from all     
       Allow from 192.168.1.  

   KeepAliveTimeout 60
   MaxKeepAliveRequests 0  
   ManagerBalancerName mycluster
   AdvertiseFrequency 5 
Here we assume that your Apache listen to the IP Address and accepts requests on port 6666.

Now the configuration is complete. Restart Apache and start a set of JBoss nodes:

JBoss AS 4/5/6 -c all -b                    

JBoss AS 7 -c standalone-ha.xml -b

Verify that both Apache and JBoss serve correctly web pages:

should serve Apache home page. ("It works!")

Now deploy a sample Web application to JBoss cluster, for example MyWebApp context:

As you can see, mod cluster automatically configures a context for all your Web applications, unless you have explicitly excluded it in mod_cluster.sar/META-INF/mod-cluster-jboss-beans.xml file. (Look for the property excludedContexts)


Related articles available on

JBoss Clustering a Web Application

Please Note: This article cover JBoss AS 4/5/6 releases. If you w

Clustering EJB 3 with JBoss AS

To cluster a stateless session bean in EJB 3 all you need to do i

JBoss monitoring HTTP Session replication

In this article we'll show how to monitor HTTPSession replication

How do I change multicast address of JBoss cluster ?

Since JBoss AS 4.0.3, the jboss.partition.udpGroup property can b

JBoss farming service

What is the farming service ? this article explains about it, als

JBoss HTTP Session replication

HTTP session replication is used to replicate the state associate

Follow us on Twitter