To configure a virtualhost as a cluster node, configure the virtualhost.xml in the following manner:
Example 12.1. Configuring a VirtualHost to use the BDBHAMessageStore
<virtualhost>
<name>myhost</name>
<myvhost>
<store>
<class>org.apache.qpid.server.store.berkeleydb.BDBHAMessageStore</class>
<environment-path>${work}/bdbhastore</environment-path>
<highAvailability>
<groupName>myclustername</groupName>
<nodeName>mynode1</nodeName>
<nodeHostPort>node1host:port</nodeHostPort>
<helperHostPort>node1host:port</helperHostPort>
<durability>NO_SYNC\,NO_SYNC\,SIMPLE_MAJORITY</durability>
<coalescingSync>true|false</coalescingSync>
<designatedPrimary>true|false</designatedPrimary>
</highAvailability>
</store>
...
</myvhost>
</virtualhost>
The groupName is the name of logical name of the cluster. All nodes within the
cluster must use the same groupName in order to be considered part of the cluster.
The nodeName is the logical name of the node. All nodes within the cluster must have a
unique name. It is recommended that the node name should be chosen from a different nomenclature from that of
the servers on which they are hosted, in case the need arises to move node to a new server in the future.
The nodeHostPort is the hostname and port number used by this node to communicate with the
the other nodes in the cluster. For the hostname, an IP address, hostname or fully qualified hostname may be used.
For the port number, any free port can be used. It is important that this address is stable over time, as BDB
records and uses this address internally.
The helperHostPort is the hostname and port number that new nodes use to discover other
nodes within the cluster when they are newly introduced to the cluster. When configuring the first node, set the
helperHostPort to its own nodeHostPort. For the second and subsequent nodes,
set their helperHostPort to that of the first node.
durability controls the durability
guarantees made by the cluster. It is important that all nodes use the same value for this property. The default value is
NO_SYNC\,NO_SYNC\,SIMPLE_MAJORITY. Owing to the internal use of Apache Commons Config, it is currently necessary
to escape the commas within the durability string.
coalescingSync controls the coalescing-sync
mode of Qpid. It is important that all nodes use the same value. If omitted, it defaults to true.
The designatedPrimary is applicable only to the two-node
case. It governs the behaviour of a node when the other node fails or becomes uncontactable. If true,
the node will be designated as primary at startup and will be able to continue operating as a single node master.
If false, the node will transition to an unavailable state until a third-party manually designates the node as
primary or the other node is restored. It is suggested that the node that normally fulfils the role of master is
set true in config file and the node that is normally replica is set false. Be aware that setting both nodes to
true will lead to a failure to start up, as both cannot be designated at the point of contact. Designating both
nodes as primary at runtime (using the JMX interface) will lead to a split-brain
in the case of network partition and must be avoided.
Note
Usage of domain names in helperHostPort and nodeHostPort is more preferebale
over IP addresses due to the tendency of more frequent changes of the last over the former.
If server IP address changes but domain name remains the same the HA cluster can continue working as normal
in case when domain names are used in cluster configuration. In case when IP addresses are used and they are changed with the time
than Qpid JMX API for HA can be used to change the addresses or remove the nodes from the cluster.
It is possible to pass BDB
environment and
replication configuration options from the virtualhost.xml. Environment configuration options are passed using
the envConfig element, and replication config using repConfig.
For example, to override the BDB environment configuration options je.cleaner.threads and
je.txn.timeout
...
</highAvailability>
<envConfig>
<name>je.cleaner.threads</name>
<value>2</value>
</envConfig>
<envConfig>
<name>je.txn.timeout</name>
<value>15 min</value>
</envConfig>
...
</store>And to override the BDB replication configuration options je.rep.electionsPrimaryRetries.
...
</highAvailability>
...
<repConfig>
<name>je.rep.electionsPrimaryRetries</name>
<value>3</value>
</repConfig>
...
</store>