Hazelcast Clustering Plugin Readme

Overview

The Hazelcast plugin adds support for running multiple redundant Openfire servers together in a cluster. By running Openfire in a cluster, you can distribute the connection load among several servers, while also providing failover in the event that one of your servers fails. This plugin is a drop-in replacement for the original Openfire clustering plugin, using the open source Hazelcast data distribution framework in lieu of an expensive proprietary third-party product.

The current Hazelcast release is version 2.3.1.

Installation

To install Hazelcast, simply drop the hazelcast.jar into $OPENFIRE_HOME/plugins along with any other plugins you may have installed. Note that Hazelcast and the original Openfire clustering plugin (clustering.jar) are mutually exclusive. You will need to remove the clustering plugin before installing Hazelcast into your Openfire instance.

To create an Openfire cluster, you will need at least two separate Openfire servers, and each server must have the Hazelcast plugin installed. By default, the servers will discover each other by exchanging UDP (multicast) packets via a configurable IP address and port, but other initialization options are available if your network does not support multicast communication (see "Configuration" below).

In addition, you will need some form of load balancer to distribute the connection load among the members of your Openfire cluster. There are several commercial and open source alternatives for this, including the Apache web server (httpd) plus mod_proxy_balancer (if you are using the HTTP/BOSH Openfire connector). Some popular solutions include the F5 LTM (commercial) and HAProxy (open source), among many others.

Configuration

There are several configuration options built into the Hazelcast plugin as Openfire system properties:

  1. hazelcast.startup.delay.seconds (5): Number of seconds to wait before launching the Hazelcast plugin. This allows Openfire to deploy any other plugins before initializing the cluster caches, etc.
  2. hazelcast.startup.retry.count (1): Number of times to retry initialization if the cluster fails to start on the first attempt.
  3. hazelcast.startup.retry.seconds (10): Number of seconds to wait between subsequent attempts to start the cluster.
  4. hazelcast.max.execution.seconds (30): Maximum time to wait when running a synchronous task across members of the cluster.
  5. hazelcast.config.xml.filename (hazelcast-cache-config.xml): Name of the Hazelcast configuration file. By overriding this value you can easily install a custom cluster configuration file in the Hazelcast plugin /classes/ directory, or in the classpath of your own custom plugin.

The Hazelcast plugin uses the XML configuration builder to initialize the cluster from the XML file described above. By default the cluster members will attempt to discover each other via multicast at the following location:

Note that these values can be overridden in the plugin's /classes/hazelcast-cache-config.xml file (via the multicast-group and multicast-port elements). Many other initialization and discovery options exist, as documented in the Hazelcast configuration docs noted above. For example, to set up a two-node cluster using well-known DNS name/port values, try the following alternative: 
...
<join>
    <multicast enabled="false"/>
    <tcp-ip enabled="true">
      <hostname>of-node-a.example.com:5701</hostname>
      <hostname>of-node-b.example.com:5701</hostname>
    </tcp-ip>
    <aws enabled="false"/>
</join>
...
Please refer to the Hazelcast reference manual for more information.