<?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>