Bug 1130495

Description of problem:

Minor doc improvements to upstream for consideration. They may not be needed in RH docs if the federation options are already documented for federation.

------------------------------------------------------------------------
r1618160 | aconway | 2014-08-15 14:00:39 +0200 (Fri, 15 Aug 2014) | 9 lines

NO-JIRA: HA documentation improvements.

The broker options link-maintenance-interval and link-heartbeat-interval were documented
only in the HA section and not in the federation section which created confusion about
whether they affected HA links only or user federation links as well.

Added documentation to the federation section and an explicit mention in the HA section
that it uses federation links.


diff --git a/qpid/cpp/src/qpid/broker/Broker.cpp b/qpid/cpp/src/qpid/broker/Broker.cpp
index f244c98..f0d4e56 100644
--- a/qpid/cpp/src/qpid/broker/Broker.cpp
+++ b/qpid/cpp/src/qpid/broker/Broker.cpp
@@ -190,7 +190,7 @@ BrokerOptions::BrokerOptions(const std::string& name) :
         ("default-message-group", optValue(defaultMsgGroup, "GROUP-IDENTIFER"), "Group identifier to assign to messages delivered to a message group queue that do not contain an identifier.")
         ("enable-timestamp", optValue(timestampRcvMsgs, "yes|no"), "Add current time to each received message.")
         ("link-maintenance-interval", optValue(linkMaintenanceInterval, "SECONDS"),
-         "Interval to check link health and re-connect  if need be")
+         "Interval to check federation link health and re-connect if need be")
         ("link-heartbeat-interval", optValue(linkHeartbeatInterval, "SECONDS"),
          "Heartbeat interval for a federation link")
         ("dtx-default-timeout", optValue(dtxDefaultTimeout, "SECONDS"), "Default timeout for DTX transaction before aborting it")
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 40b3011..fbdf321 100644
--- a/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
+++ b/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
@@ -305,7 +305,7 @@ ssl_addr = "ssl:" host [":" port]'
 		virtual IP address instead.
 	      </para>
 	      <para>
-		If set, this URL is advertized by the
+		If set, this URL is advertised by the
 		<literal>amq.failover</literal> exchange and overrides the
 		broker option <literal>known-hosts-url</literal>
 	      </para>
@@ -339,7 +339,8 @@ ssl_addr = "ssl:" host [":" port]'
 	      <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
+		They can also have an explicit unit,
+		e.g. 10s (seconds), 10ms (milliseconds), 10us (microseconds), 10ns (nanoseconds)
 	      </para>
 	    </footnote>
 	    </entry>
@@ -357,9 +358,11 @@ ssl_addr = "ssl:" host [":" port]'
 	    </entry>
 	    <entry>
 	      <para>
-		Interval for backup brokers to check the link to the primary re-connect if need be.
-		Default 2 seconds. Can be set lower for faster failover, e.g. 0.1 seconds.
-		Setting it too low will result in excessive link-checking activity on the brokers.
+		HA uses federation links to connect from backup to primary.
+		Backup brokers check the link to the primary on this interval
+		and re-connect if need be. Default 2 seconds. Set lower for
+		faster failover, e.g. 0.1 seconds.  Setting too low will result
+		in excessive link-checking on the backups.
 	      </para>
 	    </entry>
 	  </row>
@@ -370,12 +373,14 @@ ssl_addr = "ssl:" host [":" port]'
 	    </entry>
 	    <entry>
 	      <para>
-		Heartbeat interval for replication links and timeout for broker status checks.
-		It may take up to this interval for rgmanager to detect a hung or partitioned broker.
-		The primary may take up to twice this interval to detect a hung or partitioned backup.
+		HA uses federation links to connect from backup to primary.
+		If no heart-beat is received for twice this interval the primary will consider that
+		backup dead (e.g. if backup is hung or partitioned.)
+		This interval is also used to time-out for broker status checks,
+		it may take up to this interval for rgmanager to detect a hung or partitioned broker.
 		Clients sending messages may be held up during this time.
 		Default 120 seconds: you will probably want to set this to a lower value e.g. 10.
-		If set too low, a slow broker may be considered as failed and killed.
+		If set too low rgmanager may consider a slow broker to have failed and kill it.
 	      </para>
 	    </entry>
 	  </row>
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 f5fedf8..27725b2 100644
--- a/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml
+++ b/qpid/doc/book/src/cpp-broker/Using-Broker-Federation.xml
@@ -653,9 +653,63 @@ localhost       10009   tcp          N     Waiting           Connection refused
 
     </section>
 
-
   </section>
 
-
+  <section id="federation-broker-options">
+    <title>Broker options affecting federation</title>
+    <para>
+      The following broker options affect federation:
+      <table frame="all" id="ha-broker-options">
+	<title>Broker Options for Federation</title>
+	<tgroup align="left" cols="2" colsep="1" rowsep="1">
+	  <colspec colname="c1"/>
+	  <colspec colname="c2"/>
+	  <thead>
+	    <row>
+	      <entry align="center" nameend="c2" namest="c1">
+		Options for Federation
+	      </entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry>
+		<literal>federation-tag <replaceable>NAME</replaceable></literal>
+	      </entry>
+	      <entry>
+		A unique name to identify this broker in federation network.
+		If not specified, the broker will generate a unique identifier.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>
+		<literal>link-maintenance-interval <replaceable>SECONDS</replaceable></literal>
+		<footnoteref linkend="ha-seconds-spec"/>
+	      </entry>
+	      <entry>
+		<para>
+		  Interval to check if links need to be re-connected.  Default 2
+		  seconds. Can be a sub-second interval for faster failover,
+		  e.g. 0.1 seconds.
+		</para>
+	      </entry>
+	    </row>
+	    <row>
+	      <entry>
+		<literal>link-heartbeat-interval <replaceable>SECONDS</replaceable></literal>
+		<footnoteref linkend="ha-seconds-spec"/>
+	      </entry>
+	      <entry>
+		<para>
+		  Heart-beat interval for federation links. If no heart-beat is
+		  received for twice the interval the link is considered dead.
+		  Default 120 seconds.
+		</para>
+	      </entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </para>
+  </section>
 </section>
-
------------------------------------------------------------------------
[aconway@gonzo build (trunk $)]$