The Cluster Channel object

Table of Contents

Introduction

The cluster channel is the main component of a small framework we've nicknamed Apache Tribes.
The channel manages a set of sub components and together they create a group communication framework.
This framework is then used internally by the components that need to send messages between different Tomcat instances.
A few examples of these components would be the SimpleTcpCluster that does the messaging for the DeltaManager, or the BackupManager that uses a different replication strategy. The ReplicatedContext object does also use the channel object to communicate context attribute changes.

Nested Components

Channel/Membership:
The Membership component is responsible for auto discovering new nodes in the cluster and also to provide for notifications for any nodes that have not responded with a heartbeat. The default implementation uses multicast.
In the membership component you configure how your nodes, aka. members, are to be discovered and/or divided up. You can always find out more about Apache Tribes

Channel/Sender:
The Sender component manages all outbound connections and data messages that are sent over the network from one node to another. This component allows messages to be sent in parallel. The default implementation uses TCP client sockets, and socket tuning for outgoing messages are configured here.
You can always find out more about Apache Tribes

Channel/Sender/Transport:
The Transport component is the bottom IO layer for the sender component. The default implementation uses non-blocking TCP client sockets.
You can always find out more about Apache Tribes

Channel/Receiver:
The receiver component listens for messages from other nodes. Here you will configure the cluster thread pool, as it will dispatch incoming messages to a thread pool for faster processing. The default implementation uses non-blocking TCP server sockets.
You can always find out more about Apache Tribes

TLS pre-shared key support may be configured on the Channel. OpenSSL FFM is preferred when available, followed by Tomcat Native. JSSE is not used for Tribes TLS. When TLS is enabled, cluster traffic will use blocking socket I/O internally.

Channel/Interceptor:
The channel will send messages through an interceptor stack. Because of this, you have the ability to customize the way messages are sent and received, and even how membership is handled.
You can always find out more about Apache Tribes

Attributes

Common Attributes

Attribute Description
className The default value here is org.apache.catalina.tribes.group.GroupChannel and is currently the only implementation available.

org.apache.catalina.tribes.group.GroupChannel Attributes

Attribute Description
heartbeat Flag whether the channel manages its own heartbeat. If set to true, the channel start a local thread for the heart beat. If set this flag to false, you must set SimpleTcpCluster#heartbeatBackgroundEnabled to true. default value is true.
heartbeatSleeptime If heartbeat == true, specifies the interval of heartbeat thread in milliseconds. The default is 5000 (5 seconds).
jmxEnabled Flag whether the channel components register with JMX or not. The default value is true.
jmxDomain if jmxEnabled set to true, specifies the jmx domain which this channel should be registered. The ClusterChannel is used as the default value.
jmxPrefix if jmxEnabled set to true, specifies the jmx prefix which will be used with channel ObjectName.
optionCheck If set to true, the GroupChannel will check the option flags that each interceptor is using. Reports an error if two interceptor share the same flag. The default is false.
pskDigest The message digest algorithm associated with the pre-shared key for TLS 1.3, either SHA256 or SHA384. The default is SHA256. This attribute is ignored for TLS 1.2.
pskIdentity The TLS pre-shared key identity. This must be configured together with pskKey to enable TLS.
pskKey The TLS pre-shared key encoded as hexadecimal characters. This key is the secret that the security of the TLS cluster communication rests on. If this key is compromised, the security of the cluster is compromised. The key is not exposed through JMX. The key should be no longer than 512 bytes for TLS 1.2. For TLS 1.3, it must be no longer than 48 bytes. The key must be sufficiently random for the cipher used (the OpenSSL default for PSK on the system where Tomcat is running). If the value is truely random then 32 bytes are sufficient for a 256-bit cipher suite. The key must be configured together with pskIdentity.
pskProtocol The TLS protocol to use with the pre-shared key. The permitted values are TLSv1.2 and TLSv1.3. The default is TLSv1.3.
secure If true, the SEND_OPTIONS_SECURE flag is added to every message. Both pskIdentity and pskKey must also be configued for TLS to be enabled. Channel startup fails if TLS is unavailable. The default is false.