Managing Clusters

This section describes how to connect a set of brokers to form a cluster, add new brokers to an existing cluster, and remove brokers from a cluster.

Connecting Brokers

There are two general methods of connecting brokers into a cluster: from the command line (using the -cluster option) or by setting the imq.cluster.brokerlist property in the cluster configuration file. Whichever method you use, each broker that you start attempts to connect to the other brokers every five seconds; the connection will succeed once the master broker is started up (if one is configured). If a broker in the cluster starts before the master broker, it will remain in a suspended state, rejecting client connections, until the master broker starts; the suspended broker then will automatically become fully functional.

To configure a broker cluster from the command line, use the -cluster option to the imqbrokerd command to specify the complete list of brokers in the cluster when you start each one. For example, the following command starts a new broker and connects it to the brokers running at the default port (7676) on host1, at port 5000 on host2, and at port 9876 on the default host (localhost):

imqbrokerd -cluster host1,host2:5000,:9876

An alternative method, better suited for production systems, is to create a cluster configuration file that uses the imq.cluster.brokerlist property to specify the list of brokers to be connected. Each broker in the cluster must then set its own imq.cluster.url property to point to this cluster configuration file.

Whichever method you use, you must make sure that no broker in the cluster is given an address that resolves to the network loopback IP address (127.0.0.1). Any broker configured with this address will be unable to connect to other brokers in the cluster.

Some Linux installers automatically set the localhost entry to the network loopback address. On such systems, you must modify the system IP address so that all brokers in the cluster can be addressed properly.

For all Linux systems that participate in a cluster, check the /etc/hosts file as part of cluster setup. If the system uses a static IP address, edit the /etc/hosts file to specify the correct address for localhost. If the address is registered with Domain Name Service (DNS), edit the file /etc/nsswitch.conf to change the order of the entries so that DNS lookup is performed before consulting the local hosts file. The line in /etc/nsswitch.conf should read as follows:

hosts: dns files

If you want secure, encrypted message delivery between brokers in a cluster, configure the cluster connection service to use an SSL-based transport protocol. For each broker in the cluster, set up SSL-based connection services, as described in Message Encryption. Then set each broker’s imq.cluster.transport property to ssl, either in the cluster configuration file or individually for each broker.

Adding Brokers to a Cluster

The procedure for adding a new broker to a cluster depends on whether the cluster uses a cluster configuration file.

To Add a New Broker to a Cluster Using a Cluster Configuration File

1. Add the new broker to the imq.cluster.brokerlist property in the cluster configuration file.

2. Issue the following command to any broker in the cluster:

   imqcmd reload cls

   This forces each broker to reload the cluster configuration, ensuring that all persistent information for brokers in the cluster is up to date. Note that it is not necessary to issue this command to every broker in the cluster; executing it for any one broker will cause all of them to reload the cluster configuration.

3. (Optional) Set the value of the imq.cluster.url property in the broker’s config.properties file to point to the cluster configuration file.

4. Start the new broker.

   If you did not perform Adding Brokers to a Cluster, use the -D option on the imqbrokerd command line to set the value of imq.cluster.url.

To Add a New Broker to a Cluster Without a Cluster Configuration File

Set the value of the following properties, either by editing the config.properties file or by using the -D option on the imqbrokerd command line:

• imq.cluster.brokerlist

• imq.cluster.masterbroker (if necessary)

• imq.cluster.transport (if you are using a secure cluster connection service)

Removing Brokers From a Cluster

The method you use to remove a broker from a cluster depends on whether you originally created the cluster via the command line or by means of a central cluster configuration file.

Removing a Broker Using the Command Line

If you used the imqbrokerd command from the command line to connect the brokers into a cluster, you must stop each of the brokers and then restart them, specifying the new set of cluster members on the command line. The procedure is as follows:

To Remove a Broker From a Cluster Using the Command Line

1. Stop each broker in the cluster, using the imqcmd command.

2. Restart the brokers that will remain in the cluster, using the imqbrokerd command’s -cluster option to specify only those remaining brokers.

   For example, suppose you originally created a cluster consisting of brokers A, B, and C by starting each of the three with the command

   imqbrokerd -cluster A,B, C

   To remove broker A from the cluster, restart brokers B and C with the command

   imqbrokerd -cluster B,C

Removing a Broker Using a Cluster Configuration File

If you originally created a cluster by specifying its member brokers with the imq.cluster.brokerlist property in a central cluster configuration file, it isn’t necessary to stop the brokers in order to remove one of them. Instead, you can simply edit the configuration file to exclude the broker you want to remove, force the remaining cluster members to reload the cluster configuration, and reconfigure the excluded broker so that it no longer points to the same cluster configuration file. Here is the procedure:

To Remove a Broker From a Cluster Using a Cluster Configuration File

1. Edit the cluster configuration file to remove the excluded broker from the list specified for the imq.cluster.brokerlist property.

2. Issue the following command to each broker remaining in the cluster:

   imqcmd reload cls

   This forces the broker to reload the cluster configuration.

3. Stop the broker you’re removing from the cluster.

4. Edit that broker’s config.properties file, removing or specifying a different value for its imq.cluster.url property.