294 lines
16 KiB
XML
294 lines
16 KiB
XML
<?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="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="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>
|