Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / 6266f996613ae5631b7288523f895b36e30fe5af / . / tomcat-uidm / webapps / docs / config / cluster-valve.html
blob: 34aaf9d175393a1871e98cbb276781861a52b782 [file] [log] [blame]
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1<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 Valve 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 +0800[diff] [blame]80 The Apache Tomcat Servlet/JSP Container
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]81 " 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 Valve 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="#org.apache.catalina.ha.tcp.ReplicationValve">org.apache.catalina.ha.tcp.ReplicationValve</a><ol><li><a href="#org.apache.catalina.ha.tcp.ReplicationValve/Attributes">Attributes</a></li></ol></li><li><a href="#org.apache.catalina.ha.session.JvmRouteBinderValve">org.apache.catalina.ha.session.JvmRouteBinderValve</a><ol><li><a href="#org.apache.catalina.ha.session.JvmRouteBinderValve/Attributes">Attributes</a></li></ol></li><li><a href="#org.apache.catalina.ha.authenticator.ClusterSingleSignOn">org.apache.catalina.ha.authenticator.ClusterSingleSignOn</a><ol><li><a href="#org.apache.catalina.ha.authenticator.ClusterSingleSignOn/Attributes">Attributes</a></li></ol></li></ul>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]83</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 A cluster valve is no different from any other <a href="valve.html">Tomcat <code>Valve</code></a>.
86 The cluster valves are interceptors in the invocation chain for HTTP requests, and the clustering implementation
87 uses these valves to make intelligent decision around data and when data should be replicated.
88 </p>
89 <p>
90 A cluster valve must implement the <code>org.apache.catalina.ha.ClusterValve</code> interface.
91 This is a simple interface that extends the <code>org.apache.catalina.Valve</code> interface.
92 </p>
93</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.catalina.ha.tcp.ReplicationValve"><strong>org.apache.catalina.ha.tcp.ReplicationValve</strong></a></font></td></tr><tr><td><blockquote>
94 The <code>ReplicationValve</code> will notify the cluster at the end of a HTTP request
95 so that the cluster can make a decision whether there is data to be replicated or not.
96 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.catalina.ha.tcp.ReplicationValve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]97 <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 +0800[diff] [blame]98 Set value to <code>org.apache.catalina.ha.tcp.ReplicationValve</code>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]99 </td></tr><tr><td align="left" valign="center"><code class="attributeName">filter</code></td><td align="left" valign="center">
100 For known file extensions or urls, you can use this Valve to notify the
101 cluster that the session has not been modified during this request and
102 the cluster doesn't have to probe the session managers for changes. If
103 the request matches this filter pattern, the cluster assumes there has
104 been no session change. An example filter would look like <code>
105 filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"
106 </code>. The filter is a regular expression using
107 <code>java.util.regex</code>.
108 </td></tr><tr><td align="left" valign="center"><code class="attributeName">primaryIndicator</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]109 Boolean value, so to true, and the replication valve will insert a request attribute with the name
110 defined by the <code>primaryIndicatorName</code> attribute.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]111 The value inserted into the request attribute is either <code>Boolean.TRUE</code> or
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]112 <code>Boolean.FALSE</code>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]113 </td></tr><tr><td align="left" valign="center"><code class="attributeName">primaryIndicatorName</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]114 Default value is <code>org.apache.catalina.ha.tcp.isPrimarySession</code>
115 The value defined here is the name of the request attribute that contains the boolean value
116 if the session is primary on this server or not.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]117 </td></tr><tr><td align="left" valign="center"><code class="attributeName">statistics</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]118 Boolean value. Set to <code>true</code> if you want the valve to collect request statistics.
119 Default value is <code>false</code>
120 </td></tr></table>
121 </blockquote></td></tr></table>
122</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.catalina.ha.session.JvmRouteBinderValve"><strong>org.apache.catalina.ha.session.JvmRouteBinderValve</strong></a></font></td></tr><tr><td><blockquote>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]123 In case of a mod_jk failover, the <code>JvmRouteBinderValve</code> will replace the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]124 <code>jvmWorker</code> attribute in the session Id, to make future requests stick to this
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]125 node. If you want fallback capability, don't enable this valve, but if you want your failover to stick,
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]126 and for mod_jk not to have to keep probing the node that went down, you use this valve.
127 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.catalina.ha.session.JvmRouteBinderValve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]128 <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 +0800[diff] [blame]129 <code>org.apache.catalina.ha.session.JvmRouteBinderValve</code>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]130 </td></tr><tr><td align="left" valign="center"><code class="attributeName">enabled</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]131 Default value is <code>true</code>
132 Runtime attribute to turn on and off turn over of the session's jvmRoute value.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]133 </td></tr><tr><td align="left" valign="center"><code class="attributeName">sessionIdAttribute</code></td><td align="left" valign="center">
134 Old sessionid before failover is registered in request attributes with this attribute.
135 Default attribute name is <code>org.apache.catalina.ha.session.JvmRouteOrignalSessionID</code>.
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]136 </td></tr></table>
137 </blockquote></td></tr></table>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]138</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.catalina.ha.authenticator.ClusterSingleSignOn"><strong>org.apache.catalina.ha.authenticator.ClusterSingleSignOn</strong></a></font></td></tr><tr><td><blockquote>
139 The <code>ClusterSingleSignOn</code> supports feature of single sign on in cluster.
140 By using <code>ClusterSingleSignOn</code>, the security identity authenticated
141 by one web application is recognized by other web applications on the same virtual host,
142 and it is propagated to other nodes in the cluster.
143
144 <p>See the <a href="host.html#Single_Sign_On">Single Sign On</a> special
145 feature on the <strong>Host</strong> element for more information.</p>
146
147 <p><strong>Note: </strong>ClusterSingleSignOn can be configured at host level cluster only.
148 </p>
149
150 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="org.apache.catalina.ha.authenticator.ClusterSingleSignOn/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
151 <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">
152 <p>Java class name of the implementation to use. This MUST be set to
153 <strong>org.apache.catalina.ha.authenticator.ClusterSingleSignOn</strong>.</p>
154 </td></tr><tr><td align="left" valign="center"><code class="attributeName">cookieDomain</code></td><td align="left" valign="center">
155 <p>Sets the host domain to be used for sso cookies.</p>
156 </td></tr><tr><td align="left" valign="center"><code class="attributeName">mapSendOptions</code></td><td align="left" valign="center">
157 <p>The Valve uses a replicated map. You can setup the flag for how this
158 map sends messages. The default value is <code>6</code> (synchronous).
159 Note that if you use asynchronous messaging it is possible for update
160 messages to be processed by the receiving node in a different order to
161 the order in which they were sent.</p>
162 </td></tr><tr><td align="left" valign="center"><code class="attributeName">requireReauthentication</code></td><td align="left" valign="center">
163 <p>Default false. Flag to determine whether each request needs to be
164 reauthenticated to the security <strong>Realm</strong>. If "true", this
165 Valve uses cached security credentials (username and password) to
166 reauthenticate to the <strong>Realm</strong> each request associated
167 with an SSO session. If "false", the Valve can itself authenticate
168 requests based on the presence of a valid SSO cookie, without
169 rechecking with the <strong>Realm</strong>.</p>
170 </td></tr><tr><td align="left" valign="center"><code class="attributeName">rpcTimeout</code></td><td align="left" valign="center">
171 <p>The Valve uses a replicated map. This is the timeout for messages
172 that transfer state to/from the other nodes in the cluster. If not
173 specified, a default value of <code>15000</code> milliseconds is used.
174 </p>
175 </td></tr><tr><td align="left" valign="center"><code class="attributeName">terminateOnStartFailure</code></td><td align="left" valign="center">
176 <p>Set to <code>true</code> if you wish this Valve to fail if the
177 underlying replication fails to start. If the Valve fails, then the
178 associated container will fail to start. If you set this attribute to
179 false, and the underlying replications fails to start, the Valve will
180 start and it will attempt to join the cluster and start replication as
181 part of the heartbeat process. If not specified, the default value of
182 <code>false</code> is used.</p>
183 </td></tr><tr><td align="left" valign="center"><code class="attributeName">accessTimeout</code></td><td align="left" valign="center">
184 The timeout for a ping message. If a remote map does not respond within
185 this timeout period, its regarded as disappeared.
186 Default value is <code>5000</code> milliseconds.
187 </td></tr></table>
188 </blockquote></td></tr></table>
189</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
190 on improving documentation for Apache Tomcat.<br><br>
191 If you have trouble and need help, read
192 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
193 and ask your question on the tomcat-users
194 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
195 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
196 The Apache Comments System is explained <a href="../comments.html">here</a>.
197 Comments may be removed by our moderators if they are either
198 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
199 var comments_shortname = 'tomcat';
200 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/config/cluster-valve.html';
201 (function(w, d) {
202 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
203 d.write('<div id="comments_thread"><\/div>');
204 var s = d.createElement('script');
205 s.type = 'text/javascript';
206 s.async = true;
207 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
208 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
209 }
210 else {
211 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
212 }
213 })(window, document);
214 //--><!]]></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>
215 Copyright &copy; 1999-2017, Apache Software Foundation
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]216 </em></font></div></td></tr></table></body></html>