From: fhanik Date: Tue, 10 Oct 2006 21:51:00 +0000 (+0000) Subject: Updates to documentation, X-Git-Url: https://git.internetallee.de/?a=commitdiff_plain;h=d7ff85531bd128c2a1c417f14c54530da24040de;p=tomcat7.0 Updates to documentation, git-svn-id: https://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk@462593 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/webapps/docs/cluster-howto.xml b/webapps/docs/cluster-howto.xml index b8d67b657..5ba844094 100644 --- a/webapps/docs/cluster-howto.xml +++ b/webapps/docs/cluster-howto.xml @@ -16,6 +16,9 @@
+

This document is pending an update to the latest implementation.
+ You can also check the configuration reference documentation. +

To run session replication in your Tomcat 5.5 container, the following steps should be completed:

diff --git a/webapps/docs/config/cluster-channel.xml b/webapps/docs/config/cluster-channel.xml index 22218ee64..5445cd3ea 100644 --- a/webapps/docs/config/cluster-channel.xml +++ b/webapps/docs/config/cluster-channel.xml @@ -15,9 +15,48 @@
- - - + The cluster channel is the main component of a small framework we've nicknamed Apache Tribes.
+ The channel manages a set of sub components and together they create a group communication framework.
+ This framework is then used internally by the components that need to send messages between different Tomcat instances. +
+ 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. +
+
+

Channel/Membership:
+ 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.
+ 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 Apache Tribes +

+

Channel/Sender:
+ 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.
+ You can always find out more about Apache Tribes +

+

Channel/Sender/Transport:
+ The Transport component is the bottom IO layer for the sender component. + The default implementation uses non-blocking TCP client sockets.
+ You can always find out more about Apache Tribes +

+

Channel/Receiver:
+ 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.
+ You can always find out more about Apache Tribes +

+

Channel/Interceptor:
+ 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.
+ You can always find out more about Apache Tribes +

@@ -28,7 +67,8 @@ - + The default value here is org.apache.catalina.tribes.group.GroupChannel and is + currently the only implementation available. diff --git a/webapps/docs/config/cluster-membership.xml b/webapps/docs/config/cluster-membership.xml index ae0df6209..bedd8c62c 100644 --- a/webapps/docs/config/cluster-membership.xml +++ b/webapps/docs/config/cluster-membership.xml @@ -15,20 +15,98 @@
+

+ The membership component in the Apache Tribes Channel is responsible + for dynamic discovery of other members(nodes) in the cluster. +

+
- - +
+

+ 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 (mcastFrequency), and this + heartbeat is used for dynamic discovery. + In a similar fashion, if a heartbeat has not been received in a timeframe specified by mcastDropTime + ms. a member is considered suspect and the channel and any membership listener will be notified. +

+
- + - +

+ The default value is org.apache.catalina.tribes.membership.McastService + and is currently the only implementation. + This implementation uses multicast heartbeats for member discovery. +

+ + +

+ The multicast address that the membership will broadcast its presence and listen + for other heartbeats on. The default value is 228.0.0.4 + Make sure your network is enabled for multicast traffic.
+ The multicast address, in conjunction with the mcastPort is what + creates a cluster group. To divide up your farm into several different group, or to + split up QA from production, change the mcastPort or the mcastAddr +

+ + +

+ The multicast port, the default value is 45564
+ The multicast port, in conjunction with the mcastAddr is what + creates a cluster group. To divide up your farm into several different group, or to + split up QA from production, change the mcastPort or the mcastAddr +

+ + +

+ The frequency in milliseconds in which heartbeats are sent out. The default value is 500 ms.
+ In most cases the default value is sufficient. Changing this value, simply changes the interval in between heartbeats. +

+ + +

+ 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 3000 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.
+ On a high latency network you may wish to increase this value, to protect against false positives.
+ Apache Tribes also provides a TcpFailureDetector that will + verify a timeout using a TCP connection when a heartbeat timeout has occurred. This protects against false positives. +

+ + +

+ 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 0.0.0.0 and sometimes on multihomed hosts + this becomes a problem. +

+ + +

+ 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. +

+ + +

+ Apache Tribes has the ability to logically group members into domains, by using this domain attribute. + The org.apache.catalina.tribes.Member.getDomain() method returns the value specified here. +

+ + +

+ The sending and receiving of heartbeats is done on a single thread, hence to avoid blocking this thread forever, + you can control the SO_TIMEOUT value on this socket.
+ If a value smaller or equal to 0 is presented, the code will default this value to mcastFrequency +

diff --git a/webapps/docs/config/cluster.xml b/webapps/docs/config/cluster.xml index bcdeae78d..9673fa7f9 100644 --- a/webapps/docs/config/cluster.xml +++ b/webapps/docs/config/cluster.xml @@ -34,7 +34,7 @@

Manager:
- 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 <Context> configuration.
The default value is the org.apache.catalina.ha.session.DeltaManager that is closely coupled with the SimpleTcpCluster implementation. Other managers like the org.apache.catalina.ha.session.BackupManager @@ -43,38 +43,9 @@

Channel:
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" -
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 Apache Tribes - -

-

Channel/Membership:
- 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.
- You can always find out more about Apache Tribes -

-

Channel/Sender:
- 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.
- You can always find out more about Apache Tribes -

-

Channel/Sender/Transport:
- The Transport component is the bottom IO layer for the sender component. - The default implementation uses non-blocking TCP client sockets.
- You can always find out more about Apache Tribes -

-

Channel/Receiver:
- 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.
- You can always find out more about Apache Tribes -

-

Channel/Interceptor:
- 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.
+
+ 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 Apache Tribes

Valve:
@@ -103,7 +74,7 @@

- +

The main cluster class, currently only one is available, @@ -111,7 +82,10 @@

-

The Tribes channel send options, default is 11 +

The Tribes channel send options, default is 11.
+ 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.
+ int options= Channel.SEND_OPTIONS_ASYNCHRONOUS | Channel.SEND_OPTIONS_SYNCHRONIZED_ACK | @@ -121,6 +95,7 @@ Channel.SEND_OPTIONS_SYNCHRONIZED_ACK = 0x0004
Channel.SEND_OPTIONS_ASYNCHRONOUS = 0x0008
Channel.SEND_OPTIONS_USE_ACK = 0x0002
+ So to use ACK and ASYNC messaging, the flag would be 10 (8+2) or 0x000B