qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acon...@apache.org
Subject svn commit: r1484867 - in /qpid/branches/0.22/qpid: cpp/ doc/book/src/cpp-broker/
Date Tue, 21 May 2013 16:47:27 GMT
Author: aconway
Date: Tue May 21 16:47:26 2013
New Revision: 1484867

URL: http://svn.apache.org/r1484867
Log:
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.

Removed:
    qpid/branches/0.22/qpid/doc/book/src/cpp-broker/queue-state-replication.xml
Modified:
    qpid/branches/0.22/qpid/cpp/README-HA.txt
    qpid/branches/0.22/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml
    qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
    qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml
    qpid/branches/0.22/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml
    qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml
    qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml

Modified: qpid/branches/0.22/qpid/cpp/README-HA.txt
URL: http://svn.apache.org/viewvc/qpid/branches/0.22/qpid/cpp/README-HA.txt?rev=1484867&r1=1484866&r2=1484867&view=diff
==============================================================================
--- qpid/branches/0.22/qpid/cpp/README-HA.txt (original)
+++ qpid/branches/0.22/qpid/cpp/README-HA.txt Tue May 21 16:47:26 2013
@@ -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 c
 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

Modified: qpid/branches/0.22/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.22/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml?rev=1484867&r1=1484866&r2=1484867&view=diff
==============================================================================
--- qpid/branches/0.22/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml (original)
+++ qpid/branches/0.22/qpid/doc/book/src/cpp-broker/AMQP-Messaging-Broker-CPP-Book.xml Tue
May 21 16:47:26 2013
@@ -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"/>

Modified: qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml?rev=1484867&r1=1484866&r2=1484867&view=diff
==============================================================================
--- qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml (original)
+++ qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml Tue May 21
16:47:26 2013
@@ -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 con
       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 con
     </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 ] &amp;&amp; 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

Modified: qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml?rev=1484867&r1=1484866&r2=1484867&view=diff
==============================================================================
--- qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml
(original)
+++ qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Cheat-Sheet-for-configuring-Queue-Options.xml
Tue May 21 16:47:26 2013
@@ -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>
 
 

Modified: qpid/branches/0.22/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.22/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml?rev=1484867&r1=1484866&r2=1484867&view=diff
==============================================================================
--- qpid/branches/0.22/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml (original)
+++ qpid/branches/0.22/qpid/doc/book/src/cpp-broker/HA-Queue-Replication.xml Tue May 21 16:47:26
2013
@@ -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>

Modified: qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml?rev=1484867&r1=1484866&r2=1484867&view=diff
==============================================================================
--- qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml (original)
+++ qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Managing-CPP-Broker.xml Tue May 21 16:47:26
2013
@@ -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

Modified: qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml?rev=1484867&r1=1484866&r2=1484867&view=diff
==============================================================================
--- qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml (original)
+++ qpid/branches/0.22/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml Tue May 21
16:47:26 2013
@@ -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 &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62; 
+qpid-route [OPTIONS] dynamic add &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62;
 qpid-route [OPTIONS] dynamic del &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62;
 
-qpid-route [OPTIONS] route add &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62; &#60;routing-key&#62; 
+qpid-route [OPTIONS] route add &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62; &#60;routing-key&#62;
 qpid-route [OPTIONS] route del &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62; &#60;routing-key&#62;
 
 qpid-route [OPTIONS] queue add &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;dest-exchange&#62;  &#60;src-queue&#62;
 qpid-route [OPTIONS] queue del &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;dest-exchange&#62;  &#60;src-queue&#62;
 
 qpid-route [OPTIONS] list  [&#60;broker&#62;]
-qpid-route [OPTIONS] flush [&#60;broker&#62;]    
+qpid-route [OPTIONS] flush [&#60;broker&#62;]
 qpid-route [OPTIONS] map   [&#60;broker&#62;]
 
 <!--          qpid-route [OPTIONS] add connection &lt;dest-broker&gt; &lt;src-broker&gt;
@@ -185,7 +185,7 @@ qpid-route [OPTIONS] list connections [&
 		 <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 [:&#60;port&#62;]
 </screen>
@@ -235,13 +235,13 @@ qpid-route [OPTIONS] list connections [&
 						</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 [&
 							<command>-t &#60;transport&#62; [ --transport &#60;transport&#62;]</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 [&
 			 <para>
 				The syntax for creating and deleting queue routes is as follows:
 			</para>
-			 
+
 <screen>
 qpid-route [OPTIONS] queue add &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;dest-exchange&#62; &#60;src-queue&#62;
 qpid-route [OPTIONS] queue del &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;dest-exchange&#62; &#60;src-queue&#62;
@@ -320,102 +320,102 @@ qpid-route [OPTIONS] queue del &#60;dest
 			 <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 &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62; &#60;routing-key&#62; 
+qpid-route [OPTIONS] route add &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62; &#60;routing-key&#62;
 qpid-route [OPTIONS] route del &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62; &#60;routing-key&#62;
 qpid-route [OPTIONS] flush [&#60;broker&#62;]
 </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 [&#60;broker&#62;]
 </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 &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62; 
+qpid-route [OPTIONS] dynamic add &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62;
 qpid-route [OPTIONS] dynamic del &#60;dest-broker&#62; &#60;src-broker&#62;
&#60;exchange&#62;
 </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 exc
 			 <para>
 				Now let&#39;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&#39;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
 			 <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:10
 			 <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
 			</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
 			 <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 &#60;dynamic&#62;
@@ -481,7 +481,7 @@ localhost:10003 localhost:10004 fed.topi
 			 <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 &#60;dynamic&#62;
@@ -489,7 +489,7 @@ localhost:10004 localhost:10003 fed.topi
 			 <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&#39;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 l
 			 <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  
 							</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  
 			</table>
 
 		</section>
-		
+
 
 	</section>
-	
 
-</section>
 
+</section>



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message