Apache Tomcat 9 Configuration Reference (9.0.120) - The Channel Interceptor object

## The Channel Interceptor object

### Table of Contents

- Introduction
- Ordering
- Available Interceptors
- Static Membership
- Attributes
  1. Common Attributes
  2. org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor Attributes
  3. org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor Attributes
  4. org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor Attributes
  5. org.apache.catalina.tribes.group.interceptors.TcpFailureDetector Attributes
  6. org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor Attributes
  7. org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor Attributes
  8. org.apache.catalina.tribes.group.interceptors.EncryptInterceptor Attributes
- Nested Components
  1. StaticMember Attributes

### Introduction

Apache Tribes supports an interceptor architecture to intercept both messages and membership notifications. This architecture allows decoupling of logic and opens the way for some very useful feature add-ons.

### Ordering

The order of interceptors is important. The order in which the interceptors are defined in server.xml is the order in which the interceptors appear in the channel stack. Think of it as a linked list, with the head being the first most interceptor and the tail the last.

When sending a message, the message will pass through the interceptors in order (i.e. the order they are defined in server.xml). When receiving a message, the messages will pass through the interceptors in reverse order.

### Available Interceptors

Tribes has been designed as a general clustering solutiuon. Not all interceptors are expected to be of use in Tomcat cluster configurations. The interceptors expected to be of use in Tomcat clusters are described in more detail in the following sections. They are:

- `org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor`
- `org.apache.catalina.tribes.group.interceptors.EncryptInterceptor`
- `org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor`
- `org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor`
- `org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor`
- `org.apache.catalina.tribes.group.interceptors.TcpFailureDetector`
- `org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor`
- `org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor`

The interceptors not expected to be of use in Tomcat clusters are described in the Javadoc for each interceptor. They are:

- `org.apache.catalina.tribes.group.interceptors.NonBlockingCoordinator`
- `org.apache.catalina.tribes.group.interceptors.OrderInterceptor`
- `org.apache.catalina.tribes.group.interceptors.SimpleCoordinator`
- `org.apache.catalina.tribes.group.interceptors.TwoPhaseCommitInterceptor`
- `org.apache.catalina.tribes.group.interceptors.GzipInterceptor`

### Static Membership

In addition to dynamic discovery, Apache Tribes also supports static membership, with membership verification. To achieve this add the `org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor` after the `org.apache.catalina.tribes.group.interceptors.TcpFailureDetector` interceptor. Inside the `StaticMembershipInterceptor` you can add the static members you wish to have. The `TcpFailureDetector` will do a health check on the static members,and also monitor them for crashes so they will have the same level of notification mechanism as the members that are automatically discovered.

         <Interceptor className="org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor">
           <LocalMember className="org.apache.catalina.tribes.membership.StaticMember"
                      domain="staging-cluster"
                      uniqueId="{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,1}"/>
           <Member className="org.apache.catalina.tribes.membership.StaticMember"
                      port="5678"
                      securePort="-1"
                      host="tomcat01.mydomain.com"
                      domain="staging-cluster"
                      uniqueId="{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"/>
         </Interceptor>

### Attributes

#### Common Attributes

Attribute | Description
--- | ---
`className` | Required, as there is no default
`optionFlag` | If you want the interceptor to trigger on certain message depending on the message's option flag, you can setup the interceptors flag here. The default value is `0`, meaning this interceptor will trigger on all messages.

#### org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor Attributes

Attribute | Description
--- | ---
`domain` | The logical cluster domain that this Interceptor accepts. Two different type of values are possible: 1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes using ISO-8859-1 encoding. 2. byte array in string form, for example {216,123,12,3}
`logInterval` | This value indicates the interval for logging for messages from different domains. The default is 100, which means that to log per 100 messages.

#### org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor Attributes

Attribute | Description
--- | ---
`expire` | How long do we keep the fragments in memory and wait for the rest to arrive. The default is 60000 ms.
`maxSize` | The maximum message size in bytes. If the message size exceeds this value, this interceptor fragments the message and sends them. If it is less than this value, this interceptor does not fragment the message and sent in as one message. The default is 1024*100.

#### org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor Attributes

Attribute | Description
--- | ---
`optionFlag` | The default and hard coded value is `8 (org.apache.catalina.tribes.Channel.SEND_OPTIONS_ASYNCHRONOUS)`. The dispatcher will trigger on this value only, as it is predefined by Tribes.
`alwaysSend` | What behavior should be executed when the dispatch queue is full. If `true` (default), then the message is is sent synchronously, if `false` an error is thrown.
`maxQueueSize` | Size in bytes of the dispatch queue, the default value is `1024*1024*64 (64 MiB)` sets the maximum queue size for the dispatch queue if the queue fills up, one can trigger the behavior, if `alwaysSend` is set to true, the message will be sent synchronously if the flag is false, an error is thrown
`maxThreads` | The maximum number of threads in this pool, default is 10.
`maxSpareThreads` | The number of threads to keep in the pool, default is 2.
`keepAliveTime` | Maximum number of milliseconds of until Idle thread terminates. Default value is 5000(5 seconds).

#### org.apache.catalina.tribes.group.interceptors.TcpFailureDetector Attributes

Attribute | Description
--- | ---
`connectTimeout` | Specifies the timeout, in milliseconds, to use when attempting a TCP connection to the suspect node. Default is 1000.
`performSendTest` | If true is set, send a test message to the suspect node. Default is true.
`performReadTest` | If true is set, read the response of the test message that sent. Default is false. Note: if `performSendTest` is false, this attribute will have no effect.
`readTestTimeout` | Specifies the timeout, in milliseconds, to use when performing a read test to the suspicious node. Default is 5000.
`removeSuspectsTimeout` | The maximum time(in seconds) for remove from removeSuspects. Member of removeSuspects will be automatically removed after removeSuspectsTimeout. If a negative value specified, the removeSuspects members never be removed until disappeared really. If the attribute is not provided, a default of 300 seconds (5 minutes) is used.

#### org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor Attributes

Attribute | Description
--- | ---
`interval` | If useThread == true, defines the interval of sending a ping message. default is 1000 ms.
`useThread` | Flag of whether to start a thread for sending a ping message. If set to true, this interceptor will start a local thread for sending a ping message. if set to false, channel heartbeat will send a ping message. default is false.

#### org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor Attributes

Attribute | Description
--- | ---
`interval` | Defines the interval in number of messages when we are to report the throughput statistics. The report is logged to the `org.apache.juli.logging.LogFactory.getLog(ThroughputInterceptor.class)` logger under the `INFO` level. Default value is to report every `10000` messages.

#### org.apache.catalina.tribes.group.interceptors.EncryptInterceptor Attributes

The EncryptInterceptor adds encryption to the channel messages carrying session data between nodes. For the EncryptInterceptor to be effective it MUST be the final interceptor (ignoring the TcpFailureDetector - see below) in the set of interceptors for any given channel. Added in Tomcat 9.0.13.

If using the `TcpFailureDetector`, the `EncryptInterceptor` must be inserted into the interceptor chain before the `TcpFailureDetector`. This is because when validating cluster members, `TcpFailureDetector` writes channel data directly to the other members without using the remainder of the interceptor chain, but on the receiving side, the message still goes through the chain (in reverse). Because of this asymmetry, the `EncryptInterceptor` must execute before the `TcpFailureDetector` on the sender and after it on the receiver, otherwise message corruption will occur.

The EncryptInterceptor uses the timestamp of the message to provide replay protection. For this to be effective, clock skew between cluster nodes should be minimised. If not, it is likely a high proportion of valid messages will be rejected.

Attribute | Description
--- | ---
`encryptionAlgorithm` | The encryption algorithm to be used, including the mode and padding. Please see https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html for the standard JCA names that can be used. Algorithms from other JCA providers are also supported. The EncryptInterceptor currently supports the following standard block-cipher modes: CBC, CFB, OFB and GCM. Of these, it is recommended that GCM is always used. The length of the key will specify the flavor of the encryption algorithm to be used, if applicable (e.g. AES-128 versus AES-256). The default algorithm is `AES/CBC/PKCS5Padding` for backwards compatability but it is recommended that `AES/GCM/NoPadding` is used.
`encryptionKey` | The key to be used with the encryption algorithm. The key should be specified as hex-encoded bytes of the appropriate length for the algorithm (e.g. 16 bytes / 32 characters / 128 bits for AES-128, 32 bytes / 64 characters / 256 bits for AES-256, etc.).
`replayWindowTime` | Messages with a timestamp before the current time less this window or after the current time plus this window will be rejected. This window needs to account for clock skew across the cluster as well as the expected maximum delay between messages being sent and received. Specified in milliseconds. If not specified, the default value of 10000 (10 seconds) will be used.
`replayWindowMessageCount` | The number of past messages for which the nonces will be tracked to prevent replay attacks. Messages with a nonce that has already been tracked will be rejected. If not specified, the default value of 8192 will be used. If messages are received at a high rate, it is possible that a nonce will be removed from the list of tracked nonces before `replayWindowTime` milliseconds have elapsed. If that happens, any message with a timestamp older than the last nonce evicted from the list of tracked nonces will also be rejected.

### Nested Components

#### StaticMember Attributes

LocalMember:
Static member that is the local member of the static cluster group.

Attribute | Description
--- | ---
`className` | Only one implementation available:`org.apache.catalina.tribes.membership.StaticMember`
`port` | There is no need to set. The value of this attribute inherits from the cluster receiver setting.
`securePort` | There is no need to set. The value of this attribute inherits from the cluster receiver setting.
`host` | There is no need to set. The value of this attribute inherits from the cluster receiver setting.
`domain` | The logical cluster domain for that this static member listens for cluster messages. Two different type of values are possible: 1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes using ISO-8859-1 encoding. 2. byte array in string form, for example {216,123,12,3}
`uniqueId` | A universally uniqueId for this static member. The values must be 16 bytes in the following form: 1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}

Member:
Static member that add to the static cluster group.

Attribute | Description
--- | ---
`className` | Only one implementation available:`org.apache.catalina.tribes.membership.StaticMember`
`port` | The port that this static member listens to for cluster messages
`securePort` | The secure port this static member listens to for encrypted cluster messages default value is `-1`, this value means the member is not listening on a secure port
`host` | The host (or network interface) that this static member listens for cluster messages. Three different type of values are possible: 1. IP address in the form of "216.123.1.23" 2. Hostnames like "tomcat01.mydomain.com" or "tomcat01" as long as they resolve correctly 3. byte array in string form, for example {216,123,12,3}
`domain` | The logical cluster domain for that this static member listens for cluster messages. Two different type of values are possible: 1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes using ISO-8859-1 encoding. 2. byte array in string form, for example {216,123,12,3}
`uniqueId` | A universally uniqueId for this static member. The values must be 16 bytes in the following form: 1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}