# Openfire Connection Manager Module Installation Guide

Connection managers distribute the load of client connections to improve the scalability of XMPP servers. This document will guide you through installing the connection manager module as a standalone application. For a full list of features and more information, please visit the Openfire website: http://www.igniterealtime.org/projects/openfire

## Installation

### Windows

Uncompress connection_manager.zip to `c:\Program Files\connection_manager`.

### Linux/Unix

If using the .tar.gz, extract the archive to `/opt` or `/usr/bin`:

`tar -xzvf connection_manager_3_0_0.tar.gz
mv connection_manager /opt`

Note: the .tar.gz and .zip builds do not contain a bundled Java runtime (JRE). Therefore, you must have JDK or JRE 1.5.0 (Java 5) or later installed on your system. You can check your java version by typing "java -version" at the command line and (if necessary) upgrade your Java installation by visiting http://java.sun.com.

## Setup Overview

To complete the installation of the connection manager, you'll need to perform each of the following steps:

1. Setup - Configure properties to connect to XMPP server.
2. DNS Setup - Configure DNS to properly route traffic.

This document also includes information on:

- Running under Windows
- Running under Unix/Linux

## Files in the Distribution

The files in your distribution should be as follows (some sub-directories omitted for brevity):

    connection_manager/
     |- readme.html
     |- license.html
     |- conf/
     |- bin/
     |- lib/
     |- resources/
         |-security/
     |- documentation/

- The `conf` directory is where the connection manager module stores configuration files.
- The `bin` directory contains the server executables. Depending on which distribution you installed, different executables will be available.
- The `lib` directory contains libraries necessary for running the connection manager.
- The `resources/security` directory is where the connection manager maintains keystores to support SSL connection security.
- The `documentation` directory contains server documentation.

## Properties Setup

Properties are stored in conf/manager.xml. Only two properties are required to be configured. The xmpp.domain property that specifies the name of the target server that clients want to connect to and xmpp.password that specifies the password to use to log into the server.

## DNS Setup

XMPP requires that when clients or servers want to connect to another server, a DNS SRV lookup must be performed to get the real IP address and port to use to connect. Currently, connection managers only handle client-to-server traffic while server-to-server will go directly to the server. You will need to configure the DNS server so that client traffic is routed to connection managers. Depending on your architecture you may want to use a load balancer in front of a set of connection managers or just configure local DNS servers to redirect clients to a specific connection manager.

## Running the Connection Manager Module in Windows

Use the cmanager.bat batch file to start the connection manager. The file is located in the `bin/` directory of your Connection Manager installation.

### Custom Parameters

Advanced users may wish to pass in parameters to the Java virtual machine (VM) to customize the runtime environment of the connection manager module. You can do this by editing the bin/cmanager.bat or bin/cmanager.sh files and configuring the JVM_SETTINGS variable accordingly. For example, to set the minimum heap size to 512 MB and max VM heap size to 1024 MB, you'd use:

    -Xms512m -Xmx1024m

## Running the Connection Manager Module in Linux/Unix

You can start the connection manager module using the `bin/cmanager` script in your installation:

You must make the ant script executable. From the build directory, type: `chmod u+x cmanager.sh`

# ./cmanager