[jboss-cvs] JBossAS SVN: r99588 - 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
Tue Jan 19 03:15:52 EST 2010
Author: laubai
Date: 2010-01-19 03:15:52 -0500 (Tue, 19 Jan 2010)
New Revision: 99588
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:
Partial corrections to 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-19 07:59:11 UTC (rev 99587)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Book_Info.xml 2010-01-19 08:15:52 UTC (rev 99588)
@@ -7,7 +7,7 @@
<subtitle>for JBoss Enterprise Web Platform 5.0</subtitle>
<edition>1</edition>
<issuenum>1</issuenum>
- <pubsnumber>0.6</pubsnumber>
+ <pubsnumber>0.7</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-19 07:59:11 UTC (rev 99587)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JBoss_Cache_JGroups.xml 2010-01-19 08:15:52 UTC (rev 99588)
@@ -846,7 +846,7 @@
</varlistentry>
<varlistentry>
<term><varname>shun</varname></term>
- <listitem><para>Specifiees whether a failed node will be shunned. Once shunned, the node will
+ <listitem><para>Specifies 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>
@@ -1367,124 +1367,176 @@
</varlistentry>
</variablelist>
</section>
-<!--hajime-->
+
<section id="jbosscache-jgroups-other-merge">
<title>Merging</title>
<para>
- When a network error occurs, the cluster might be partitioned into several different partitions. JGroups has a MERGE service that allows the coordinators in partitions to communicate with each other and form a single cluster back again. The flow control service is configured in the <literal>MERGE2</literal> sub-element under the JGroups <literal>Config</literal> element. Here is an example configuration.
- </para>
-
-<programlisting>
-<MERGE2 max_interval="10000"
+ When a network error occurs, a cluster may be divided into several partitions. The JGroups
+ <literal>MERGE</literal> service lets partitions communicate with each other and reform into
+ a single cluster. Merging is configured in the <literal>MERGE2</literal> sub-element in the
+ JGroups <literal>Config</literal> element, like so:
+ </para>
+ <programlisting><![CDATA[<MERGE2 max_interval="10000"
min_interval="2000"
- down_thread="false" up_thread="false"/>
-</programlisting>
+ down_thread="false" up_thread="false"/>]]></programlisting>
-
- <para>The configurable attributes in the <literal>FC</literal> element are as follows.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">max_interval</emphasis> specifies the maximum number of
- milliseconds to send out a MERGE message.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">min_interval</emphasis> specifies the minimum number of
- milliseconds to send out a MERGE message.</para>
- </listitem>
- </itemizedlist>
- <para>JGroups chooses a random value between <literal>min_interval</literal> and
- <literal>max_interval</literal> to send out the MERGE message.</para>
+ <para>The configurable attributes in the <literal>MERGE2</literal> element are as follows.</para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>max_interval</varname></term>
+ <listitem><para>Specifies the maximum number of milliseconds between
+ <literal>MERGE</literal> messages.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>min_interval</varname></term>
+ <listitem><para>Specifies the minimum number of milliseconds between
+ <literal>MERGE</literal> messages.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ JGroups selects a random value between <varname>min_interval</varname> and
+ <varname>max_interval</varname> to send out the <literal>MERGE</literal> message.
+ </para>
<note>
- <para>
- The cluster states are not merged in a merger. This has to be done by the application. If <literal>MERGE2</literal> is used in conjunction with TCPPING, the <literal>initial_hosts</literal> attribute must contain all the nodes that could potentially be merged back, in order for the merge process to work properly. Otherwise, the merge process would not merge all the nodes even though shunning is disabled. Alternatively use MPING, which is commonly used with TCP to provide multicast member discovery capabilities, instead of TCPPING to avoid having to specify all the nodes.
- </para>
+ <title><literal>MERGE</literal> does not merge cluster states</title>
+ <para>
+ Cluster state merging must be performed by the application. If <literal>MERGE2</literal>
+ is used in conjunction with <literal>TCPPING</literal>, the <varname>initial_hosts</varname>
+ attribute must list all nodes to be merged. Only the listed nodes will be included
+ in the merge process.
+ </para>
+ <para>
+ Alternatively, <literal>MPING</literal> can be used with TCP to provide multicast member
+ discovery capabilities without needing to specify all nodes.
+ </para>
</note>
</section>
<section><title>Binding JGroups Channels to a particular interface</title>
<para>
- In the Transport Protocols section above, we briefly touched on how the interface to which JGroups will bind sockets is configured. Let's get into this topic in more depth:
+ <xref linkend="jgroups-transport"/> briefly described the interface to which JGroups binds sockets.
+ Read this section to understand how to configure this interface.
</para>
<para>
- First, it's important to understand that the value set in any bind_addr element in an XML configuration file will be ignored by JGroups if it finds that system property jgroups.bind_addr (or a deprecated earlier name for the same thing, <literal>bind.address</literal>) has been set. The system property trumps XML. If JBoss AS is started with the -b (a.k.a. --host) switch, the AS will set <literal>jgroups.bind_addr</literal> to the specified value.
+ The value set in any <varname>bind_addr</varname> element in an XML configuration file is
+ ignored by JGroups if the <varname>jgroups.bind_addr</varname> (or deprecated
+ <varname>bind.address</varname> system property is already set. The system property will
+ always override the XML configuration. The <code>-b</code> (or <code>--host</code>) switch
+ is used to set the <varname>jgroups.bind_addr</varname> system property at server startup.
</para>
<para>
- Beginning with Enterprise Web Platform 4.2.0, for security reasons the Enterprise Web Platform will bind most services to localhost if -b is not set. The effect of this is that in most cases users are going to be setting -b and thus jgroups.bind_addr is going to be set and any XML setting will be ignored.
+ By default, JBoss Enterprise Web Platform binds most services to the local host if the
+ <code>-b</code> switch is not set. Therefore, most users need to set <code>-b</code>,
+ and any XML configuration will be ignored.
</para>
<para>
So, what are <emphasis>best practices</emphasis> for managing how JGroups binds to interfaces?
</para>
- <itemizedlist>
- <listitem>
- <para>
- Binding JGroups to the same interface as other services. Simple, just use -b:
- <screen>./run.sh -b 192.168.1.100 -c all</screen>
- </para>
-</listitem>
-<listitem>
- <para>
- Binding services (e.g., JBoss Web) to one interface, but use a different one for JGroups:
- <screen>./run.sh -b 10.0.0.100 -Djgroups.bind_addr=192.168.1.100 -c all</screen>
-
- Specifically setting the system property overrides the -b value. This is a common usage pattern; put client traffic on one network, with intra-cluster traffic on another.
- </para>
- </listitem>
- <listitem>
- <para>
-
- Binding services (e.g., JBoss Web) to all interfaces. This can be done like this:
- <screen>./run.sh -b 0.0.0.0 -c all</screen>
- However, doing this will not cause JGroups to bind to all interfaces! Instead , JGroups will bind to the machine's default interface. See the Transport Protocols section for how to tell JGroups to receive or send on all interfaces, if that is what you really want.
- </para>
- </listitem>
- <listitem>
- <para>
- Binding services (e.g., JBoss Web) to all interfaces, but specify the JGroups interface:
- <screen>./run.sh -b 0.0.0.0 -Djgroups.bind_addr=192.168.1.100 -c all</screen>
-
- Again, specifically setting the system property overrides the -b value.
- </para>
- </listitem>
- <listitem>
- <para>
- Using different interfaces for different channels:
- <screen>./run.sh -b 10.0.0.100 -Djgroups.ignore.bind_addr=true -c all</screen>
- </para>
- </listitem>
-</itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term>Bind JGroups to the same interface as other services</term>
+ <listitem>
+ <para>Use the <code>-b</code> switch, like so:</para>
+ <screen>./run.sh -b 192.168.1.100 -c production</screen>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Bind services to one interface and JGroups to another</term>
+ <listitem>
+ <para>Specifically setting the system property with <code>-D</code> overrides the
+ value specified by <code>-b</code>:</para>
+ <screen>./run.sh -b 10.0.0.100 -Djgroups.bind_addr=192.168.1.100 -c production</screen>
+ <para>The code here is a common usage pattern. It places client traffic on one
+ network and intra-cluster traffic on another.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Bind services to all interfaces</term>
+ <listitem>
+ <para>Bind services to all interfaces with the following command on startup:</para>
+ <screen>./run.sh -b 0.0.0.0 -c production</screen>
+ <note>
+ <title>This will not bind JGroups to all interfaces</title>
+ <para>JGroups will bind to the machine's default interface. See
+ <xref linkend="jgroups-transport"/> to learn how to tell JGroups to send and receive
+ on all interfaces.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Bind services to all interfaces and specify a JGroups interface</term>
+ <listitem>
+ <para>Specifically setting the system property with <code>-D</code> overrides the
+ value specified by <code>-b</code>:</para>
+ <screen>./run.sh -b 0.0.0.0 -Djgroups.bind_addr=192.168.1.100 -c production</screen>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Use different interfaces for different channels</term>
+ <listitem>
+ <para>
+ Set the <varname>jgroups.ignore.bind_addr</varname> property to <literal>true</literal>
+ on server startup, like so:
+ </para>
+ <screen>./run.sh -b 10.0.0.100 -Djgroups.ignore.bind_addr=true -c production</screen>
+ <para>This setting tells JGroups to ignore the <varname>jgroups.bind_addr</varname>
+ system property and use the value specified in the XML. You would then edit the XML
+ configuration files to specify the <varname>bind_addr</varname> to the desired
+ interface.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
-<para>
-This setting tells JGroups to ignore the <literal>jgroups.bind_addr</literal> system property, and instead use whatever is specfied in XML. You would need to edit the various XML configuration files to set the <literal>bind_addr</literal> to the desired interfaces.
- </para>
- </section>
-
<section><title>Isolating JGroups Channels</title>
<para>
- Within JBoss Enterprise Web Platform, there are a number of services that independently create JGroups channels -- 3 different JBoss Cache services (used for HttpSession replication, EJB3 SFSB replication and EJB3 entity replication) along with the general purpose clustering service called HAPartition that underlies most other JBossHA services.
- </para>
+ A number of services independently create JGroups channels: three JBoss Cache services
+ (used for HTTP session replication, EJB3 SFSB replication, and EJB3 entity replication),
+ and <classname>HAPartition</classname>, a clustering service that underlies most
+ JBoss high availability services.
+ </para>
+ <important><title>These channels must only communicate with their intended peers</title>
+ <para>
+ They must not communicate with channels used by other services, or channels for the same
+ service opened on machines outside the group. Nodes communicating improperly is one of
+ the most common issues for users attempting to cluster JBoss Enterprise Web Platform.
+ </para>
+ </important>
<para>
- It is critical that these channels only communicate with their intended peers; not with the channels used by other services and not with channels for the same service opened on machines not meant to be part of the group. Nodes improperly communicating with each other is one of the most common issues users have with JBoss AS clustering.
+ JGroups channels communicate based on group name, multicast address and multicast port.
+ Isolating a JGroups channel means ensuring that different channels use different values
+ for the group name, multicast address, and multicast port.
</para>
<para>
- Whom a JGroups channel will communicate with is defined by its group name, multicast address, and multicast port, so isolating JGroups channels comes down to ensuring different channels use different values for the group name, multicast address and multicast port.
+ To isolate different services' JGroups channels from each other in the same cluster, you
+ must change the group name and multicast port. Each channel must have its own set of values.
</para>
<para>
- To isolate JGroups channels for different services on the same set of AS instances from each other, you MUST change the group name and the multicast port. In other words, each channel must have its own set of values.
+ As an example, say we have a production cluster of three machines, and each machine has
+ deployed <classname>HAPartition</classname> with a JBoss Cache instance for web session
+ clustering. The <classname>HAPartition</classname> channels should not communicate with
+ the JBoss Cache channels. They should use a different group name and multicast port.
+ They may use the same multicast address, though this is not mandatory.
</para>
<para>
- For example, say we have a production cluster of 3 machines, each of which has an HAPartition deployed along with a JBoss Cache used for web session clustering. The HAPartition channels should not communicate with the JBoss Cache channels. They should use a different group name and multicast port. They can use the same multicast address, although they don't need to.
+ To isolate the same service's JGroups channels from other instances of the service on the
+ network, you must change all three values. Each channel must have a unique group name,
+ multicast address, and multicast port.
</para>
<para>
- To isolate JGroups channels for the same service from other instances of the service on the network, you MUST change ALL three values. Each channel must have its own group name, multicast address, and multicast port.
+ As an example, say we have a production cluster of three machines, and each machine has
+ deployed <classname>HAPartition</classname>. On the same network, there is another cluster
+ of three machines intended for quality assurance testing, which also deploys
+ <classname>HAPartition</classname>. The <classname>HAPartition</classname> group name,
+ multicast address, and multicast port for the production machines must be different from
+ those used on the quality assurance machines.
</para>
- <para>
- For example, say we have a production cluster of 3 machines, each of which has an HAPartition deployed. On the same network there is also a QA cluster of 3 machines, which also has an HAPartition deployed. The HAPartition group name, multicast address, and multicast port for the production machines must be different from those used on the QA machines.
- </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.
</para>
<para>
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-19 07:59:11 UTC (rev 99587)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Revision_History.xml 2010-01-19 08:15:52 UTC (rev 99588)
@@ -8,8 +8,8 @@
<simpara>
<revhistory>
<revision>
- <revnumber>1.7</revnumber>
- <date>Mon Jan 18 2010</date>
+ <revnumber>1.8</revnumber>
+ <date>Tue Jan 19 2010</date>
<author>
<firstname>Laura</firstname>
<surname>Bailey</surname>
More information about the jboss-cvs-commits
mailing list