diff options
| -rw-r--r-- | cpp/README-HA.txt | 20 | ||||
| -rw-r--r-- | doc/book/src/cpp-broker/Active-Passive-Cluster.xml | 24 | ||||
| -rw-r--r-- | doc/book/src/cpp-broker/HA-Queue-Replication.xml | 130 |
3 files changed, 115 insertions, 59 deletions
diff --git a/cpp/README-HA.txt b/cpp/README-HA.txt index d93c99d8f3..ae9bec5182 100644 --- a/cpp/README-HA.txt +++ b/cpp/README-HA.txt @@ -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 cluster fails, when restarting the 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 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 ] && 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> |