NO-JIRA: create branch for qpid-cpp 0.34 RC process

git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/qpid-cpp-0.34-rc@1687469 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 126 insertions, 0 deletions

diff --git a/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml b/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml
new file mode 100644
index 0000000000..81b55a3914
--- /dev/null
+++ b/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml
@@ -0,0 +1,126 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+
+-->
+
+<section id="ha-queue-replication">
+  <title>Replicating Queues with the HA module</title>
+  <para>
+    As well as support for an active-passive cluster, the
+    HA 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 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 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 HA 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>