blob: 67e2a015d59d10ffd5f65ca1a2117776e0e0e2d2 [file] [log] [blame]
刘洪青6266f992017-05-15 21:21:03 +08001<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 Configuration Reference (7.0.77) - The Cluster object</title><meta name="author" content="Filip Hanik"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4</style><style type="text/css">
5code {background-color:rgb(224,255,255);padding:0 0.1em;}
6code.attributeName, code.propertyName {background-color:transparent;}
7
8
9table {
10 border-collapse: collapse;
11 text-align: left;
12}
13table *:not(table) {
14 /* Prevent border-collapsing for table child elements like <div> */
15 border-collapse: separate;
16}
17
18th {
19 text-align: left;
20}
21
22
23div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
24 background-color: transparent;
25}
26div.codeBox {
27 overflow: auto;
28 margin: 1em 0;
29}
30div.codeBox pre {
31 margin: 0;
32 padding: 4px;
33 border: 1px solid #999;
34 border-radius: 5px;
35 background-color: #eff8ff;
36 display: table; /* To prevent <pre>s from taking the complete available width. */
37 /*
38 When it is officially supported, use the following CSS instead of display: table
39 to prevent big <pre>s from exceeding the browser window:
40 max-width: available;
41 width: min-content;
42 */
43}
44
45div.codeBox pre.wrap {
46 white-space: pre-wrap;
47}
48
49
50table.defaultTable tr, table.detail-table tr {
51 border: 1px solid #CCC;
52}
53
54table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
55 background-color: #FAFBFF;
56}
57
58table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
59 background-color: #EEEFFF;
60}
61
62table.defaultTable th, table.detail-table th {
63 background-color: #88b;
64 color: #fff;
65}
66
67table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
68 padding: 5px 8px;
69}
70
71
72p.notice {
73 border: 1px solid rgb(255, 0, 0);
74 background-color: rgb(238, 238, 238);
75 color: rgb(0, 51, 102);
76 padding: 0.5em;
77 margin: 1em 2em 1em 1em;
78}
79</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="
Hongqing Liufd5ee812014-05-10 16:32:51 +080080 The Apache Tomcat Servlet/JSP Container
刘洪青6266f992017-05-15 21:21:03 +080081 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>web.xml</strong></p><ul><li><a href="filter.html">Filter</a></li></ul><p><strong>Other</strong></p><ul><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>The Cluster object</h1><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>
82<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Security">Security</a></li><li><a href="#Engine_vs_Host_placement">Engine vs Host placement</a></li><li><a href="#Context_Attribute_Replication">Context Attribute Replication</a></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Deprecated_configuration_options">Deprecated configuration options</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#SimpleTcpCluster_Attributes">SimpleTcpCluster Attributes</a></li></ol></li></ul>
Hongqing Liufd5ee812014-05-10 16:32:51 +080083</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
84 <p>
85 The tomcat cluster implementation provides session replication, context attribute replication and
86 cluster wide WAR file deployment.
87 While the <code>Cluster</code> configuration is fairly complex, the default configuration will work
88 for most people out of the box. </p><p>
89 The Tomcat Cluster implementation is very extensible, and hence we have exposed a myriad of options,
90 making the configuration seem like a lot, but don't lose faith, instead you have a tremendous control
91 over what is going on.</p>
刘洪青6266f992017-05-15 21:21:03 +080092</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Security"><strong>Security</strong></a></font></td></tr><tr><td><blockquote>
93
94<p>The cluster implementation is written on the basis that a secure, trusted
95network is used for all of the cluster related network traffic. It is not safe
96to run a cluster on a insecure, untrusted network.</p>
97
98<p>There are many options for providing a secure, trusted network for use by a
99Tomcat cluster. These include:</p>
100<ul>
101 <li>private LAN</li>
102 <li>a Virtual Private Network (VPN)</li>
103 <li>IPSEC</li>
104</ul>
105
Hongqing Liufd5ee812014-05-10 16:32:51 +0800106</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Engine vs Host placement"><!--()--></a><a name="Engine_vs_Host_placement"><strong>Engine vs Host placement</strong></a></font></td></tr><tr><td><blockquote>
107 <p>
108 You can place the <code>&lt;Cluster&gt;</code> element inside either the <code>&lt;Engine&gt;</code>
109 container or the <code>&lt;Host&gt;</code> container.<br>
110 Placing it in the engine, means that you will support clustering in all virtual hosts of Tomcat,
111 and share the messaging component. When you place the <code>&lt;Cluster&gt;</code> inside the <code>&lt;Engine&gt;</code>
刘洪青6266f992017-05-15 21:21:03 +0800112 element, the cluster will append the host name of each session manager to the managers name so that two contexts with
Hongqing Liufd5ee812014-05-10 16:32:51 +0800113 the same name but sitting inside two different hosts will be distinguishable.
114 </p>
115</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Context Attribute Replication"><!--()--></a><a name="Context_Attribute_Replication"><strong>Context Attribute Replication</strong></a></font></td></tr><tr><td><blockquote>
116 <p>To configure context attribute replication, simply do this by swapping out the context implementation
刘洪青6266f992017-05-15 21:21:03 +0800117 used for your application context.</p>
118 <div class="codeBox"><pre><code>&lt;Context className="org.apache.catalina.ha.context.ReplicatedContext"/&gt;</code></pre></div>
119 <p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800120 This context extends the Tomcat <code><a href="context.html">StandardContext</a></code>
121 so all the options from the <a href="context.html">base implementation</a> are valid.
122 </p>
123</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
124 <p><b><a href="cluster-manager.html">Manager</a>:</b> <br>
125 The session manager element identifies what kind of session manager is used in this cluster implementation.
刘洪青6266f992017-05-15 21:21:03 +0800126 This manager configuration is identical to the one you would use in a regular <code><a href="context.html#Nested_Components">&lt;Context&gt;</a></code> configuration.
Hongqing Liufd5ee812014-05-10 16:32:51 +0800127 <br>The default value is the <code>org.apache.catalina.ha.session.DeltaManager</code> that is closely coupled with
128 the <code>SimpleTcpCluster</code> implementation. Other managers like the <code>org.apache.catalina.ha.session.BackupManager</code>
129 are/could be loosely coupled and don't rely on the <code>SimpleTcpCluster</code> for its data replication.
130 </p>
131 <p><b><a href="cluster-channel.html">Channel</a>:</b> <br>
刘洪青6266f992017-05-15 21:21:03 +0800132 The Channel and its sub components are all part of the IO layer
Hongqing Liufd5ee812014-05-10 16:32:51 +0800133 for the cluster group, and is a module in it's own that we have nick named "Tribes"
134 <br>
135 Any configuring and tuning of the network layer, the messaging and the membership logic
136 will be done in the channel and its nested components.
137 You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
138 </p>
139 <p><b><a href="cluster-valve.html">Valve</a>:</b> <br>
140 The Tomcat Cluster implementation uses <code>Tomcat <a href="valve.html">Valves</a></code> to
141 track when requests enter and exit the servlet container. It uses these valves to be able to make
142 intelligent decisions on when to replicate data, which is always at the end of a request.
143 </p>
144 <p><b><a href="cluster-deployer.html">Deployer</a>:</b> <br>
145 The Deployer component is the Tomcat Farm Deployer. It allows you to deploy and undeploy applications
146 cluster wide.
147 </p>
148 <p><b><a href="cluster-listener.html">ClusterListener</a>:</b> <br>
149 ClusterListener's are used to track messages sent and received using the <code>SimpleTcpCluster</code>.
150 If you wish to track messages, you can add a listener here, or you can add a valve to the channel object.
151 </p>
152</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deprecated configuration options"><!--()--></a><a name="Deprecated_configuration_options"><strong>Deprecated configuration options</strong></a></font></td></tr><tr><td><blockquote>
153 <p>
154 <b>Deprecated settings:</b> In the previous version of Tomcat you were able to control session
155 manager settings using manager.&lt;property&gt;=value.
刘洪青6266f992017-05-15 21:21:03 +0800156 This has been discontinued, as the way it was written interferes with
Hongqing Liufd5ee812014-05-10 16:32:51 +0800157 the ability to support multiple different manager classes under one cluster implementation,
158 as the same properties might have the different effect on different managers.
159 </p>
160</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
161 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="SimpleTcpCluster Attributes"><!--()--></a><a name="SimpleTcpCluster_Attributes"><strong>SimpleTcpCluster Attributes</strong></a></font></td></tr><tr><td><blockquote>
刘洪青6266f992017-05-15 21:21:03 +0800162 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800163 <p>The main cluster class, currently only one is available,
164 <code>org.apache.catalina.ha.tcp.SimpleTcpCluster</code>
165 </p>
刘洪青6266f992017-05-15 21:21:03 +0800166 </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">channelSendOptions</code></strong></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800167 <p>The Tribes channel send options, default is <code>8</code>.<br>
刘洪青6266f992017-05-15 21:21:03 +0800168 This option is used to set the flag that all messages sent through the
169 SimpleTcpCluster uses. The flag decides how the messages are sent, and is a simple logical OR.</p>
170
171 <div class="codeBox"><pre><code>int options = Channel.SEND_OPTIONS_ASYNCHRONOUS |
172 Channel.SEND_OPTIONS_SYNCHRONIZED_ACK |
173 Channel.SEND_OPTIONS_USE_ACK;</code></pre></div>
174 <p>Some of the values are:<br>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800175 <code>Channel.SEND_OPTIONS_SYNCHRONIZED_ACK = 0x0004</code><br>
176 <code>Channel.SEND_OPTIONS_ASYNCHRONOUS = 0x0008</code><br>
177 <code>Channel.SEND_OPTIONS_USE_ACK = 0x0002</code><br>
刘洪青6266f992017-05-15 21:21:03 +0800178 So to use ACK and ASYNC messaging, the flag would be <code>10</code> (8+2)
179 <br>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800180 Note that if you use ASYNC messaging it is possible for update messages
181 for a session to be processed by the receiving nodes in a different order
刘洪青6266f992017-05-15 21:21:03 +0800182 to the order in which they were sent.</p>
183 </td></tr><tr><td align="left" valign="center"><code class="attributeName">channelStartOptions</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800184 <p>Sets the start and stop flags for the &lt;Channel&gt; object used by the cluster.
刘洪青6266f992017-05-15 21:21:03 +0800185 The default is <code>Channel.DEFAULT</code> which starts all the channel services, such as
Hongqing Liufd5ee812014-05-10 16:32:51 +0800186 sender, receiver, multicast sender and multicast receiver.
刘洪青6266f992017-05-15 21:21:03 +0800187 The following flags are available today:</p>
188 <div class="codeBox"><pre><code>Channel.DEFAULT = Channel.SND_RX_SEQ (1) |
189 Channel.SND_TX_SEQ (2) |
190 Channel.MBR_RX_SEQ (4) |
191 Channel.MBR_TX_SEQ (8);</code></pre></div>
192 <p>To start a channel without multicasting, you would want to use the value <code>Channel.SND_RX_SEQ | Channel.SND_TX_SEQ</code>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800193 that equals to <code>3</code>.
194 </p>
刘洪青6266f992017-05-15 21:21:03 +0800195 </td></tr><tr><td align="left" valign="center"><code class="attributeName">heartbeatBackgroundEnabled</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800196 <p>Flag whether invoke channel heartbeat at container background thread. Default value is false.
197 Enable this flag don't forget to disable the channel heartbeat thread.
198 </p>
刘洪青6266f992017-05-15 21:21:03 +0800199 </td></tr><tr><td align="left" valign="center"><code class="attributeName">notifyLifecycleListenerOnFailure</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800200 <p>Flag whether notify LifecycleListeners if all ClusterListener couldn't accept channel message.
201 Default value is false.
202 </p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800203 </td></tr></table>
204 </blockquote></td></tr></table>
刘洪青6266f992017-05-15 21:21:03 +0800205</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
206 on improving documentation for Apache Tomcat.<br><br>
207 If you have trouble and need help, read
208 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
209 and ask your question on the tomcat-users
210 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
211 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
212 The Apache Comments System is explained <a href="../comments.html">here</a>.
213 Comments may be removed by our moderators if they are either
214 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
215 var comments_shortname = 'tomcat';
216 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/config/cluster.html';
217 (function(w, d) {
218 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
219 d.write('<div id="comments_thread"><\/div>');
220 var s = d.createElement('script');
221 s.type = 'text/javascript';
222 s.async = true;
223 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
224 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
225 }
226 else {
227 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
228 }
229 })(window, document);
230 //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
231 Copyright &copy; 1999-2017, Apache Software Foundation
Hongqing Liufd5ee812014-05-10 16:32:51 +0800232 </em></font></div></td></tr></table></body></html>