<section name="Quick Start">
+<p>This document is pending an update to the latest implementation.<br/>
+ You can also check the <a href="config/cluster.html">configuration reference documentation.</a>
+</p>
<p>To run session replication in your Tomcat 5.5 container, the following steps
should be completed:</p>
<section name="Introduction">
-
-
-
+ The cluster channel is the main component of a small framework we've nicknamed Apache Tribes.<br/>
+ The channel manages a set of sub components and together they create a group communication framework.<br/>
+ This framework is then used internally by the components that need to send messages between different Tomcat instances.
+ <br/>
+ A few examples of these components would be the SimpleTcpCluster that does the messaging for the DeltaManager,
+ or the BackupManager that uses a different replication strategy. The ReplicatedContext object does also
+ use the channel object to communicate context attribute changes.
+</section>
+<section name="Nested Components">
+ <p><b><a href="cluster-membership.html">Channel/Membership</a>:</b> <br/>
+ The Membership component is responsible for auto discovering new nodes in the cluster
+ and also to provide for notifications for any nodes that have not responded with a heartbeat.
+ The default implementation uses multicast.<br/>
+ In the membership component you configure how your nodes, aka. members, are to be discovered and/or
+ divided up.
+ You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
+ </p>
+ <p><b><a href="cluster-sender.html">Channel/Sender</a>:</b> <br/>
+ The Sender component manages all outbound connections and data messages that are sent
+ over the network from one node to another.
+ This component allows messages to be sent in parallel.
+ The default implementation uses TCP client sockets, and socket tuning for outgoing messages are
+ configured here.<br/>
+ You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
+ </p>
+ <p><b><a href="cluster-sender.html#transport">Channel/Sender/Transport</a>:</b> <br/>
+ The Transport component is the bottom IO layer for the sender component.
+ The default implementation uses non-blocking TCP client sockets.<br/>
+ You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
+ </p>
+ <p><b><a href="cluster-receiver.html">Channel/Receiver</a>:</b> <br/>
+ The receiver component listens for messages from other nodes.
+ Here you will configure the cluster thread pool, as it will dispatch incoming
+ messages to a thread pool for faster processing.
+ The default implementation uses non-blocking TCP server sockets.<br/>
+ You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
+ </p>
+ <p><b><a href="cluster-interceptor.html">Channel/Interceptor</a>:</b> <br/>
+ The channel will send messages through an interceptor stack. Because of this, you have the ability to
+ customize the way messages are sent and received, and even how membership is handled.<br/>
+ You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
+ </p>
</section>
<attributes>
<attribute name="className" required="true">
-
+ The default value here is <code>org.apache.catalina.tribes.group.GroupChannel</code> and is
+ currently the only implementation available.
</attribute>
<section name="Introduction">
+ <p>
+ The membership component in the Apache Tribes <a href="cluster-channel.html">Channel</a> is responsible
+ for dynamic discovery of other members(nodes) in the cluster.
+ </p>
+</section>
-
-
+<section name="Default Implementation">
+ <p>
+ The default implementation of the cluster group notification is built on top of multicast heartbeats
+ sent using UDP packets to a multicast IP address.
+ Cluster members are grouped together by using the same multicast address/port combination.
+ Each member sends out a heartbeat with a given interval (<code>mcastFrequency</code>), and this
+ heartbeat is used for dynamic discovery.
+ In a similar fashion, if a heartbeat has not been received in a timeframe specified by <code>mcastDropTime</code>
+ ms. a member is considered suspect and the channel and any membership listener will be notified.
+ </p>
</section>
+
<section name="Attributes">
- <subsection name="Common Attributes">
+ <subsection name="Multicast Attributes">
<attributes>
<attribute name="className" required="true">
-
+ <p>
+ The default value is <code>org.apache.catalina.tribes.membership.McastService</code>
+ and is currently the only implementation.
+ This implementation uses multicast heartbeats for member discovery.
+ </p>
+ </attribute>
+ <attribute name="mcastAddr" required="false">
+ <p>
+ The multicast address that the membership will broadcast its presence and listen
+ for other heartbeats on. The default value is <code>228.0.0.4</code>
+ Make sure your network is enabled for multicast traffic.<br/>
+ The multicast address, in conjunction with the <code>mcastPort</code> is what
+ creates a cluster group. To divide up your farm into several different group, or to
+ split up QA from production, change the <code>mcastPort</code> or the <code>mcastAddr</code>
+ </p>
+ </attribute>
+ <attribute name="mcastPort" required="false">
+ <p>
+ The multicast port, the default value is <code>45564</code><br/>
+ The multicast port, in conjunction with the <code>mcastAddr</code> is what
+ creates a cluster group. To divide up your farm into several different group, or to
+ split up QA from production, change the <code>mcastPort</code> or the <code>mcastAddr</code>
+ </p>
+ </attribute>
+ <attribute name="mcastFrequency" required="false">
+ <p>
+ The frequency in milliseconds in which heartbeats are sent out. The default value is <code>500</code> ms.<br/>
+ In most cases the default value is sufficient. Changing this value, simply changes the interval in between heartbeats.
+ </p>
+ </attribute>
+ <attribute name="mcastDropTime" required="false">
+ <p>
+ The membership component will time out members and notify the Channel if a member fails to send a heartbeat within
+ a give time. The default value is <code>3000</code> ms. This means, that if a heartbeat is not received from a
+ member in that timeframe, the membership component will notify the cluster of this.<br/>
+ On a high latency network you may wish to increase this value, to protect against false positives.<br/>
+ Apache Tribes also provides a <a href="cluster-interceptor.html#tcpfailuredetector"><code>TcpFailureDetector</code></a> that will
+ verify a timeout using a TCP connection when a heartbeat timeout has occurred. This protects against false positives.
+ </p>
+ </attribute>
+ <attribute name="mcastBindAddress" required="false">
+ <p>
+ Use this attribute if you wish to bind your multicast traffic to a specific network interface.
+ By default, or when this attribute is unset, it tries to bind to <code>0.0.0.0</code> and sometimes on multihomed hosts
+ this becomes a problem.
+ </p>
+ </attribute>
+ <attribute name="mcastTTL" required="false">
+ <p>
+ The time-to-live setting for the multicast heartbeats.
+ This setting should be a value between 0 and 255. The default value is VM implementation specific.
+ </p>
+ </attribute>
+ <attribute name="domain" required="false">
+ <p>
+ Apache Tribes has the ability to logically group members into domains, by using this domain attribute.
+ The <code>org.apache.catalina.tribes.Member.getDomain()</code> method returns the value specified here.
+ </p>
+ </attribute>
+ <attribute name="mcastSoTimeout" required="false">
+ <p>
+ The sending and receiving of heartbeats is done on a single thread, hence to avoid blocking this thread forever,
+ you can control the <code>SO_TIMEOUT</code> value on this socket.<br/>
+ If a value smaller or equal to 0 is presented, the code will default this value to mcastFrequency
+ </p>
</attribute>
</section>
<section name="Nested Components">
<p><b><a href="cluster-manager.html">Manager</a>:</b> <br/>
- The manager element identifies what kind of session manager is used in this cluster implementation.
+ The session manager element identifies what kind of session manager is used in this cluster implementation.
This manager configuration is identical to the one you would use in a regular <code><a href="context.html#Nested%20xComponents"><Context></a></code> configuration.
<br/>The default value is the <code>org.apache.catalina.ha.session.DeltaManager</code> that is closely coupled with
the <code>SimpleTcpCluster</code> implementation. Other managers like the <code>org.apache.catalina.ha.session.BackupManager</code>
<p><b><a href="cluster-channel.html">Channel</a>:</b> <br/>
The Channel and its sub components are all part of the IO layer
for the cluster group, and is a module in it's own that we have nick named "Tribes"
- <br/>Any configuring and tuning of the network layer will be done in the channel and its nested components.
- You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
-
- </p>
- <p><b><a href="cluster-membership.html">Channel/Membership</a>:</b> <br/>
- The Membership component is responsible for auto discovering new nodes in the cluster
- and also to provide for notifications for any nodes that have not responded with a heartbeat.
- The default implementation uses multicast.<br/>
- You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
- </p>
- <p><b><a href="cluster-sender.html">Channel/Sender</a>:</b> <br/>
- The Sender component manages all outbound connections and data messages that are sent
- over the network from one node to another.
- This component allows messages to be sent in parallel.
- The default implementation uses TCP client sockets.<br/>
- You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
- </p>
- <p><b><a href="cluster-sender.html#transport">Channel/Sender/Transport</a>:</b> <br/>
- The Transport component is the bottom IO layer for the sender component.
- The default implementation uses non-blocking TCP client sockets.<br/>
- You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
- </p>
- <p><b><a href="cluster-receiver.html">Channel/Receiver</a>:</b> <br/>
- The receiver component listens for messages from other nodes.
- Here you will configure the cluster thread pool, as it will dispatch incoming
- messages to a thread pool for faster processing.
- The default implementation uses non-blocking TCP server sockets.<br/>
- You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
- </p>
- <p><b><a href="cluster-interceptor.html">Channel/Interceptor</a>:</b> <br/>
- The channel will send messages through an interceptor stack. Because of this, you have the ability to
- customize the way messages are sent and received, and even how membership is handled.<br/>
+ <br/>
+ Any configuring and tuning of the network layer, the messaging and the membership logic
+ will be done in the channel and its nested components.
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
<p><b><a href="cluster-valve.html">Valve</a>:</b> <br/>
</section>
<section name="Attributes">
- <subsection name="Common Attributes">
+ <subsection name="SimpleTcpCluster Attributes">
<attributes>
<attribute name="className" required="true">
<p>The main cluster class, currently only one is available,
</p>
</attribute>
<attribute name="channelSendOptions" required="true">
- <p>The Tribes channel send options, default is 11
+ <p>The Tribes channel send options, default is 11.<br/>
+ This option is used to set the flag that all messages sent through the
+ SimpleTcpCluster uses. The flag decides how the messages are sent, and is a simple logical OR.<br/>
+
<source>
int options= Channel.SEND_OPTIONS_ASYNCHRONOUS |
Channel.SEND_OPTIONS_SYNCHRONIZED_ACK |
<code>Channel.SEND_OPTIONS_SYNCHRONIZED_ACK = 0x0004</code><br/>
<code>Channel.SEND_OPTIONS_ASYNCHRONOUS = 0x0008</code><br/>
<code>Channel.SEND_OPTIONS_USE_ACK = 0x0002</code><br/>
+ So to use ACK and ASYNC messaging, the flag would be <code>10 (8+2) or 0x000B</code><br/>
</p>
</attribute>
projects / tomcat7.0 / commitdiff