ejabberd on Uberspace

auf Deutsch lesen


Goal of this instruction is to end up with a system that offers in your area of responsibility a high level on self management and data confidentiality for your communication with your interlocutors. For that purpose we will explain how to install a service called ejabberd at Uberspace to chat via XMPP.

A detailed explanation on XMPP/Jabber ist available on Wikipedia. It is a protocol that allows communication like a chat aside from a specific software or a specific device. Every user can chose either to register on one of the many free servers or to run an own server. There is a selection of free clients and programs alike for the different operating systems and device, desktop and laptop computer and smartphones, to connect with your account to a server and to communicate with other users.

The choice in my case was ejabberd, because I found an instruction on the list of cool stuff in the Uberspace wiki. After reading about it on Wikipedia I got a likeable impression and was satisfied with the features mentioned there. Unfortunately the listed instruction was outdated and I failed in setting up a working server.

With hints from Kim from the Uberspace crew and some users from the Jitsi mailing list and mainly a lot of help and endurance from my friend and personal IT support Uranoxyd, I succeed. To thank and to contribute to the distribution of free software and secure, self-determined communication, Uranoxyd and I wrote this introduction. We hope it makes more users dare to install their own server and helps them to successfully complete this task. We are accepting hints, amendments and correction. Send me an e-mail or login to my XMPP server with the browser client (the tab on the bottom at the left) as user visitor and the password rotisiv.


In 2018 Christian applied this guide on the ejabberd version 18 and reported success. As expected the numbers of the lines in the configuration part don't fit anymore, but the rest does.


This instruction presumes that you have an Uberspace account and that you are familiar with the shell.

To explain certain things we will use the common domain example.org which you always have to replace by your own domain. Decide if you want to run your ejabberd server on your main domain or on a subdomain like xmpp (could be any other as well). The names of your user's account depend on this choice. Either foobar@example.org or foobar@xmpp.example.org.

The former might look nicer and easier to remember but has an underbelly. Some modules of the ejabberd server expect services on subdomains. Their are four of these kind: conference., echo., pubsub. and irc. The multi user chat, shortly MUC, likes to be available on conference.example.org. If you don't want to have these subdomains, for example because your are using at least one of them already for other things, it would be better to run the server on a subdomain. Like that the ejabberd subdomains would become sub-subdomains like irc.xmpp.example.org.

We explain the whole process for the case of using a subdomain called xmpp.example.org. Like that it is easier to cover both cases. If you don't use a subdomain replace the phrase xmpp.example.org by example.org every time you find it in this text.


Ejabberd is a service that communicates on three different ports which are standardised. It isn't possible to use these standards on Uberspace and so you have to unlock three other ones on their firewall. You'll get explanation and instruction in the uberspace wiki`. So execute three time in a row the shell command for adding a port:

$ uberspace-add-port -p tcp --firewall

Every time you'll receive a confirmation with the opened port.

Determine the port you want to use for the connection between servers, the one for the connection between clients and server and the one to access the administration frontend with the browser.

To be found by other servers and the clients despite of differing ports you have to add some DNS entries at your domain host. Details about these SRV entries you'll find in the XMPP Wiki.

User of INWX for example have to go to Nameserver in the client's menu. Make sure that you have an A entry for your subdomain xmpp.example.org and add two SRV entries. (Replace <The IP address of your webspace> like ti is said, <your c2s port> by the port that you've chosen for the Client to server connection and <your s2s port> by the port that you've chosen for the server to server connection). Working defaults for the weight is 5 and 0 for the priority.

To run ejabberd on a subdomain requires the following entries, in which you still have adapt xmpp by your subdomain:

* A <IP address of your webspace> 3600
_xmpp-client._tcp.xmpp SRV 5 <your c2s port> example.org 3600
_xmpp-server._tcp.xmpp SRV 5 <your s2s port> example.org 3600
_xmpp-server._tcp.conference.xmpp SRV 5 <your s2s port> example.org 3600

To run ejabberd on the main domain add instead adapted entries like these:

_xmpp-client._tcp SRV 5 <your c2s port> example.org 3600
_xmpp-server._tcp SRV 5 <your s2s port> example.org 3600
_xmpp-server._tcp.conference SRV 5 <your s2s port> example.org 3600

You can also replace example.org in both cases and for both entries with the hostnamen of your Uberspace: <servername>.uberspace.de. (Replace <servername> by the name you find on your data sheet.)


Probably you already created your own certificates to have a secured connection with your webspace. If not, follow the existing introduction from Uberspace.

In both cases it is necessary to change the cli.ini which is stored in ~/.config/letsencrypt/. TTake care that all addresses have to be seperated by comma but without space.

Now you create your keys with the following shell command:

$ letsencrypt certonly


The first installation ist pretty simple. First download the source code from the ejabberd release page then compile and install. (Adjust the version number in the first three commands, here 17.07, if neccesairy. If you encounter any problems with later versions of ejabberd while following this instruction, please try the installation with 17.07.)

$ wget https://github.com/processone/ejabberd/archive/17.07.tar.gz
$ tar xfvz 17.07.tar.gz
$ mv ejabberd-17.07 ejabberd
$ cd ejabberd
$ ./autogen.sh
$ ./configure --enable-user=$USER --enable-mysql --prefix=/home/$USER/ejabberd
$ make
$ make install

ejabberd has a controll application to start and stop the server and to do other things. This application is in the ~/ejabberd/sbin/ directory. To use it whatever directory you are actually in, we suggest to create a symlink in your ~/bin/ directory:

$ ln -s ~/ejabberd/sbin/ejabberdctl ~/bin/ejabberdctl

Now get the certificates together in one package that can be used by ejabberd. Again there is an easy shell command to accomplish that. And again like mentioned above replace example.org by the directory that is first in your cli.ini and independant from using a subdomain for ejabberd or not!

$ cat ~/.config/letsencrypt/live/example.org/privkey.pem ~/.config/letsencrypt/live/example.org/fullchain.pem > ~/ejabberd/cert.pem

Next thing we need are the Diffie Hellman parameters for the key exchange. You create them with this shell command:

$ openssl dhparam -out ~/ejabberd/dhparams.pem 2048


The configuration file is ~/ejabberd/etc/ejabberd/ejabberd.yml. to find the items that have to be changed we will name the numbers of the lines as they are at the time we are writing this introduction (Beginning August 2017). It is possible that this might change in later versions of ejabberd (we used 17.07.79). So it is only a guide to find your way around the file. Comments are made of two hash signs and one space right behind (## ). All three have to be removed when it comes to remove a comment.

Line 96 - hosts: - The hostname

Here you have to change localhost to xmpp.example.org.

Line 110 - define_macro: - Macros for the SSL settings

In the whole block from define_macro: inclusive, you have to delete the comments. In this block you have to replace the path for the certificate file 'CERTFILE' from /path/to/xmpp.pem to /home/<username>/ejabberd/cert.pem. (Replace <username> by your Uberspace username). Also change the path for 'DHFILE' from /path/to/dhparams.pem to /home/<username>/ejabberd/dhparams.pem.

Some XMPP servers with whom your server tries to built up a server to server connection, might be configurated to only accept perfect forward secrecy ciphers (like the one from the CCC: jabber.ccc.de.) We have chosen some Ciphers that support PFS. These are to put it for 'CIPHERS':


After all these adjustments your makro block should look like that:

  'CERTFILE': /home/<username>/ejabberd/cert.pem
    - no_sslv3
    - no_tlsv1
    - cipher_server_preference
    - no_compression
  'DHFILE': /home/<username>/ejabberd/dhparams.pem

Line 124 - listen: - Ports and encryption settings

There is something to change here wherefor you'll find a small summary at the end. First you enter the ports that you got from Uberspace. The value of the module: item shows the purpose of the port above.

Line 126 is the port for client to server connections Line 153 is the port for the server to server connections Line 157 is the port for the web interface

The following settings are needed for the encryption: Remove the comments from the line 134 - certfile: to 138 - ciphers:.

If you want to enforce encryption, delete the comment in line 143 - starttls_required: true.

Your listen block should look like this. (<your c2s port> has to be replaced by the Port that you chosed for the client to server connection.)

    port: <your c2s port>
    ip: ::
    module: ejabberd_c2s
    starttls: true
    certfile: 'CERTFILE'
    protocol_options: 'TLSOPTS'
    dhfile: 'DHFILE'
    ciphers: 'CIPHERS'
    starttls_required: true

    max_stanza_size: 65536
    shaper: c2s_shaper
    access: c2s

To activate the encryption between servers delete the comments in the lines 237 - s2s_use_starttls: required, 242 - s2s_certfile: 'CERTFILE' and 246 - s2s_protocol_options: 'TLSOPTS' and add the two following lines below:

    s2s_dhfile: 'DHFILE'
    s2s_ciphers: 'CIPHERS'

The section should look like this afterwards:

    s2s_use_starttls: required
    s2s_certfile: 'CERTFILE'
    s2s_protocol_options: 'TLSOPTS'
    s2s_dhfile: 'DHFILE'
    s2s_ciphers: 'CIPHERS'

User management

Would you like to allow registration of user accounts by your webinterface remove the comment in line 167:

register: true
If you want allow registration of user accounts with XMPP clients, activate the register modul be removing the commentin line 729:
The handling of the other settings of this module you'll find in the manual.

First advice is to create an administrative account. You can chose the username you're already using to connect to your server yourself. If you allow user registration by others, we propose to register names like admin and administrator by yourself also to avoid others using them.

All administration accounts have to be declared in the config file. You'll find the right place beginning with the line 454 and it should look similiar to the following after you removed the comments:
        - "deinbenutzername@xmpp.example.org"


How mentioned at the beginning the server can be controled by using the ejabberdctl tool. To start the server use the following command:

$ ejabberdctl start
Wait a few seconds then check if the server is running:
$ ejabberdctl status
The feedback should be like this:
The node ejabberd@localhost is started with status: started

    ejabberd 17.07.79 is running in that node
If this is not the case there might be en error in the config file. Check the log file:
$ cat ~/ejabberd/var/log/ejabberd/ejabberd.log | less
Stop of the server is done by:
$ ejabberdctl stop
If you intend to restart the server after changing the config and while it is running, use:
$ ejabberdctl restart
To add an user account use the command below. Replace <username> and <password> by corresponding values and be aware of case sensitive.
$ ejabberdctl register <username> xmpp.example.org <password>
To delete an user account use:
$ ejabberdctl unregister <username> xmpp.example.org

Control of success

In the directory ~/ejabberd/var/log/ejabberd you'll find the log files that are created and filled generally during the uptime but also on errores and crashes.

Finally you can enter the address of your ejabberd server on http://check.messaging.one/ to get its capabilities tested and rated.


To chat on Windows and Linux we use Pidgin with the OTR plugin. It is a easy to use and less ressources needing client that also allows to connect other chat protocolls. For video or audio conferences I use additionally Jitsi. As a user of thunderbird you can also start (there is no encryption) with using its chat module to connect to an XMPP server. You'll find it in the menu at navigation

As we don't use smartphones we can't recommand any programm, but link to this list.

The browser client from Converse.js is integrsted in this website.

Last update: 21. November 2018