QPID-8409:[Broker-J][Docs] Improve documentation for BDB HA priority and add an example of BDB HA initial configuration
diff --git a/doc/java-broker/src/docbkx/Apache-Qpid-Broker-J-Book.xml b/doc/java-broker/src/docbkx/Apache-Qpid-Broker-J-Book.xml
index ee8aa96..a8d04df 100644
--- a/doc/java-broker/src/docbkx/Apache-Qpid-Broker-J-Book.xml
+++ b/doc/java-broker/src/docbkx/Apache-Qpid-Broker-J-Book.xml
@@ -41,4 +41,5 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Queue-Alerts.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Miscellaneous.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Queue-Declaration-Arguments.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-BDB-HA-Initial-Configuration.xml"/>
</book>
diff --git a/doc/java-broker/src/docbkx/Java-Broker-Appendix-BDB-HA-Initial-Configuration.xml b/doc/java-broker/src/docbkx/Java-Broker-Appendix-BDB-HA-Initial-Configuration.xml
new file mode 100644
index 0000000..465e201
--- /dev/null
+++ b/doc/java-broker/src/docbkx/Java-Broker-Appendix-BDB-HA-Initial-Configuration.xml
@@ -0,0 +1,221 @@
+<?xml version="1.0"?>
+<!--
+ ~
+ ~ 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.
+ ~
+ -->
+
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Java-Broker-Appendix-BDB-HA-initial-configuration">
+ <title>BDB HA initial configuration</title>
+ <para>The section <xref linkend="Java-Broker-Initial-Configuration-Introduction"/>
+ provides an introduction into Broker-J initial configuration and how broker configuration can be created from
+ initial configuration on first broker start-up. This appendix illustrates how to create a BDB HA group from an
+ initial configuration file. For creation of BDB HA group using Web Management Console please refer <xref linkend="Java-Broker-Management-Channel-Web-Console"/>.
+ </para>
+ <para>The BDB HA group usually consists of two or more nodes hosting a distributed virtual host.</para>
+ <para>When BDB HA node is created the following attributes has to be provided
+ <itemizedlist>
+ <listitem><para><emphasis>groupName</emphasis>; a name of BDB HA group</para></listitem>
+ <listitem><para><emphasis>nodeName</emphasis>; a name of BDB HA node</para></listitem>
+ <listitem><para><emphasis>address</emphasis>; a node address as colon-separated pair of host name and port</para></listitem>
+ <listitem><para><emphasis>helperAddress</emphasis>; an address of existing helper node. It is required when node joins an existing group.</para></listitem>
+ <listitem><para><emphasis>helperNodeName</emphasis>; a name of existing helper node. It is required when node joins an existing group.</para></listitem>
+ <listitem><para><emphasis>permittedNodes</emphasis>; an array containing all addresses of nodes allowed to join the group.</para></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ A node priority can be optionally specified for the node to influence master election among nodes with the most current set of data.
+ An attribute <emphasis>priority</emphasis> is used to specify a priority as an integer number.
+ </para>
+
+ <para>Apart from a group name and permitted nodes, the rest of node attribute values varies from node to node.</para>
+ <para>In order to use the same initial configuration for creation of BDB HA nodes, the context variable can be used for varying attribute values.</para>
+ <para>In the example of initial configuration illustrated in this apendix, the following context variables are defined.
+ <itemizedlist>
+ <listitem><para><emphasis>\${ha.group_name}</emphasis>; used to pass an HA group name</para></listitem>
+ <listitem><para><emphasis>\${ha.node_name}</emphasis>; used to pass a node name</para></listitem>
+ <listitem><para><emphasis>\${ha.node_address}</emphasis>; used to pass a node address</para></listitem>
+ <listitem><para><emphasis>\${ha.helper_address}</emphasis>; used to pass an address of helper node.</para></listitem>
+ <listitem><para><emphasis>\${ha.helper_node_name}</emphasis>; used to pass an address of helper node.</para></listitem>
+ <listitem><para><emphasis>\${ha.permitted_nodes}</emphasis>; used to pass a stringified json array containing permitted nodes for the group.</para></listitem>
+ <listitem><para><emphasis>\${ha.priority}</emphasis>; used to pass a node priority.</para></listitem>
+ </itemizedlist>
+ </para>
+ <section xml:id="Java-Broker-Appendix-BDB-HA-initial-configuration-example">
+ <title>Example of BDB HA 'Initial Configuration'</title>
+ <para> An example of 'Initial Configuration' for BDB HA:</para>
+ <example>
+ <title>BDB HA 'Initial configuration'</title>
+ <programlisting>
+{
+ "name": "\${broker.name}",
+ "modelVersion" : "8.0",
+ "authenticationproviders" : [ {
+ "name" : "plain",
+ "type" : "Plain",
+ "users" : [ {
+ "name" : "guest",
+ "type" : "managed",
+ "password" : "guest"
+ } ]
+ } ],
+ "brokerloggers" : [ {
+ "name" : "logfile",
+ "type" : "File",
+ "fileName" : "\${qpid.work_dir}\${file.separator}log\${file.separator}qpid.log",
+ "brokerloginclusionrules" : [ {
+ "name" : "Root",
+ "type" : "NameAndLevel",
+ "level" : "WARN",
+ "loggerName" : "ROOT"
+ }, {
+ "name" : "Qpid",
+ "type" : "NameAndLevel",
+ "level" : "INFO",
+ "loggerName" : "org.apache.qpid.*"
+ }, {
+ "name" : "Operational",
+ "type" : "NameAndLevel",
+ "level" : "INFO",
+ "loggerName" : "qpid.message.*"
+ }, {
+ "name" : "Statistics",
+ "type" : "NameAndLevel",
+ "level" : "INFO",
+ "loggerName" : "qpid.statistics.*"
+ } ]
+ }, {
+ "name" : "memory",
+ "type" : "Memory",
+ "brokerloginclusionrules" : [ {
+ "name" : "Root",
+ "type" : "NameAndLevel",
+ "level" : "WARN",
+ "loggerName" : "ROOT"
+ }, {
+ "name" : "Qpid",
+ "type" : "NameAndLevel",
+ "level" : "INFO",
+ "loggerName" : "org.apache.qpid.*"
+ }, {
+ "name" : "Operational",
+ "type" : "NameAndLevel",
+ "level" : "INFO",
+ "loggerName" : "qpid.message.*"
+ }, {
+ "name" : "Statistics",
+ "type" : "NameAndLevel",
+ "level" : "INFO",
+ "loggerName" : "qpid.statistics.*"
+ } ]
+ } ],
+ "ports" : [ {
+ "name" : "AMQP",
+ "port" : "\${qpid.amqp_port}",
+ "authenticationProvider" : "plain",
+ "virtualhostaliases" : [ {
+ "name" : "nameAlias",
+ "type" : "nameAlias"
+ }, {
+ "name" : "defaultAlias",
+ "type" : "defaultAlias"
+ }, {
+ "name" : "hostnameAlias",
+ "type" : "hostnameAlias"
+ } ]
+ }, {
+ "name" : "HTTP",
+ "port" : "\${qpid.http_port}",
+ "authenticationProvider" : "plain",
+ "protocols" : [ "HTTP" ]
+ }],
+ "virtualhostnodes" : [ {
+ "name" : "\${ha.node_name}",
+ "type" : "BDB_HA",
+ "address" : "\${ha.node_address}",
+ "groupName" : "\${ha.group_name}",
+ "helperAddress" : "\${ha.helper_address}",
+ "helperNodeName" : "\${ha.helper_node_name}",
+ "permittedNodes" : "\${ha.permitted_nodes}",
+ "priority" : "\${ha.priority}",
+ "defaultVirtualHostNode" : "true",
+ "virtualHostInitialConfiguration" : "\${qpid.initial_config_virtualhost_config}"
+ } ],
+ "plugins" : [ {
+ "type" : "MANAGEMENT-HTTP",
+ "name" : "httpManagement"
+ } ]
+}
+ </programlisting>
+ </example>
+
+ </section>
+ <section xml:id="Java-Broker-Appendix-BDB-HA-initial-configuration-creation">
+ <title>Creation of BDB HA group using an initial configuration.</title>
+ <para>Let's create a BDB HA group with name <literal>weather</literal>
+ consisting of tree nodes <literal>weather1</literal>, <literal>weather2</literal>, and <literal>weather3</literal>
+ using the initial configuration above. We start node <literal>weather1</literal> on host/port
+ <literal>chaac:5000</literal>, node <literal>weather2</literal> on host/port <literal>indra:5000</literal>
+ and node <literal>weather3</literal> on host/port <literal>thor:5000</literal>.</para>
+ <para>The node <literal>weather1</literal> can be created with the following command</para>
+ <screen>
+ $ ./qpid-server -icp ./initial-config.json -prop ha.node_name=weather1 -prop ha.node_address=chaac:5000 \
+ -prop ha.group_name=weather -prop ha.helper_address=chaac:5000 -prop ha.helper_node_name=weather1 \
+ -prop ha.permitted_nodes="[\"chaac:5000\",\"indra:5000\",\"thor:5000\"]" -prop ha.priority=3 \
+ -prop qpid.amqp_port=10000 -prop qpid.http_port=20000
+ </screen>
+ <para>Please note, the broker is started with initial configuration at file <literal>./initial-config.json</literal>.
+ The context variable for node name <literal>ha.node_name</literal> is set to <literal>weather1</literal>.
+ The node address context variable <literal>ha.node_address</literal> is set to <literal>chaac:5000</literal>.
+ As it is a first node, the helper address is set to the same address as a node address (<literal>ha.helper_address=chaac:5000</literal>)
+ and the helper node name is to itself (<literal>ha.helper_node_name=weather1</literal>). The group name is set to <literal>weather</literal>
+ with <literal>ha.group_name=weather</literal>. The group nodes are listed in <literal>ha.permitted_nodes</literal>.
+ The amqp and http ports are overridden to 10000 and 20000 accordingly. The node priority is set to <literal>3</literal>.
+ </para>
+ <para>The node <literal>weather2</literal> can be created on host<literal>indra</literal> with the following command:</para>
+ <screen>
+ $ ./qpid-server -icp ./initial-config.json -prop ha.node_name=weather2 -prop ha.node_address=indra:5000 \
+ -prop ha.group_name=weather -prop ha.helper_address=chaac:5000 -prop ha.helper_node_name=weather1 \
+ -prop ha.permitted_nodes="[\"chaac:5000\",\"indra:5000\",\"thor:5000\"]" -prop ha.priority=2 \
+ -prop qpid.amqp_port=10001 -prop qpid.http_port=20001
+ </screen>
+ <para>
+ The context variable for node name <literal>ha.node_name</literal> is set to <literal>weather2</literal>.
+ The node address context variable <literal>ha.node_address</literal> is set <literal>indra:5000</literal>.
+ The amqp and http ports are overridden to 10001 and 20001 accordingly. The node <literal>weather2</literal>
+ priority is set to <literal>2</literal>. The rest of the context variables have
+ the same values as for node <literal>weather1</literal>. The latter is used as a helper node for creation of
+ <literal>weather2</literal>.
+ </para>
+ <para>The node <literal>weather3</literal> can be created on host<literal>thor</literal> with the following command:</para>
+ <screen>
+ $ ./qpid-server -icp ./initial-config.json -prop ha.node_name=weather3 -prop ha.node_address=thor:5000 \
+ -prop ha.group_name=weather -prop ha.helper_address=chaac:5000 -prop ha.helper_node_name=weather1 \
+ -prop ha.permitted_nodes="[\"chaac:5000\",\"indra:5000\",\"thor:5000\"]" -prop ha.priority=1 \
+ -prop qpid.amqp_port=10002 -prop qpid.http_port=20002
+ </screen>
+ <para>
+ The context variable for node name <literal>ha.node_name</literal> is set to <literal>weather3</literal>.
+ The node address context variable <literal>ha.node_address</literal> is set <literal>thor:5000</literal>.
+ The amqp and http ports are overridden to 10002 and 20002 accordingly. The node <literal>weather3</literal>
+ priority is set to <literal>1</literal>. The rest of the context variables have
+ the same values as for node <literal>weather1</literal> which is used as a helper node for creation of
+ <literal>weather3</literal>.
+ </para>
+ </section>
+</appendix>
diff --git a/doc/java-broker/src/docbkx/Java-Broker-High-Availability.xml b/doc/java-broker/src/docbkx/Java-Broker-High-Availability.xml
index 739a78b..8bbab4c 100644
--- a/doc/java-broker/src/docbkx/Java-Broker-High-Availability.xml
+++ b/doc/java-broker/src/docbkx/Java-Broker-High-Availability.xml
@@ -95,8 +95,11 @@
<para>This section describes how to create a group. At a high level, creating a group involves
first creating the first node standalone, then creating subsequent nodes referencing the first
node so the nodes can introduce themselves and gradually the group is built up.</para>
- <para>A group is created through either <link linkend="Java-Broker-Management-Channel-Web-Console">Web Management</link> or the <link linkend="Java-Broker-Management-Channel-REST-API">REST API</link>. These instructions
- presume you are using Web Management. To illustrate the example it builds the group
+ <para>A group is created through either <link linkend="Java-Broker-Management-Channel-Web-Console">Web Management</link>
+ or the <link linkend="Java-Broker-Management-Channel-REST-API">REST API</link>
+ or the initial configuration (<xref linkend="Java-Broker-Appendix-BDB-HA-initial-configuration"/>
+ illustrates how to use initial configuration for BDB HA group creation).
+ These instructions presume you are using Web Management. To illustrate the example it builds the group
illustrated in figure <xref linkend="Java-Broker-High-Availability-OverviewOfHA-Figure"/></para>
<para><orderedlist>
<listitem>
@@ -295,39 +298,52 @@
</listitem>
</itemizedlist></para>
<para>It is possible to assign a one policy to the master and a different policy to the
- replicas. These are configured as <link linkend="Java-Broker-Management-Managing-Virtualhost-Attributes">attributes on the
- virtualhost</link>. By default the master uses <emphasis>SYNC</emphasis> and replicas use
- <emphasis>NO_SYNC</emphasis>.</para>
+ replicas. These are configured as <link linkend="Java-Broker-Management-Managing-Virtualhost-Attributes">
+ attributes <emphasis>localTransactionSynchronizationPolicy</emphasis> and
+ <emphasis>remoteTransactionSynchronizationPolicy</emphasis> on the virtualhost</link>.
+ By default the master uses <emphasis>SYNC</emphasis> and replicas use
+ <emphasis>NO_SYNC</emphasis>.</para>
</section>
<section xml:id="Java-Broker-High-Availability-Behaviour-NodePriority">
<title>Node Priority</title>
<para>Node priority can be used to influence the behaviour of the election algorithm. It is
useful in the case were you want to favour some nodes over others. For instance, if you wish
to favour nodes located in a particular data centre over those in a remote site. </para>
- <para>The following options are available: <itemizedlist>
+ <para>
+ A new master is elected among nodes with the most current set of log files. When there is a tie,
+ the priority is used as a tie-breaker to select amongst these nodes.
+ </para>
+ <para>
+ The node priority is set as an integer value. A priority of zero is used to ensure that a node cannot
+ be elected master, even if it has the most current set of files.
+ </para>
+ <para>For convenience, the Web Management Console uses user friendly names for the priority integer values
+ in range from 0 to 3 inclusive. The following priority options are available: <itemizedlist>
<listitem>
<para><emphasis>Highest</emphasis>. Nodes with this priority will be more favoured. In
the event of two or more nodes having the most recent transaction, the node with this
priority will be elected master. If two or more nodes have this priority the algorithm
- will make an arbitrary choice.</para>
+ will make an arbitrary choice. The priority value for option <emphasis>Highest</emphasis> is <emphasis>3</emphasis>.</para>
</listitem>
<listitem>
<para><emphasis>High</emphasis>. Nodes with this priority will be favoured but not as
- much so as those with Highest.</para>
+ much so as those with Highest. The priority value for this option is <emphasis>2</emphasis>.</para>
</listitem>
<listitem>
- <para><emphasis>Normal</emphasis>. This is default election priority.</para>
+ <para><emphasis>Normal</emphasis>. This is a default election priority.
+ The priority value for this option is <emphasis>1</emphasis>.</para>
</listitem>
<listitem>
<para><emphasis>Never</emphasis>. The node will never be elected <emphasis>even if the
node has the most recent transaction</emphasis>. The node will still keep up to date
with the replication stream and will still vote itself, but can just never be
- elected.</para>
+ elected. The priority value for this option is <emphasis>0</emphasis>.</para>
</listitem>
</itemizedlist>
</para>
- <para>Node priority is configured as an <link linkend="Java-Broker-Management-Managing-Virtualhost-Nodes-Attributes">attribute on the
- virtualhost node</link> and can be changed at runtime and is effective immediately.</para>
+ <para>Node priority is configured as an <link linkend="Java-Broker-Management-Managing-Virtualhost-Nodes-Attributes">
+ attribute <emphasis>priority</emphasis> on the virtualhost node</link> and can be changed
+ at runtime and is effective immediately.</para>
<important>
<para>Use of the Never priority can lead to transaction loss. For example, consider a group
of three where replica-2 is marked as Never. If a transaction were to arrive and it be
@@ -354,8 +370,9 @@
just this one node?</para>
<para>In this case, Required Number of Nodes can be reduced to 1 on the remain node, allowing
the node to elect itself and service to be restored from the singleton. Required minimum
- number of nodes is configured as an <link linkend="Java-Broker-Management-Managing-Virtualhost-Nodes-Attributes">attribute on the
- virtualhost node</link> and can be changed at runtime and is effective immediately.</para>
+ number of nodes is configured as an <link linkend="Java-Broker-Management-Managing-Virtualhost-Nodes-Attributes">
+ attribute <emphasis>quorumOverride</emphasis> on the virtualhost node</link> and can be changed
+ at runtime and is effective immediately.</para>
<important>
<para>The attribute must be used cautiously. Careless use will lead to lost transactions and
can lead to a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://en.wikipedia.org/wiki/Split-brain_(computing)">split-brain</link> in the event of a network partition. If used to temporarily restore
@@ -370,8 +387,9 @@
<para> In a group of two, if a node were to fail then in default configuration work will cease
as quorum no longer exists. A single node cannot elect itself master. </para>
<para>The <literal>allow to operate solo</literal> flag allows a node in a two node group to elect itself master and
- to operate sole. It is configured as an <link linkend="Java-Broker-Management-Managing-Virtualhost-Nodes-Attributes">attribute on the
- virtualhost node</link> and can be changed at runtime and is effective immediately.</para>
+ to operate sole. It is configured as an <link linkend="Java-Broker-Management-Managing-Virtualhost-Nodes-Attributes">
+ attribute <emphasis>designatedPrimary</emphasis> on the virtualhost node</link> and can be changed
+ at runtime and is effective immediately.</para>
<para>For example, consider a group of two where the master fails. Service will be interrupted
as the remaining node cannot elect itself master. To allow it to become master, apply the
<literal>allow to operate solo</literal> flag to it. It will elect itself master and work can continue, albeit
