# Clustering Plugin Readme

## Overview

The clustering 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, as well as having some form of failover in the event that one of your servers dies. This plugin requires a valid Oracle Coherence license.

In order to run Oracle Coherence in production mode, you will need to secure licensing for (at least) the Enterprise Edition (EE) of Coherence. Refer to the Oracle Fusion licensing docs for more information. Openfire uses the Compute Grid InvocationService to distribute tasks among the cluster members, but this feature is currently available only in EE or Grid Edition (GE).

Note that Coherence is configured to run as GE in development mode by default. You can change this setting by overriding the following Java system properties via /etc/sysconfig/openfire (RPM) or openfired.vmoptions (Windows):

       -Dtangosol.coherence.edition=EE
       -Dtangosol.coherence.mode=prod

The current Coherence release is version 3.7.1.

## Installation

After installing the clustering plugin (by copying clustering.jar into the Openfire plugins directory), follow steps 1 through 4 for adding Oracle Coherence libraries to Openfire. Step 5 explains how to add this plugin to your Openfire setup.

1. Get Oracle Coherence for Java Version.
2. Unzip the coherence file and locate coherence.jar and coherence-work.jar in folder coherence/lib.
3. Copy coherence.jar and coherence-work.jar to [openfire_home]/plugins/clustering/lib.
4. Restart Openfire server.

This version of the plugin has been updated to be compatible with Oracle Coherence Version 3.7.1. Earlier versions of the clustering plugin are incompatible with Coherence 3.7.1 due to certain changes in the Coherence API.

## Upgrading from Openfire Enterprise

To upgrade from Enterprise, you will need to shut down your server, remove the enterprise.jar file and enterprise directory from the plugins directory in your Openfire install root, and then follow the steps outlined in the Installation section above.

## Configuration

To enable clustering or monitor the cluster go to: Server --> Server Manager --> Clustering

You can change a number of Coherence properties by overriding Java system properties via /etc/sysconfig/openfire (RPM) or openfired.vmoptions (Windows). For example, to change the default cluster multicast port number, use the following:

       -Dtangosol.coherence.clusterport=32380

Other such settings may be found in the tangosol-coherence.xml file located in the coherence.jar file, identified via the "system-property" attribute.

## Compiling from source code

If you want to modify or maintain this plugin you will need to get its source code and compile it. Source code of this plugin is now available in the list of plugins that you get when you download the Openfire's source code. Follow these steps to have a working environment:

1. Get Openfire's source code.
2. Get Oracle Coherence for Java Version.
3. Unzip the coherence file and locate coherence.jar and coherence-work.jar in folder coherence/lib.
4. Copy coherence.jar and coherence-work.jar to [openfire]/plugins/clustering/lib.
5. Add coherence.jar and coherence-work.jar to your IDE build path, or use the Ant build script provided with the Openfire source distribution (e.g. "ant -Dplugin=clustering plugin").