NO-JIRA: HA documentation: minor updates to HA chapter.

git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/0.22@1464657 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 118 insertions, 0 deletions

diff --git a/qpid/cpp/README-HA.txt b/qpid/cpp/README-HA.txt
new file mode 100644
index 0000000000..0b79664535
--- /dev/null
+++ b/qpid/cpp/README-HA.txt
@@ -0,0 +1,118 @@
+<!--*-markdown-*-->
+
+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.
+
+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
+[HA chapter of the C++ Broker Book][chapter-ha]
+
+Client connections and fail-over
+--------------------------------
+
+The old cluster module was active-active: clients could connect to any broker in
+the cluster. The new ha module is active-passive. Exactly 1 broker acts as
+*primary* the other brokers act as *backup*. Only the primary accepts client
+connections. If a client attempts to connect to a *backup* broker, the connection
+will be aborted and the client will fail-over until it connects to the primary. See
+["Client Connections and Failover"][ha-failover].
+
+The new cluster module also supports a [virtual IP address][ha-virtual-ip].
+Clients can be configured with a single IP address that is automatically routed
+to the primary broker. This is the recommended configuration.
+
+Migrating configuration options for the old cluster module
+----------------------------------------------------------
+
+`cluster-name`: Not needed.
+
+`cluster-size`: Not needed but see "Using a message store in a cluster" below
+
+`cluster-url`: Use `ha-public-url`, which is recommended to use a [virtual IP address][ha-virtual-ip]
+
+`cluster-cman`: Not needed
+
+`cluster-username, cluster-password, cluster-mechanism`: use `ha-username,
+ha-password, ha-mechanism`
+
+Configuration options for new HA module
+----------------------------------------
+
+`ha-cluster`: set to `yes` to enable clustering.
+
+`ha-brokers-url`: set to a URL listing each node in the cluster. For example
+`amqp:node1.exaple.com,node2.exaple.com,node3.exaple.com`. The set of addresses
+for the cluster is fixed, you can't add new members with different addresses
+while the cluster is running. You can shut-down and re-start a broker on the
+same address.
+
+`ha-public-url`: URL used by clients to connect to the cluster. It is
+recommended to set this to the [Virtual IP address][ha-virtual-ip] of the
+cluster.
+
+`ha-replicate`: Set to `all` to replicate everything like the old cluster does.
+New HA provides more flexibility over what is replicated, see ["Controlling replication of queues and exchanges"][ha-replicate-values].
+
+`ha-username, ha-password, ha-mechanism`: Same as old `cluster-username,
+cluster-password, cluster-mechanism`
+
+`ha-backup-timeout`: Maximum time that a recovering primary will wait for an
+expected backup to connect and become ready.
+
+`link-maintenance-interval`: Interval in seconds for the broker to check link
+health and re-connect links if need be. If you want brokers to fail over quickly
+you can set this to a fraction of a second, for example: 0.1.
+
+`link-heartbeat-interval` Heartbeat interval for replication links. The link
+will be assumed broken if there is no heartbeat for twice the interval.
+
+Configuring rgmanager
+---------------------
+
+The new HA module requires an external cluster resource manager, `rgmanager`
+provided by the `cman` package.  `rgmanager` is responsible for stopping and
+starting brokers and determining which broker is promoted to primary. It is also
+responsible for detecting primary failures and promoting a new primary.  See
+["Configuring rgmanager as resource manager"][ha-rm-config]
+
+Broker Administration Tools
+---------------------------
+
+ Normally, clients are not allowed to connect to a backup broker. However
+ management tools are allowed to connect to a backup brokers. If you use these
+ tools you must not add or remove messages from replicated queues, nor create or
+ delete replicated queues or exchanges as this will disrupt the replication
+ process and may cause message loss.
+
+qpid-ha allows you to view and change HA configuration settings.
+
+The tools qpid-config, qpid-route and qpid-stat will connect to a backup if you
+pass the flag ha-admin on the command line.
+
+Fail-over exchange
+------------------
+
+The fail-over exchange is not supported in new HA, use a
+[virtual IP address][ha-virtual-ip] instead.[]
+
+Using a message store in a cluster
+----------------------------------
+
+If you use a persistent store for your messages then each broker in a cluster
+will have its own store. If the entire cluster fails, when restarting the
+*first* broker that becomes primary will recover from its store. All the other
+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-failover]: 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
+