You can also check the configuration reference documentation.
Clustering/Session Replication HOW-TO
Table of Contents
For the impatient
<Engine> or your
<Host> element to enable clustering.
Using the above configuration will enable all-to-all session replication
DeltaManager to replicate session deltas. By all-to-all we mean that the session gets replicated to all the other
nodes in the cluster. This works great for smaller cluster but we don't recommend it for larger clusters(a lot of Tomcat nodes).
Also when using the delta manager it will replicate to all nodes, even nodes that don't have the application deployed.
To get around this problem, you'll want to use the BackupManager. This manager only replicates the session data to one backup node, and only to nodes that have the application deployed. Downside of the BackupManager: not quite as battle tested as the delta manager.
Here are some of the important default values:
- Multicast address is 220.127.116.11
- Multicast port is 45564 (the port and the address together determine cluster membership.
- The IP broadcasted is
java.net.InetAddress.getLocalHost().getHostAddress()(make sure you don't broadcast 127.0.0.1, this is a common error)
- The TCP port listening for replication messages is the first available server socket in range
- Listener is configured
- Two interceptors are configured
The following is the default cluster configuration:
<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="18.104.22.168" port="45564" frequency="500" dropTime="3000"/> <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" address="auto" port="4000" autoBind="100" selectorTimeout="5000" maxThreads="6"/> <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> <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" filter=""/> <Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/> <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" tempDir="/tmp/war-temp/" deployDir="/tmp/war-deploy/" watchDir="/tmp/war-listen/" watchEnabled="false"/> <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> </Cluster>
Will cover this section in more detail later in this document.
The cluster implementation is written on the basis that a secure, trusted network is used for all of the cluster related network traffic. It is not safe to run a cluster on a insecure, untrusted network.
There are many options for providing a secure, trusted network for use by a Tomcat cluster. These include:
- private LAN
- a Virtual Private Network (VPN)
To run session replication in your Tomcat 9 container, the following steps should be completed:
- All your session attributes must implement
- Uncomment the
Clusterelement in server.xml
- If you have defined custom cluster valves, make sure you have the
ReplicationValvedefined as well under the Cluster element in server.xml
- If your Tomcat instances are running on the same machine, make sure the
Receiver.portattribute is unique for each instance, in most cases Tomcat is smart enough to resolve this on it's own by autodetecting available ports in the range 4000-4100
- Make sure your
- If you are using mod_jk, make sure that jvmRoute attribute is set at your Engine
<Engine name="Catalina" jvmRoute="node01" >and that the jvmRoute attribute value matches your worker name in workers.properties
- Make sure that all nodes have the same time and sync with NTP service!
- Make sure that your loadbalancer is configured for sticky session mode.
Load balancing can be achieved through many techniques, as seen in the Load Balancing chapter.
Note: Remember that your session state is tracked by a cookie, so your URL must look the same from the out side otherwise, a new session will be created.
Note: Clustering support currently requires the JDK version 1.5 or later.
The Cluster module uses the Tomcat JULI logging framework, so you can configure logging
through the regular logging.properties file. To track messages, you can enable logging on the key:
To enable session replication in Tomcat, three different paths can be followed to achieve the exact same thing:
- Using session persistence, and saving the session to a shared file system (PersistenceManager + FileStore)
- Using session persistence, and saving the session to a shared database (PersistenceManager + JDBCStore)
- Using in-memo