1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
|
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-manager.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The ClusterManager object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>A cluster manager is an extension to Tomcat's session manager interface,
<code>org.apache.catalina.Manager</code>.
A cluster manager must implement the
<code>org.apache.catalina.ha.ClusterManager</code> and is solely responsible
for how the session is replicated.<br/>
There are currently two different managers, the
<code>org.apache.catalina.ha.session.DeltaManager</code> 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 <code>org.apache.catalina.ha.session.BackupManager</code> 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.</p>
</section>
<section name="The <Manager>">
<p>The <code><Manager></code> element defined inside the
<code><Cluster></code> element is the template defined for all web
applications that are marked <code><distributable/></code> in their
<code>web.xml</code> file. However, you can still override the manager
implementation on a per web application basis, by putting the
<code><Manager></code> inside the <code><Context></code> element
either in the <code><a href="context.html">context.xml</a></code> file or the
<code><a href="index.html">server.xml</a></code> file.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
</attribute>
<attribute name="name" required="false">
<b>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
<code>Cluster</code> element to make it unique in the container.</b>
</attribute>
<attribute name="notifyListenersOnReplication" required="false">
Set to <code>true</code> if you wish to have session listeners notified
when session attributes are being replicated or removed across Tomcat
nodes in the cluster.
</attribute>
<attribute name="processExpiresFrequency" required="false">
<p>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.
</p>
</attribute>
<attribute name="secureRandomClass" required="false">
<p>Name of the Java class that extends
<code>java.security.SecureRandom</code> to use to generate session IDs.
If not specified, the default value is
<code>java.security.SecureRandom</code>.</p>
</attribute>
<attribute name="secureRandomProvider" required="false">
<p>Name of the provider to use to create the
<code>java.security.SecureRandom</code> 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.</p>
</attribute>
<attribute name="secureRandomAlgorithm" required="false">
<p>Name of the algorithm to use to create the
<code>java.security.SecureRandom</code> 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.</p>
</attribute>
<attribute name="recordAllActions" required="false">
<p>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 <code>false</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.ha.session.DeltaManager Attributes">
<attributes>
<attribute name="expireSessionsOnShutdown" required="false">
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 <code>true</code>.
Default value is <code>false</code>.
</attribute>
<attribute name="maxActiveSessions" required="false">
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.
</attribute>
<attribute name="notifySessionListenersOnReplication" required="false">
Set to <code>true</code> if you wish to have session listeners notified
when sessions are created and expired across Tomcat nodes in the
cluster.
</attribute>
<attribute name="notifyContainerListenersOnReplication" required="false">
Set to <code>true</code> if you wish to have container listeners notified
across Tomcat nodes in the cluster.
</attribute>
<attribute name="persistAuthenticationNotes" required="false">
<p>Should authentication notes (used during FORM authentication) be
included when sessions are replicated? If <code>true</code>, the
session's authentication notes (used during FORM authentication) are
replicated so that an in progress FORM authentication can continue if
failover occurs during FORM authentication. If not specified, the
default value of <code>false</code> will be used.</p>
<p>Please note that all nodes must be upgraded to at least 9.0.66 (the
version where this feature was introduced) before this feature is
enabled else session replication may fail.</p>
<p>This attribute has been removed for Tomcat 10.1.x onwards which
always replicates FORM authenticaton notes.</p>
</attribute>
<attribute name="stateTransferTimeout" required="false">
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 <code>60</code> seconds.
</attribute>
<attribute name="sendAllSessions" required="false">
Flag whether send sessions as split blocks.
If set to <code>true</code>, send all sessions as one big block.
If set to <code>false</code>, send sessions as split blocks.
Default value is <code>true</code>.
</attribute>
<attribute name="sendAllSessionsSize" required="false">
The number of sessions in a session block message. This value is
effective only when <code>sendAllSessions</code> is <code>false</code>.
Default is <code>1000</code>.
</attribute>
<attribute name="sendAllSessionsWaitTime" required="false">
Wait time between sending of session block messages. This value is
effective only when <code>sendAllSessions</code> is <code>false</code>.
Default is <code>2000</code> milliseconds.
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>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 <code>null</code>, 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 <code>(userName|sessionHistory)</code> will only replicate the
two session attributes named <code>userName</code> and
<code>sessionHistory</code>. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>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 <code>null</code>, 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
<code>null</code> will be used unless a <code>SecurityManager</code> is
enabled in which case the default will be
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
</attribute>
<attribute name="stateTimestampDrop" required="false">
When this node sends a <code>GET_ALL_SESSIONS</code> message to other
node, all session messages that are received as a response are queued.
If this attribute is set to <code>true</code>, the received session
messages (except any <code>GET_ALL_SESSIONS</code> sent by other nodes)
are filtered by their timestamp. A message is dropped if it is not a
<code>GET_ALL_SESSIONS</code> message and its timestamp is earlier than
the timestamp of our <code>GET_ALL_SESSIONS</code> message.
If set to <code>false</code>, all queued session messages are handled.
Default is <code>true</code>.
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<p>If <strong>sessionAttributeNameFilter</strong> or
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
attribute, should this be logged at <code>WARN</code> level? If
<code>WARN</code> level logging is disabled then it will be logged at
<code>DEBUG</code>. The default value of this attribute is
<code>false</code> unless a <code>SecurityManager</code> is enabled in
which case the default will be <code>true</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.ha.session.BackupManager Attributes">
<attributes>
<attribute name="mapSendOptions" required="false">
The backup manager uses a replicated map, this map is sending and
receiving messages. You can setup the flag for how this map is sending
messages, the default value is <code>6</code>(synchronous).<br/>
Note that if you use asynchronous messaging 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.
</attribute>
<attribute name="maxActiveSessions" required="false">
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.
</attribute>
<attribute name="persistAuthenticationNotes" required="false">
<p>Should authentication notes (used during FORM authentication) be
included when sessions are replicated? If <code>true</code>, the
session's authentication notes (used during FORM authentication) are
replicated so that an in progress FORM authentication can continue if
failover occurs during FORM authentication. If not specified, the
default value of <code>false</code> will be used.</p>
<p>Please note that all nodes must be upgraded to at least 9.0.66 (the
version where this feature was introduced) before this feature is
enabled else session replication may fail.</p>
<p>This attribute has been removed for Tomcat 10.1.x onwards which
always replicates FORM authenticaton notes.</p>
</attribute>
<attribute name="rpcTimeout" required="false">
Timeout for RPC message used for broadcast and transfer state from
another map.
Default value is <code>15000</code> milliseconds.
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>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 <code>null</code>, 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 <code>(userName|sessionHistory)</code> will only replicate the
two session attributes named <code>userName</code> and
<code>sessionHistory</code>. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>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 <code>null</code>, 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
<code>null</code> will be used unless a <code>SecurityManager</code> is
enabled in which case the default will be
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
</attribute>
<attribute name="terminateOnStartFailure" required="false">
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 <code>false</code> .
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<p>If <strong>sessionAttributeNameFilter</strong> or
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
attribute, should this be logged at <code>WARN</code> level? If
<code>WARN</code> level logging is disabled then it will be logged at
<code>DEBUG</code>. The default value of this attribute is
<code>false</code> unless a <code>SecurityManager</code> is enabled in
which case the default will be <code>true</code>.</p>
</attribute>
<attribute name="accessTimeout" required="false">
The timeout for a ping message. If a remote map does not respond within
this timeout period, its regarded as disappeared.
Default value is <code>5000</code> milliseconds.
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<h3>All Manager Implementations</h3>
<p>All Manager implementations allow nesting of a
<strong><SessionIdGenerator></strong> element. It defines
the behavior of session id generation. All implementations
of the <a href="sessionidgenerator.html">SessionIdGenerator</a> allow the
following attributes:
</p>
<attributes>
<attribute name="sessionIdLength" required="false">
<p>The length of the session ID may be changed with the
<strong>sessionIdLength</strong> attribute.
</p>
</attribute>
</attributes>
</section>
</body>
</document>
|
