ejabberd cluster setup

by Gregor Uhlenheuer on October 3, 2013

Like I mentioned already in an older post on ejabberd - it is a really great piece of software but the biggest problem when using it or especially when you are troubleshooting is the lack of proper documentation or help resources.

You may often just need to install ejabberd as it is on your server and have it run like forever without the need of touching it. But problems arise if you have to go off the main route of using the out-of-the-box setup of ejabberd - i.e. you want to migrate your existing ejabberd into a clustered setup or create a clustered ejabberd from the very beginning. I didn’t find much help on this topic so I will describe a small walkthrough on how to setup some ejabberds in a cluster. The way I approach this task may not be the best one but this is the way I found to be the most stable and reproducable way I came up with after trying a lot of things on the way.

Building ejabberd

The first step will be the building and installation of the ejabberd nodes itself. These steps will be repeated for every node you want to participate in the cluster.

Get the sources

At first we will fetch the latest sources from ProcessOne’s repository on github. As recommended by ProcessOne the version 2.x is still the stable branch for production mode. So we will checkout the appropriate branch and compile from the sources. I have gone trough the described process for the latest commits on the so called “community edition” of ejabberd as well - and it works the same.

Building and installing

Next we will compile the sources with the familiar configure, make, make install procedure. Probably you have to create the configure script with autoreconf.

Now your ejabberd is successfully compiled and installed on your (first) node and is ready to be configured. In a non-clustered setup you would be almost finished - after adjusting our ejabberd.cfg you could already start the service by running ejabberdctl start.


This configuration part is actually the most important step of the setup. You will probably have to edit the three following files:


The ejabberd configuration can be found at /etc/ejabberd/ejabberd.cfg. There are a few settings you will probably want to edit.

$ vim /etc/ejabberd/ejabberd.cfg

If you have specific needs for ejabberd modules you can search for the modules section in the configuration file and (un)comment the appropriate modules:

At work we have the need to adjust the shaping settings as we are using the XMPP messaging for internal communication between different services that may exceed the default shaper limits.


Basically you have to adjust two settings in your ejabberdctl.cfg file - the configuration file of the ejabberd control script.

$ vim /etc/ejabberd/ejabberdctl.cfg


The last file we have to edit before we can start the first node is the control script ejabberdctl itself. I don’t really like to edit this file because updates of ejabberd and subsequent runs of make install would override your current settings. But sadly there is no way to set the ejabberd hostname in the ejabberdctl.cfg apart from being passed as an environment variable.

$ vim /sbin/ejabberdctl

The big advantage of editing the ejabberdctl script like this is that you can later start, stop, restart the ejabberd just by running ejabberdctl ... in your shell without caring about the correct ejabberd node name you are talking with. At work we found this to be the safest way especially to people not 100% aware of the ejabberd setup to execute basic control commands.

Starting the first node

Now we are ready to fire up the first ejabberd node. After starting the service you can register the root account you specified in your ejabberd.cfg.

$ ejabberdctl start
$ ejabberdctl register admin my.net ***

You should now be able to login into the web administration interface of ejabberd using your accout: http://node1:5280/admin

By the way, the web interface is configured in ejabberd.cfg in the listen section. You could for example modify the listening port like this:

Second and subsequent nodes

After the first node is up and running we can proceed with building the next nodes and joining those to the cluster.


The building and configuation of the other nodes can simply be repeated from the first node steps with modifying host names.

Join the cluster

After ejabberd is successfully built and installed when can proceed with the joining to the running first node.

First we have to exchange/synchronize the erlang cookie files. You could easily copy the erlang cookie file from the first node like this:

Connect mnesia

Now we are ready to connect the mnesia of the current node with the running first node’s mnesia database. We simply start an erlang shell and start a mnesia in the specified directory /var/lib/ejabberd:

Now as we are in the erlang shell we can interactively connect the two mnesia databases with each other. In case you are not sure what you are doing you can exit the erlang shell every time with <ctrl-c><ctrl-c>.

Join ejabberd to cluster

Now that the mnesia databases are connected you can start the second ejabberd.

$ ejabberdctl start

You can use the web interface on both hosts to check for all running nodes: http://node1:5280/admin/nodes/

More nodes…

The described procedure can now be repeated for as many ejabberd nodes you have and would like to join to the clustered setup.

When all ejabberds are up and running you can simply add ejabberdctl start/stop to your distribution’s init scripts and you have a reboot consistent ejabberd cluster!

This post is tagged with ejabberd, cluster, erlang and mnesia