[jboss-cvs] JBossAS SVN: r99645 - 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
Wed Jan 20 03:37:13 EST 2010
Author: laubai
Date: 2010-01-20 03:37:13 -0500 (Wed, 20 Jan 2010)
New Revision: 99645
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_Building_Blocks.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:
Finished correcting Clustering JBoss Cache JGroups chapter in Admin and Config Guide for EWP5.
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-20 07:52:23 UTC (rev 99644)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml 2010-01-20 08:37:13 UTC (rev 99645)
@@ -7,7 +7,7 @@
<subtitle>for JBoss Enterprise Web Platform 5.0</subtitle>
<edition>1</edition>
<issuenum>1</issuenum>
- <pubsnumber>0.7</pubsnumber>
+ <pubsnumber>0.8</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_Building_Blocks.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Building_Blocks.xml 2010-01-20 07:52:23 UTC (rev 99644)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_Building_Blocks.xml 2010-01-20 08:37:13 UTC (rev 99645)
@@ -24,7 +24,7 @@
<title>The JBoss Enterprise Web Platform clustering architecture</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/clustering-as-arch.png" />
+ <imagedata align="center" fileref="images/clustering-as-arch-ewp.png" />
</imageobject>
</mediaobject>
</figure>
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-20 07:52:23 UTC (rev 99644)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JBoss_Cache_JGroups.xml 2010-01-20 08:37:13 UTC (rev 99645)
@@ -177,7 +177,7 @@
ip_ttl="${jgroups.udp.ip_ttl:2}"
down_thread="false" up_thread="false"/>]]>
</programlisting>
-<!--hajime-->
+
<para>The available attributes in the above JGroups configuration are listed below.</para>
<variablelist>
@@ -1533,109 +1533,157 @@
</para>
</section>
-<!--hajime-->
+
<section><title>Changing the Group Name</title>
<para>
-
- The group name for a JGroups channel is configured via the service that starts the channel. Unfortunately, different services use different attribute names for configuring this. For HAPartition and related services configured in the deploy/cluster-service.xml file, this is configured via a PartitionName attribute. For JBoss Cache services, the name of the attribute is ClusterName.
+ A JGroups channel's <emphasis>group name</emphasis> is configured through the service that
+ starts the channel. The attribute used to set the group name differs with the service.
+ For <classname>HAPartition</classname> and other services configured in
+ <filename>deploy/cluster-service.xml</filename>, the group name is configured with the
+ <varname>PartitionName</varname> attribute. For JBoss Cache services, the group name is
+ configured with the <varname>ClusterName</varname> attribute.
</para>
<para>
- For the HAPartition and all the standard JBoss Cache services, we make it easy for you to create unique groups names simply by using the -g (a.k.a. –partition) switch when starting JBoss:
- <screen>./run.sh -g QAPartition -b 192.168.1.100 -c all</screen>
- This switch sets the jboss.partition.name system property, which is used as a component in the configuration of the group name in all the standard clustering configuration files. For example,
+ Use the <code>-g</code> (or <code>--partition</code>) switch at server startup to create
+ unique group names:
+ </para>
+ <screen>./run.sh -g QAPartition -b 192.168.1.100 -c production</screen>
+ <para>
+ This switch sets the <varname>jboss.partition.name</varname> system property, which
+ configures the group name in all standard clustering configuration files, for example:
+ </para>
<screen><![CDATA[<attribute name="ClusterName">Tomcat-${jboss.partition.name:Cluster}</attribute>]]></screen>
- </para>
</section>
-
-
-<section><title>Changing the multicast address and port</title>
+<section>
+ <title>Changing the multicast address and port</title>
<para>
- The -u (a.k.a. --udp) command line switch may be used to control the multicast address used by the JGroups channels opened by all standard AS services.
-<screen><![CDATA[/run.sh -u 230.1.2.3 -g QAPartition -b 192.168.1.100 -c all]]></screen>
-This switch sets the jboss.partition.udpGroup system property, which you can see referenced in all of the standard protocol stack configs in JBoss Enterprise Web Platform:
+ Use the <code>-u</code> switch on server startup to control the multicast address used by
+ JGroups channels opened by all standard server services:
+ </para>
+ <screen><![CDATA[/run.sh -u 230.1.2.3 -g QAPartition -b 192.168.1.100 -c production]]></screen>
+ <para>
+ This switch sets the <varname>jboss.partition.udpGroup</varname> system property, which is
+ referenced in all standard protocol stack configurations in JBoss Enterprise Web Platform:
</para>
+ <programlisting><![CDATA[<Config>
+ <UDP mcast_addr="${jboss.partition.udpGroup:228.1.2.3}"
+ ....]]></programlisting>
+ <para>
+ Setting the multicast ports is more difficult. By default, there are four separate JGroups channels
+ in the standard JBoss Enterprise Web Platform <literal>production</literal> configuration. Each
+ should be given a unique port. The standard configuration files use system properties to set these
+ ports. Use <code>-D</code> to configure them from the command line:
+ </para>
+ <programlisting>/run.sh -u 230.1.2.3 -g QAPartition -Djboss.hapartition.mcast_port=12345
+-Djboss.webpartition.mcast_port=23456 -Djboss.ejb3entitypartition.mcast_port=34567
+-Djboss.ejb3sfsbpartition.mcast_port=45678 -b 192.168.1.100 -c production</programlisting>
-<programlisting><![CDATA[<Config>
-<UDP mcast_addr="${jboss.partition.udpGroup:228.1.2.3}"
- ....]]>
-</programlisting>
-<para>
- Unfortunately, setting the multicast ports is not so simple. As described above, by default there are four separate JGroups channels in the standard JBoss Enterprise Web Platform all configuration, and each should be given a unique port. There are no command line switches to set these, but the standard configuration files do use system properties to set them. So, they can be configured from the command line by using -D. For example,
- </para>
-<programlisting>
- /run.sh -u 230.1.2.3 -g QAPartition -Djboss.hapartition.mcast_port=12345 -Djboss.webpartition.mcast_port=23456 -Djboss.ejb3entitypartition.mcast_port=34567 -Djboss.ejb3sfsbpartition.mcast_port=45678 -b 192.168.1.100 -c all
-</programlisting>
-
-<para><emphasis>Why isn't it sufficient to change the group name?</emphasis></para>
-<para>
- If channels with different group names share the same multicast address and port, the lower level JGroups protocols in each channel will see, process and eventually discard messages intended for the other group. This will at a minimum hurt performance and can lead to anomalous behavior.
- </para>
+ <warning><title>Why isn't it sufficient to change the group name?</title>
+ <para>
+ If channels with different group names share a multicast address and port, lower level JGroups
+ protocols in each channel will view, process and discard messages intended for the other group.
+ This harms performance and can lead to anomalous behavior.
+ </para>
+ </warning>
- <para><emphasis>Why do I need to change the multicast port if I change the address?</emphasis></para>
+ <warning><title>Why do I need to change the multicast port if I change the address?</title>
<para>
- It should be sufficient to just change the address, but there is a problem on several operating systems whereby packets addressed to a particular multicast port are delivered to all listeners on that port, regardless of the multicast address they are listening on. So the recommendation is to change both the address and the port.
+ On some operating systems, packets addressed to a particular multicast port are delivered to
+ all listeners on that port, regardless of the multicast address on which they listen.
+ Therefore, we recommend changing both address and port.
</para>
+ </warning>
</section>
<section><title>JGroups Troubleshooting</title>
- <para><emphasis>Nodes do not form a cluster</emphasis></para>
-
+ <section><title>Nodes do not form a cluster</title>
<para>
- Make sure your machine is set up correctly for IP multicast. There are 2 test programs that can be used to detect this: McastReceiverTest and McastSenderTest. Go to the <literal>$JBOSS_HOME/server/all/lib</literal> directory and start McastReceiverTest, for example:
-<screen>java -cp jgroups.jar org.jgroups.tests.McastReceiverTest -mcast_addr 224.10.10.10 -port 5555 </screen>
-</para>
-
-<para>
-Then in another window start <literal>McastSenderTest</literal>:
-<screen>java -cp jgroups.jar org.jgroups.tests.McastSenderTest -mcast_addr 224.10.10.10 -port 5555</screen>
-</para>
-
-<para>
- If you want to bind to a specific network interface card (NIC), use <literal>-bind_addr 192.168.0.2</literal>, where 192.168.0.2 is the IP address of the NIC to which you want to bind. Use this parameter in both the sender and the receiver.
-</para>
-<para>
- You should be able to type in the <literal>McastSenderTest</literal> window and see the output in the <literal>McastReceiverTest</literal> window. If not, try to use -ttl 32 in the sender. If this still fails, consult a system administrator to help you setup IP multicast correctly, and ask the admin to make sure that multicast will work on the interface you have chosen or, if the machines have multiple interfaces, ask to be told the correct interface.
-Once you know multicast is working properly on each machine in your cluster, you can repeat the above test to test the network, putting the sender on one machine and the receiver on another.
-
- </para>
+ Ensure that your machine is set up correctly for IP multicast. There are two test programs that
+ can detect this: <application>McastReceiverTest</application> and
+ <application>McastSenderTest</application>.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>Start <application>McastReceiverTest</application> from the
+ <filename>$JBOSS_HOME/server/production/lib</filename> directory, like so:</para>
+ <screen>java -cp jgroups.jar org.jgroups.tests.McastReceiverTest -mcast_addr 224.10.10.10 -port 5555</screen>
+ </listitem>
+ <listitem>
+ <para>In another window, start <application>McastSenderTest</application> from the same
+ directory:</para>
+ <screen>java -cp jgroups.jar org.jgroups.tests.McastSenderTest -mcast_addr 224.10.10.10 -port 5555</screen>
+ <note>
+ <para>
+ Use the <code>-bind_addr</code> switch to bind to a specific network interface card (NIC). To bind
+ to an NIC with an IP address of <literal>192.168.0.2</literal>, you would use
+ <code>-bind_addr 192.168.0.2</code>. This parameter can be used in both senders and receivers.
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ Type in the <application>McastSenderTest</application> window. You should be able to see the
+ output in the <application>McastReceiverTest</application> window.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ If you cannot, try using <literal>-ttl 32</literal> in the sender. If this still fails, consult
+ a system administrator to help you set up IP multicast correctly. Check that multicast will
+ work on the interface you have chosen. If the machines have multiple interfaces, ask which
+ interface is correct for multicasting.
+ </para>
+ <para>
+ When multicast is working correctly on each machine in your cluster, verify that your network is
+ working correctly by repeating this test with <application>McastReceiverTest</application> on
+ one machine and <application>McastSenderTest</application> on another.
+ </para>
</section>
<section><title>Causes of missing heartbeats in FD</title>
<para>
- Sometimes a member is suspected by FD because a heartbeat ack has not been received for some time T (defined by timeout and max_tries). This can have multiple reasons, e.g. in a cluster of A,B,C,D; C can be suspected if (note that A pings B, B pings C, C pings D and D pings A):
+ Sometimes a member is suspected by FD because a heartbeat acknowledgement has not been received for
+ some time (defined by <varname>timeout</varname> and <varname>max_tries</varname>). This may occur for
+ several reasons. As an example, say you have a cluster consisting of nodes A, B, C and D.
+ In this cluster, A pings B, B pings C, C pings D, and D pings A.
+ </para>
+ <para>
+ C may be suspected in any of the following situations.
</para>
-
<itemizedlist>
<listitem>
<para>
- B or C are running at 100% CPU for more than T seconds. So even if C sends a heartbeat ack to B, B may not be able to process it because it is at 100%
+ If B and C are running at 100% CPU for longer than the time defined by <varname>timeout</varname>
+ and <varname>max_tries</varname>. Even if C sends a heartbeat acknowledgement to B, B may not be
+ able to process the acknowledgement.
</para>
</listitem>
<listitem>
<para>
- B or C are garbage collecting, same as above.
+ If B or C are garbage collecting, they may not respond or process acknowledgement of a
+ heartbeat message.
</para>
</listitem>
<listitem>
<para>
- A combination of the 2 cases above
+ If the network loses packets, heartbeat messages or acknowledgements may be lost. This can occur
+ when a network has high traffic. Packets are usually dropped in the following order:
+ broadcasts, IP multicasts, then TCP packets.
</para>
</listitem>
<listitem>
<para>
- The network loses packets. This usually happens when there is a lot of traffic on the network, and the switch starts dropping packets (usually broadcasts first, then IP multicasts, TCP packets last).
- </para>
- </listitem>
- <listitem>
- <para>
- B or C are processing a callback. Let's say C received a remote method call over its channel and takes T+1 seconds to process it. During this time, C will not process any other messages, including heartbeats, and therefore B will not receive the heartbeat ack and will suspect C.
+ If B or C are processing a callback. Say C receives a remote method call and takes longer than the
+ <varname>timeout</varname> or <varname>max_tries</varname> period to process it. During this time,
+ C does not process any other message, including heartbeats. Therefore B will not receive a
+ heartbeat acknowledgement, and will suspect C.
</para>
</listitem>
</itemizedlist>
-
</section>
</section>
+</section>
- </chapter>
+</chapter>
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-20 07:52:23 UTC (rev 99644)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Revision_History.xml 2010-01-20 08:37:13 UTC (rev 99645)
@@ -8,7 +8,7 @@
<simpara>
<revhistory>
<revision>
- <revnumber>1.8</revnumber>
+ <revnumber>1.9</revnumber>
<date>Tue Jan 19 2010</date>
<author>
<firstname>Laura</firstname>
More information about the jboss-cvs-commits
mailing list