Clustering with JBoss mod

Clustering with JBoss mod_cluster

JBoss Mod_cluster is an http based load balancer. It is an alternative to mod_jk and it is implemented as an httpd set of modules.

Mod cluster is an innovative module 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.

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:

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. In this example we will suppose you have an Apache 2.2 Web Server installed and a JBoss 5.1.0 application server.

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).

Let's begin with the Java Bundle (1):

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

jboss clustering cluster

Now let's move to the binaries (2).
You have to copy the following modules to your Apache Web server installation:

mod_proxy.so
mod_proxy_ajp.so
mod_slotmem.so
mod_manager.so
mod_proxy_cluster.so
mod_advertise.so

The modules can be extracted from the archive mod-cluster-1.0.3.GA-xxx-ssl.zip. The modules need to be copied in the APACHE_HOME/modules dir.

Update JBoss AS 5 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)

 <depends>ModClusterService</depends>

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.

Add this configuration to the bottom of your Apache's httpd.conf file:

LoadModule proxy_module ./modules/mod_proxy.so
LoadModule proxy_ajp_module ./modules/mod_proxy_ajp.so
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

Listen 192.168.1.0:6666

<VirtualHost 192.168.1.0:6666>
    <Directory />
       Order deny,allow
       Deny from all
       Allow from 192.168.1.
   </Directory>

   KeepAliveTimeout 60
   MaxKeepAliveRequests 0
   ManagerBalancerName mycluster
   AdvertiseFrequency 5
</VirtualHost>

Here we assume that your Apache listen to the IP Address 192.168.1.0 and accepts requests on port 6666.

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

run -c all -b 192.168.1.10

(Where 192.168.1.10 is the IP address where the node is bound)

Verify that both Apache and JBoss serve correctly web pages:

http://192.168.1.0:6666

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

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

http://192.168.1.0:6666/MyWebApp

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)

References:

http://www.jboss.org/mod_cluster/quick-start.html
http://oddthesis.org/posts/2008-12-jboss-and-mod_cluster/

MASTERTHEBOSS.COM

JBoss and Java EE tutorials

The AS7 book!

JBoss Tuning

JBoss 5 book

Poll