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.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@1483957 13f79535-47bb-0310-9956-ffa450edef68

2 files changed, 101 insertions, 53 deletions

diff --git a/doc/book/src/cpp-broker/Active-Passive-Cluster.xml b/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
index 9c5f3a4fc7..8ddd87a2c4 100644
--- a/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
+++ b/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
@@ -873,30 +873,6 @@ NOTE: fencing is not shown, you must configure fencing appropriately for your cl
       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>
diff --git a/doc/book/src/cpp-broker/HA-Queue-Replication.xml b/doc/book/src/cpp-broker/HA-Queue-Replication.xml
index b7c533e4cb..71ad1578fb 100644
--- a/doc/book/src/cpp-broker/HA-Queue-Replication.xml
+++ b/doc/book/src/cpp-broker/HA-Queue-Replication.xml
@@ -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 ] &amp;&amp; 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>