Configuring Broker Clusters

You create a broker cluster by specifying cluster configuration properties for each of its member brokers. Except where noted in this chapter, cluster configuration properties must be set to the same value for each broker in a cluster. This section introduces these properties and the use of a cluster configuration file to specify them:

• The Cluster Configuration File

• Cluster Configuration Properties

• Displaying a Cluster Configuration

The Cluster Configuration File

Like all broker properties, cluster configuration properties can be set individually for each broker in a cluster, either in its instance configuration file (config.properties) or by using the -D option on the command line when you start the broker. However, except where noted in this chapter, each cluster configuration property must be set to the same value for each broker in a cluster.

For example, to specify the transport protocol for the cluster connection service, you can include the following property in the instance configuration file for each broker in the cluster: imq.cluster.transport=ssl. If you need to change the value of this property, you must change its value in the instance configuration file for every broker in the cluster.

For consistency and ease of maintenance, it is generally more convenient to collect all of the common cluster configuration properties into a central cluster configuration file that all of the individual brokers in a cluster reference. Using a cluster configuration file prevents the settings from getting out of synch and ensures that all brokers in a cluster use the same, consistent cluster configuration information.

When using a cluster configuration file, each broker’s instance configuration file must point to the location of the cluster configuration file by setting the imq.cluster.url property. For example,

imq.cluster.url=file:/home/cluster.properties

Cluster Configuration Properties

This section reviews the most important cluster configuration properties, grouped into the following categories:

• Cluster Connection Service Properties

• Conventional Broker Cluster Properties

• Enhanced Broker Cluster Properties

A complete list of cluster configuration properties can be found in Table 17-14

Cluster Connection Service Properties

The following properties are used to configure the cluster connection service used for internal communication between brokers in the cluster. These properties are used by both conventional and enhanced clusters.

• imq.cluster.transport specifies the transport protocol used by the cluster connection service, such as tcp or ssl.

• imq.cluster.port specifies the port number for the cluster connection service. You might need to set this property, for instance, to specify a static port number for connecting to the broker through a firewall.

• imq.cluster.hostname specifies the host name or IP address for the cluster connection service, used for internal communication between brokers in the cluster. The default setting works fine, however, explicitly setting the property can be useful if there is more than one network interface card installed in a computer. If you set the value of this property to localhost, the value will be ignored and the default will be used.

Conventional Broker Cluster Properties

In addition to the properties listed in Cluster Connection Service Properties, all conventional clusters use the following properties:

• imq.cluster.brokerlist specifies a list of broker addresses defining the membership of the cluster; all brokers in the cluster must have the same value for this property.

  For example, to create a conventional cluster consisting of brokers at port 9876 on host1, port 5000 on host2, and the default port (7676) on ctrlhost, use the following value:

  imq.cluster.brokerlist=host1:9876,host2:5000,ctrlhost

• imq.cluster.nomasterbroker specifies whether the cluster is a conventional cluster of peer brokers, which uses a shared JDBC data store for the cluster's configuration change record. When true, the cluster is a conventional cluster of peer brokers. When false (or omitted, as false is the default), the cluster is considered to be a conventional cluster with master broker, even if no master broker is actually specified. All brokers in a given cluster must have the same value for this property.

Each type of conventional cluster has additional properties to support its configuration, as described in the following two sections.

Additional Properties for Conventional Clusters with Master Broker

The following additional properties are used to configure a conventional cluster with a master broker:

• imq.cluster.masterbroker specifies which broker in a conventional cluster is the master broker that maintains the configuration change record that tracks the addition and deletion of destinations and durable subscribers. For example:

  imq.cluster.masterbroker=host2:5000

  While specifying a master broker using the imq.cluster.masterbroker is not mandatory for a conventional cluster with master broker to function, it guarantees that persistent information propagated across brokers (destinations and durable subscriptions) is always synchronized. See Conventional Clusters in Oracle GlassFish Server Message Queue 4.5 Technical Overview.

• imq.cluster.dynamicChangeMasterBrokerEnabled specifies whether the master broker can be changed to another broker in the cluster without stopping all the broker in the cluster. All brokers in a given cluster must have the same value for this property.

Additional Properties for Conventional Clusters of Peer Brokers

The following additional properties are used to configure a conventional cluster of peer brokers. All brokers in a given cluster must have the same values for these properties.

• imq.cluster.clusterid specifies the cluster identifier, which will be appended to the name of the configuration change record's database table in the JDBC data store. The value of this property must be the same for all brokers in a given cluster, but must be unique for each cluster: no two clusters may have the same cluster identifier.

• imq.cluster.sharecc.persist.jdbc.dbVendor specifies the name of the database vendor of the JDBC data store housing the configuration change record's table.

• imq.cluster.sharecc.persist.jdbc.<vendorName>.user specifies the user name, if required, for connecting to the database from vendor <vendorName>.

• imq.cluster.sharecc.persist.jdbc.<vendorName>.needpassword specifies whether a password is needed for connecting to the database from vendor <vendorName>.

• imq.cluster.sharecc.persist.jdbc.<vendorName>.password specifies the password, if required, for connecting to the database from vendor <vendorName>. This value should be set only in password files, as described in Password Files.

• imq.cluster.sharecc.persist.jdbc.<vendorName>.driver specifies the Java class name of the JDBC driver, if required, for connecting to the database from vendor <vendorName>.

• imq.cluster.sharecc.persist.jdbc.<vendorName>.opendburl specifies the URL for connecting to an existing database from vendor <vendorName>. This applies when a java.sql.Driver is used to connect to the database.

• imq.cluster.sharecc.persist.jdbc.<vendorName>.createdburl optionally specifies the URL for creating a new database from vendor <vendorName>. This applies only to embedded databases, such as Java DB.

• imq.cluster.sharecc.persist.jdbc.<vendorName>.closedburl optionally specifies the URL for closing a connection to the database from vendor <vendorName>. This applies only to some embedded databases, such as Java DB.

• imq.cluster.sharecc.persist.jdbc.<vendorName>.tableoption optionally specifies vendor-specific options to be passed to the database from vendor <vendorName> when creating the table schema.

• imq.cluster.sharecc.persist.jdbc.<vendorName>.property.<propName> specifies a vendor-specific property <propName> for the database from vendor <vendorName>.

Enhanced Broker Cluster Properties

Enhanced broker clusters, which share a JDBC-based data store, require more configuration than do conventional broker clusters. In addition to the properties listed in Cluster Connection Service Properties, the following categories of properties are used to configure an enhanced cluster:

• Enhanced Clusters: General Configuration Properties

• Enhanced Clusters: JDBC Configuration Properties

• Enhanced Clusters: Failure Detection Properties

Enhanced Clusters: General Configuration Properties

• imq.cluster.ha is a boolean value that specifies if the cluster is an enhanced cluster (true) or a conventional broker (false). The default value is false.

  If set to true, mechanisms for failure detection and takeover of a failed broker are enabled. Enhanced clusters are self-configuring: any broker configured to use the cluster’s shared data store is automatically registered as part of the cluster, without further action on your part. If the conventional cluster property, imq.cluster.brokerlist, is specified for a high–availability broker, the property is ignored and a warning message is logged at broker startup.

• imq.persist.store specifies the model for a broker's persistent data store. This property must be set to the value jdbc for every broker in an enhanced cluster.

• imq.cluster.clusterid specifies the cluster identifier, which will be appended to the names of all database tables in the cluster’s shared persistent store. The value of this property must be the same for all brokers in a given cluster, but must be unique for each cluster: no two running clusters may have the same cluster identifier.

• imq.brokerid is a broker identifier that must be unique for each broker in the cluster. Hence, this property must be set in each broker's instance configuration file rather than in a cluster configuration file.

Enhanced Clusters: JDBC Configuration Properties

The persistent data store for an enhanced cluster is maintained on a highly-available JDBC database.

The highly-availabile database may be MySQL Cluster Edition or Oracle Real Application Clusters (RAC), or it may be an open-source or third-party product. As described in JDBC-Based Persistence Properties, the imq.persist.jdbc.dbVendor broker property specifies the name of the database vendor, and all of the remaining JDBC-related properties are qualified with this vendor name.

The JDBC-related properties are discussed under JDBC-Based Persistence Properties and summarized in Table 17-8. See the example configuration for MySQL in Example 8-1.

Enhanced Clusters: Failure Detection Properties

The following configuration properties (listed in Table 17-14) specify the parameters for the exchange of heartbeat and status information within an enhanced cluster:

• imq.cluster.heartbeat.hostname specifies the host name (or IP address) for the heartbeat connection service.

• imq.cluster.heartbeat.port specifies the port number for the heartbeat connection service.

• imq.cluster.heartbeat.interval specifies the interval, in seconds, at which heartbeat packets are transmitted.

• imq.cluster.heartbeat.threshold specifies the number of missed heartbeat intervals after which a broker is considered suspect of failure.

• imq.cluster.monitor.interval specifies the interval, in seconds, at which to monitor a suspect broker’s state information to determine whether it has failed.

• imq.cluster.monitor.threshold specifies the number of elapsed monitor intervals after which a suspect broker is considered to have failed.

Smaller values for these heartbeat and monitoring intervals will result in quicker reaction to broker failure, but at the cost of reduced performance and increased likelihood of false suspicions and erroneous failure detection.

Displaying a Cluster Configuration

To display information about a cluster’s configuration, use the Command utility’s list bkr subcommand:

This lists the current state of all brokers included in the cluster to which a given broker belongs. The broker states are described in the following table:

Table 10-1 Broker States

The results of the imqcmd list bkr command are shown in Example 10-1 (for a conventional cluster) and Example 10-2 (for an enhanced cluster).

Example 10-1 Configuration Listing for a Conventional Cluster

Listing all the brokers in the cluster that the following broker is a member of:

-------------------------
Host         Primary Port
-------------------------
localHost    7676

Cluster Is Highly Available             False

-------------------------
Address         State
---------------------
whippet:7676    OPERATING
greyhound:7676  OPERATING

Example 10-2 Configuration Listing for an Enhanced Cluster

Listing all the brokers in the cluster that the following broker is a member of:

----------------------------------------------
Host         Primary Port    Cluster Broker ID
----------------------------------------------
localHost    7676            brokerA

Cluster ID                              myClusterID
Cluster Is Highly Available             True

--------------------------------------------------------------------------------------------------------------
                                                                           ID of broker       Time since last
Broker ID       Address         State                   Msgs in store   performing takeover   status timestamp
--------------------------------------------------------------------------------------------------------------
brokerA         localhost:7676  OPERATING               121                                   30 sec
brokerB         greyhound:7676  TAKEOVER_STARTED        52              brokerA               3 hrs
brokerC         jpgserv:7676    SHUTDOWN_STARTED        12346                                 10 sec
brokerD         icdev:7676      TAKEOVER_COMPLETE       0               brokerA               2 min
brokerE         mrperf:7676     *unknown                12                                    0 sec
brokerG         iclab1:7676     QUIESCING               4                                     2 sec
brokerH         iclab2:7676     QUIESCE_COMPLETE        8                                     5 sec