Tomcat clustering configuration

The following steps assume that you have installed a Tomcat 5.5.x bundle or latest, i only tested on 5.5.27 but is should work for other configuration as well. The network configuration apply to Linux and may vary with the distribution. It should work as is for distributions based on Red Hat.

For Tomcat clustering we have two main things to configure:

Configure the network support for cluster

Opening Specific HTTP Ports (e.g. Port 45564, 4001)

The cluster class will start up a membership service (multicast) and a replication service (tcp unicast). See also for a brief article on this. You will need to have root access as noted above to complete this.

Your server may or may not already have this entry. Open iptables:

> vi /etc/sysconfig/iptables

Add the following entries:

-A RH-Firewall-1-INPUT -p udp -m udp --dport 45564 -j ACCEPT
-A RH-Firewall-1-INPUT -p tcp -m tcp --dport 45564 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 4001 -j ACCEPT

Save and close the above file and after restart the iptables

  > /etc/init.d/iptables restart

Configure the multicast address and routes.

Clustering membership is established using very simple multicast pings. Each Tomcat instance will periodically send out a multicast ping, in the ping message the instance will broad cast its IP and TCP listen port for replication. If an instance has not received such a ping within a given timeframe, the member is considered dead.

Add route  (the server’s ip address)

sudo /sbin/route add gw dev bond0

Edit rc.local to make the change persistent through restarts.

sudo vim /etc/rc.d/rc.local

Add this line at the end (the server’s ip address)

/sbin/route add gw dev bond0

Configure Tomcat to support clustering.

Application clustering with Tomcat has two steps:

Enable Tomcat clustering support

You need to enable the cluster support in Tomcat by editing the server.xml file. Open server.xml

sudo vim /usr/local/tomcat-5.5.27/conf/server.xml

Enable clustering configuration in the configuration file, notice that the default configuration is using the DeltaManager which will replicate only the session’s changes and not the entire object:

<Cluster className="org.apache.catalina.cluster.tcp.SimpleTcpCluster"
<Membership className="org.apache.catalina.cluster.mcast.McastService"
<Receiver className="org.apache.catalina.cluster.tcp.ReplicationListener"
<Sender className="org.apache.catalina.cluster.tcp.ReplicationTransmitter"
<Valve className="org.apache.catalina.cluster.tcp.ReplicationValve"
<Deployer className="org.apache.catalina.cluster.deploy.FarmWarDeployer"
<ClusterListener className="org.apache.catalina.cluster.session.ClusterSessionListener"/>

One main condition for replication to work is that your session content is serializable. Add a _jvmRoute_ to your Tomcat Engine section From

  <Engine name="Catalina" defaultHost="localhost">


  <Engine name="Catalina" defaultHost="localhost" jvmRoute="tomcat1">

jvmRoute identifies unique a Tomcat instance in a cluster. If multiple servers are used I recommend you to use descriptive names.

Make your application clusterizable

Configuring Tomcat clustering is not enough to cluster your application. For that you need to tell Tomcat which application you want to be clusterizable. This is achieved in two ways:

Enable application clustering by ROOT.xml

Edit ROOT.xml file

 sudo vim /usr/local/tomcat-5.5.27/conf/Catalina/localhost/ROOT.xml

Look for

 <Context path="" cookies="true" distributable="true" crossContext="true">

Change it to

 <Context path="" debug="0" reloadable="true"
cookies="true" crossContext="false" privileged="false" >

Enable application clustering by editing the web.xml

Edit the web.xml file

 sudo vim /usr/local/tomcat-5.5.27/webapps/ROOT/WEB-INF/web.xml

Look for:

 <web-app xmlns="" xmlns:xsi="" xsi:schemaLocation="" version="2.4">

Change it to:

 <web-app xmlns="" xmlns:xsi="" xsi:schemaLocation="" version="2.4">

Restart Tomcat

 cd /usr/local/tomcat-5.5.27/bin/
sudo ./
sudo ./
or if you have a init script
sudo /etc/init.d/tomcat5 restart

You need to configure all the nodes in the cluster as detailed above. Every node should have unique name provided by “jvmRoute” attribute.

Further reading

Cluster-howto |


5 Responses to “Tomcat clustering configuration”

  1. len on June 29th, 2009 6:09 am

    I was searching for jboss, clustering and multicast and run into your post. Nice! Funny! The internet is not so large after all 🙂

  2. bserban on July 6th, 2009 8:51 am

    Well, nice to hear you again after so many years. I hope that my post helped you somehow.



  3. Rakesh on June 24th, 2010 7:19 am

    Let me try thanks for the article 😉

  4. Rahul on August 4th, 2010 10:59 am

    I tried your example but with the following Setup: Windows 7 Apache 2.2 Tomcat 5.5 mod_jk-1.2.30-httpd-2.2.3

    After performing the appropriate installs, I can get to the Apache default page, and I can access the Tomcat on localhost as well. But when I try to access jsp-examples via Apache, I’m getting the following error 503:

    “Service Temporarily Unavailable The server is temporarily unable to service your request due to maintenance downtime or capacity problems. Please try again later.

    I checked apache and tomcat logs, but they do not report any exceptions there, would appreciate if anyone can point how can I find what is the problem.

    I have different ports, checked the jvmRoute names and all, but I am not able to locate the problem.

    any help would be appreciated.

  5. Sreejith P on December 21st, 2010 2:28 am

    Hi ,

    I am using apache+mod_jk as loadbalancer and two different tomcats are running on two diffrent systems. The loadbalance is working fiine but have issue related to the session relication. The session is not maintained. Please find the server.xml details given below :

    IP of the tomcat running instances are and and the version of the tomcat used is tomcat-6.0.26



    And my file is given below :




    worker.tomcat.sticky_session = 1

    worker.tomcat.balance_workers = worker1, worker2



    I have added the

    in the conf/Catalina/localhost/ROOT.xml


    in the file webapps/ROOT/WEB-INF/web.xml

    Please guid me to set session replication set up.