The procedures in this section show how to perform the following tasks for a conventional cluster:
There are two general methods of connecting brokers into a conventional 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 in the cluster 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. It is therefore a good idea to start the master broker first and then the others, after the master broker has completed its startup.
When connecting brokers into a conventional cluster, you should be aware of the following issues:
Mixed broker versions. A conventional cluster can contain brokers of different versions if all brokers have a version at least as great as that of the master broker. If the cluster is not configured to use a master broker, then all brokers must be of the same version.
Matching broker property values. In addition to cluster configuration properties, the following broker properties also must have the same value for all brokers in a cluster:
This restriction is particularly important when a cluster contains mixed broker versions that might contain properties with different default values. For example, If you are clustering a Message Queue version 4.1 or later broker together with those from earlier versions than Message Queue 4.1, you must set the value of the imq.autocreate.queue.maxNumActiveConsumers property, which has different default values before and after version 4.1 (1 and -1, respectively), to be the same. Otherwise the brokers will not be able to establish a cluster connection.
Multiple interface cards. On a multi-homed computer, in which there is more than one network interface card, be sure to explicitly set the network interface to be used by the broker for client connection services (imq.hostname) and for the cluster connection service (imq.cluster.hostname). If imq.cluster.hostname is not set, then connections between brokers might not succeed and as a result, the cluster will not be established.
Network loopback IP address. 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.
In particular, 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 each Linux system participating in the 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 DNS lookup is performed before consulting the local hosts file. The line in /etc/nsswitch.conf should read as follows: hosts: dns files/etc/nsswitch.conf to change the order of the entries so that
If you are using a master broker, identify it with the imq.cluster.masterbroker property in the configuration file.
Use the imqbrokerd command to start each broker.
If there is a master broker, start it first, then the others after it has completed its startup.
For example, the following command starts the broker as part of a cluster consisting of 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
Once the master broker (if any) is running, start each of the other brokers in the cluster with the imqbrokerd command, using the same list of brokers with the -cluster option that you used for the master broker.
The value specified for the -cluster option must be the same for all brokers in the cluster.
For each broker in the cluster, set up SSL-based connection services, as described in Message Encryption.
Issue the following command to any broker in the cluster:
imqcmd reload cls
This forces each broker to reload the imq.cluster.brokerlist property. 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.
Start the new broker.
(Optional) Set the values of the following properties in the new broker’s instance configuration file (config.properties) :
When the newly added broker starts, it connects and exchanges data with all the other brokers in the imq.cluster.brokerlist value.
Modify the imq.cluster.brokerlist property of other brokers in the cluster to include the new broker.
This step is not strictly necessary to add a broker to a functioning cluster. However, should any broker need to be restarted, its imq.cluster.brokerlist value must include all other brokers in the cluster, including the newly added broker.
Start the new broker.
If you did not perform step 1, use the -D option on the imqbrokerd command line to set the property values listed there.
The method you use to remove a broker from a conventional cluster depends on whether you originally created the cluster using a cluster configuration file or by means of command line options.
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:
Issue the following command to each broker remaining in the cluster:
imqcmd reload cls
This forces the brokers to reload the cluster configuration.
Stop the broker you’re removing from the cluster.
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:
Stop each broker in the cluster, using the imqcmd command.
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
As noted earlier, a conventional cluster can optionally have one master broker, which maintains a configuration change record to keep track of any changes in the cluster’s persistent state. The master broker is identified by the imq.cluster.masterbroker configuration property, either in the cluster configuration file or in the instance configuration files of the individual brokers.
Because of the important information that the configuration change record contains, it is important to back it up regularly so that it can be restored in case of failure. Although restoring from a backup will lose any changes in the cluster’s persistent state that have occurred since the backup was made, frequent backups can minimize this potential loss of information. The backup and restore operations also have the positive effect of compressing and optimizing the change history contained in the configuration change record, which can grow significantly over time.
imqbrokerd -backup mybackuplog
Shut down all brokers in the cluster.
Restore the master broker’s configuration change record from the backup file.
imqbrokerd -restore mybackuplog
If you assign a new name or port number to the master broker, update the imq.cluster.brokerlist and imq.cluster.masterbroker properties accordingly in the cluster configuration file.
Restart all brokers in the cluster.