ejabberd is a free XMPP server. It’s a program that runs on your server and enables communication via instant messaging, chat, and presence information. In simpler terms, it’s the server part of the equation that makes XMPP possible.
XMPP (Extensible Messaging and Presence Protocol) is a communication protocol used for instant messaging, presence, and other related applications. It’s the underlying technology that allows users of different clients/programs to communicate with each other even if they are using different software. This is known as federation.
What is federation?
Federation allows separate deployments of a communication service to
communicate with each other - for instance a mail server run by Google
federates with a mail server run by Microsoft when you send email from
Interoperable clients may simply be running on the same deployment - whereas in federation the deployments themselves are exchanging data in a compatible manner.
XMPP provides open federation - meaning that anyone on the internet can join into the XMPP ecosystem by deploying their own server. Credentials from your own server can be used as valid credentials on a different, totally unrelated server.
ejabberd is easiest installed through their official DEB and RPM packages
hosted on GitHub. DEB is what you use on Debian, and RPM is what you use on
Fedora. Head over to the GitHub page
here to install the latest
package. For instance, if you run Debian on an x86_64 machine, you download the
ejabberd_xx.yy-z_amd64.deb package. Thereafter, you run the following
commands in the directory where you downloaded your package:
More information on the official documentation page. There are also Docker images and Linux distribution packages, but those are either outdated or complicated compared to simply getting the official ejabberd packages from GitHub.
The ejabberd server is configured in
/etc/ejabberd/ejabberd.yml on Debian, or
/opt/ejabberd/conf/ejabberd.yml on Fedora. Changes are only applied by
restarting the ejabberd service in systemd:
systemctl restart ejabberd
Everything is done through this configuration file. Unlike many other programs which typically have two or more configuration files, ejabberd is controlled through one.
The XMPP hostname is specified in the hosts section of
ejabberd doesn’t come equipped with a script that can automatically copy over the relevant certificates to a directory where the ejabberd user can read them.
One way of organizing certificates for ejabberd is to have them stored in
/etc/ejabberd/certs, with each domain having a separate directory for both
the fullchain cert and private key.
Using certbot, this process can be easily automated with these commands:
certbot --nginx -d $DOMAIN certonly
mkdir -p /etc/ejabberd/certs/$DOMAIN
cp /etc/letsencrypt/live/$DOMAIN/fullchain.pem /etc/ejabberd/certs/$DOMAIN
cp /etc/letsencrypt/live/$DOMAIN/privkey.pem /etc/ejabberd/certs/$DOMAIN
Make sure all the certificates are readable by the
chown -R ejabberd:ejabberd /etc/ejabberd/certs
To enable the use of all these certificates in ejabberd, the following configuration is necessary:
The admin user can be specified in
ejabberd.yml under the
This would make
email@example.com the user with administrator privileges.
This is how login credentials look in XMPP, which might look strange if never
used IRC before, and are used to how modern software operates.
To ensure full compliance with XMPP standards, add the following configuration to mod_http_upload:
Make sure to create and give the ejabberd user ownership of
or any other directory you choose to use for file uploads:
chown -R ejabberd:ejabberd /var/www/upload
The ejabberd server supports keeping archives of messages through its mod_mam module. This can be enabled by uncommenting the following lines:
It’s disabled by default, in line with the philosophy that privacy should be opted out of, not into.
We can find the following comment in the
mod_mam section of the configuration file:
## Mnesia is limited to 2GB, better to use an SQL backend
## For small servers SQLite is a good fit and is very easy
## to configure. Uncomment this when you have SQL configured:
## db_type: sql
As these comments imply, an SQL backend is recommended if you wish to use your ejabberd server for anything more than just testing. Ejabberd supports MySQL, SQLite and PostgreSQL.
Setting up SQLite for ejabberd is very simple. Add the following lines somewhere in your configuration. These are top-level configuration (you don’t put them under anything else):
sql_database entry can of course be any directory and file name you like.
Make sure the
ejabberd user has permissions for that directory.
Lastly, your server will need the SQLite runtime libraries.
To begin using ejabberd, firstly start the ejabberd daemon:
systemctl start ejabberd
ejabberdctl as the
ejabberd user, register the admin user which
is set in the configuration file:
su -c "ejabberdctl register admin example.org password" ejabberd
This will create the user
By default, ejabberd has a web interface accessible from
http://example.org:5280/admin. When accessing this interface, you will be
prompted for the admin credentials:
After signing in with the admin credentials, you will be able to manage your ejabberd server from this web interface:
After following this guide, you should have an ejabberd server up and running. However, this is just the server. We of course need a client to go with it. Because, as said, XMPP is an open protocol, anyone can make any server and client implementation. Strangely, the mobile clients are the best, while there is only one graphical desktop program that is serviceable, and it is middling. Only mobile clients support voice chat.
As of the latest update of this article, the following clients are available:
- iOS and macOS
- Monal IM
The XMPP project, sponsored by the company behind ejabberd and others, maintains an interactive list of available clients for XMPP. However, the above list lists the only serviceable clients. All others are poor or abandonware, at least for now.
This guide is less of a comprehensive resource for everything ejabberd-related and more of a springboard towards getting you started as a landchad; who can run his own federated chat.
For a deeper look into all the modules and options, have a look at the following ejabberd documentation and concepts: