This section presents step-by-step procedures for performing a variety of administrative tasks for a high-availability cluster:
Because high-availability clusters are self-configuring, there is no need to explicitly specify the list of brokers to be included in the cluster. Instead, all that is needed is to set each broker’s configuration properties appropriately and then start the broker; as long as its properties are set properly, it will automatically be incorporated into the cluster. Table 8–1 shows the required settings. In addition, there may be vendor-specific settings required for a particular vendor’s database; Table 8–2 and Table 8–3 show these vendor-specific settings for Sun’s own HADB and MySQL from MySQLAB, respectively.
Table 8–1 Required Configuration Properties for HA ClustersTable 8–2 Vendor-Specific Configuration Properties for HADB Database
Table 8–3 Vendor-Specific Configuration Properties for MySQL Database
Property |
Description |
---|---|
imq.persist.jdbc.mysql.user |
User name for opening database connection |
imq.persist.jdbc.mysql.password |
Password for opening database connection |
imq.persist.jdbc.mysql.property.url |
JDBC URL for opening database |
The property values can be set separately in each broker’s instance configuration file, or they can be specified in a cluster configuration file that all the brokers share. The procedures are as follows:
For each broker in the cluster:
Start the broker with the imqbrokerd command.
The first time a broker instance is run, an instance configuration file (config.properties) is automatically created.
Shut down the broker.
Use the imqcmd shutdown bkr command.
Edit the instance configuration file to specify the broker’s HA-related configuration properties.
Table 8–1 shows the required property values.
Specify any additional, vendor-specific properties that may be needed.
Table 8–2 and Table 8–3 show the required properties for HADB and MySQL databases, respectively.
Place a copy of, or a symbolic link to, your JDBC driver’s .jar file in the appropriate location, depending on your platform:
Solaris: /usr/share/lib/imq/ext/
Linux: /opt/sun/mq/share/lib/
Windows: IMQ_VARHOME\lib\ext
Create the database schema needed for Message Queue persistence.
Use the imqdbmgr create tbl command; see Database Manager Utility.
Restart each broker with the imqbrokerd command.
The brokers will automatically register themselves into the cluster on startup.
An alternative method, better suited for production systems, is to use a cluster configuration file to specify the composition of the cluster:
Create a cluster configuration file specifying the cluster’s HA-related configuration properties.
Table 8–1 shows the required property values. However, do not include the imq.brokerid property in the cluster configuration file; this must be specified separately for each individual broker in the cluster.
Specify any additional, vendor-specific properties that may be needed.
Table 8–2 and Table 8–3 show the required properties for HADB and MySQL databases, respectively.
For each broker in the cluster:
Start the broker with the imqbrokerd command.
The first time a broker instance is run, an instance configuration file (config.properties) is automatically created.
Shut down the broker.
Use the imqcmd shutdown bkr command.
Edit the instance configuration file to specify the location of the cluster configuration file.
In the broker’s instance configuration file, set the imq.cluster.url property to point to the location of the cluster configuration file you created in step 1.
Specify the broker identifier.
Set the imq.brokerid property in the instance configuration file to the broker’s unique broker identifier. This value must be different for each broker.
Place a copy of, or a symbolic link to, your JDBC driver’s .jar file in the appropriate location, depending on your platform:
Solaris: /usr/share/lib/imq/ext/
Linux: /opt/sun/mq/share/lib/
Windows: IMQ_VARHOME\lib\ext
Create the database schema needed for Message Queue persistence.
Use the imqdbmgr create tbl command; see Database Manager Utility.
Restart each broker with the imqbrokerd command.
The brokers will automatically register themselves into the cluster on startup.
Because HA clusters are self-configuring, the procedures for adding and removing brokers are simpler than for a conventional cluster:
Set the new broker’s HA-related properties, as described in the preceding section.
You can do this either by specifying the individual properties in the broker’s instance configuration file (config.properties) or, if there is a cluster configuration file, by setting the broker’s imq.cluster.url property to point to it.
Start the new broker with the imqbrokerd command.
The broker will automatically register itself into the cluster on startup.
Make sure the broker is not running.
If necessary, use the command
imqcmd shutdown bkr
to shut down the broker.
Remove the broker from the cluster with the command
imqdbmgr remove bkr
Although the takeover of a failed broker’s persistent data by another broker in an HA cluster is normally automatic, there may be times when you want to prevent such a takeover from occurring. To suppress automatic takeover when shutting down a broker, use the -nofailover option to the imqcmd shutdown bkr subcommand:
imqcmd shutdown bkr -nofailover -b hostName:portNumber
where hostName and portNumber are the host name and port number of the broker to be shut down.
Conversely, you may sometimes need to force a broker takeover to occur manually. (This might be necessary, for instance, if an automatic takeover broker were to fail before completing the takeover process.) In such cases, you can initiate a takeover manually from the command line: first shut down the broker to be taken over with the -nofailover option, as shown above, then issue the command
imqcmd takeover bkr -n brokerID
where brokerID is the broker identifier of the broker to be taken over. If the specified broker appears to be running, the Command utility will display a confirmation message:
The broker associated with brokerID last accessed the database # seconds ago. Do you want to take over for this broker?
You can suppress this message, and force the takeover to occur unconditionally, by using the -f option to the imqcmd takeover bkr command:
imqcmd takeover bkr -f -n brokerID
The imqcmd takeover bkr subcommand is intended only for use in failed-takeover situations. You should use it only as a last resort, and not as a general way of forcibly taking over a running broker.
You may also find it useful to quiesce a broker before shutting it down, causing it to refuse any new client connections while continuing to service old ones. This allows the broker’s operations to wind down gradually without triggering a takeover by another broker, for instance in preparation for shutting it down administratively for upgrade or similar purposes; see Quiescing a Broker for more information.
When converting to high-availability operation, you can use the Message Queue Database Manager utility (imqdbmgr) subcommand
imqdbmgr upgrade hastore
to convert an existing standalone HADB persistent data store to a shared HADB store. You can use this command in the following cases:
Moving from a Message Queue 4.0 standalone HADB store to a Message Queue 4.1 shared HADB store. In this case, the broker will automatically upgrade the store. You can then run the imqdbmgr upgrade hastore command to convert the upgraded data store for shared use.
Moving from a standalone Message Queue 4.1 HADB store to a shared HADB store. In this case, you just need to run the imqdbmgr upgrade hastore command to convert the data store for shared use.
Because this command only supports conversion of HADB stores, it cannot be used to convert file-based stores or other JDBC-based stores to a shared HADB store. If you were previously running a 3.x version of Message Queue, you must create an HADB store and then manually migrate your data to that store in order to use the high availability feature.
For durability and reliability, it is a good idea to back up a high-availability cluster’s shared persistent data store periodically to backup files. This creates a snapshot of the data store that you can then use to restore the data in case of catastrophic failure. The command for backing up the data store is
imqdbmgr backup -dir backupDir
where backupDir is the path to the directory in which to place the backup files. To restore the data store from these files, use the command
imqdbmgr restore -restore backupDir