diff options
| author | Alan Conway <aconway@apache.org> | 2013-05-21 16:47:26 +0000 |
|---|---|---|
| committer | Alan Conway <aconway@apache.org> | 2013-05-21 16:47:26 +0000 |
| commit | 25cc9e700b123efceec39f4c1c61ba19576b854c (patch) | |
| tree | 2cf01341181aaf84605acdd643c067c9649814f2 | |
| parent | 72c205c2e87e4534fb64284bf5a0e730267a0140 (diff) | |
| download | qpid-python-25cc9e700b123efceec39f4c1c61ba19576b854c.tar.gz | |
QPID-4865: HA Update documents for queue replication
- 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.
- Removed lingering traces of old broker.
git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/0.22@1484867 13f79535-47bb-0310-9956-ffa450edef68
8 files changed, 230 insertions, 543 deletions
diff --git a/qpid/cpp/README-HA.txt b/qpid/cpp/README-HA.txt index 03e190a3fc..9a621f6b04 100644 --- a/qpid/cpp/README-HA.txt +++ b/qpid/cpp/README-HA.txt @@ -4,10 +4,15 @@ Migrating to new HA =================== Up to version 0.20, Qpid provided the `cluster` module to support active-active -clustering for Qpid C++ brokers. In version 0.20 the `ha` module was introduced -supporting active-passive HA clustering. From version 0.22 the older `cluster` -module is no longer available so users will have to migrate to the new `ha` -module. +clustering for Qpid C++ brokers. There were some issues with this module. It +relied on synchronization of too much broker state, which made it difficult to +maintain. It also had a design limitation that made it effectively +single-threaded. + +In version 0.20, a new `ha` module was introduced, providing active-passive +clustering. This module is more maintainable and fits better into the +broker threading modle. From version 0.22 the older `cluster` module +is no longer available so users will have to migrate to the new `ha` module. This document summarizes the differences between the old and new HA modules and the steps to migrate to new HA. It assumes you have read the @@ -106,7 +111,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 ---------------------------------- @@ -117,9 +122,16 @@ 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/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml b/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml index 6122b12e18..9680682e3d 100644 --- a/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml +++ b/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml @@ -52,7 +52,6 @@ <xi:include href="Using-Broker-Federation.xml"/> <xi:include href="Security.xml"/> <xi:include href="LVQ.xml"/> - <xi:include href="queue-state-replication.xml"/> <xi:include href="producer-flow-control.xml"/> <xi:include href="AMQP-Compatibility.xml"/> <xi:include href="Qpid-Interoperability-Documentation.xml"/> diff --git a/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml b/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml index b98e054b98..39173a51b1 100644 --- a/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml +++ b/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml @@ -317,7 +317,15 @@ ssl_addr = "ssl:" host [":" port]' </entry> </row> <row> - <entry><literal>ha-backup-timeout <replaceable>SECONDS</replaceable></literal> </entry> + <entry><literal>ha-backup-timeout<replaceable>SECONDS</replaceable></literal> + <footnote id="ha-seconds-spec"> + <para> + Values specified as <replaceable>SECONDS</replaceable> can be a + fraction of a second, e.g. "0.1" for a tenth of a second. + They can also have an explicit unit, e.g. 10s, 10ms, 10us, 10ns + </para> + </footnote> + </entry> <entry> <para> Maximum time that a recovering primary will wait for an expected @@ -326,7 +334,10 @@ ssl_addr = "ssl:" host [":" port]' </entry> </row> <row> - <entry><literal>link-maintenance-interval <replaceable>SECONDS</replaceable></literal></entry> + <entry> + <literal>link-maintenance-interval <replaceable>SECONDS</replaceable></literal> + <footnoteref linkend="ha-seconds-spec"/> + </entry> <entry> <para> Interval for the broker to check link health and re-connect links if need @@ -336,7 +347,10 @@ ssl_addr = "ssl:" host [":" port]' </entry> </row> <row> - <entry><literal>link-heartbeat-interval <replaceable>SECONDS</replaceable></literal></entry> + <entry> + <literal>link-heartbeat-interval <replaceable>SECONDS</replaceable></literal> + <footnoteref linkend="ha-seconds-spec"/> + </entry> <entry> <para> Heartbeat interval for replication links. The link will be assumed broken @@ -859,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> @@ -895,6 +885,60 @@ NOTE: fencing is not shown, you must configure fencing appropriately for your cl </para> </section> + <section id="ha-link-failover-workaround"> + <title>Failover of federation links and queue replication.</title> + <para> + Failover for Federation links (<xref + linkend="chap-Messaging_User_Guide-Broker_Federation"/>) and queue + replication (<xref linkend="ha-queue-replication"/>) is not fully + automated. Until it is you can use the following workaround. + </para> + <para> + Note: In the following we will <emphasis>source</emphasis> to refer to the + source of a federation link or the <emphasis>original</emphasis> of a + replicated queue. We will use <emphasis>destination</emphasis> to refer + to the destination of a federation link or the + <emphasis>replica</emphasis> of a replicated queue. + </para> + <para> + If the primary <emphasis>source</emphasis> broker fails, the destination + broker will automatically failover to the new source primary and + re-establish the link or queue replication. + </para> + <para> + However if the <emphasis>destination</emphasis> broker fails, there is no + automatic failover. You can use the following workaround: + </para> + <para> + When the 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 re-create your replica queues or federation links just before + the broker is promoted, as illustrated in the following excerpt from the + script: + <programlisting> + start() { + service qpidd start + + ################################ + #### Add your commands here #### + ################################ + + echo -n $"Promoting qpid daemon to cluster primary: " + $QPID_HA -b localhost:$QPID_PORT promote + [ "$?" -eq 0 ] && success || failure + } + </programlisting> + Whenever the system fails over to a new primary your commands will be run + and your replicas or links created before the primary begins to accept + connections from backups and clients. + </para> + </section> </section> <!-- LocalWords: scalability rgmanager multicast RGManager mailto LVQ qpidd IP dequeued Transactional username API diff --git a/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml b/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml index 78272b7ef4..b709289406 100644 --- a/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml +++ b/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml @@ -1,7 +1,7 @@ <?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 @@ -9,16 +9,16 @@ 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><title> @@ -50,14 +50,6 @@ <xref linkend="CheatSheetforconfiguringQueueOptions-Settingadditionalbehaviors"/> </para></listitem> <listitem><para> - <itemizedlist> - <listitem><para> - <xref linkend="CheatSheetforconfiguringQueueOptions-PersistLastNode"/> - </para></listitem> - <listitem><para> - <xref linkend="CheatSheetforconfiguringQueueOptions-Queueeventgeneration"/> - </para></listitem> - </itemizedlist> </para></listitem> <listitem><para> <xref linkend="CheatSheetforconfiguringQueueOptions-OtherClients"/> @@ -155,7 +147,7 @@ .... for each message, set the into application headers before transfer message.getHeaders().setString(key,"RHT"); - + </programlisting> <para> Notes: @@ -179,68 +171,7 @@ A fully worked <xref linkend="LVQ-Example"/> can be found here </para> <!--h3--></section> - <section role="h3" id="CheatSheetforconfiguringQueueOptions-Settingadditionalbehaviors"><title> - Setting additional behaviors - </title> - <section role="h4" id="CheatSheetforconfiguringQueueOptions-PersistLastNode"><title> - Persist - Last Node - </title> - <para> - This option is used in conjunction with clustering. It allows for - a queue configured with this option to persist transient messages - if the cluster fails down to the last node. If additional nodes - in the cluster are restored it will stop persisting transient - messages. - </para><para> - Note - </para><itemizedlist> - <listitem><para>if a cluster is started with only one active node, this mode - will not be triggered. It is only triggered the first time the - cluster fails down to 1 node. - </para></listitem> - <listitem><para>The queue MUST be configured durable - </para></listitem> - </itemizedlist><para> - Example: - </para> - <programlisting> -#include "qpid/client/QueueOptions.h" - QueueOptions qo; - qo.clearPersistLastNode(); - - session.queueDeclare(arg::queue=queue, arg::durable=true, arg::arguments=qo); -</programlisting> - <!--h4--></section> - <section role="h4" id="CheatSheetforconfiguringQueueOptions-Queueeventgeneration"><title> - Queue - event generation - </title> - <para> - This option is used to determine whether enqueue/dequeue events - representing changes made to queue state are generated. These - events can then be processed by plugins such as that used for - <xref linkend="queue-state-replication"/>. - </para><para> - Example: - </para> - <programlisting> -#include "qpid/client/QueueOptions.h" - - QueueOptions options; - options.enableQueueEvents(1); - session.queueDeclare(arg::queue="my-queue", arg::arguments=options); -</programlisting> - <para> - The boolean option indicates whether only enqueue events should - be generated. The key set by this is - 'qpid.queue_event_generation' and the value is and integer value - of 1 (to replicate only enqueue events) or 2 (to replicate both - enqueue and dequeue events). - </para> - <!--h3--></section> - <!--h4--></section> <section role="h3" id="CheatSheetforconfiguringQueueOptions-OtherClients"><title> Other Clients @@ -252,7 +183,7 @@ </para> <!--h3--></section> - + <!--h2--></section> diff --git a/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml b/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml index b7c533e4cb..3d8bd2283a 100644 --- a/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml +++ b/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml @@ -20,35 +20,80 @@ 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. Automatic failover will be + supported in the future, in the meantime you can use the workaround + detailed in <xref linkend="ha-link-failover-workaround"/>. + </para> + </listitem> + </orderedlist> + </section> </section> diff --git a/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml b/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml index d2abea4296..d6e52c4fdf 100644 --- a/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml +++ b/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml @@ -70,7 +70,6 @@ Options: Add Queue Options: --durable Queue is durable - --cluster-durable Queue becomes durable if there is only one functioning cluster node --file-count N (8) Number of files in queue's persistence journal --file-size N (24) File size in pages (64Kib/page) --max-queue-size N Maximum in-memory queue size as bytes diff --git a/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml b/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml index f5fedf814c..328c50e069 100644 --- a/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml +++ b/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml @@ -1,6 +1,6 @@ <?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 @@ -8,16 +8,16 @@ 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="chap-Messaging_User_Guide-Broker_Federation"> @@ -29,7 +29,7 @@ Broker Federation can be used to build large messaging networks, with many brokers, one route at a time. If network connectivity permits, an entire distributed messaging network can be configured from a single location. The rules used for routing can be changed dynamically as servers change, responsibilities change, at different times of day, or to reflect other changing conditions. </para> <para> - Broker Federation is useful in a wide variety of scenarios. Some of these have to do with functional organization; for instance, brokers may be organized by geography, service type, or priority. Here are some use cases for federation: + Broker Federation is useful in a wide variety of scenarios. Some of these have to do with functional organization; for instance, brokers may be organized by geography, service type, or priority. Here are some use cases for federation: <itemizedlist> <listitem> <para> @@ -98,7 +98,7 @@ </para> </section> - + <section id="sect-Messaging_User_Guide-Message_Routes-Exchange_Routes"> <title>Exchange Routes</title> <para> @@ -109,7 +109,7 @@ </para> </section> - + <section id="sect-Messaging_User_Guide-Message_Routes-Dynamic_Exchange_Routes"> <title>Dynamic Exchange Routes</title> <para> @@ -126,10 +126,10 @@ </para> </section> - + </section> - + <section id="sect-Messaging_User_Guide-Broker_Federation-Federation_Topologies"> <title>Federation Topologies</title> <para> @@ -143,18 +143,18 @@ </para> </section> - + <section id="sect-Messaging_User_Guide-Broker_Federation-Federation_among_High_Availability_Message_Clusters"> <title>Federation among High Availability Message Clusters</title> <para> - Federation is generally used together with High Availability Message Clusters, using clusters to provide high availability on each LAN, and federation to route messages among the clusters. Because message state is replicated within a cluster, it makes little sense to define message routes between brokers in the same cluster. + Federation can be used together with High Availability Message Clusters, using clusters to provide high availability on each LAN, and federation to route messages among the clusters. </para> <para> - To create a message route between two clusters, simply create a route between any one broker in the first cluster and any one broker in the second cluster. Each broker in a given cluster can use message routes defined for another broker in the same cluster. If the broker for which a message route is defined should fail, another broker in the same cluster can restore the message route. + To create a message route between two clusters, simply create a route between the primaries of each cluster. If the broker for which a message route is defined should fail, another broker in the same cluster can restore the message route. + Note that failover of federation routes between clusters is not fully automated, see <xref linkend="ha-link-failover-workaround"/> for a workaround. </para> - </section> - + <section id="sect-Messaging_User_Guide-Broker_Federation-The_qpid_route_Utility"> <title>The qpid-route Utility</title> <para> @@ -163,19 +163,19 @@ <para> The syntax of <command>qpid-route</command> is as follows: </para> - + <screen> -qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange> +qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange> qpid-route [OPTIONS] dynamic del <dest-broker> <src-broker> <exchange> -qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key> +qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key> qpid-route [OPTIONS] route del <dest-broker> <src-broker> <exchange> <routing-key> qpid-route [OPTIONS] queue add <dest-broker> <src-broker> <dest-exchange> <src-queue> qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <dest-exchange> <src-queue> qpid-route [OPTIONS] list [<broker>] -qpid-route [OPTIONS] flush [<broker>] +qpid-route [OPTIONS] flush [<broker>] qpid-route [OPTIONS] map [<broker>] <!-- qpid-route [OPTIONS] add connection <dest-broker> <src-broker> @@ -185,7 +185,7 @@ qpid-route [OPTIONS] list connections [<broker>] <para> The syntax for <command>broker</command>, <command>dest-broker</command>, and <command>src-broker</command> is as follows: </para> - + <screen> [username/password@] hostname | ip-address [:<port>] </screen> @@ -235,13 +235,13 @@ qpid-route [OPTIONS] list connections [<broker>] </entry> </row> - <!-- + <!-- <row> <entry> <command>-e</command> </entry> <entry> - Delete link after deleting the last route on the link. + Delete link after deleting the last route on the link. </entry> </row> --> <row> <entry> @@ -275,7 +275,7 @@ qpid-route [OPTIONS] list connections [<broker>] <command>-t <transport> [ --transport <transport>]</command> </entry> <entry> - Transport protocol to be used for the route. + Transport protocol to be used for the route. <itemizedlist> <listitem> <para> @@ -312,7 +312,7 @@ qpid-route [OPTIONS] list connections [<broker>] <para> The syntax for creating and deleting queue routes is as follows: </para> - + <screen> qpid-route [OPTIONS] queue add <dest-broker> <src-broker> <dest-exchange> <src-queue> qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <dest-exchange> <src-queue> @@ -320,102 +320,102 @@ qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <d <para> For instance, the following creates a queue route that routes all messages from the queue named <command>public</command> on the source broker <command>localhost:10002</command> to the <command>amq.fanout</command> exchange on the destination broker <command>localhost:10001</command>: </para> - + <screen> $ qpid-route queue add localhost:10001 localhost:10002 amq.fanout public </screen> <para> If the <command>-d</command> option is specified, this queue route is persistent, and will be restored if one or both of the brokers is restarted: </para> - + <screen> $ qpid-route -d queue add localhost:10001 localhost:10002 amq.fanout public </screen> <para> The <command>del</command> command takes the same arguments as the <command>add</command> command. The following command deletes the queue route described above: </para> - + <screen> $ qpid-route queue del localhost:10001 localhost:10002 amq.fanout public </screen> </section> - + <section id="sect-Messaging_User_Guide-The_qpid_route_Utility-Creating_and_Deleting_Exchange_Routes"> <title>Creating and Deleting Exchange Routes</title> <para> The syntax for creating and deleting exchange routes is as follows: </para> - + <screen> -qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key> +qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key> qpid-route [OPTIONS] route del <dest-broker> <src-broker> <exchange> <routing-key> qpid-route [OPTIONS] flush [<broker>] </screen> <para> For instance, the following creates an exchange route that routes messages that match the binding key <command>global.#</command> from the <command>amq.topic</command> exchange on the source broker <command>localhost:10002</command> to the <command>amq.topic</command> exchange on the destination broker <command>localhost:10001</command>: </para> - + <screen> $ qpid-route route add localhost:10001 localhost:10002 amq.topic global.# </screen> <para> In many applications, messages published to the destination exchange should also be routed to the source exchange. This is accomplished by creating a second exchange route, reversing the roles of the two exchanges: </para> - + <screen> $ qpid-route route add localhost:10002 localhost:10001 amq.topic global.# </screen> <para> If the <command>-d</command> option is specified, the exchange route is persistent, and will be restored if one or both of the brokers is restarted: </para> - + <screen> $ qpid-route -d route add localhost:10001 localhost:10002 amq.fanout public </screen> <para> The <command>del</command> command takes the same arguments as the <command>add</command> command. The following command deletes the first exchange route described above: </para> - + <screen> $ qpid-route route del localhost:10001 localhost:10002 amq.topic global.# </screen> </section> - + <section id="sect-Messaging_User_Guide-The_qpid_route_Utility-Deleting_all_routes_for_a_broker"> <title>Deleting all routes for a broker</title> <para> Use the <command>flush</command> command to delete all routes for a given broker: </para> - + <screen> qpid-route [OPTIONS] flush [<broker>] </screen> <para> For instance, the following command deletes all routes for the broker <command>localhost:10001</command>: </para> - + <screen> $ qpid-route flush localhost:10001 </screen> </section> - + <section id="sect-Messaging_User_Guide-The_qpid_route_Utility-Creating_and_Deleting_Dynamic_Exchange_Routes"> <title>Creating and Deleting Dynamic Exchange Routes</title> <para> The syntax for creating and deleting dynamic exchange routes is as follows: </para> - + <screen> -qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange> +qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange> qpid-route [OPTIONS] dynamic del <dest-broker> <src-broker> <exchange> </screen> <para> In the following examples, we will route messages from a topic exchange. We will create a new topic exchange and federate it so that we are not affected by other all clients that use the built-in <command>amq.topic</command> exchange. The following commands create a new topic exchange on each of two brokers: </para> - + <screen> $ qpid-config -a localhost:10003 add exchange topic fed.topic $ qpid-config -a localhost:10004 add exchange topic fed.topic @@ -423,7 +423,7 @@ $ qpid-config -a localhost:10004 add exchange topic fed.topic <para> Now let's create a dynamic exchange route that routes messages from the <command>fed.topic</command> exchange on the source broker <command>localhost:10004</command> to the <command>fed.topic</command> exchange on the destination broker <command>localhost:10003</command> if they match any binding on the destination broker's <command>fed.topic</command> exchange: </para> - + <screen> $ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic </screen> @@ -433,14 +433,14 @@ $ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic <para> In many applications, messages published to the destination exchange should also be routed to the source exchange. This is accomplished by creating a second dynamic exchange route, reversing the roles of the two exchanges: </para> - + <screen> $ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic </screen> <para> If the <command>-d</command> option is specified, the exchange route is persistent, and will be restored if one or both of the brokers is restarted: </para> - + <screen> $ qpid-route -d dynamic add localhost:10004 localhost:10003 fed.topic </screen> @@ -450,7 +450,7 @@ $ qpid-route -d dynamic add localhost:10004 localhost:10003 fed.topic <para> The <command>del</command> command takes the same arguments as the <command>add</command> command. The following command deletes the first exchange route described above: </para> - + <screen> $ qpid-route dynamic del localhost:10004 localhost:10003 fed.topic </screen> @@ -459,13 +459,13 @@ $ qpid-route dynamic del localhost:10004 localhost:10003 fed.topic </para> </section> - + <section id="sect-Messaging_User_Guide-The_qpid_route_Utility-Viewing_Routes"> <title>Viewing Routes</title> <para> The <command>route list</command> command shows the routes associated with an individual broker. For instance, suppose we have created the following two routes: </para> - + <screen> $ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic $ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic @@ -473,7 +473,7 @@ $ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic <para> We can now use <command>route list</command> to show all routes for the broker <command>localhost:10003</command>: </para> - + <screen> $ qpid-route route list localhost:10003 localhost:10003 localhost:10004 fed.topic <dynamic> @@ -481,7 +481,7 @@ localhost:10003 localhost:10004 fed.topic <dynamic> <para> Note that this shows only one of the two routes we created, the route for which <command>localhost:10003</command> is a destination. If we want to see the route for which <command>localhost:10004</command> is a destination, we need to do another route list: </para> - + <screen> $ qpid-route route list localhost:10004 localhost:10004 localhost:10003 fed.topic <dynamic> @@ -489,7 +489,7 @@ localhost:10004 localhost:10003 fed.topic <dynamic> <para> The <command>route map</command> command shows all routes associated with a broker, and recursively displays all routes for brokers involved in federation relationships with the given broker. For instance, here is the output for the two brokers configured above: </para> - + <screen> $ qpid-route route map localhost:10003 @@ -508,7 +508,7 @@ Static Routes: <para> Note that the two dynamic exchange links are displayed as though they were one bidirectional link. The <command>route map</command> command is particularly helpful for larger, more complex networks. Let's configure a somewhat more complex network with 16 dynamic exchange routes: </para> - + <screen> qpid-route dynamic add localhost:10001 localhost:10002 fed.topic qpid-route dynamic add localhost:10002 localhost:10001 fed.topic @@ -534,7 +534,7 @@ qpid-route dynamic add localhost:10008 localhost:10006 fed.topic <para> Now we can use <command>route map</command> starting with any one broker, and see the entire network: </para> - + <screen> $ ./qpid-route route map localhost:10001 @@ -564,7 +564,7 @@ Static Routes: </screen> </section> - + <section id="sect-Messaging_User_Guide-The_qpid_route_Utility-Resilient_Connections"> <title>Resilient Connections</title> <para> @@ -573,14 +573,14 @@ Static Routes: <para> The command <command>list connections</command> can be used to show the resilient connections for a broker: </para> - + <screen> $ qpid-route list connections localhost:10001 Host Port Transport Durable State Last Error ============================================================================= -localhost 10002 tcp N Operational -localhost 10003 tcp N Operational +localhost 10002 tcp N Operational +localhost 10003 tcp N Operational localhost 10009 tcp N Waiting Connection refused </screen> <para> @@ -635,15 +635,6 @@ localhost 10009 tcp N Waiting Connection refused </entry> </row> - <row> - <entry> - Passive - </entry> - <entry> - If a cluster is federated to another cluster, only one of the nodes has an actual connection to remote node. Other nodes in the cluster have a passive connection. - </entry> - - </row> </tbody> @@ -652,10 +643,9 @@ localhost 10009 tcp N Waiting Connection refused </table> </section> - + </section> - -</section> +</section> diff --git a/qpid/doc/book/src/cpp-broker/queue-state-replication.xml b/qpid/doc/book/src/cpp-broker/queue-state-replication.xml deleted file mode 100644 index 3ffac805eb..0000000000 --- a/qpid/doc/book/src/cpp-broker/queue-state-replication.xml +++ /dev/null @@ -1,333 +0,0 @@ -<?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="queue-state-replication"> - <title> - Queue State Replication - </title> - - <section role="h2" id="queuestatereplication-AsynchronousReplicationofQueueState"> - <title> - Asynchronous - Replication of Queue State - </title> - - <section role="h3" id="queuestatereplication-Overview"> - <title> - Overview - </title> - <para> - There is support in qpidd for selective asynchronous replication - of queue state. This is achieved by: - </para> - <para> - (a) enabling event generation for the queues in question - </para> - <para> - (b) loading a plugin on the 'source' broker to encode those - events as messages on a replication queue (this plugin is - called - replicating_listener.so) - </para> - <para> - (c) loading a custom exchange plugin on the 'backup' broker (this - plugin is called replication_exchange.so) - </para> - <para> - (d) creating an instance of the replication exchange type on the - backup broker - </para> - <para> - (e) establishing a federation bridge between the replication - queue on the source broker and the replication exchange on the - backup broker - </para> - <para> - The bridge established between the source and backup brokers for - replication (step (e) above) should have acknowledgements turned - on (this may be done through the --ack N option to qpid-route). - This ensures that replication events are not lost if the bridge - fails. - </para> - <para> - The replication protocol will also eliminate duplicates to ensure - reliably replicated state. Note though that only one bridge per - replication exchange is supported. If clients try to publish to - the replication exchange or if more than a the single required - bridge from the replication queue on the source broker is - created, replication will be corrupted. (Access control may be - used to restrict access and help prevent this). - </para> - <para> - The replicating event listener plugin (step (b) above) has the - following options: - </para> - <programlisting> -Queue Replication Options: - --replication-queue QUEUE Queue on which events for - other queues are recorded - --replication-listener-name NAME (replicator) name by which to register the - replicating event listener - --create-replication-queue if set, the replication will - be created if it does not - exist - </programlisting> - <para> - The name of the queue is required. It can either point to a - durable queue whose definition has been previously recorded, or - the --create-replication-queue option can be specified in which - case the queue will be created a simple non-durable queue if it - does not already exist. - </para> - <!--h3--> - </section> - - <section role="h3" id="queuestatereplication-UsewithClustering"> - <title> - Use with - Clustering - </title> - <para> - The source and/or backup brokers may also be clustered brokers. - In this case the federated bridge will be re-established between - replicas should either of the originally connected nodes fail. - There are however the following limitations at present: - </para> - <itemizedlist> - <listitem> - <para>The backup site does not process membership updates after it - establishes the first connection. In order for newly added - members on a source cluster to be eligible as failover targets, - the bridge must be recreated after those members have been added - to the source cluster. - </para> - </listitem> - </itemizedlist> - <itemizedlist> - <listitem> - <para>New members added to a backup cluster will not receive - information about currently established bridges. Therefore in - order to allow the bridge to be re-established from these members - in the event of failure of older nodes, the bridge must be - recreated after the new members have joined. - </para> - </listitem> - </itemizedlist> - <itemizedlist> - <listitem> - <para>Only a single URL can be passed to create the initial link - from backup site to the primary site. this means that at the time - of creating the initial connection the initial node in the - primary site to which the connection is made needs to be running. - Once connected the backup site will receive a membership update - of all the nodes in the primary site, and if the initial - connection node in the primary fails, the link will be - re-established on the next node that was started (time) on the - primary site. - </para> - </listitem> - </itemizedlist> - <para> - Due to the acknowledged transfer of events over the bridge (see - note above) manual recreation of the bridge and automatic - re-establishment of te bridge after connection failure (including - failover where either or both ends are clustered brokers) will - not result in event loss. - </para> - <!--h3--> - </section> - - <section role="h3" id="queuestatereplication-OperationsonBackupQueues"> - <title> - Operations - on Backup Queues - </title> - <para> - When replicating the state of a queue to a backup broker it is - important to recognise that any other operations performed - directly on the backup queue may break the replication. - </para> - <para> - If the backup queue is to be an active (i.e. accessed by clients - while replication is on) only enqueues should be selected - for - replication. In this mode, any message enqueued on the source - brokers copy of the queue will also be enqueued on the backup - brokers copy. However not attempt will be made to remove messages - from the backup queue in response to removal of messages from the - source queue. - </para> - <!--h3--> - </section> - - <section role="h3" id="queuestatereplication-SelectingQueuesforReplication"> - <title> - Selecting - Queues for Replication - </title> - <para> - Queues are selected for replication by specifying the types of - events they should generate (it is from these events that the - replicating plugin constructs messages which are then pulled and - processed by the backup site). This is done through options - passed to the initial queue-declare command that creates the - queue and may be done either through qpid-config or similar - tools, or by the application. - </para> - <para> - With qpid-config, the --generate-queue-events options is used: - </para> - <programlisting> - --generate-queue-events N - If set to 1, every enqueue will generate an event that can be processed by - registered listeners (e.g. for replication). If set to 2, events will be - generated for enqueues and dequeues - </programlisting> - <para> - From an application, the arguments field of the queue-declare - AMQP command is used to convey this information. An entry should - be added to the map with key 'qpid.queue_event_generation' and an - integer value of 1 (to replicate only enqueue events) or 2 (to - replicate both enqueue and dequeue events). - </para> - <para> - Applications written using the c++ client API may fine the - qpid::client::QueueOptions class convenient. This has a - enableQueueEvents() method on it that can be used to set the - option (the instance of QueueOptions is then passed as the value - of the arguments field in the queue-declare command. The boolean - option to that method should be set to true if only enequeue - events should be replicated; by default it is false meaning that - both enqueues and dequeues will be replicated. E.g. - </para> - <programlisting> - QueueOptions options; - options.enableQueueEvents(false); - session.queueDeclare(arg::queue="my-queue", arg::arguments=options); - </programlisting> - <!--h3--> - </section> - - <section role="h3" id="queuestatereplication-Example"> - <title> - Example - </title> - <para> - Lets assume we will run the primary broker on host1 and the - backup on host2, have installed qpidd on both and have the - replicating_listener and replication_exchange plugins in qpidd's - module directory(*1). - </para> - <para> - On host1 we start the source broker and specifcy that a queue - called 'replication' should be used for storing the events until - consumed by the backup. We also request that this queue be - created (as transient) if not already specified: - </para> - <programlisting> - qpidd --replication-queue replication-queue --create-replication-queue true --log-enable info+ - </programlisting> - <para> - On host2 we start up the backup broker ensuring that the - replication exchange module is loaded: - </para> - <programlisting> - qpidd - </programlisting> - <para> - We can then create the instance of that replication exchange that - we will use to process the events: - </para> - <programlisting> - qpid-config -a host2 add exchange replication replication-exchange - </programlisting> - <para> - If this fails with the message "Exchange type not implemented: - replication", it means the replication exchange module was - not - loaded. Check that the module is installed on your system and if - necessary provide the full path to the library. - </para> - <para> - We then connect the replication queue on the source broker with - the replication exchange on the backup broker using the - qpid-route command: - </para> - <programlisting> - qpid-route --ack 50 queue add host2 host1 replication-exchange replication-queue -</programlisting> - <para> - The example above configures the bridge to acknowledge messages - in batches of 50. - </para> - <para> - Now create two queues (on both source and backup brokers), one - replicating both enqueues and dequeues (queue-a) and the - other - replicating only dequeues (queue-b): - </para> - <programlisting> - qpid-config -a host1 add queue queue-a --generate-queue-events 2 - qpid-config -a host1 add queue queue-b --generate-queue-events 1 - - qpid-config -a host2 add queue queue-a - qpid-config -a host2 add queue queue-b - </programlisting> - <para> - We are now ready to use the queues and see the replication. - </para> - <para> - Any message enqueued on queue-a will be replicated to the backup - broker. When the message is acknowledged by a client connected to - host1 (and thus dequeued), that message will be removed from the - copy of the queue on host2. The state of queue-a on host2 will - thus mirror that of the equivalent queue on host1, albeit with a - small lag. (Note - however that we must not have clients connected to host2 publish - to-or consume from- queue-a or the state will fail to replicate - correctly due to conflicts). - </para> - <para> - Any message enqueued on queue-b on host1 will also be enqueued on - the equivalent queue on host2. However the acknowledgement and - consequent dequeuing of messages from queue-b on host1 will have - no effect on the state of queue-b on host2. - </para> - <para> - (*1) If not the paths in the above may need to be modified. E.g. - if using modules built from a qpid svn checkout, the following - would be added to the command line used to start qpidd on host1: - </para> - <programlisting> - --load-module <path-to-qpid-dir>/src/.libs/replicating_listener.so - </programlisting> - <para> - and the following for the equivalent command line on host2: - </para> - <programlisting> - --load-module <path-to-qpid-dir>/src/.libs/replication_exchange.so - </programlisting> - <!--h3--> - </section> - <!--h2--> - </section> -</section> |