QPID-6035: HA clearly distinguish qpid-ha commands intended for cluster manager.

This commit adds a --cluster-manager flag to qpid-ha tool.

Without this flag
- the 'promote' command is not listed in the tool help.
- using the promote command raises an error saying that it is only for cluster manager use
  and mentioning the --cluster-manager flag.

With the flag: promote functions as before.

The qpid-ha help text for promote is also more clear now that it is for cluster
manager only.

Originally the idea was to split qpid-ha into two tools but I have kept one tool
with the flag and warning messages because it:

- avoids packaging changes that might trip things up.

- helps people who are already using qpid-ha promote: their scripts will
  break but the error message explains how to fix it.

I think the special role of promote is sufficiently clear now even if it is
part of the same tool.

This commit also updates the following to take account of the new flag:
- rgmanager qpidd-primary script.
- qpidd tests.
- qpid book HA chapter.

NOTE: THIS WILL BREAK TEST HARNESSES that do promotion outside of rgmanager.
You'll need to add the --cluster-manager flag in the relevant places.

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

1 files changed, 23 insertions, 16 deletions

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 fbdf321c56..26d701df64 100644
--- a/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
+++ b/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
@@ -927,29 +927,35 @@ acl allow <replaceable>USER</replaceable>@QPID all all
       </itemizedlist>
     </para>
     <para>
-      The <command>qpid-ha</command> command allows you to check if a broker is primary,
-      and to promote a backup to primary.
+      The <command>qpid-ha</command> command allows you to check if a broker is
+      primary, and to promote a backup to primary.
     </para>
     <para>
       To test if a broker is the primary:
-      <programlisting>
-qpid-ha -b <replaceable>broker-address</replaceable> status --expect=primary
-      </programlisting>
-      This command will return 0 if the broker at <replaceable>broker-address</replaceable>
-      is the primary, non-0 otherwise.
+    </para>
+    <programlisting>qpid-ha -b <replaceable>broker-address</replaceable> status --expect=primary</programlisting>
+    <para>
+      This will return 0 if the broker at <replaceable>broker-address</replaceable> is the primary,
+      non-0 otherwise.
     </para>
     <para>
       To promote a broker to primary:
-      <programlisting>
-qpid-ha -b <replaceable>broker-address</replaceable> promote
-      </programlisting>
+    <programlisting>qpid-ha --cluster-manager -b <replaceable>broker-address</replaceable> promote</programlisting>
+    </para>
+    <para>
+      Note that <literal>promote</literal> is considered a "cluster manager
+      only" command. Incorrect use of <literal>promote</literal> outside of the
+      cluster manager could create a cluster with multiple primaries. Such a
+      cluster will malfunction and lose data.  "Cluster manager only" commands
+      are not accessible in <command>qpid-ha</command> without the
+      <literal>--cluster-manager</literal> option.
     </para>
     <para>
-      <command>qpid-ha --help</command> gives information on other commands and options available.
-      You can also use <command>qpid-ha</command> to manually examine and promote brokers. This
-      can be useful for testing failover scenarios without having to set up a full resource manager,
-      or to simulate a cluster on a single node. For deployment, a resource manager is required.
+      To list the full set of commands use:
     </para>
+    <programlisting>
+qpid-ha --cluster-manager --help
+    </programlisting>
   </section>
 
   <section id ="ha-store">
@@ -999,8 +1005,9 @@ warning Client closed connection with 320: ACL denied anonymous@QPID creating a
       <para>
 	Set the HA security configuration and ACL file as described in <xref
 	linkend="ha-security"/>.  Once the cluster is running and the primary is
-	promoted , run <literal>qpid-ha</literal> to make sure that the brokers
-	are running as one cluster.
+	promoted , run:
+	<programlisting>qpid-ha status --all</programlisting>
+	to make sure that the brokers are running as one cluster.
       </para>
     </section>
     <section id="ha-troubleshoot-slow-recovery">