Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / fd5ee81fec460cbe9ad65f300b0faf1bf03c19bc / . / tomcat-uidm / webapps / docs / cluster-howto.html
blob: 7fa0ec10664de3b3fe592b153e76ce04f90bd9ac [file] [log] [blame]
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 (6.0.39) - Clustering/Session Replication HOW-TO</title><meta name="author" content="Filip Hanik"><meta name="author" content="Peter Rossbach"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
5 The Apache Tomcat Servlet/JSP Container
6 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.39, Jan 27 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Apache Tomcat 6.0</h1><h2>Clustering/Session Replication HOW-TO</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Important Note"><!--()--></a><a name="Important_Note"><strong>Important Note</strong></a></font></td></tr><tr><td><blockquote>
7<p><b>You can also check the <a href="config/cluster.html">configuration reference documentation.</a></b>
8</p>
9</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
10<ul><li><a href="#For_the_impatient">For the impatient</a></li><li><a href="#Cluster_Basics">Cluster Basics</a></li><li><a href="#Overview">Overview</a></li><li><a href="#Cluster_Information">Cluster Information</a></li><li><a href="#Bind_session_after_crash_to_failover_node">Bind session after crash to failover node</a></li><li><a href="#Configuration_Example">Configuration Example</a></li><li><a href="#Cluster_Architecture">Cluster Architecture</a></li><li><a href="#How_it_Works">How it Works</a></li><li><a href="#FAQ">FAQ</a></li></ul>
11</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="For the impatient"><!--()--></a><a name="For_the_impatient"><strong>For the impatient</strong></a></font></td></tr><tr><td><blockquote>
12 <p>
13 Simply add <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>&lt;Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/&gt;</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
14 to your <code>&lt;Engine&gt;</code> or your <code>&lt;Host&gt;</code> element to enable clustering.
15 </p>
16 <p>
17 Using the above configuration will enable all-to-all session replication
18 using the <code>DeltaManager</code> to replicate session deltas. By all-to-all we mean that the session gets replicated to all the other
19 nodes in the cluster. This works great for smaller cluster but we don't recommend it for larger clusters(a lot of tomcat nodes).
20 Also when using the delta manager it will replicate to all nodes, even nodes that don't have the application deployed.<br>
21 To get around this problem, you'll want to use the BackupManager. This manager only replicates the session data to one backup
22 node, and only to nodes that have the application deployed. Downside of the BackupManager: not quite as battle tested as the delta manager.
23 <br>
24 Here are some of the important default values:<br>
25 1. Multicast address is 228.0.0.4<br>
26 2. Multicast port is 45564 (the port and the address together determine cluster membership.<br>
27 3. The IP broadcasted is <code>java.net.InetAddress.getLocalHost().getHostAddress()</code> (make sure you don't broadcast 127.0.0.1, this is a common error)<br>
28 4. The TCP port listening for replication messages is the first available server socket in range <code>4000-4100</code><br>
29 5. Two listeners are configured <code>ClusterSessionListener</code> and <code>JvmRouteSessionIDBinderListener</code><br>
30 6. Two interceptors are configured <code>TcpFailureDetector</code> and <code>MessageDispatch15Interceptor</code><br>
31 The following is the default cluster configuration:<br>
32 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
33 &lt;Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
34 channelSendOptions="8"&gt;
35
36 &lt;Manager className="org.apache.catalina.ha.session.DeltaManager"
37 expireSessionsOnShutdown="false"
38 notifyListenersOnReplication="true"/&gt;
39
40 &lt;Channel className="org.apache.catalina.tribes.group.GroupChannel"&gt;
41 &lt;Membership className="org.apache.catalina.tribes.membership.McastService"
42 address="228.0.0.4"
43 port="45564"
44 frequency="500"
45 dropTime="3000"/&gt;
46 &lt;Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
47 address="auto"
48 port="4000"
49 autoBind="100"
50 selectorTimeout="5000"
51 maxThreads="6"/&gt;
52
53 &lt;Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"&gt;
54 &lt;Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/&gt;
55 &lt;/Sender&gt;
56 &lt;Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/&gt;
57 &lt;Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/&gt;
58 &lt;/Channel&gt;
59
60 &lt;Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
61 filter=""/&gt;
62 &lt;Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/&gt;
63
64 &lt;Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
65 tempDir="/tmp/war-temp/"
66 deployDir="/tmp/war-deploy/"
67 watchDir="/tmp/war-listen/"
68 watchEnabled="false"/&gt;
69
70 &lt;ClusterListener className="org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener"/&gt;
71 &lt;ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/&gt;
72 &lt;/Cluster&gt;
73 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
74 </p>
75 <p>Will cover this section in more detail later in this document.</p>
76</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Cluster Basics"><!--()--></a><a name="Cluster_Basics"><strong>Cluster Basics</strong></a></font></td></tr><tr><td><blockquote>
77
78<p>To run session replication in your Tomcat 6.0 container, the following steps
79should be completed:</p>
80<ul>
81 <li>All your session attributes must implement <code>java.io.Serializable</code></li>
82 <li>Uncomment the <code>Cluster</code> element in server.xml</li>
83 <li>If you have defined custom cluster valves, make sure you have the <code>ReplicationValve</code> defined as well under the Cluster element in server.xml</li>
84 <li>If your Tomcat instances are running on the same machine, make sure the <code>tcpListenPort</code>
85 attribute is unique for each instance, in most cases Tomcat is smart enough to resolve this on it's own by autodetecting available ports in the range 4000-4100</li>
86 <li>Make sure your <code>web.xml</code> has the
87 <code>&lt;distributable/&gt;</code> element</li>
88 <li>If you are using mod_jk, make sure that jvmRoute attribute is set at your Engine <code>&lt;Engine name="Catalina" jvmRoute="node01" &gt;</code>
89 and that the jvmRoute attribute value matches your worker name in workers.properties</li>
90 <li>Make sure that all nodes have the same time and sync with NTP service!</li>
91 <li>Make sure that your loadbalancer is configured for sticky session mode.</li>
92</ul>
93<p>Load balancing can be achieved through many techniques, as seen in the
94<a href="balancer-howto.html">Load Balancing</a> chapter.</p>
95<p>Note: Remember that your session state is tracked by a cookie, so your URL must look the same from the out
96 side otherwise, a new session will be created.</p>
97<p>Note: Clustering support currently requires the JDK version 1.5 or later.</p>
98<p>The Cluster module uses the Tomcat JULI logging framework, so you can configure logging
99 through the regular logging.properties file. To track messages, you can enable logging on the key:<code>org.apache.catalina.tribes.MESSAGES</code></p>
100</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
101
102<p>To enable session replication in Tomcat, three different paths can be followed to achieve the exact same thing:</p>
103<ol>
104 <li>Using session persistence, and saving the session to a shared file system (PersistenceManager + FileStore)</li>
105 <li>Using session persistence, and saving the session to a shared database (PersistenceManager + JDBCStore)</li>
106 <li>Using in-memory-replication, using the SimpleTcpCluster that ships with Tomcat 6 (lib/catalina-tribes.jar + lib/catalina-ha.jar)</li>
107</ol>
108
109<p>In this release of session replication, Tomcat can perform an all-to-all replication of session state using the <code>DeltaManager</code> or
110 perform backup replication to only one node using the <code>BackupManager</code>.
111 The all-to-all replication is an algorithm that is only efficient when the clusters are small. For larger clusters, to use
112 a primary-secondary session replication where the session will only be stored at one backup server simply setup the BackupManager. <br>
113 Currently you can use the domain worker attribute (mod_jk &gt; 1.2.8) to build cluster partitions
114 with the potential of having a more scaleable cluster solution with the DeltaManager(you'll need to configure the domain interceptor for this).
115 In order to keep the network traffic down in an all-to-all environment, you can split your cluster
116 into smaller groups. This can be easily achieved by using different multicast addresses for the different groups.
117 A very simple setup would look like this:
118 </p>
119
120<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
121 DNS Round Robin
122 |
123 Load Balancer
124 / \
125 Cluster1 Cluster2
126 / \ / \
127 Tomcat1 Tomcat2 Tomcat3 Tomcat4
128</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
129
130<p>What is important to mention here, is that session replication is only the beginning of clustering.
131 Another popular concept used to implement clusters is farming, i.e., you deploy your apps only to one
132 server, and the cluster will distribute the deployments across the entire cluster.
133 This is all capabilities that can go into with the FarmWarDeployer (s. cluster example at <code>server.xml</code>)</p>
134<p>In the next section will go deeper into how session replication works and how to configure it.</p>
135
136</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Cluster Information"><!--()--></a><a name="Cluster_Information"><strong>Cluster Information</strong></a></font></td></tr><tr><td><blockquote>
137<p>Membership is established using multicast heartbeats.
138 Hence, if you wish to subdivide your clusters, you can do this by
139 changing the multicast IP address or port in the <code>&lt;Membership&gt;</code> element.
140</p>
141<p>
142 The heartbeat contains the IP address of the Tomcat node and the TCP port that
143 Tomcat listens to for replication traffic. All data communication happens over TCP.
144</p>
145<p>
146 The <code>ReplicationValve</code> is used to find out when the request has been completed and initiate the
147 replication, if any. Data is only replicated if the session has changed (by calling setAttribute or removeAttribute
148 on the session).
149</p>
150<p>
151 One of the most important performance considerations is the synchronous versus asynchronous replication.
152 In a synchronous replication mode the request doesn't return until the replicated session has been
153 sent over the wire and reinstantiated on all the other cluster nodes.
154 Synchronous vs. asynchronous is configured using the <code>channelSendOptions</code>
155 flag and is an integer value. The default value for the <code>SimpleTcpCluster/DeltaManager</code> combo is
156 8, which is asynchronous. You can read more on the <a href="tribes/introduction.html">send flag(overview)</a> or the
157 <a href="http://tomcat.apache.org/tomcat-6.0-doc/api/org/apache/catalina/tribes/Channel.html">send flag(javadoc)</a>.
158 During async replication, the request is returned before the data has been replicated. async replication yields shorter
159 request times, and synchronous replication guarantees the session to be replicated before the request returns.
160</p>
161</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Bind session after crash to failover node"><!--()--></a><a name="Bind_session_after_crash_to_failover_node"><strong>Bind session after crash to failover node</strong></a></font></td></tr><tr><td><blockquote>
162<p>
163 If you are using mod_jk and not using sticky sessions or for some reasons sticky session don't
164 work, or you are simply failing over, the session id will need to be modified as it previously contained
165 the worker id of the previous tomcat (as defined by jvmRoute in the Engine element).
166 To solve this, we will use the JvmRouteBinderValve.
167</p>
168<p>
169 The JvmRouteBinderValve rewrites the session id to ensure that the next request will remain sticky
170 (and not fall back to go to random nodes since the worker is no longer available) after a fail over.
171 The valve rewrites the JSESSIONID value in the cookie with the same name.
172 Not having this valve in place, will make it harder to ensure stickyness in case of a failure for the mod_jk module.
173</p>
174<p>
175 By default, if no valves are configured, the JvmRouteBinderValve is added on.
176 The cluster message listener called JvmRouteSessionIDBinderListener is also defined by default and is used to actually rewrite the
177 session id on the other nodes in the cluster once a fail over has occurred.
178 Remember, if you are adding your own valves or cluster listeners in server.xml then the defaults are no longer valid,
179 make sure that you add in all the appropriate valves and listeners as defined by the default.
180</p>
181<p>
182 <b>Hint:</b><br>
183 With attribute <i>sessionIdAttribute</i> you can change the request attribute name that included the old session id.
184 Default attribute name is <i>org.apache.catalina.cluster.session.JvmRouteOrignalSessionID</i>.
185</p>
186<p>
187 <b>Trick:</b><br>
188 You can enable this mod_jk turnover mode via JMX before you drop a node to all backup nodes!
189 Set enable true on all JvmRouteBinderValve backups, disable worker at mod_jk
190 and then drop node and restart it! Then enable mod_jk Worker and disable JvmRouteBinderValves again.
191 This use case means that only requested session are migrated.
192</p>
193
194
195
196</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Configuration Example"><!--()--></a><a name="Configuration_Example"><strong>Configuration Example</strong></a></font></td></tr><tr><td><blockquote>
197 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
198 &lt;Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
199 channelSendOptions="6"&gt;
200
201 &lt;Manager className="org.apache.catalina.ha.session.BackupManager"
202 expireSessionsOnShutdown="false"
203 notifyListenersOnReplication="true"
204 mapSendOptions="6"/&gt;
205 &lt;!--
206 &lt;Manager className="org.apache.catalina.ha.session.DeltaManager"
207 expireSessionsOnShutdown="false"
208 notifyListenersOnReplication="true"/&gt;
209 --&gt;
210 &lt;Channel className="org.apache.catalina.tribes.group.GroupChannel"&gt;
211 &lt;Membership className="org.apache.catalina.tribes.membership.McastService"
212 address="228.0.0.4"
213 port="45564"
214 frequency="500"
215 dropTime="3000"/&gt;
216 &lt;Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
217 address="auto"
218 port="5000"
219 selectorTimeout="100"
220 maxThreads="6"/&gt;
221
222 &lt;Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"&gt;
223 &lt;Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/&gt;
224 &lt;/Sender&gt;
225 &lt;Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/&gt;
226 &lt;Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/&gt;
227 &lt;Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/&gt;
228 &lt;/Channel&gt;
229
230 &lt;Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
231 filter=".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;"/&gt;
232
233 &lt;Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
234 tempDir="/tmp/war-temp/"
235 deployDir="/tmp/war-deploy/"
236 watchDir="/tmp/war-listen/"
237 watchEnabled="false"/&gt;
238
239 &lt;ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/&gt;
240 &lt;/Cluster&gt;
241 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
242 <p>
243 Break it down!!
244 </p>
245 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
246 &lt;Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
247 channelSendOptions="6"&gt;
248 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
249 <p>
250 The main element, inside this element all cluster details can be configured.
251 The <code>channelSendOptions</code> is the flag that is attached to each message sent by the
252 SimpleTcpCluster class or any objects that are invoking the SimpleTcpCluster.send method.
253 The description of the send flags is available at <a href="http://tomcat.apache.org/tomcat-6.0-doc/api/org/apache/catalina/tribes/Channel.html">
254 our javadoc site</a>
255 The <code>DeltaManager</code> sends information using the SimpleTcpCluster.send method, while the backup manager
256 sends it itself directly through the channel.
257 <br>For more info, Please visit the <a href="config/cluster.html">reference documentation</a>
258 </p>
259 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
260 &lt;Manager className="org.apache.catalina.ha.session.BackupManager"
261 expireSessionsOnShutdown="false"
262 notifyListenersOnReplication="true"
263 mapSendOptions="6"/&gt;
264 &lt;!--
265 &lt;Manager className="org.apache.catalina.ha.session.DeltaManager"
266 expireSessionsOnShutdown="false"
267 notifyListenersOnReplication="true"/&gt;
268 --&gt;
269 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
270 <p>
271 This is a template for the manager configuration that will be used if no manager is defined in the &lt;Context&gt;
272 element. In Tomcat 5.x each webapp marked distributable had to use the same manager, this is no longer the case
273 since Tomcat 6 you can define a manager class for each webapp, so that you can mix managers in your cluster.
274 Obviously the managers on one node's application has to correspond with the same manager on the same application on the other node.
275 If no manager has been specified for the webapp, and the webapp is marked &lt;distributable/&gt; Tomcat will take this manager configuration
276 and create a manager instance cloning this configuration.
277 <br>For more info, Please visit the <a href="config/cluster-manager.html">reference documentation</a>
278 </p>
279 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
280 &lt;Channel className="org.apache.catalina.tribes.group.GroupChannel"&gt;
281 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
282 <p>
283 The channel element is <a href="tribes/introduction.html">Tribes</a>, the group communication framework
284 used inside Tomcat. This element encapsulates everything that has to do with communication and membership logic.
285 <br>For more info, Please visit the <a href="config/cluster-channel.html">reference documentation</a>
286 </p>
287 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
288 &lt;Membership className="org.apache.catalina.tribes.membership.McastService"
289 address="228.0.0.4"
290 port="45564"
291 frequency="500"
292 dropTime="3000"/&gt;
293 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
294 <p>
295 Membership is done using multicasting. Please note that Tribes also supports static memberships using the
296 <code>StaticMembershipInterceptor</code> if you want to extend your membership to points beyond multicasting.
297 The address attribute is the multicast address used and the port is the multicast port. These two together
298 create the cluster separation. If you want a QA cluster and a production cluster, the easiest config is to
299 have the QA cluster be on a separate multicast address/port combination the the production cluster.<br>
300 The membership component broadcasts TCP adress/port of itselt to the other nodes so that communication between
301 nodes can be done over TCP. Please note that the address being broadcasted is the one of the
302 <code>Receiver.address</code> attribute.
303 <br>For more info, Please visit the <a href="config/cluster-membership.html">reference documentation</a>
304 </p>
305 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
306 &lt;Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
307 address="auto"
308 port="5000"
309 selectorTimeout="100"
310 maxThreads="6"/&gt;
311 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
312 <p>
313 In tribes the logic of sending and receiving data has been broken into two functional components. The Receiver, as the name suggests
314 is responsible for receiving messages. Since the Tribes stack is thread less, (a popular improvement now adopted by other frameworks as well),
315 there is a thread pool in this component that has a maxThreads and minThreads setting.<br>
316 The address attribute is the host address that will be broadcasted by the membership component to the other nodes.
317 <br>For more info, Please visit the <a href="config/cluster-receiver.html">reference documentation</a>
318 </p>
319 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
320
321 &lt;Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"&gt;
322 &lt;Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/&gt;
323 &lt;/Sender&gt;
324 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
325 <p>
326 The sender component, as the name indicates is responsible for sending messages to other nodes.
327 The sender has a shell component, the <code>ReplicationTransmitter</code> but the real stuff done is done in the
328 sub component, <code>Transport</code>.
329 Tribes support having a pool of senders, so that messages can be sent in parallel and if using the NIO sender,
330 you can send messages concurrently as well.<br>
331 Concurrently means one message to multiple senders at the same time and Parallel means multiple messages to multiple senders
332 at the same time.
333 <br>For more info, Please visit the <a href="config/cluster-sender.html">reference documentation</a>
334 </p>
335 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
336 &lt;Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/&gt;
337 &lt;Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/&gt;
338 &lt;Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/&gt;
339 &lt;/Channel&gt;
340 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
341 <p>
342 Tribes uses a stack to send messages through. Each element in the stack is called an interceptor, and works much like the valves do
343 in the Tomcat servlet container.
344 Using interceptors, logic can be broken into more managable pieces of code. The interceptors configured above are:<br>
345 TcpFailureDetector - verifies crashed members through TCP, if multicast packets get dropped, this interceptor protects against false positives,
346 ie the node marked as crashed even though it still is alive and running.<br>
347 MessageDispatch15Interceptor - dispatches messages to a thread (thread pool) to send message asynchrously.<br>
348 ThroughputInterceptor - prints out simple stats on message traffic.<br>
349 Please note that the order of interceptors is important. the way they are defined in server.xml is the way they are represented in the
350 channel stack. Think of it as a linked list, with the head being the first most interceptor and the tail the last.
351 <br>For more info, Please visit the <a href="config/cluster-interceptor.html">reference documentation</a>
352 </p>
353 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
354 &lt;Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
355 filter=".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;"/&gt;
356 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
357 <p>
358 The cluster uses valves to track requests to web applications, we've mentioned the ReplicationValve and the JvmRouteBinderValve above.
359 The &lt;Cluster&gt; element itself is not part of the pipeline in Tomcat, instead the cluster adds the valve to its parent container.
360 If the &lt;Cluster&gt; elements is configured in the &lt;Engine&gt; element, the valves get added to the engine and so on.
361 <br>For more info, Please visit the <a href="config/cluster-valve.html">reference documentation</a>
362 </p>
363 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
364 &lt;Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
365 tempDir="/tmp/war-temp/"
366 deployDir="/tmp/war-deploy/"
367 watchDir="/tmp/war-listen/"
368 watchEnabled="false"/&gt;
369 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
370 <p>
371 The default tomcat cluster supports farmed deployment, ie, the cluster can deploy and undeploy applications on the other nodes.
372 The state of this component is currently in flux but will be addressed soon. There was a change in the deployment algorithm
373 between Tomcat 5.0 and 5.5 and at that point, the logic of this component changed to where the deploy dir has to match the
374 webapps directory.
375 <br>For more info, Please visit the <a href="config/cluster-deployer.html">reference documentation</a>
376 </p>
377 <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
378 &lt;ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/&gt;
379 &lt;/Cluster&gt;
380 </pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
381 <p>
382 Since the SimpleTcpCluster itself is a sender and receiver of the Channel object, components can register themselves as listeners to
383 the SimpleTcpCluster. The listener above <code>ClusterSessionListener</code> listens for DeltaManager replication messages
384 and applies the deltas to the manager that in turn applies it to the session.
385 <br>For more info, Please visit the <a href="config/cluster-listener.html">reference documentation</a>
386 </p>
387
388</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Cluster Architecture"><!--()--></a><a name="Cluster_Architecture"><strong>Cluster Architecture</strong></a></font></td></tr><tr><td><blockquote>
389
390<p><b>Component Levels:</b>
391<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
392 Server
393 |
394 Service
395 |
396 Engine
397 | \
398 | --- Cluster --*
399 |
400 Host
401 |
402 ------
403 / \
404 Cluster Context(1-N)
405 | \
406 | -- Manager
407 | \
408 | -- DeltaManager
409 | -- BackupManager
410 |
411 ---------------------------
412 | \
413 Channel \
414 ----------------------------- \
415 | \
416 Interceptor_1 .. \
417 | \
418 Interceptor_N \
419 ----------------------------- \
420 | | | \
421 Receiver Sender Membership \
422 -- Valve
423 | \
424 | -- ReplicationValve
425 | -- JvmRouteBinderValve
426 |
427 -- LifecycleListener
428 |
429 -- ClusterListener
430 | \
431 | -- ClusterSessionListener
432 | -- JvmRouteSessionIDBinderListener
433 |
434 -- Deployer
435 \
436 -- FarmWarDeployer
437
438
439</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
440</p>
441
442</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="How it Works"><!--()--></a><a name="How_it_Works"><strong>How it Works</strong></a></font></td></tr><tr><td><blockquote>
443<p>To make it easy to understand how clustering works, We are gonna take you through a series of scenarios.
444 In the scenario we only plan to use two tomcat instances <code>TomcatA</code> and <code>TomcatB</code>.
445 We will cover the following sequence of events:</p>
446
447<ol>
448<li><code>TomcatA</code> starts up</li>
449<li><code>TomcatB</code> starts up (Wait that TomcatA start is complete)</li>
450<li><code>TomcatA</code> receives a request, a session <code>S1</code> is created.</li>
451<li><code>TomcatA</code> crashes</li>
452<li><code>TomcatB</code> receives a request for session <code>S1</code></li>
453<li><code>TomcatA</code> starts up</li>
454<li><code>TomcatA</code> receives a request, invalidate is called on the session (<code>S1</code>)</li>
455<li><code>TomcatB</code> receives a request, for a new session (<code>S2</code>)</li>
456<li><code>TomcatA</code> The session <code>S2</code> expires due to inactivity.</li>
457</ol>
458
459<p>Ok, now that we have a good sequence, we will take you through exactly what happens in the session repliction code</p>
460
461<ol>
462<li><b><code>TomcatA</code> starts up</b>
463 <p>
464 Tomcat starts up using the standard start up sequence. When the Host object is created, a cluster object is associated with it.
465 When the contexts are parsed, if the distributable element is in place in web.xml
466 Tomcat asks the Cluster class (in this case <code>SimpleTcpCluster</code>) to create a manager
467 for the replicated context. So with clustering enabled, distributable set in web.xml
468 Tomcat will create a <code>DeltaManager</code> for that context instead of a <code>StandardManager</code>.
469 The cluster class will start up a membership service (multicast) and a replication service (tcp unicast).
470 More on the architecture further down in this document.
471 </p><p></p>
472</li>
473<li><b><code>TomcatB</code> starts up</b>
474 <p>
475 When TomcatB starts up, it follows the same sequence as TomcatA did with one exception.
476 The cluster is started and will establish a membership (TomcatA,TomcatB).
477 TomcatB will now request the session state from a server that already exists in the cluster,
478 in this case TomcatA. TomcatA responds to the request, and before TomcatB starts listening
479 for HTTP requests, the state has been transferred from TomcatA to TomcatB.
480 In case TomcatA doesn't respond, TomcatB will time out after 60 seconds, and issue a log
481 entry. The session state gets transferred for each web application that has distributable in
482 its web.xml. Note: To use session replication efficiently, all your tomcat instances should be
483 configured the same.
484 </p><p></p>
485</li>
486<li><B><code>TomcatA</code> receives a request, a session <code>S1</code> is created.</B>
487 <p>
488 The request coming in to TomcatA is treated exactly the same way as without session replication.
489 The action happens when the request is completed, the <code>ReplicationValve</code> will intercept
490 the request before the response is returned to the user.
491 At this point it finds that the session has been modified, and it uses TCP to replicata the
492 session to TomcatB. Once the serialized data has been handed off to the operating systems TCP logic,
493 the request returns to the user, back through the valve pipeline.
494 For each request the entire session is replicated, this allows code that modifies attributes
495 in the session without calling setAttribute or removeAttribute to be replicated.
496 a useDirtyFlag configuration parameter can be used to optimize the number of times
497 a session is replicated.
498 </p><p></p>
499
500</li>
501<li><b><code>TomcatA</code> crashes</b>
502 <p>
503 When TomcatA crashes, TomcatB receives a notification that TomcatA has dropped out
504 of the cluster. TomcatB removes TomcatA from its membership list, and TomcatA will no longer
505 be notified of any changes that occurs in TomcatB.
506 The load balancer will redirect the requests from TomcatA to TomcatB and all the sessions
507 are current.
508 </p><p></p>
509</li>
510<li><b><code>TomcatB</code> receives a request for session <code>S1</code></b>
511 <p>Nothing exciting, TomcatB will process the request as any other request.
512 </p><p></p>
513</li>
514<li><b><code>TomcatA</code> starts up</b>
515 <p>Upon start up, before TomcatA starts taking new request and making itself
516 available to it will follow the start up sequence described above 1) 2).
517 It will join the cluster, contact TomcatB for the current state of all the sessions.
518 And once it receives the session state, it finishes loading and opens its HTTP/mod_jk ports.
519 So no requests will make it to TomcatA until it has received the session state from TomcatB.
520 </p><p></p>
521</li>
522<li><b><code>TomcatA</code> receives a request, invalidate is called on the session (<code>S1</code>)</b>
523 <p>The invalidate is call is intercepted, and the session is queued with invalidated sessions.
524 When the request is complete, instead of sending out the session that has changed, it sends out
525 an "expire" message to TomcatB and TomcatB will invalidate the session as well.
526 </p><p></p>
527
528</li>
529<li><b><code>TomcatB</code> receives a request, for a new session (<code>S2</code>)</b>
530 <p>Same scenario as in step 3)
531 </p><p></p>
532
533
534</li>
535<li><code>TomcatA</code> The session <code>S2</code> expires due to inactivity.
536 <p>The invalidate is call is intercepted the same was as when a session is invalidated by the user,
537 and the session is queued with invalidated sessions.
538 At this point, the invalidet session will not be replicated across until
539 another request comes through the system and checks the invalid queue.
540 </p><p></p>
541</li>
542</ol>
543
544<p>Phuuuhh! :)</p>
545
546<p><b>Membership</b>
547 Clustering membership is established using very simple multicast pings.
548 Each Tomcat instance will periodically send out a multicast ping,
549 in the ping message the instance will broad cast its IP and TCP listen port
550 for replication.
551 If an instance has not received such a ping within a given timeframe, the
552 member is considered dead. Very simple, and very effective!
553 Of course, you need to enable multicasting on your system.
554</p>
555
556<p><b>TCP Replication</b>
557 Once a multicast ping has been received, the member is added to the cluster
558 Upon the next replication request, the sending instance will use the host and
559 port info and establish a TCP socket. Using this socket it sends over the serialized data.
560 The reason I choose TCP sockets is because it has built in flow control and guaranteed delivery.
561 So I know, when I send some data, it will make it there :)
562</p>
563
564<p><b>Distributed locking and pages using frames</b>
565 Tomcat does not keep session instances in sync across the cluster.
566 The implementation of such logic would be to much overhead and cause all
567 kinds of problems. If your client accesses the same session
568 simultanously using multiple requests, then the last request
569 will override the other sessions in the cluster.
570</p>
571
572</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="FAQ"><strong>FAQ</strong></a></font></td></tr><tr><td><blockquote>
573<p>Please see <a href="http://wiki.apache.org/tomcat/FAQ/Clustering">the clustering section of the FAQ</a>.</p>
574</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
575 Copyright &copy; 1999-2014, Apache Software Foundation
576 </em></font></div></td></tr></table></body></html>