The Cluster object

Table of Contents

Introduction

The tomcat cluster implementation provides session replication, context attribute replication and cluster wide WAR file deployment. While the Cluster configuration is fairly complex, the default configuration will work for most people out of the box.

The Tomcat Cluster implementation is very extensible, and hence we have exposed a myriad of options, making the configuration seem like a lot, but don't lose faith, instead you have a tremendous control over what is going on.

Security

Tomcat clustering is typically used over a secure, trusted network. If a trusted network is not available then a cluster may be configured to use TLS. To configure a cluster to use TLS the following changes/additions to a working non-TLS cluster configuration are required:

  • OpenSSL-FFM support (Java 22+ and OpenSSL library) or Tomact Native 1.2.17+ must be available to provide the TLS support.
  • The pskKey and pskIdentity attributes of the Channel must be set to the same values on each cluster node.
  • The secure attribute of the Channel must be set to true on each cluster node.
  • The securePort attribute of the Receiver must be set.
  • The securePort attribute of each Member must be set to match the associated Receiver.
  • It is recommended that the cluster is configured to use static membership. It is possible to use TLS in combination with dynamic membership (multicast discovery) but the network communication that manages the dynamic membership takes place in the clear. If any nodes (including potentially untrusted nodes) attempt to join a cluster using TLS with dynamic membership without the correct TLS configuration, it will trigger a significant amount of logging until those nodes stop attempting to join the cluster.

The EncryptInterceptor is deprecated and should no longer be used to secure cluster traffic.

Other options for providing a secure, trusted network for use by a Tomcat cluster include:

  • private LAN
  • a Virtual Private Network (VPN)
  • IPSEC

Engine vs Host placement

You can place the <Cluster> element inside either the <Engine> container or the <Host> container.
Placing it in the engine, means that you will support clustering in all virtual hosts of Tomcat, and share the messaging component. When you place the <Cluster> inside the <Engine> element, the cluster will append the host name of each session manager to the managers name so that two contexts with the same name but sitting inside two different hosts will be distinguishable.

Context Attribute Replication

To configure context attribute replication, simply do this by swapping out the context implementation used for your application context.

<Context className="org.apache.catalina.ha.context.ReplicatedContext"/>

This context extends the Tomcat StandardContext so all the options from the base implementation are valid.

Nested Components

Manager:
The session manager element identifies what kind of session manager is used in this cluster implementation. This manager configuration is identical to the one you would use in a regular <Context> configuration.
The default value is the org.apache.catalina.ha.session.DeltaManager that is closely coupled with the SimpleTcpCluster implementation. Other managers like the org.apache.catalina.ha.session.BackupManager are/could be loosely coupled and don't rely on the SimpleTcpCluster for its data replication.

Channel:
The Channel and its sub components are all part of the IO layer for the cluster group, and is a module in it's own that we have nick named "Tribes"
Any configuring and tuning of the network layer, the messaging and the membership logic will be done in the channel and its nested components. You can always find out more about Apache Tribes

Valve:
The Tomcat Cluster implementation uses Tomcat Valves to track when requests enter and exit the servlet container. It uses these valves to be able to make intelligent decisions on when to replicate data, which is always at the end of a request.

Deployer:
The Deployer component is the Tomcat Farm Deployer. It allows you to deploy and undeploy applications cluster wide.

ClusterListener:
ClusterListener's are used to track messages sent and received using the SimpleTcpCluster. If you wish to track messages, you can add a listener here, or you can add a valve to the channel object.

Attributes

SimpleTcpCluster Attributes

Attribute Description
className

The main cluster class, currently only one is available, org.apache.catalina.ha.tcp.SimpleTcpCluster

channelSendOptions

The Tribes channel send options. This option is used for all messages sent through the SimpleTcpCluster.

The value may be specified either as an integer (add values to use multiple flags) or using a comma-separate list of the human-readable option names. Human-readable names are translated to their integer values on startup.

The different values offer a tradeoff between throughput on the sending node and the reliability of replication should the sending or receiving node(s) fail.

The supported values are:

byte_message, byte or 1
The message is a pure byte message and no marshaling or unmarshalling will be performed
use_ack or 2
The message is sent and an ACK is received when the message has been received by the recipient. If no ack is received, the message is not considered successful.
synchronized_ack, sync or 4
Has no effect unless use_ack is set. The message is sent and an ACK is received when the message has been received and processed by the recipient. If no ack is received, the message is not considered successful.
asynchronous, async or 8
The message will be placed on a queue and sent by a separate thread. It is possible for update messages for a session to be processed by the receiving node in a different order to the order in which they were sent.
secure or 16
Not implemented. Has no effect if used.
udp or 32
The message will be sent using UDP instead of TCP.
multicast or 64
Not implemented. Messages will not be sent if used.

The default value is 8 (async).

channelStartOptions

Sets the start and stop flags for the <Channel> object used by the cluster. The default is Channel.DEFAULT which starts all the channel services, such as sender, receiver, membership sender and membership receiver. The following flags are available today:

Channel.DEFAULT = Channel.SND_RX_SEQ (1) |
                  Channel.SND_TX_SEQ (2) |
                  Channel.MBR_RX_SEQ (4) |
                  Channel.MBR_TX_SEQ (8);

When using the static membership service org.apache.catalina.tribes.membership.StaticMembershipService you must ensure that this attribute is configured to use the default value.

heartbeatBackgroundEnabled

Flag whether invoke channel heartbeat at container background thread. Default value is false. Enable this flag don't forget to disable the channel heartbeat thread.

notifyLifecycleListenerOnFailure

Flag whether notify LifecycleListeners if all ClusterListener couldn't accept channel message. Default value is false.