## The ClusterManager object

### Table of Contents

- Introduction
- The <Manager>
- Attributes
  1. Common Attributes
  2. org.apache.catalina.ha.session.DeltaManager Attributes
  3. org.apache.catalina.ha.session.BackupManager Attributes
- Nested Components

### Introduction

A cluster manager is an extension to Tomcat's session manager interface, `org.apache.catalina.Manager`. A cluster manager must implement the `org.apache.catalina.ha.ClusterManager` and is solely responsible for how the session is replicated.
There are currently two different managers, the `org.apache.catalina.ha.session.DeltaManager` replicates deltas of session data to all members in the cluster. This implementation is proven and works very well, but has a limitation as it requires the cluster members to be homogeneous, all nodes must deploy the same applications and be exact replicas. The `org.apache.catalina.ha.session.BackupManager` also replicates deltas but only to one backup node. The location of the backup node is known to all nodes in the cluster. It also supports heterogeneous deployments, so the manager knows at what locations the web application is deployed.

### The <Manager>

The `<Manager>` element defined inside the `<Cluster>` element is the template defined for all web applications that are marked `<distributable/>` in their `web.xml` file. However, you can still override the manager implementation on a per web application basis, by putting the `<Manager>` inside the `<Context>` element either in the `context.xml` file or the `server.xml` file.

### Attributes

#### Common Attributes

Attribute | Description
--- | ---
`className` |
`name` | The name of this cluster manager, the name is used to identify a session manager on a node. The name might get modified by the `Cluster` element to make it unique in the container.
`notifyListenersOnReplication` | Set to `true` if you wish to have session listeners notified when session attributes are being replicated or removed across Tomcat nodes in the cluster.
`processExpiresFrequency` | Frequency of the session expiration, and related manager operations. Manager operations will be done once for the specified amount of backgroundProcess calls (i.e., the lower the amount, the more often the checks will occur). The minimum value is 1, and the default value is 6.
`secureRandomClass` | Name of the Java class that extends `java.security.SecureRandom` to use to generate session IDs. If not specified, the default value is `java.security.SecureRandom`.
`secureRandomProvider` | Name of the provider to use to create the `java.security.SecureRandom` instances that generate session IDs. If an invalid algorithm and/or provider is specified, the Manager will use the platform default provider and the default algorithm. If not specified, the platform default provider will be used.

`secureRandomAlgorithm`

Name of the algorithm to use to create the `java.security.SecureRandom` instances that generate session IDs. If an invalid algorithm and/or provider is specified, the Manager will use the platform default provider and the default algorithm. If not specified, the default algorithm of SHA1PRNG will be used. If the default algorithm is not supported, the platform default will be used. To specify that the platform default should be used, do not set the secureRandomProvider attribute and set this attribute to the empty string.

`recordAllActions` | Flag whether send all actions for session across Tomcat cluster nodes. If set to false, if already done something to the same attribute, make sure don't send multiple actions across Tomcat cluster nodes. In that case, sends only the actions that have been added at last. Default is `false`.

#### org.apache.catalina.ha.session.DeltaManager Attributes

Attribute | Description
--- | ---
`enableStatistics` | Tracks statistics for the session and events of the cluster. Default value is `true`.
`expireSessionsOnShutdown` | When a web application is being shutdown, Tomcat issues an expire call to each session to notify all the listeners. If you wish for all sessions to expire on all nodes when a shutdown occurs on one node, set this value to `true`. Default value is `false`.
`maxActiveSessions` | The maximum number of active sessions that will be created by this Manager, or -1 (the default) for no limit. For this manager, all sessions are counted as active sessions irrespective if whether or not the current node is the primary node for the session.
`notifySessionListenersOnReplication` | Set to `true` if you wish to have session listeners notified when sessions are created and expired across Tomcat nodes in the cluster.
`notifyContainerListenersOnReplication` | Set to `true` if you wish to have container listeners notified across Tomcat nodes in the cluster.
`stateTransferTimeout` | The time in seconds to wait for a session state transfer to complete from another node when a node is starting up. Default value is `60` seconds.
`sendAllSessions` | Flag whether send sessions as split blocks. If set to `true`, send all sessions as one big block. If set to `false`, send sessions as split blocks. Default value is `true`.
`sendAllSessionsSize` | The number of sessions in a session block message. This value is effective only when `sendAllSessions` is `false`. Default is `1000`.
`sendAllSessionsWaitTime` | Wait time between sending of session block messages. This value is effective only when `sendAllSessions` is `false`. Default is `2000` milliseconds.

`sessionAttributeNameFilter`

A regular expression used to filter which session attributes will be replicated. An attribute will only be replicated if its name matches this pattern. If the pattern is zero length or `null`, all attributes are eligible for replication. The pattern is anchored so the session attribute name must fully match the pattern. As an example, the value `(userName|sessionHistory)` will only replicate the two session attributes named `userName` and `sessionHistory`. If not specified, the default value of `null` will be used.

`sessionAttributeValueClassNameFilter`

A regular expression used to filter which session attributes will be replicated. An attribute will only be replicated if the implementation class name of the value matches this pattern. If the pattern is zero length or `null`, all attributes are eligible for replication. The pattern is anchored so the fully qualified class name must fully match the pattern. If not specified, the default value of `null` will be used unless a `SecurityManager` is enabled in which case the default will be `java\\.lang\\.(?:Boolean|Integer|Long|Number|String)`.

`stateTimestampDrop`

When this node sends a `GET_ALL_SESSIONS` message to other node, all session messages that are received as a response are queued. If this attribute is set to `true`, the received session messages (except any `GET_ALL_SESSIONS` sent by other nodes) are filtered by their timestamp. A message is dropped if it is not a `GET_ALL_SESSIONS` message and its timestamp is earlier than the timestamp of our `GET_ALL_SESSIONS` message. If set to `false`, all queued session messages are handled. Default is `true`.

`warnOnSessionAttributeFilterFailure` | If sessionAttributeNameFilter or sessionAttributeValueClassNameFilter blocks an attribute, should this be logged at `WARN` level? If `WARN` level logging is disabled then it will be logged at `DEBUG`. The default value of this attribute is `false` unless a `SecurityManager` is enabled in which case the default will be `true`.

#### org.apache.catalina.ha.session.BackupManager Attributes

Attribute | Description
--- | ---

`mapSendOptions`

The backup manager uses a replicated map. This map sends and receives messages internally. You can configure the flag that controls how this map sends messages.

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 `6` (`use_ack` with `sync`).

`maxActiveSessions` | The maximum number of active sessions that will be created by this Manager, or -1 (the default) for no limit. For this manager, only sessions where the current node is the primary node for the session are considered active sessions.
`rpcTimeout` | Timeout for RPC message used for broadcast and transfer state from another map. Default value is `15000` milliseconds.

`sessionAttributeNameFilter`

A regular expression used to filter which session attributes will be replicated. An attribute will only be replicated if its name matches this pattern. If the pattern is zero length or `null`, all attributes are eligible for replication. The pattern is anchored so the session attribute name must fully match the pattern. As an example, the value `(userName|sessionHistory)` will only replicate the two session attributes named `userName` and `sessionHistory`. If not specified, the default value of `null` will be used.

`sessionAttributeValueClassNameFilter`

A regular expression used to filter which session attributes will be replicated. An attribute will only be replicated if the implementation class name of the value matches this pattern. If the pattern is zero length or `null`, all attributes are eligible for replication. The pattern is anchored so the fully qualified class name must fully match the pattern. If not specified, the default value of `null` will be used unless a `SecurityManager` is enabled in which case the default will be `java\\.lang\\.(?:Boolean|Integer|Long|Number|String)`.

`terminateOnStartFailure` | Set to true if you wish to terminate replication map when replication map fails to start. If replication map is terminated, associated context will fail to start. If you set this attribute to false, replication map does not end. It will try to join the map membership in the heartbeat. Default value is `false` .
`warnOnSessionAttributeFilterFailure` | If sessionAttributeNameFilter or sessionAttributeValueClassNameFilter blocks an attribute, should this be logged at `WARN` level? If `WARN` level logging is disabled then it will be logged at `DEBUG`. The default value of this attribute is `false` unless a `SecurityManager` is enabled in which case the default will be `true`.
`accessTimeout` | The timeout for a ping message. If a remote map does not respond within this timeout period, its regarded as disappeared. Default value is `5000` milliseconds.

### Nested Components

### All Manager Implementations

All Manager implementations allow nesting of a <SessionIdGenerator> element. It defines the behavior of session id generation. All implementations of the SessionIdGenerator allow the following attributes:

Attribute | Description
--- | ---
`sessionIdLength` | The length of the session ID may be changed with the sessionIdLength attribute.