Menu Search

13.5. Configuring a Virtual Host to be a node

To configure a virtualhost as a cluster node, configure the virtualhost.xml in the following manner:

Example 13.1. Configuring a VirtualHost to use the BDBHAMessageStore

<virtualhosts>
  <virtualhost>
    <name>vhostname</name>
    <vhostname>
      <store>
	<class>org.apache.qpid.server.store.berkeleydb.BDBHAMessageStore</class>
	<environment-path>${QPID_WORK}/bdbhastore/vhostname</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>
      ...
   </vhostname>
  </virtualhost>
</virtualhosts>


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.

13.5.1. Passing BDB environment and replication configuration options

It is possible to pass BDB environment and replication configuration options from the virtualhost.xml.

Environment configuration options are passed as described in Section 14.3.1, “Passing BDB environment configuration options”

Replication configuration option are passed using repConfig elements with the store element.

For example, to override the BDB replication configuration option je.rep.electionsPrimaryRetries.

         ...
      </highAvailability>
      ...
      <repConfig>
        <name>je.rep.electionsPrimaryRetries</name>
        <value>3</value>
      </repConfig>
      ...
    </store>