Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 Configuration Reference (9.0.112) - The Cluster Membership object</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9 Configuration Reference</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Top Level Elements</h2><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul></div><div><h2>Executors</h2><ul><li><a href="executor.html">Executor</a></li></ul></div><div><h2>Connectors</h2><ul><li><a href="http.html">HTTP/1.1</a></li><li><a href="http2.html">HTTP/2</a></li><li><a href="ajp.html">AJP</a></li></ul></div><div><h2>Containers</h2><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></div><div><h2>Nested Components</h2><ul><li><a href="cookie-processor.html">CookieProcessor</a></li><li><a href="credentialhandler.html">CredentialHandler</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="jar-scan-filter.html">JarScanFilter</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></div><div><h2>Cluster Elements</h2><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></div><div><h2>web.xml</h2><ul><li><a href="filter.html">Filter</a></li></ul></div><div><h2>Other</h2><ul><li><a href="runtime-attributes.html">Runtime attributes</a></li><li><a href="systemprops.html">System properties</a></li><li><a href="jaspic.html">JASPIC</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>The Cluster Membership object</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Default_Implementation">Default Implementation</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Multicast_Attributes">Multicast Attributes</a></li><li><a href="#Static_Membership_Attributes">Static Membership Attributes</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a><ol><li><a href="#StaticMember_Attributes">StaticMember Attributes</a></li><li><a href="#Setting">Setting</a></li></ol></li></ul>
6 
</div><h3 id="Introduction">Introduction</h3><div class="text">
7 
  <p>
8 
    The membership component in the Apache Tribes <a href="cluster-channel.html">Channel</a> is responsible
9 
    for dynamic discovery of other members(nodes) in the cluster.
10 
    There are currently two different membership service, the <code>org.apache.catalina.tribes.membership.McastService</code>
11 
    and the <code>org.apache.catalina.tribes.membership.StaticMembershipService</code>.
12 
    The <code>McastService</code> builds a multicast based membership service
13 
    that sends UDP packets to multicast IP addresses.
14 
    The <code>StaticMembershipService</code> builds  a unicast based membership
15 
    service that sends TCP packets to predefined member address.
16 
  </p>
17 
</div><h3 id="Default_Implementation">Default Implementation</h3><div class="text">
18 
  <p>
19 
    The default implementation of the cluster group notification is built on top of multicast heartbeats
20 
    sent using UDP packets to a multicast IP address.
21 
    Cluster members are grouped together by using the same multicast address/port combination.
22 
    Each member sends out a heartbeat with a given interval (<code>frequency</code>), and this
23 
    heartbeat is used for dynamic discovery.
24 
    In a similar fashion, if a heartbeat has not been received in a timeframe specified by <code>dropTime</code>
25 
    ms. a member is considered suspect and the channel and any membership listener will be notified.
26 
  </p>
27 
</div><h3 id="Attributes">Attributes</h3><div class="text">
28 
  <div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
29 
    <table class="defaultTable"><tr><th style="width: 15%;">
30 
          Attribute
31 
        </th><th style="width: 85%;">
32 
          Description
33 
        </th></tr><tr id="Attributes_Common Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td>
34 
        <p>
35 
        The implementation of the membership component.
36 
        Two implementations available, <code>org.apache.catalina.tribes.membership.McastService</code>
37 
        and <code>org.apache.catalina.tribes.membership.StaticMembershipService</code>.
38 
        </p>
39 
      </td></tr></table>
40 
  </div></div>
41 
  <div class="subsection"><h4 id="Multicast_Attributes">Multicast Attributes</h4><div class="text">
42 
 
43 
  <table class="defaultTable"><tr><th style="width: 15%;">
44 
          Attribute
45 
        </th><th style="width: 85%;">
46 
          Description
47 
        </th></tr><tr id="Attributes_Multicast Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td>
48 
      <p>
49 
      The value is <code>org.apache.catalina.tribes.membership.McastService</code>.
50 
      This implementation uses multicast heartbeats for member discovery.
51 
      </p>
52 
    </td></tr><tr id="Attributes_Multicast Attributes_address"><td><code class="attributeName">address</code></td><td>
53 
      <p>
54 
      The multicast address that the membership will broadcast its presence and listen
55 
      for other heartbeats on. The default value is <code>228.0.0.4</code>
56 
      Make sure your network is enabled for multicast traffic.<br>
57 
      The multicast address, in conjunction with the <code>port</code> is what
58 
      creates a cluster group. To divide up your farm into several different group, or to
59 
      split up QA from production, change the <code>port</code> or the <code>address</code>
60 
      <br>Previously known as mcastAddr.
61 
      </p>
62 
    </td></tr><tr id="Attributes_Multicast Attributes_port"><td><code class="attributeName">port</code></td><td>
63 
      <p>
64 
      The multicast port, the default value is <code>45564</code><br>
65 
      The multicast port, in conjunction with the <code>address</code> is what
66 
      creates a cluster group. To divide up your farm into several different group, or to
67 
      split up QA from production, change the <code>port</code> or the <code>address</code>
68 
      </p>
69 
    </td></tr><tr id="Attributes_Multicast Attributes_frequency"><td><code class="attributeName">frequency</code></td><td>
70 
      <p>
71 
      The frequency in milliseconds in which heartbeats are sent out. The default value is <code>500</code> ms.<br>
72 
      In most cases the default value is sufficient. Changing this value, simply changes the interval in between heartbeats.
73 
      </p>
74 
    </td></tr><tr id="Attributes_Multicast Attributes_dropTime"><td><code class="attributeName">dropTime</code></td><td>
75 
      <p>
76 
      The membership component will time out members and notify the Channel if a member fails to send a heartbeat within
77 
      a give time. The default value is <code>3000</code> ms. This means, that if a heartbeat is not received from a
78 
      member in that timeframe, the membership component will notify the cluster of this.<br>
79 
      On a high latency network you may wish to increase this value, to protect against false positives.<br>
80 
      Apache Tribes also provides a <a href="cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.TcpFailureDetector_Attributes"><code>TcpFailureDetector</code></a> that will
81 
      verify a timeout using a TCP connection when a heartbeat timeout has occurred. This protects against false positives.
82 
      </p>
83 
    </td></tr><tr id="Attributes_Multicast Attributes_bind"><td><code class="attributeName">bind</code></td><td>
84 
      <p>
85 
      Use this attribute if you wish to bind your multicast traffic to a specific network interface.
86 
      By default, or when this attribute is unset, it tries to bind to <code>0.0.0.0</code> and sometimes on multihomed hosts
87 
      this becomes a problem.
88 
      </p>
89 
    </td></tr><tr id="Attributes_Multicast Attributes_ttl"><td><code class="attributeName">ttl</code></td><td>
90 
      <p>
91 
      The time-to-live setting for the multicast heartbeats.
92 
      This setting should be a value between 0 and 255. The default value is VM implementation specific.
93 
      </p>
94 
    </td></tr><tr id="Attributes_Multicast Attributes_domain"><td><code class="attributeName">domain</code></td><td>
95 
      <p>
96 
      Apache Tribes has the ability to logically group members into domains, by using this domain attribute.
97 
      The <code>org.apache.catalina.tribes.Member.getDomain()</code> method returns the value specified here.
98 
      </p>
99 
    </td></tr><tr id="Attributes_Multicast Attributes_soTimeout"><td><code class="attributeName">soTimeout</code></td><td>
100 
      <p>
101 
      The sending and receiving of heartbeats is done on a single thread, hence to avoid blocking this thread forever,
102 
      you can control the <code>SO_TIMEOUT</code> value on this socket.<br>
103 
      If a value smaller or equal to 0 is presented, the code will default this value to frequency
104 
      </p>
105 
    </td></tr><tr id="Attributes_Multicast Attributes_recoveryEnabled"><td><code class="attributeName">recoveryEnabled</code></td><td>
106 
      <p>
107 
      In case of a network failure, Java multicast socket don't transparently fail over, instead the socket will continuously
108 
      throw IOException upon each receive request. When recoveryEnabled is set to true, this will close the multicast socket
109 
      and open a new socket with the same properties as defined above.<br>
110 
      The default is <code>true</code>. <br>
111 
      </p>
112 
    </td></tr><tr id="Attributes_Multicast Attributes_recoveryCounter"><td><code class="attributeName">recoveryCounter</code></td><td>
113 
      <p>
114 
      When <code>recoveryEnabled==true</code> this value indicates how many
115 
      times an error has to occur before recovery is attempted. The default is
116 
      <code>10</code>. <br>
117 
      </p>
118 
    </td></tr><tr id="Attributes_Multicast Attributes_recoverySleepTime"><td><code class="attributeName">recoverySleepTime</code></td><td>
119 
      <p>
120 
      When <code>recoveryEnabled==true</code> this value indicates how long time (in milliseconds)
121 
      the system will sleep in between recovery attempts, until it recovers successfully.
122 
      The default is <code>5000</code> (5 seconds). <br>
123 
      </p>
124 
    </td></tr><tr id="Attributes_Multicast Attributes_localLoopbackDisabled"><td><code class="attributeName">localLoopbackDisabled</code></td><td>
125 
      <p>
126 
      Membership uses multicast, it will call <code>java.net.MulticastSocket.setLoopbackMode(localLoopbackDisabled)</code>.
127 
      When <code>localLoopbackDisabled==true</code> multicast messages will not reach other nodes on the same local machine.
128 
      The default is <code>false</code>. <br>
129 
      </p>
130 
    </td></tr></table>
131 
 
132 
  </div></div>
133 
 
134 
  <div class="subsection"><h4 id="Static_Membership_Attributes">Static Membership Attributes</h4><div class="text">
135 
 
136 
    <p>When using the static membership service you must ensure that the
137 
    <code>channelStartOptions</code> attribute of the <code>Cluster</code>
138 
    element is set to the default value of <code>15</code>.</p>
139 
 
140 
    <table class="defaultTable"><tr><th style="width: 15%;">
141 
          Attribute
142 
        </th><th style="width: 85%;">
143 
          Description
144 
        </th></tr><tr id="Attributes_Static Membership Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td>
145 
        <p>
146 
        The value is <code>org.apache.catalina.tribes.membership.StaticMembershipService</code>.
147 
        </p>
148 
      </td></tr><tr id="Attributes_Static Membership Attributes_connectTimeout"><td><code class="attributeName">connectTimeout</code></td><td>
149 
        <p>
150 
        Timeout for attempting a TCP connection to address of predefined static member.
151 
        Default is <code>500</code> ms.
152 
        </p>
153 
      </td></tr><tr id="Attributes_Static Membership Attributes_expirationTime"><td><code class="attributeName">expirationTime</code></td><td>
154 
        <p>
155 
        If members have failed to update their alive time within the given time,
156 
        this membership will notify the memberDisappeared event to cluster.
157 
        Default is <code>5000</code> ms.
158 
        </p>
159 
      </td></tr><tr id="Attributes_Static Membership Attributes_rpcTimeout"><td><code class="attributeName">rpcTimeout</code></td><td>
160 
        <p>
161 
        Timeout for messages that used for member notification to/from othee nodes.
162 
        Default is <code>3000</code> ms.
163 
        </p>
164 
      </td></tr><tr id="Attributes_Static Membership Attributes_useThread"><td><code class="attributeName">useThread</code></td><td>
165 
        <p>
166 
        If set to true, this membership service will start a local thread for
167 
        sending a ping message. if set to <code>false</code>, channel heartbeat
168 
        will send a ping message. Default is <code>false</code>.
169 
        </p>
170 
      </td></tr><tr id="Attributes_Static Membership Attributes_pingInterval"><td><code class="attributeName">pingInterval</code></td><td>
171 
        <p>
172 
        If <code>useThread</code> == <code>true</code>, defines the interval of
173 
        sending a ping message. Default is <code>1000</code> ms.
174 
        </p>
175 
      </td></tr></table>
176 
  </div></div>
177 
 
178 
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
179 
  <p>
180 
  Static Membership Service allows nesting of a <strong>&lt;LocalMember&gt;</strong>
181 
  and <strong>&lt;Member&gt;</strong> element.
182 
  </p>
183 
  <div class="subsection"><h4 id="StaticMember_Attributes">StaticMember Attributes</h4><div class="text">
184 
    <p><b>LocalMember:</b> <br>
185 
    Static member that is the local member of the static cluster group.
186 
    </p>
187 
    <p><strong>Note:</strong> In Tomcat 9.0.17 and later, it is not necessary to explicitly configure the local member
188 
    using the <strong>&lt;LocalMember&gt;</strong> element. All cluster members, including the local member, may be
189 
    defined using the <strong>&lt;Member&gt;</strong> element and Tomcat work out which one is the local member.
190 
    </p>
191 
    <table class="defaultTable"><tr><th style="width: 15%;">
192 
          Attribute
193 
        </th><th style="width: 85%;">
194 
          Description
195 
        </th></tr><tr id="Nested Components_StaticMember Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td>
196 
        Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
197 
      </td></tr><tr id="Nested Components_StaticMember Attributes_port"><td><code class="attributeName">port</code></td><td>
198 
        There is no need to set.
199 
        The value of this attribute inherits from the cluster receiver setting.
200 
      </td></tr><tr id="Nested Components_StaticMember Attributes_securePort"><td><code class="attributeName">securePort</code></td><td>
201 
        There is no need to set.
202 
        The value of this attribute inherits from the cluster receiver setting.
203 
      </td></tr><tr id="Nested Components_StaticMember Attributes_host"><td><code class="attributeName">host</code></td><td>
204 
        There is no need to set.
205 
        The value of this attribute inherits from the cluster receiver setting.
206 
      </td></tr><tr id="Nested Components_StaticMember Attributes_domain"><td><code class="attributeName">domain</code></td><td>
207 
        The logical cluster domain for that this static member listens for cluster messages.
208 
        Two different type of values are possible:<br>
209 
        1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes
210 
        using ISO-8859-1 encoding.
211 
        2. byte array in string form, for example {216,123,12,3}<br>
212 
      </td></tr><tr id="Nested Components_StaticMember Attributes_uniqueId"><td><strong><code class="attributeName">uniqueId</code></strong></td><td>
213 
        A universally uniqueId for this static member.
214 
        The values must be 16 bytes in the following form:<br>
215 
        1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}<br>
216 
      </td></tr></table>
217 
 
218 
    <p><b>Member:</b> <br>
219 
    Static member that add to the static cluster group.
220 
    </p>
221 
    <table class="defaultTable"><tr><th style="width: 15%;">
222 
          Attribute
223 
        </th><th style="width: 85%;">
224 
          Description
225 
        </th></tr><tr id="Nested Components_StaticMember Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td>
226 
        Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
227 
      </td></tr><tr id="Nested Components_StaticMember Attributes_port"><td><strong><code class="attributeName">port</code></strong></td><td>
228 
        The port that this static member listens to for cluster messages
229 
      </td></tr><tr id="Nested Components_StaticMember Attributes_securePort"><td><code class="attributeName">securePort</code></td><td>
230 
        The secure port this static member listens to for encrypted cluster messages
231 
        default value is <code>-1</code>, this value means the member is not listening on a secure port
232 
      </td></tr><tr id="Nested Components_StaticMember Attributes_host"><td><strong><code class="attributeName">host</code></strong></td><td>
233 
        The host (or network interface) that this static member listens for cluster messages.
234 
        Three different type of values are possible:<br>
235 
        1. IP address in the form of "216.123.1.23"<br>
236 
        2. Hostnames like "tomcat01.mydomain.com" or "tomcat01" as long as they resolve correctly<br>
237 
        3. byte array in string form, for example {216,123,12,3}<br>
238 
      </td></tr><tr id="Nested Components_StaticMember Attributes_domain"><td><code class="attributeName">domain</code></td><td>
239 
        The logical cluster domain for that this static member listens for cluster messages.
240 
        Two different type of values are possible:<br>
241 
        1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes
242 
        using ISO-8859-1 encoding.<br>
243 
        2. byte array in string form, for example {216,123,12,3}<br>
244 
      </td></tr><tr id="Nested Components_StaticMember Attributes_uniqueId"><td><strong><code class="attributeName">uniqueId</code></strong></td><td>
245 
        A universally uniqueId for this static member.
246 
        The values must be 16 bytes in the following form:<br>
247 
        1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}<br>
248 
      </td></tr></table>
249 
  </div></div>
250 
 
251 
  <div class="subsection"><h4 id="Setting">Setting</h4><div class="text">
252 
    <p><b>Before Tomcat 9.0.16</b> <br>
253 
    <div class="codeBox"><pre><code>     &lt;Membership className="org.apache.catalina.tribes.membership.StaticMembershipService"&gt;
254 
       &lt;LocalMember className="org.apache.catalina.tribes.membership.StaticMember"
255 
                  uniqueId="{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"/&gt;
256 
       &lt;Member className="org.apache.catalina.tribes.membership.StaticMember"
257 
                  port="4004"
258 
                  host="tomcat02.mydomain.com"
259 
                  uniqueId="{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,1}"/&gt;
260 
     &lt;/Membership&gt;</code></pre></div>
261 
     </p>
262 
     <p><b>Tomcat9.0.17 and later</b> <br>
263 
      <div class="codeBox"><pre><code>     &lt;Membership className="org.apache.catalina.tribes.membership.StaticMembershipService"&gt;
264 
       &lt;Member className="org.apache.catalina.tribes.membership.StaticMember"
265 
                  port="4004"
266 
                  host="tomcat01.mydomain.com"
267 
                  uniqueId="{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"/&gt;
268 
       &lt;Member className="org.apache.catalina.tribes.membership.StaticMember"
269 
                  port="4004"
270 
                  host="tomcat02.mydomain.com"
271 
                  uniqueId="{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,1}"/&gt;
272 
     &lt;/Membership&gt;</code></pre></div>
273 
     </p>
274 
  </div></div>
275 
</div></div></div></div></div><footer><div id="footer">
276 
    Copyright &copy; 1999-2025, The Apache Software Foundation
277 
    <br>
278 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
279 
    are either registered trademarks or trademarks of the Apache Software
280 
    Foundation.
281 
    </div></footer></div></body></html>