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

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:

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.

Deprecated configuration options

Deprecated settings: In the previous version of Tomcat you were able to control session manager settings using manager.<property>=value. This has been discontinued, as the way it was written interferes with the ability to support multiple different manager classes under one cluster implementation, as the same properties might have the different effect on different managers.

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, default is 8.
This option is used to set the flag that all messages sent through the SimpleTcpCluster uses. The flag decides how the messages are sent, and is a simple logical OR.

int options = Channel.SEND_OPTIONS_ASYNCHRONOUS |
              Channel.SEND_OPTIONS_SYNCHRONIZED_ACK |
              Channel.SEND_OPTIONS_USE_ACK;

Some of the values are:
Channel.SEND_OPTIONS_SYNCHRONIZED_ACK = 0x0004
Channel.SEND_OPTIONS_ASYNCHRONOUS = 0x0008
Channel.SEND_OPTIONS_USE_ACK = 0x0002
So to use ACK and ASYNC messaging, the flag would be 10 (8+2)
Note that if you use ASYNC messaging it is possible for update messages for a session to be processed by the receiving nodes in a different order to the order in which they were sent.

The various channelSendOptions values offer a tradeoff between throughput on the sending node and the reliability of replication should the sending or receiving node(s) fail. Here are some common options. "Message" could be any message sent between nodes, but only session-change messages are considered, here.

channelSendOptions="8" / channelSendOptions="async" As far as the sender is concerned, the message is "sent" as soon as it has been placed in the queue on the sender for transmission to the other nodes. The message may not reach any or all of the recipient nodes and may not be successfully processed on any nodes that it does reach. This option offers the highest throughput on the sender but the least reliability, as the triggering request will complete without any knowledge of the success/failure of the session replication.

channelSendOptions="2" / channelSendOptions="use_ack" The sender will block the completion of the current request until all of the receiving nodes have acknowledged that they have received the message, but have not necessarily processed that message. This option will result in lower throughput on the sending node, because the message must be transmitted and the acknowledgement received, but the reliability is greater than the asynchronous model.

channelSendOptions="6" / channelSendOptions="sync,use_ack" The sender will block the completion of the current request until all of the receiving nodes have acknowledged that they have received and processed the message. This option will have the lowest throughput (of these three) but the greatest reliability.

You may also set these options as a comma separated string, e.g. "async, multicast", which will be translated into Channel.SEND_OPTIONS_ASYNCHRONOUS | Channel.SEND_OPTIONS_MULTICAST
The valid option names are "asynchronous" (alias "async"), "byte_message" (alias "byte") , "multicast", "secure", "synchronized_ack" (alias "sync"), "udp", "use_ack"

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);
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.