Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Clustering and Sessions

Session Replication and Clustering in Tomcat

Learn how Tomcat clusters replicate HttpSession data between nodes, the difference between DeltaManager and BackupManager, membership, jvmRoute and distributable apps.

One Tomcat is a single point of failure and has a ceiling on how much traffic it can handle. The usual answer is to run several instances behind a load balancer. That brings a new problem: the user's session lives in the memory of one instance, and if their next request reaches another instance, or the first one dies, the session is gone. There are two ways to solve this. You can keep sessions out of the servers (in Redis or a database, with the application designed for it), or you can let Tomcat replicate sessions between nodes. This lesson covers the second approach, what it costs and when it is the right choice.

Tomcat cannot run on this site, so the configuration here is read-only. Two runnable Java stand-ins model replication so you can see how each strategy behaves.

The pieces of a Tomcat cluster

A cluster is declared with a <Cluster> element inside an <Engine> or <Host>. Its main parts are:

  • Membership: nodes find each other, traditionally by multicast heartbeat on an address such as 228.0.0.4:45564, or with a static member list where multicast is blocked (most cloud networks).
  • Receiver: a TCP listener (NioReceiver, default port 4000) that accepts replicated data.
  • Sender: a pooled sender that pushes changes to other members.
  • Interceptors: a chain of steps such as failure detection and message dispatching.
  • ClusterManager: the session manager, either DeltaManager or BackupManager.
XML
<Engine name="Catalina" defaultHost="localhost" jvmRoute="node1">
  <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
           channelSendOptions="8">
    <Manager className="org.apache.catalina.ha.session.DeltaManager"
             expireSessionsOnShutdown="false"
             notifyListenersOnReplication="true"/>
    <Channel className="org.apache.catalina.tribes.group.GroupChannel">
      <Membership className="org.apache.catalina.tribes.membership.McastService"
                  address="228.0.0.4" port="45564" frequency="500" dropTime="3000"/>
      <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
                address="auto" port="4000" autoBind="100"/>
      <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
        <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/>
      </Sender>
      <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
      <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor"/>
    </Channel>
    <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>
  </Cluster>
</Engine>

Each node needs a unique jvmRoute on the Engine. Tomcat appends it to the session id (ABC123.node1), which lets a load balancer see which node owns the session (a "sticky" session).

Two more requirements: the application must declare <distributable/> in web.xml, and every session attribute must be serializable (see sessions and persistence). Without <distributable/> Tomcat does not replicate that app.

DeltaManager: everyone has everything

DeltaManager is the all-to-all strategy. Every node holds a copy of every session. When a session changes, the change (the "delta") is sent to every other node. A node that starts up asks another node for the full session state before it takes traffic.

Advantages: any node can serve any user, so failover is instant and load balancing needs no stickiness. Costs: memory use on each node equals the sum of all sessions, and network traffic grows with each node you add, which is why it is practical only for small clusters (about four nodes or fewer).

BackupManager: one backup per session

BackupManager keeps each session on one primary node plus one backup node. It scales better, since a session is stored twice no matter how many nodes you have. It requires sticky sessions so that requests go to the primary, and after a failure the load balancer will route to the node that holds the backup (the jvmRoute suffix helps it find the right node). It is simpler on the network but has a smaller safety margin: if both the primary and the backup die, the session is lost.

DeltaManager BackupManager
Copies per session every node primary plus one backup
Network traffic high, grows with nodes low
Best for 2 to 4 nodes larger clusters
Sticky sessions optional needed

Sync or async replication

channelSendOptions controls the delivery guarantee. 8 is asynchronous (the request finishes without waiting for the copy), and 6 is synchronous with acknowledgement. Asynchronous is faster but a failure between the response and the copy can lose the last change. Replication also happens only when the session is marked changed, so always call session.setAttribute() after modifying a mutable attribute, otherwise Tomcat does not notice the change.

Stand-in: delta replication between two nodes

This stand-in sends only the changed attribute from one node to another, like DeltaManager does, and shows why mutating an object without calling setAttribute is not replicated.

Java Stand-in: delta replication

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

In a real cluster each node deserializes its own copy, which the stand-in imitates by copying the list. After the silent change, node2 still has only the book. The fix is the last setAttribute.

Stand-in: failover with a backup

Now the BackupManager idea: each session has a primary and a backup, and after the primary fails the backup node takes over.

Java Stand-in: primary and backup

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The stand-in uses a hash to choose the primary; real Tomcat decides differently, but the failure behavior is the same: one failure is survived, two at once are not.

When not to cluster sessions

Replication couples the nodes: a slow or faulty node can slow the others, large sessions saturate the network, and rolling upgrades are tricky when class versions differ. Many teams make the application stateless instead: authentication in a signed token, shared state in Redis or a database, and plain round-robin load balancing. See load balancing for how requests are distributed.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which element must an application declare for Tomcat to replicate its sessions?

    The <distributable/> element in web.xml tells the container the app's sessions may be replicated.
  2. 2. What does DeltaManager do?

    DeltaManager is all-to-all replication, so every node has every session.
  3. 3. Why call session.setAttribute() after changing a mutable object in the session?

    Replication is triggered by attribute set calls, not by in-place mutation.
  4. 4. What is jvmRoute used for?

    Tomcat appends the jvmRoute to JSESSIONID, e.g. ABC123.node1.

Summary

  • A Tomcat cluster has membership, a receiver, a sender and a cluster manager.
  • DeltaManager copies sessions everywhere (small clusters); BackupManager keeps a primary and one backup (larger clusters, sticky sessions).
  • Apps need <distributable/>, serializable attributes, setAttribute on every change and a unique jvmRoute per node.
  • A stateless design with external session storage is often simpler and scales better.

Next: Load balancing and sticky sessions