doc/java-broker/src/docbkx/Java-Broker-Appendix-BDB-HA-Initial-Configuration.xml - qpid-broker-j - Git at Google

 <?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>
	<?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>