[jboss-cvs] JBossAS SVN: r99521 - projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Jan 18 00:12:11 EST 2010
Author: laubai
Date: 2010-01-18 00:12:10 -0500 (Mon, 18 Jan 2010)
New Revision: 99521
Modified:
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JBoss_Cache_JGroups.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Revision_History.xml
Log:
Corrections to JBoss Cache JGroups chapter.
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml 2010-01-18 04:55:15 UTC (rev 99520)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml 2010-01-18 05:12:10 UTC (rev 99521)
@@ -7,7 +7,7 @@
<subtitle>for JBoss Enterprise Web Platform 5.0</subtitle>
<edition>1</edition>
<issuenum>1</issuenum>
- <pubsnumber>0.4</pubsnumber>
+ <pubsnumber>0.5</pubsnumber>
<productname>JBoss Enterprise Web Platform</productname>
<productnumber>5.0</productnumber>
<!-- <pubdate>, 2009</pubdate> -->
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JBoss_Cache_JGroups.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JBoss_Cache_JGroups.xml 2010-01-18 04:55:15 UTC (rev 99520)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JBoss_Cache_JGroups.xml 2010-01-18 05:12:10 UTC (rev 99521)
@@ -347,7 +347,7 @@
</note>
</section>
- <!--tsuzukeru-->
+
<section id="jbosscache-jgroups-transport-tcp">
<title>TCP configuration</title>
<para>
@@ -567,30 +567,25 @@
sub-elements in the JGroups MBean <literal>Config</literal> element.
</para>
- <!--hajime-->
-
<section id="jbosscache-jgroups-discovery-ping">
<title>PING</title>
<para>
- PING is a discovery protocol that works by either multicasting PING requests to an IP
- multicast address or connecting to a gossip router. As such, PING normally sits on top of
- the UDP or TUNNEL transport protocols. Each node responds with a packet
- <literal>{C, A}</literal>, where <literal>C</literal> is the coordinator's address, and
- <literal>A</literal> is the node's own address. After <varname>timeout</varname> milliseconds
- or <varname>num_initial_members</varname> replies, the joiner determines the coordinator from
- the responses, and sends a JOIN request to it (handled by). If no node responds, it assumes it is
- the first member of a group.
+ <literal>PING</literal> is a discovery protocol that works by either multicasting
+ <literal>PING</literal> requests to an IP multicast address or connecting to a gossip router.
+ As such, <literal>PING</literal> normally sits on top of the UDP or TUNNEL transport protocols.
+ Each node responds with a packet <literal>{C, A}</literal>, where <literal>C</literal> is the
+ coordinator's address, and <literal>A</literal> is the node's own address. After
+ <varname>timeout</varname> milliseconds or <varname>num_initial_members</varname> replies, the
+ joiner determines the coordinator from the responses, and sends a JOIN request to it (handled by).
+ If no node responds, it assumes it is the first member of a group.
</para>
<para>Here is an example PING configuration for IP multicast.
</para>
-
-
- <programlisting>
-<PING timeout="2000"
+
+ <programlisting><![CDATA[<PING timeout="2000"
num_initial_members="2"
- down_thread="false" up_thread="false"/>
- </programlisting>
+ down_thread="false" up_thread="false"/>]]></programlisting>
<para>
Here is another example PING configuration for contacting a Gossip Router.
<programlisting><![CDATA[
@@ -605,50 +600,56 @@
<para>The available attributes in the <literal>PING</literal> element are listed below.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">timeout</emphasis> specifies the maximum number of milliseconds
- to wait for any responses. The default is 3000.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">num_initial_members</emphasis> specifies the maximum number of
- responses to wait for unless timeout has expired. The default is 2.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">gossip_host</emphasis> specifies the host on which the
- GossipRouter is running.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">gossip_port</emphasis> specifies the port on which the
- GossipRouter is listening on.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">gossip_refresh</emphasis> specifies the interval (in
- milliseconds) for the lease from the GossipRouter. The default is 20000.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">initial_hosts</emphasis> is a comma-seperated list of addresses
- (e.g., <literal>host1[12345],host2[23456]</literal>), which are pinged for
- discovery.</para>
- </listitem>
- </itemizedlist>
- <para>If both <literal>gossip_host</literal> and <literal>gossip_port</literal> are defined, the
- cluster uses the GossipRouter for the initial discovery. If the <literal>initial_hosts</literal>
- is specified, the cluster pings that static list of addresses for discovery. Otherwise, the
- cluster uses IP multicasting for discovery.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>timeout</varname></term>
+ <listitem><para>Specifies the maximum number of milliseconds to wait for any responses.
+ The default value is <literal>3000</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>num_initial_members</varname></term>
+ <listitem><para>Specifies the maximum number of responses to wait for unless the
+ <varname>timeout</varname> has expired. The default value is <literal>2</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>gossip_host</varname></term>
+ <listitem><para>Specifies the host on which the <classname>GossipRouter</classname> is running.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>gossip_port</varname></term>
+ <listitem><para>Specifies the port on which the <classname>GossipRouter</classname> is listening.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>gossip_refresh</varname></term>
+ <listitem><para>Specifies the interval, in milliseconds, for the lease from the
+ <classname>GossipRouter</classname>. The default value is <literal>20000</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>initial_hosts</varname></term>
+ <listitem><para>A comma-separated list of addresses to ping for discovery, for example,
+ <literal>host1[12345],host2[23456]</literal>.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>If both <varname>gossip_host</varname> and <varname>gossip_port</varname> are defined, the
+ cluster uses the <classname>GossipRouter</classname> for the initial discovery. If
+ <varname>initial_hosts</varname> is specified, the cluster pings that static list of addresses
+ for discovery. Otherwise, the cluster uses IP multicasting for discovery.</para>
<note>
- <para>The discovery phase returns when the <literal>timeout</literal> ms have elapsed or the
- <literal>num_initial_members</literal> responses have been received.</para>
+ <para>The discovery phase returns when the <varname>timeout</varname> period has elapsed or
+ <varname>num_initial_members</varname> responses have been received.</para>
</note>
</section>
-
-
<section id="jbosscache-jgroups-discovery-tcpgossip">
<title>TCPGOSSIP</title>
- <para>The TCPGOSSIP protocol only works with a GossipRouter. It works essentially the same way as
- the PING protocol configuration with valid <literal>gossip_host</literal> and
- <literal>gossip_port</literal> attributes. It works on top of both UDP and TCP transport protocols. Here is an example.</para>
+ <para>The <literal>TCPGOSSIP</literal> protocol only works with a <classname>GossipRouter</classname>.
+ It works similarly to the <literal>PING</literal> protocol configuration with valid
+ <varname>gossip_host</varname> and <varname>gossip_port</varname> attributes. It works on top of both
+ UDP and TCP transport protocols, like so:</para>
<programlisting><![CDATA[
<TCPGOSSIP timeout="2000"
initial_hosts="192.168.5.1[12000],192.168.0.2[12000]"
@@ -656,62 +657,73 @@
down_thread="false" up_thread="false"/>]]>
</programlisting>
-
<para>The available attributes in the <literal>TCPGOSSIP</literal> element are listed below.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">timeout</emphasis> specifies the maximum number of milliseconds
- to wait for any responses. The default is 3000.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">num_initial_members</emphasis> specifies the maximum number of
- responses to wait for unless timeout has expired. The default is 2.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">initial_hosts</emphasis> is a comma-seperated list of addresses
- (e.g., <literal>host1[12345],host2[23456]</literal>) for GossipRouters to register
- with.</para>
- </listitem>
- </itemizedlist>
+ <variablelist>
+ <varlistentry><term><varname>timeout</varname></term>
+ <listitem>
+ <para>Specifies the maximum number of milliseconds to wait for any responses.
+ The default value is <literal>3000</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><varname>num_initial_members</varname></term>
+ <listitem>
+ <para>Specifies the maximum number of responses to wait for unless <varname>timeout</varname>
+ has expired. The default value is <literal>2</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><varname>initial_hosts</varname></term>
+ <listitem>
+ <para>A comma-seperated list of addresses for <classname>GossipRouter</classname>s to register
+ with, for example, <literal>host1[12345],host2[23456]</literal>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
<section id="jbosscache-jgroups-discovery-tcpping">
<title>TCPPING</title>
- <para>The TCPPING protocol takes a set of known members and ping them for discovery. This is
- essentially a static configuration. It works on top of TCP. Here is an example of the
- <literal>TCPPING</literal> configuration element in the JGroups <literal>Config</literal>
- element.</para>
- <programlisting>
-<TCPPING timeout="2000"
+ <para>The <literal>TCPPING</literal> protocol takes a set of known members and pings them for
+ discovery. This is a static configuration. It works on top of TCP. Here is an example of the
+ <literal>TCPPING</literal> configuration sub-element in the JGroups <literal>Config</literal>
+ element.</para>
+ <programlisting><![CDATA[<TCPPING timeout="2000"
initial_hosts="hosta[2300],hostb[3400],hostc[4500]"
port_range="3"
num_initial_members="3"
- down_thread="false" up_thread="false"/>
-</programlisting>
+ down_thread="false" up_thread="false"/>]]></programlisting>
-
<para>The available attributes in the <literal>TCPPING</literal> element are listed below.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">timeout</emphasis> specifies the maximum number of milliseconds
- to wait for any responses. The default is 3000.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">num_initial_members</emphasis> specifies the maximum number of
- responses to wait for unless timeout has expired. The default is 2.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">initial_hosts</emphasis> is a comma-seperated list of addresses
- (e.g., <literal>host1[12345],host2[23456]</literal>) for pinging.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">port_range</emphasis> specifies the number of consecutive ports to be probed when getting the initial membership, starting with the port specified in the initial_hosts parameter. Given the current values of port_range and initial_hosts above, the TCPPING layer will try to connect to hosta:2300, hosta:2301, hosta:2302, hostb:3400, hostb:3401, hostb:3402, hostc:4500, hostc:4501, hostc:4502. The configuration options allows for multiple nodes on the same host to be pinged.
- </para>
- </listitem>
- </itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term><varname>timeout</varname></term>
+ <listitem><para>Specifies the maximum number of milliseconds to wait for any responses.
+ The default value is <literal>3000</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>num_initial_members</varname></term>
+ <listitem><para>Specifies the maximum number of responses to wait for unless the
+ <varname>timeout</varname> has expired. The default value is <literal>2</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>initial_hosts</varname></term>
+ <listitem><para>A comma-separated list of addresses to ping fgor discovery, for example,
+ <literal>host1[12345],host2[23456]</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>port_range</varname></term>
+ <listitem><para>Specifies the number of consecutive ports to be probed when getting the
+ initial membership, starting from the port specified in the <varname>initial_hosts</varname>
+ parameter. Given the values of <varname>port_range</varname> and <varname>initial_hosts</varname>
+ given in the example code, the <literal>TCPPING</literal> layer will try to connect to
+ <literal>hosta:2300</literal>, <literal>hosta:2301</literal>, <literal>hosta:2302</literal>,
+ <literal>hostb:3400</literal>, <literal>hostb:3401</literal>, <literal>hostb:3402</literal>,
+ <literal>hostc:4500</literal>, <literal>hostc:4501</literal> and <literal>hostc:4502</literal>.
+ The configuration options allow for multiple nodes on the same host to be pinged.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
</section>
@@ -720,43 +732,74 @@
<section id="jbosscache-jgroups-discovery-mping">
<title>MPING</title>
<para>
- MPING uses IP multicast to discover the initial membership. It can be used with all transports, but usually this is used in combination with TCP. TCP usually requires TCPPING, which has to list all group members explicitly, but MPING doesn't have this requirement. The typical use case for this is when we want TCP as transport, but multicasting for discovery so we don't have to define a static list of initial hosts in TCPPING or require external Gossip Router.
+ <literal>MPING</literal> uses IP multicast to discover the initial membership. It can be used
+ with all transports, but usually this is used in combination with TCP. TCP usually requires
+ <literal>TCPPING</literal>, which has to list all group members explicitly, but <literal>MPING</literal>
+ does not have this requirement. The typical use case for this is when we want TCP as transport,
+ but multicasting for discovery so we don't have to define a static list of initial hosts in
+ <literal>TCPPING</literal> or require an external <classname>GossipRouter</classname>.
</para>
-<programlisting>
-<MPING timeout="2000"
+<programlisting><![CDATA[<MPING timeout="2000"
bind_to_all_interfaces="true"
mcast_addr="228.8.8.8"
mcast_port="7500"
ip_ttl="8"
num_initial_members="3"
- down_thread="false" up_thread="false"/>
-</programlisting>
+ down_thread="false" up_thread="false"/>]]></programlisting>
<para>The available attributes in the <literal>MPING</literal> element are listed below.</para>
- <itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term><varname>timeout</varname></term>
+ <listitem><para>Specifies the maximum number of milliseconds to wait for any responses.
+ The default value is <literal>3000</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>num_initial_members</varname></term>
+ <listitem><para>Specifies the maximum number of responses to wait for unless
+ <varname>timeout</varname> has expired. The default value is <literal>2</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>bind_addr</varname></term>
+ <listitem><para>Specifies the interface on which to send and receive multicast packets.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>bind_to_all_interfaces</varname></term>
+ <listitem><para>Overrides the <varname>bind_addr</varname> value and uses all interfaces
+ in multihome nodes.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>mcast_addr</varname></term>
<listitem>
- <para><emphasis role="bold">timeout</emphasis> specifies the maximum number of milliseconds
- to wait for any responses. The default is 3000.</para>
+ <para>
+ Specifies the multicast address <!--(class D)--> for joining a cluster. If omitted,
+ the default is <literal>228.8.8.8</literal>.
+ </para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>mcast_port</varname></term>
<listitem>
- <para><emphasis role="bold">num_initial_members</emphasis> specifies the maximum number of
- responses to wait for unless timeout has expired. The default is 2..</para>
+ <para>
+ Specifies the multicast port number. If omitted, the default is
+ <literal>45566</literal>.
+ </para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>ip_ttl</varname></term>
<listitem>
- <para><emphasis role="bold">bind_addr</emphasis> specifies the interface on which to send
- and receive multicast packets.</para>
+ <para>
+ Specifies the <emphasis>time to live</emphasis> (TTL) for IP multicast packets.
+ TTL is the common term in multicast networking, but the value actually refers to
+ how many network hops a packet will be allowed to travel before networking
+ equipment drops it.
+ </para>
</listitem>
- <listitem>
- <para><emphasis role="bold">bind_to_all_interfaces</emphasis> overrides the
- <literal>bind_addr</literal> and uses all interfaces in multihome nodes.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">mcast_addr, mcast_port, ip_ttl</emphasis> attributes are the
- same as related attributes in the UDP protocol configuration.</para>
- </listitem>
- </itemizedlist>
+ </varlistentry>
+ </variablelist>
</section>
</section>
@@ -764,44 +807,55 @@
<section id="jbosscache-jgroups-fd">
<title>Failure Detection Protocols</title>
- <para>The failure detection protocols are used to detect failed nodes. Once a failed node is detected, a suspect verification phase can occur after which, if the node is still considered dead, the cluster updates its view so that the load balancer and client interceptors know to avoid the dead node. The failure detection protocols are configured as sub-elements in the JGroups MBean
- <literal>Config</literal> element.</para>
+ <para>The failure detection protocols are used to detect failed nodes. Once a failed node is detected,
+ a suspect verification phase can occur. If the node is still considered dead after this phase, the
+ cluster updates its view so that the load balancer and client interceptors know to avoid the dead node.
+ The failure detection protocols are configured as sub-elements in the JGroups MBean
+ <literal>Config</literal> element.</para>
<section id="jbosscache-jgroups-fd-fd">
<title>FD</title>
<para>
- FD is a failure detection protocol based on heartbeat messages. This protocol requires each node to periodically send are-you-alive messages to its neighbour. If the neighbour fails to respond, the calling node sends a SUSPECT message to the cluster. The current group coordinator can optionally double check whether the suspected node is indeed dead after which, if the node is still considered dead, updates the cluster's view. Here is an example FD configuration.
+ <literal>FD</literal> is a failure detection protocol based on <emphasis>heartbeat</emphasis>
+ messages. This protocol requires each node to periodically send messages to its neighbour to check
+ that the neighbour is alive. If the neighbour fails to respond, the calling node sends a SUSPECT
+ message to the cluster.
+ The current group coordinator can optionally double check whether the suspected node is indeed
+ dead. If the node is still considered dead after this check, the group coordinator updates the
+ cluster's view. Here is an example FD configuration:
</para>
-<programlisting>
-<FD timeout="2000"
+<programlisting><![CDATA[<FD timeout="2000"
max_tries="3"
shun="true"
- down_thread="false" up_thread="false"/>
-</programlisting>
+ down_thread="false" up_thread="false"/>]]></programlisting>
-
- <para>The available attributes in the <literal>FD</literal> element are listed below.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">timeout</emphasis> specifies the maximum number of milliseconds
- to wait for the responses to the are-you-alive messages. The default is 3000.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">max_tries</emphasis> specifies the number of missed
- are-you-alive messages from a node before the node is suspected. The default is 2.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">shun</emphasis> specifies whether a failed node will be shunned.
- Once shunned, the node will be expelled from the cluster even if it comes back later.
- The shunned node would have to re-join the cluster through the discovery process. JGroups allows to configure itself such that shunning leads to automatic rejoins and state transfer, which is the default behaivour within JBoss Application Server.</para>
- </listitem>
- </itemizedlist>
+ <para>The available attributes in the <literal>FD</literal> element are listed below.</para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>timeout</varname></term>
+ <listitem><para>Specifies the maximum number of milliseconds to wait for a response to
+ the heartbeat messages. The default value is <literal>3000</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>max_tries</varname></term>
+ <listitem><para>Specifies the number of heartbeat messages that a node can fail to reply to
+ before the node is suspected. The default value is <literal>2</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>shun</varname></term>
+ <listitem><para>Specifiees whether a failed node will be shunned. Once shunned, the node will
+ be expelled from the cluster even if it is later revived. The shunned node would have to rejoin
+ the cluster through the discovery process. You can configure JGroups so that shunning leads to
+ automatic rejoins and state transfer (the default behavior).</para></listitem>
+ </varlistentry>
+ </variablelist>
+
<note>
- <para>Regular traffic from a node counts as if it is a live. So, the are-you-alive messages are
- only sent when there is no regular traffic to the node for sometime.</para>
+ <para>Normal node traffic is considered proof of life, so heartbeat messages are
+ sent only when there is no normal traffic to the node for some time.</para>
</note>
</section>
@@ -811,27 +865,37 @@
<section id="jbosscache-jgroups-fd-fdsock">
<title>FD_SOCK</title>
<para>
-FD_SOCK is a failure detection protocol based on a ring of TCP sockets created between group members. Each member in a group connects to its neighbor (last member connects to first) thus forming a ring. Member B is suspected when its neighbor A detects abnormally closed TCP socket (presumably due to a node B crash). However, if a member B is about to leave gracefully, it lets its neighbor A know, so that it does not become suspected. The simplest FD_SOCK configuration does not take any attribute. You can just declare an empty <literal>FD_SOCK</literal> element in JGroups's <literal>Config</literal> element.</para>
+ <literal>FD_SOCK</literal> is a failure detection protocol based on a ring of TCP sockets
+ created between group members. Each member in a group connects to its neighbor (last member
+ connects to first) thus forming a ring. Member B is suspected when its neighbor A detects an
+ abnormally closed TCP socket (presumably due to a node B crash). However, if a member B is
+ about to leave gracefully, it lets its neighbor A know, so that it does not become suspected.
+ The simplest <literal>FD_SOCK</literal> configuration does not take any attribute. You can
+ just declare an empty <literal>FD_SOCK</literal> element in JGroups's
+ <literal>Config</literal> element.</para>
-
-<programlisting>
-<FD_SOCK_down_thread="false" up_thread="false"/>
-</programlisting>
+<programlisting><![CDATA[<FD_SOCK down_thread="false" up_thread="false"/>]]></programlisting>
<para>There available attributes in the <literal>FD_SOCK</literal> element are listed below.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">bind_addr</emphasis> specifies the interface to which the server socket should bind to. If -Djgroups.bind_address system property is defined, XML value will be ignore. This behaivour can be reversed setting -Djgroups.ignore.bind_addr=true system property.</para>
- </listitem>
- </itemizedlist>
-
- </section>
+ <variablelist>
+ <varlistentry>
+ <term><varname>bind_addr</varname></term>
+ <listitem><para>Specifies the interface to which the server socket should bind. If
+ <code>-Djgroups.bind_address</code> system property is defined, this XML value will be ignored.
+ This behavior can be reversed by setting the <code>-Djgroups.ignore.bind_addr=true</code>
+ system property.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
<section><title>VERIFY_SUSPECT</title>
<para>
- This protocol verifies whether a suspected member is really dead by pinging that member once again. This verification is performed by the coordinator of the cluster. The suspected member is dropped from the cluster group if confirmed to be dead. The aim of this protocol is to minimize false suspicions. Here's an example.
+ This protocol verifies that a suspected member is dead by pinging them a second time.
+ This verification is performed by the coordinator of the cluster. The suspected member
+ is dropped from the cluster group if confirmed dead. The aim of this protocol is to
+ minimize false suspicions. See the following code for an example:
</para>
<programlisting><![CDATA[
@@ -840,16 +904,15 @@
</programlisting>
<para>
- The available attributes in the FD_SOCK element are listed below.
+ The available attributes in the VERIFY_SUSPECT element are listed below.
</para>
- <itemizedlist>
- <listitem>
- <para>
- timeout specifies how long to wait for a response from the suspected member before considering it dead.
- </para>
-</listitem>
-</itemizedlist>
-
+ <variablelist>
+ <varlistentry>
+ <term><varname>timeout</varname></term>
+ <listitem><para>Specifies how long to wait for a response from the suspected member before
+ considering it dead.</para></listitem>
+ </varlistentry>
+ </variablelist>
</section>
@@ -857,255 +920,254 @@
<section><title>FD versus FD_SOCK</title>
<para>
- FD and FD_SOCK, each taken individually, do not provide a solid failure detection layer. Let's look at the the differences between these failure detection protocols to understand how they complement each other:
+ <literal>FD</literal> and <literal>FD_SOCK</literal> do not individually provide a solid
+ failure detection layer. Their differences are outlined below to show how they complement
+ each other.
</para>
- <itemizedlist>
- <listitem><para><emphasis>FD</emphasis></para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- An overloaded machine might be slow in sending are-you-alive responses.
- </para>
- </listitem>
- <listitem>
- <para>
- A member will be suspected when suspended in a debugger/profiler.
- </para>
- </listitem>
- <listitem>
- <para>
- Low timeouts lead to higher probability of false suspicions and higher network traffic.
- </para>
- </listitem>
- <listitem>
- <para>
- High timeouts will not detect and remove crashed members for some time.
- </para>
- </listitem>
-</itemizedlist>
+ <itemizedlist>
+ <title><literal>FD</literal></title>
+ <listitem>
+ <para>An overloaded machine might be slow in sending heartbeat responses.</para>
+ </listitem>
+ <listitem>
+ <para>A member will become suspected when suspended in a debugger or profiler.</para>
+ </listitem>
+ <listitem>
+ <para>Low timeouts lead to a higher probability of false suspicions and
+ higher network traffic.</para>
+ </listitem>
+ <listitem>
+ <para>High timeouts will not detect and remove crashed members for a long
+ period of time.</para>
+ </listitem>
+ </itemizedlist>
-<itemizedlist>
-<listitem><para><emphasis>FD_SOCK</emphasis>:</para>
-</listitem>
-</itemizedlist>
+ <itemizedlist>
+ <title><literal>FD_SOCK</literal></title>
+ <listitem>
+ <para>Suspension in a debugger does not mean a member will become suspected
+ because the TCP connection remains open.</para>
+ </listitem>
+ <listitem>
+ <para>High load is not a problem for the same reason.</para>
+ </listitem>
+ <listitem>
+ <para>Members will be suspected only when the TCP connection breaks, so hung
+ members will not be detected.</para>
+ </listitem>
+ <listitem>
+ <para>A crashed switch will not be detected until the connection encounters
+ the TCP timeout (between two and twenty minutes, depending on TCP/IP
+ stack implementation).</para>
+ </listitem>
+ </itemizedlist>
-<itemizedlist>
- <listitem>
- <para>
- Suspended in a debugger is no problem because the TCP connection is still open.
- </para>
- </listitem>
- <listitem>
- <para>
- High load no problem either for the same reason.
- </para>
- </listitem>
- <listitem>
- <para>
- Members will only be suspected when TCP connection breaks
- </para>
- </listitem>
-</itemizedlist>
+ <para>
+ A failure detection layer aims to report real failures and avoid reporting false
+ suspicions. Two methods of achieving this are outlined in the following paragraphs.
+ </para>
+ <para>
+ By default, JGroups configures the <varname>FD_SOCK</varname> socket with
+ <literal>KEEP_ALIVE</literal>, which means that TCP sends a heartbeat to a socket
+ that has received no traffic in two hours. If a host or immediate switch or router
+ crashed without closing the TCP connection properly, it would be detected shortly
+ after two hours. This is better than never closing the connection (where
+ <literal>KEEP_ALIVE</literal> is off), but may not be helpful. The first solution,
+ therefore, is to lower the timeout value for <literal>KEEP_ALIVE</literal>. This is
+ a kernel-wide value on most operating systems and therefore affects all TCP sockets.
+ </para>
- <itemizedlist>
- <listitem>
- <para>
- So hung members will not be detected.
- </para>
- </listitem>
- <listitem>
- <para>
-
- Also, a crashed switch will not be detected until the connection runs into the TCP timeout (between 2-20 minutes, depending on TCP/IP stack implementation).
- </para>
- </listitem>
-</itemizedlist>
-
-<para>
- The aim of a failure detection layer is to report real failures and therefore avoid false suspicions. There are two solutions:
- </para>
- <orderedlist>
- <listitem>
- <para>
- By default, JGroups configures the FD_SOCK socket with KEEP_ALIVE, which means that TCP sends a heartbeat on socket on which no traffic has been received in 2 hours. If a host crashed (or an intermediate switch or router crashed) without closing the TCP connection properly, we would detect this after 2 hours (plus a few minutes). This is of course better than never closing the connection (if KEEP_ALIVE is off), but may not be of much help. So, the first solution would be to lower the timeout value for KEEP_ALIVE. This can only be done for the entire kernel in most operating systems, so if this is lowered to 15 minutes, this will affect all TCP sockets.
- </para>
- </listitem>
- <listitem>
- <para>
- The second solution is to combine FD_SOCK and FD; the timeout in FD can be set such that it is much lower than the TCP timeout, and this can be configured individually per process. FD_SOCK will already generate a suspect message if the socket was closed abnormally. However, in the case of a crashed switch or host, FD will make sure the socket is eventually closed and the suspect message generated. Example:
- </para>
- </listitem>
-</orderedlist>
-<programlisting><![CDATA[
-<FD_SOCK down_thread="false" up_thread="false"/>
+ <para>
+ Alternatively, you can combine <literal>FD_SOCK</literal> and <literal>FD</literal>.
+ The <varname>timeout</varname> in FD can be set such that it is much lower than the TCP
+ <varname>timeout</varname>. This can be configured on a per-process basis.
+ <literal>FD_SOCK</literal> generates a SUSPECT message if the socket closes abnormally,
+ but in the case of a crashed switch or host, <literal>FD</literal> ensures that the
+ socket is eventually closed, and a suspect message generated.
+ </para>
+ <para>
+ The following code shows how the two could be combined:
+ </para>
+ <programlisting><![CDATA[<FD_SOCK down_thread="false" up_thread="false"/>
<FD timeout="10000" max_tries="5" shun="true"
-down_thread="false" up_thread="false" /> ]]>
-</programlisting>
+down_thread="false" up_thread="false" /> ]]></programlisting>
+ <para>
+ This code suspects a member when the socket to its neighbour has been closed abnormally
+ (for example, in a process crash, since the operating system closes all sockets).
+ However, if a host or switch crashes, the sockets would not be closed. As a secondary
+ line of defense, <literal>FD</literal> suspects the neighbour after <literal>50</literal>
+ seconds. Note that if you use this example code and your system is stopped in a debugging
+ breakpoint, the node you are debugging will be suspected after the specified fifty seconds.
+ </para>
-<para>
- This suspects a member when the socket to the neighbor has been closed abonormally (e.g. process crash, because the OS closes all sockets). However, f a host or switch crashes, then the sockets won't be closed, therefore, as a seond line of defense, FD will suspect the neighbor after 50 seconds. Note that with this example, if you have your system stopped in a breakpoint in the debugger, the node you're debugging will be suspected after ca 50 seconds.
+ <para>
+ Combining <literal>FD</literal> and <literal>FD_SOCK</literal> provides a solid failure detection
+ layer. This technique is used across the JGroups configurations included in
+ JBoss Enterprise Web Platform.
</para>
-<para>
- A combination of FD and FD_SOCK provides a solid failure detection layer and for this reason, such technique is used accross JGroups configurations included within JBoss Application Server.
- </para>
</section>
- </section>
+ </section>
<section id="jbosscache-jgroups-reliable">
<title>Reliable Delivery Protocols</title>
- <para>
- Reliable delivery protocols within the JGroups stack ensure that data pockets are actually delivered in the right order (FIFO) to the destination node. The basis for reliable message delivery is positive and negative delivery acknowledgments (ACK and NAK). In the ACK mode, the sender resends the message until the acknowledgment is received from the receiver. In the NAK mode, the receiver requests retransmission when it discovers a gap.
- </para>
-
-
-
+ <para>
+ Reliable delivery protocols within the JGroups stack ensure that data packets are delivered
+ in the correct order (FIFO) to the destination node. The basis for reliable message delivery
+ is positive and negative delivery acknowledgments: respectively, <literal>ACK</literal>
+ and <literal>NAK</literal>. In <literal>ACK</literal> mode, the sender resends the message
+ until acknowledgement is received. In <literal>NAK</literal> mode, the receiver requests
+ retransmission when it discovers a gap.
+ </para>
+
<section id="jbosscache-jgroups-reliable-unicast">
<title>UNICAST</title>
<para>
- The UNICAST protocol is used for unicast messages. It uses ACK. It is configured as a sub-element under the JGroups Config element. If the JGroups stack is configured with TCP transport protocol, UNICAST is not necessary because TCP itself guarantees FIFO delivery of unicast messages. Here is an example configuration for the <literal>UNICAST</literal> protocol.</para>
+ The <literal>UNICAST</literal> protocol is used for unicast messages. It uses
+ <literal>ACK</literal>. It is configured as a sub-element under the JGroups
+ <literal>Config</literal> element. <literal>UNICAST</literal> is not required for
+ JGroups stacks configured with the TCP transport protocol, since TCP guarantees
+ FIFO delivery of unicast messages. The following is an example of
+ <literal>UNICAST</literal> protocol:</para>
-<programlisting>
-<UNICAST timeout="100,200,400,800"
-down_thread="false" up_thread="false"/>
-</programlisting>
+<programlisting><![CDATA[<UNICAST timeout="100,200,400,800"
+down_thread="false" up_thread="false"/>]]></programlisting>
-<para>There is only one configurable attribute in the <literal>UNICAST</literal> element.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">timeout</emphasis> specifies the retransmission timeout (in
- milliseconds). For instance, if the timeout is "100,200,400,800", the sender resends the
- message if it hasn't received an ACK after 100 ms the first time, and the second time it
- waits for 200 ms before resending, and so on.</para>
- </listitem>
- </itemizedlist>
+ <para>There is only one configurable attribute in the <literal>UNICAST</literal> element.</para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>timeout</varname></term>
+ <listitem><para>Specifies the retransmission timeout in milliseconds. For example,
+ if the timeout is <literal>"100,200,400,800"</literal>, the sender resends the message
+ if it has not received an <literal>ACK</literal> after 100 milliseconds the first time,
+ 200 milliseconds the second time, and so on.</para></listitem>
+ </varlistentry>
+ </variablelist>
</section>
-
-
+
<section id="jbosscache-jgroups-reliable-nakack">
<title>NAKACK</title>
- <para>The NAKACK protocol is used for multicast messages. It uses NAK. Under this protocol, each
- message is tagged with a sequence number. The receiver keeps track of the sequence numbers and
- deliver the messages in order. When a gap in the sequence number is detected, the receiver asks
- the sender to retransmit the missing message. The NAKACK protocol is configured as the
- <literal>pbcast.NAKACK</literal> sub-element under the JGroups <literal>Config</literal>
- element. Here is an example configuration.</para>
+ <para>The <literal>NAKACK</literal> protocol is used for multicast messages. It uses
+ <literal>NAK</literal>. Under this protocol, each message is tagged with a sequence number.
+ The receiver tracks the sequence numbers to deliver the messages in order. When a gap in the
+ sequence is detected, the receiver asks the sender to retransmit the missing message. The
+ <literal>NAKACK</literal> protocol is configured as the <literal>pbcast.NAKACK</literal>
+ sub-element under the JGroups <literal>Config</literal> element, like so:</para>
-<programlisting>
-<pbcast.NAKACK max_xmit_size="60000" use_mcast_xmit="false"
+ <programlisting><![CDATA[<pbcast.NAKACK max_xmit_size="60000" use_mcast_xmit="false"
retransmit_timeout="300,600,1200,2400,4800" gc_lag="0"
discard_delivered_msgs="true"
- down_thread="false" up_thread="false"/>
-</programlisting>
+ down_thread="false" up_thread="false"/>]]></programlisting>
-<para>The configurable attributes in the <literal>pbcast.NAKACK</literal> element are as follows.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">retransmit_timeout</emphasis> specifies the retransmission
- timeout (in milliseconds). It is the same as the <literal>timeout</literal> attribute in
- the UNICAST protocol.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">use_mcast_xmit</emphasis> determines whether the sender should
- send the retransmission to the entire cluster rather than just the node requesting it.
- This is useful when the sender drops the pocket -- so we do not need to retransmit for
- each node.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">max_xmit_size</emphasis> specifies maximum size for a bundled
- retransmission, if multiple packets are reported missing.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">discard_delivered_msgs</emphasis> specifies whether to discard
- delivery messages on the receiver nodes. By default, we save all delivered messages.
- However, if we only ask the sender to resend their messages, we can enable this option
- and discard delivered messages.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">gc_lag specifies</emphasis> the number of messages garbage collection lags behind.
- </para>
- </listitem>
-
- </itemizedlist>
+ <para>The configurable attributes in the <literal>pbcast.NAKACK</literal> element are as follows.</para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>retransmit_timeout</varname></term>
+ <listitem><para>Specifies the retransmission timeout in milliseconds. This is same as
+ the <varname>timeout</varname> attribute in the <literal>UNICAST</literal> protocol.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>use_mcast_xmit</varname></term>
+ <listitem><para>Determines whether the sender should send retransmit to the entire cluster
+ rather than just the node requesting the retransmit. This is useful when the sender drops
+ the packet, so that we do not need to retransmit for each node.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>max_xmit_size</varname></term>
+ <listitem><para>Specifies maximum size for a bundled retransmission, if multiple packets
+ are reported missing.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>discard_delivered_msgs</varname></term>
+ <listitem><para>Specifies whether to discard delivered messages on receiver nodes. By
+ default, we save all delivered messages. If the sender can resend the message, we can
+ enable this option and discard delivered messages.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>gc_lag</varname></term>
+ <listitem><para>Specifies the number of messages garbage collection lags behind.</para></listitem>
+ </varlistentry>
+ </variablelist>
</section>
</section>
-
-
<section id="jbosscache-jgroups-other">
<title>Other Configuration Options</title>
- <para>In addition to the protocol stacks, you can also configure JGroups network services in the <literal>Config</literal> element.</para>
+ <para>In addition to the protocol stacks, you can also configure JGroups network services in
+ the <literal>Config</literal> element.</para>
-
<section id="jbosscache-jgroups-other-gms">
<title>Group Membership</title>
- <para>The group membership service in the JGroups stack maintains a list of active nodes. It handles
- the requests to join and leave the cluster. It also handles the SUSPECT messages sent by failure
- detection protocols. All nodes in the cluster, as well as the load balancer and client side
- interceptors, are notified if the group membership changes. The group membership service is
- configured in the <literal>pbcast.GMS</literal> sub-element under the JGroups
- <literal>Config</literal> element. Here is an example configuration.</para>
-<programlisting>
-<pbcast.GMS print_local_addr="true"
+ <para>The group membership service in the JGroups stack maintains a list of active nodes.
+ It handles requests to join and leave the cluster. It also handles the SUSPECT messages
+ sent by failure detection protocols. All nodes in the cluster, as well as the load balancer
+ and client side interceptors, are notified if the group membership changes. The group
+ membership service is configured in the <literal>pbcast.GMS</literal> sub-element under the
+ JGroups <literal>Config</literal> element, like so:</para>
+
+ <programlisting><![CDATA[<pbcast.GMS print_local_addr="true"
join_timeout="3000"
down_thread="false" up_thread="false"
join_retry_timeout="2000"
shun="true"
- view_bundling="true"/>
-</programlisting>
-
+ view_bundling="true"/>]]></programlisting>
+ <para>The configurable attributes in the <literal>pbcast.GMS</literal> element are as follows.</para>
-<para>The configurable attributes in the <literal>pbcast.GMS</literal> element are as follows.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">join_timeout</emphasis> specifies the maximum number of
- milliseconds to wait for a new node JOIN request to succeed. Retry afterwards.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">join_retry_timeout</emphasis> specifies the maximum number of
- milliseconds to wait after a failed JOIN to re-submit it.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">print_local_addr</emphasis> specifies whether to dump the node's
- own address to the output when started.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">shun</emphasis> specifies whether a node should shun itself if
- it receives a cluster view that it is not a member node.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">disable_initial_coord</emphasis> specifies whether to prevent
- this node as the cluster coordinator.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">view_bundling</emphasis> specifies whether multiple JOIN or LEAVE request arriving at the same time are bundled and handled together at the same time, only sending out 1 new view / bundle. This is is more efficient than handling each request separately.
- </para>
- </listitem>
-
- </itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term><varname>join_timeout</varname></term>
+ <listitem><para>Specifies the maximum number of milliseconds to wait for a new node
+ <literal>JOIN</literal> request to succeed. Retries afterward.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>join_retry_timeout</varname></term>
+ <listitem><para>Sepcifies the maximum numver of milliseconds to wait after a failed
+ <literal>JOIN</literal> request to resubmit the request.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>print_local_addr</varname></term>
+ <listitem><para>Specifies whether to dump the node's own address to the output
+ when started.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>shun</varname></term>
+ <listitem><para>Specifies whether a node should shun itself if it receives a cluster view
+ that is not a member node.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>disable_initial_coord</varname></term>
+ <listitem><para>Specifies whether to prevent this node from becoming the cluster
+ coordinator.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>view_bundling</varname></term>
+ <listitem><para>Specifies whether multiple <literal>JOIN</literal> or
+ <literal>LEAVE</literal> requests arriving at the same time are bundled together
+ and handled at the same time. This is more efficient than handling each request
+ separately, as it sends only one new view.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
</section>
<section id="jbosscache-jgroups-other-fc">
<title>Flow Control</title>
<para>The flow control service tries to adapt the sending data rate and the receiving data among
- nodes. If a sender node is too fast, it might overwhelm the receiver node and result in dropped
- packets that have to be retransmitted. In JGroups, the flow control is implemented via a
- credit-based system. The sender and receiver nodes have the same number of credits (bytes) to
- start with. The sender subtracts credits by the number of bytes in messages it sends. The
- receiver accumulates credits for the bytes in the messages it receives. When the sender's credit
- drops to a threshold, the receivers sends some credit to the sender. If the sender's credit is
- used up, the sender blocks until it receives credits from the receiver. The flow control service
- is configured in the <literal>FC</literal> sub-element under the JGroups
- <literal>Config</literal> element. Here is an example configuration.</para>
+ nodes. If a sender node is too fast, it might overwhelm the receiver node and result in dropped
+ packets that have to be retransmitted. In JGroups, the flow control is implemented via a
+ credit-based system. The sender and receiver nodes have the same number of credits (bytes) to
+ start with. The sender subtracts credits by the number of bytes in messages it sends. The
+ receiver accumulates credits for the bytes in the messages it receives. When the sender's credit
+ drops to a threshold, the receivers sends some credit to the sender. If the sender's credit is
+ used up, the sender blocks until it receives credits from the receiver. The flow control service
+ is configured in the <literal>FC</literal> sub-element under the JGroups
+ <literal>Config</literal> element. Here is an example configuration.</para>
<programlisting>
<FC max_credits="1000000"
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Revision_History.xml 2010-01-18 04:55:15 UTC (rev 99520)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Revision_History.xml 2010-01-18 05:12:10 UTC (rev 99521)
@@ -8,7 +8,7 @@
<simpara>
<revhistory>
<revision>
- <revnumber>1.5</revnumber>
+ <revnumber>1.6</revnumber>
<date>Wed Jan 13 2010</date>
<author>
<firstname>Laura</firstname>
More information about the jboss-cvs-commits
mailing list