Author: aconway
Date: Fri May 17 19:26:34 2013
New Revision: 1483957
URL: http://svn.apache.org/r1483957
Log:
NO-JIRA: HA updated queue replication section of qpid C++ book.
- Added information needed to use HA queue replication as a replacement for
old async queue state replication.
- Updated links in README-HA.txt to point to (as yet non-existent) 0.22
documentation.
Modified:
qpid/trunk/qpid/cpp/README-HA.txt
qpid/trunk/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
qpid/trunk/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml
Modified: qpid/trunk/qpid/cpp/README-HA.txt
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/README-HA.txt?rev=1483957&r1=1483956&r2=1483957&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/README-HA.txt (original)
+++ qpid/trunk/qpid/cpp/README-HA.txt Fri May 17 19:26:34 2013
@@ -112,7 +112,7 @@ Fail-over exchange
------------------
The fail-over exchange is not supported in new HA, use a
-[virtual IP address][ha-virtual-ip] instead.[]
+[virtual IP address][ha-virtual-ip] instead.
Using a message store in a cluster
----------------------------------
@@ -123,9 +123,17 @@ will have its own store. If the entire c
brokers will clear their stores and get an update from the primary to ensure
consistency. See ["Using a message store in a cluster"][ha-store].
-[chapter-ha]:
http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html
-[ha-failover]:
http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-failover
-[ha-virtual-ip]:
http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-virtual-ip
-[ha-replicate-values]:
http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-replicate-values
-[ha-rm-config]:
http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-rm-config
+Replacing Queue State Replication
+---------------------------------
+The queue state replication mechanism implemented by the modules
`replicating_listener` and `replication_exchange` is no longer available.
Instead you should use the queue replication mechanism provided by the `ha`
module as described in the [HA Queue Replication chapter of the C++ Broker
Book][ha-queue-replication]
+
+
+
+
+[chapter-ha]:
http://qpid.apache.org/books/0.22/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html
+[ha-failover]:
http://qpid.apache.org/books/0.22/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-failover
+[ha-virtual-ip]:
http://qpid.apache.org/books/0.22/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-virtual-ip
+[ha-replicate-values]:
http://qpid.apache.org/books/0.22/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-replicate-values
+[ha-rm-config]:
http://qpid.apache.org/books/0.22/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-rm-config
+[ha-queue-replication]:
http://qpid.apache.org/books/0.22/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-queue-replication
Modified: qpid/trunk/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml?rev=1483957&r1=1483956&r2=1483957&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
(original)
+++ qpid/trunk/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml Fri May
17 19:26:34 2013
@@ -873,30 +873,6 @@ NOTE: fencing is not shown, you must con
or to simulate a cluster on a single node. For deployment, a resource
manager is required.
</para>
</section>
- <section id="ha-queue-replication">
- <title>Replicating specific queues</title>
- <para>
- In addition to the automatic replication performed in a cluster, you can
- set up replication for specific queues between arbitrary brokers, even if
- the brokers are not members of a cluster. The command:
- </para>
- <programlisting>
- qpid-ha replicate <replaceable>QUEUE</replaceable>
<replaceable>REMOTE-BROKER</replaceable>
- </programlisting>
- <para>
- sets up replication of <replaceable>QUEUE</replaceable> on
<replaceable>REMOTE-BROKER</replaceable> to <replaceable>QUEUE</replaceable> on
the current broker.
- </para>
- <para>
- Set the configuration option
- <literal>ha-queue-replication=yes</literal> on both brokers to enable
this
- feature on non-cluster brokers. It is automatically enabled for brokers
- that are part of a cluster.
- </para>
- <para>
- Note that this feature does not provide automatic fail-over, for that you
- need to run a cluster.
- </para>
- </section>
<section id ="ha-store">
<title>Using a message store in a cluster</title>
Modified: qpid/trunk/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml?rev=1483957&r1=1483956&r2=1483957&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml (original)
+++ qpid/trunk/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml Fri May 17
19:26:34 2013
@@ -20,35 +20,107 @@ under the License.
-->
-<section>
- <title>Queue Replication with the HA module</title>
+<section id="ha-queue-replication">
+ <title>Replicating Queues with the HA module</title>
<para>
- As well as support for an active-passive cluster, the
<filename>ha</filename> module
- also allows you to replicate individual queues. The
<firstterm>original</firstterm>
- queue is used as normal. The <firstterm>replica</firstterm> queue is
updated
- automatically as messages are added to or removed from the original queue.
- </para>
- <para>
- To create a replica you need the HA module to be loaded on both the
orignal and replica
- brokers. Note that it is not safe to modify the replica queue other than
via the
- automatic updates from the original. Adding or removing messages on the
replica queue
- will make replication inconsistent and may cause message loss. The HA
module does
- <emphasis>not</emphasis> enforce restricted access to the replica queue
(as it does in
- the case of a cluster) so it is up to the application to ensure the replca
is not used
- until it has been disconnected from the original.
- </para>
- <para>
- Suppose that <command>myqueue</command> is a queue on
<command>node1</command> and
- we want to create a replica of <command>myqueue</command> on
<command>node2</command>
- (where both brokers are using the default AMQP port.) This is accomplished
by the command:
- <programlisting>
- qpid-config --broker=node2 add queue --start-replica node1 myqueue
- </programlisting>
- </para>
- <para>
- If <command>myqueue</command> already exists on the replica broker you
can start replication from the original queue like this:
- <programlisting>
- qpid-ha replicate -b node2 node1 myqueue
- </programlisting>
+ As well as support for an active-passive cluster, the
+ <filename>HA</filename> module allows you to replicate individual queues,
+ even if the brokers are not in a cluster. The
<firstterm>original</firstterm>
+ queue is used as normal. The <firstterm>replica</firstterm> queue is
+ updated automatically as messages are added to or removed from the original
+ queue.
</para>
+ <warning>
+ <para>
+ It is not safe to modify the replica queue
+ other than via the automatic updates from the original. Adding or
removing
+ messages on the replica queue will make replication inconsistent and may
+ cause message loss.
+ The <filename>HA</filename> module does <emphasis>not</emphasis> enforce
+ restricted access to the replica queue (as it does in the case of a
cluster)
+ so it is up to the application to ensure the replica is not used until
it has
+ been disconnected from the original.
+ </para>
+ </warning>
+ <section>
+ <title>Replicating queues</title>
+ <para>
+ To create a replica queue, the <filename>HA</filename> module must be
+ loaded on both the original and replica brokers (it is loaded by
default.)
+ You also need to set the configuration option:
+ <programlisting>
+ ha-queue-replication=yes
+ </programlisting>
+ to enable this feature on a stand-alone broker. It is automatically
+ enabled for brokers that are part of a cluster.
+ </para>
+ <para>
+ Suppose that <command>myqueue</command> is a queue on
+ <command>node1</command> and we want to create a replica of
+ <command>myqueue</command> on <command>node2</command> (where both
brokers
+ are using the default AMQP port.) This is accomplished by the command:
+ <programlisting>
+ qpid-config --broker=node2 add queue --start-replica node1 myqueue
+ </programlisting>
+ If <command>myqueue</command> already exists on the replica
+ broker you can start replication from the original queue like this:
+ <programlisting>
+ qpid-ha replicate -b node2 node1 myqueue
+ </programlisting>
+ </para>
+ </section>
+ <section>
+ <title>Replicating queues between clusters</title>
+ <para>
+ You can replicate queues between two standalone brokers, between a
+ standalone broker and a cluster, or between two clusters (see <xref
+ linkend="chapter-ha"/>.) For failover in a cluster there are two cases to
+ consider.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ When the <emphasis>original</emphasis> queue is on the active node
+ of a cluster, failover is automatic. If the active node
+ fails, the replication link will automatically reconnect and the
+ replica will continue to be updated from the new primary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When the <emphasis>replica</emphasis> queue is on the active node of a
+ cluster, there is no automatic failover. However you can use the
+ following workaround.
+ </para>
+ </listitem>
+ </orderedlist>
+ <section>
+ <title>Work around for fail-over of replica queue in a cluster</title>
+ <para>
+ When a primary broker fails the cluster resource manager calls a script
+ to promote a backup broker to be the new primary. By default this script
+ is <filename>/etc/init.d/qpidd-primary</filename> but you can modify
+ that in your <filename>cluster.conf</filename> file (see <xref
+ linkend="ha-rm-config"/>.)
+ </para>
+ <para>
+ You can modify this script (on each host in your cluster) by adding
+ commands to create your replica queues just before the broker is
+ promoted, as indicated in the following exceprt from the script:
+ <programlisting>
+start() {
+ service qpidd start
+ echo -n $"Promoting qpid daemon to cluster primary: "
+ ################################
+ #### Add your commands here ####
+ ################################
+ $QPID_HA -b localhost:$QPID_PORT promote
+ [ "$?" -eq 0 ] && success || failure
+}
+ </programlisting>
+ Your commands will be run, and your replicas created, whenever
+ the system fails over to a new primary.
+ </para>
+ </section>
+ </section>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
