Please Note: This article cover JBoss AS 4/5/6 releases. If you want to learn about clustering JBoss AS 7 and WildFly check this tutorial: Clustering JBoss AS 7

Clustering allows us to run an applications on several parallel servers (a.k.a cluster nodes). The load is distributed across different servers, and even if any of the servers fails, the application is still accessible via other cluster nodes. Clustering is crucial for scalable enterprise applications, as you can improve performance by simply adding more nodes to the cluster.

The JBoss Application Server (AS) comes with clustering support out of the box. 

The simplest way to start a JBoss server cluster is to start several JBoss instances on the same local network, using the run -c all command for each instance. Those server instances, all started in the all configuration, detect each other and automatically form a cluster.

For Web applications, a hardware- or software-based HTTP load-balancer usually sits in front of the application servers within a cluster. These load-balancers can be used to decrypt HTTPS requests quickly, distribute the load between nodes in the cluster, and detect server failures. The usual setup is to have a user session live entirely on one server that is picked by the load-balancer. This is called a "sticky" session.

Configuring JBoss to run in a cluster

So let's see how to configure 2 instances of JBoss in a cluster. We'll define two nodes nodeA and nodeB

Node Name Address

Now for every installation of JBoss go under the folder deploy\jboss-web.deployer (jBoss 4.X) or under the folder deploy\jbossweb.sar (jBoss 5.X and later) and pick up the file server.xml  line.

Configure on the machine

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

and on the machine

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

Now create an HelloWorld web application and add a Servlet which simply dumps some session information:

public void doGet(HttpServletRequest request, HttpServletResponse response)

 throws ServletException, IOException { 
  String dummy = (String)request.getSession().getAttribute("dummy"); 
  PrintWriter out = response.getWriter(); 
  System.out.print("Hello from Node "+ InetAddress.getLocalHost().toString()); 
  if (dummy == null) {  
   out.println("Dummy value not found. Inserting it....");  
   request.getSession().setAttribute("dummy", "dummyOk"); 
  } else {  
   out.println("Dummy is " +dummy); 

Before packing the application add at the very beginning of the web.xml file

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"


Ok so now you're ready to deploy the web application: where can I deploy it ?

The easiest way to deploy an application into the cluster is to use the farming service. That is to hot-deploy the application archive file (e.g., the EAR, WAR or SAR file) in the all/farm/ directory of any of the cluster member and the application is automatically duplicated across all nodes in the same cluster.

You can only put archive files, not exploded directories, in the farm directory. This way, the application on a remote node is only deployed when the entire archive file is copied over. Otherwise, the application might be deployed (and failed) when the directory is only partially copied.

If you want to read more about the Farming Service continue reading this article:

Ok, so now Jboss is ready to accept Cluster Web Applications, now we need at first something something sitting in front of our JBoss Cluster. We'll use for our purpose Apache Web Server.

For a detailed explanation of all steps necessary to configure Apache-JBoss via modJK we suggest you reading the Wiki Now we'll focus in particular on the part of the configuration relative to the cluster.

The first thing we need to have is redirecting calls to the mod_JK load balancer: this is done in file

# Where to find
JkWorkersFile conf/

# Where to put jk logs
JkLogFile logs/mod_jk.log

JkMount /HelloWorld/* loadbalancer

Here HelloWorld is the Web Context of our sample application. Now let's move to file.





# Status worker for managing load balancer

As you can see we have the two nodes (nodeA and nodeB) with relative port and IP address.

Now launch the two instances of JBoss using the command run -c all. The first instance started will display this information when the second instance kicks in:

16:09:20,562 INFO [AjpProtocol] Starting Coyote AJP/1.3 on ajp-
16:09:20,578 INFO [Server] JBoss (MX MicroKernel) [4.2.0.GA (build: SVNTag=JBoss_4_2_0_GA date=200705111440)] Started in 1m:20s:438ms
16:10:28,343 INFO [TreeCache] viewAccepted(): [|1] [
16:10:28,421 INFO [TreeCache] locking the subtree at / to transfer state
16:10:28,593 INFO [StateTransferGenerator_140] returning the state for tree roo
ted in /(1024 bytes)
16:10:40,921 INFO [DefaultPartition] New cluster view for partition DefaultPart
ition (id: 1, delta: 1) : [,]
16:10:40,984 INFO [DefaultPartition] I am ( received membership
Changed event:
16:10:40,984 INFO [DefaultPartition] Dead members: 0 ([])
16:10:40,984 INFO [DefaultPartition] New Members : 1 ([])
16:10:40,984 INFO [DefaultPartition] All Members : 2 ([,])
16:10:45,187 INFO [TreeCache] viewAccepted(): [|1] [ 309,]
16:10:47,453 INFO [TreeCache] viewAccepted(): [|1] [ 313,]

Ok. In order to invoke our Servlet simply point to our Apache Web Server domain address


You'll see that the balancer load balances calls and, once it has created the session, it will replicate the session to the secondary server. You can do experiments to test your cluster, switching off one instance of the cluster and verifying that the session stays alive on the other server. 

Simply verify that the dummy values stays in the Session when you switch off the current instance of JBoss.

Dummy is dummyOk


JBoss clustering is designed to be simple to configure and simple to extend. It is one of the final pieces of the puzzle that makes JBoss a viable open source competitor to other enterprise J2EE offerings.

You can read more about Cluster Http replication in this tutorial.


Related articles available on

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

How do I know the Http Session replication size?

You need to add the <SIZE /> tag into your Cluster configur