How to setup a Jabber / XMPP server on Debian 8 (jessie) using ejabberd

Having the goal of offering a safe way to communicate for friends and nearby living people I decided to setup my own Jabber / XMPP server using Debian 8.7 (jessie).  The most compelling aspects of ejabberd are it’s scalability, it’s robustness and the fact that it is so well documented.

This guide is structured into two parts. It commences with the essentials and closes with enabling various options (linking ejabberd with mysql, file transfer proxy via mod_proxy65).

The Essentials

This tutorial assumes the following setup:

  • Debian 8.7 (jessie)
  • a working domain environment
  • open firewall ports:
    • 5222/tcp – client to server connection (c2s)
    • 5269/tcp – server to server connection (s2s)
    • 5280/tcp – admin web interface
    • 7777/tcp – file transfer (mod_proxy65)

First you should ensure that everything is up to date:

sudo apt-get update && upgrade

Installing ejabberd

sudo apt-get install ejabberd ejabberd-contrib

Create ejabberd.pem using Let’s Encrypt and certbot

Get the public root certificate of let’s encrypt, it is used for signing our certificates. Copy it to /etc/letsencrypt/ and rename it to ca.crt:

wget "https://letsencrypt.org/certs/isrgrootx1.pem.txt"

The certificates created by certbot only last 90 days, thus I wrote a script which simplifies combining the new certificates into the file that is expected by ejabberd (ejabberd.pem):

sudo touch certificate_script

which includes:

cat /etc/letsencrypt/live/helenenhof.org/priykey.pem \
/etc/letsencrypt/live/helenenhof.org/fullchain.pem \
/etc/letsencrypt/ca.crt
> /etc/ejabberd/ejabberd.pem

Making the script executable and executing the script:

sudo chmod +x certificate_script

sudo ./certificate_script

Configuring ejabberd

You should be aware of correct indention and case-sensitivity whilst working with .yml files. The whole configuration file is streaked with helpful comments. Create a backup of the initial configuration file:

cp /etc/ejabberd/ejabberd.yml /etc/ejabberd/ejabberd.yml.orig

Adjust the host:

hosts:
  - "helenenhof.org"

Set the path to the certfile, enable and force TLS on the listening port 5222:

certfile: "/etc/ejabberd/ejabberd.pem"
starttls: true
starttls_required: true

Store passwords hashed (SCRAM) and set the FQDN:

auth_password_format: scram
fqdn: "helenenhof.org"

Set admin rights to specific users:

acl:
  admin:
    user:
      - "admin": "helenenhof.org"

Enable mod_register to allow In-Band registration:

mod_register:
  captcha_protected: true
  registration_watchers:
    - "admin@helenenhof.org"
  access: register

Enabling captcha to increase spam protection

Installing imagemagick and ghostscript:

sudo apt install imagemagick ghostscript --no-install-recommends

Uncomment and change the following in ejabberd.yml:

captcha_cmd: "/usr/share/ejabberd/captcha.sh"
captcha_host: "http://helenenhof.org:5280"
captcha_limit: 5

mod_register:
       captcha_protected: true
preview of a captcha

Restart the ejabberd deamon:

sudo service ejabberd restart

If you receive any errors check the latest error logs found in /var/log/ejabberd for guidance. I also linked the documentaries for reference at the appropriate locations.

Killing frozen ejabberd processes might work wonders as well:

ps -aux | grep 'ejabberd'

sudo kill -9 process_id

Adding new users

There are numerous ways of adding new accounts, some are shown below:

  • via command line:
sudo ejabberdctl register testuser helenenhof.org testpassword
  • via admin web interface:

Visit helenenhof.org:5280/admin/server/helenenhof.org/users/

  • via an XMPP Client (e.g. Pidgin):

You can add new accounts by clicking on accounts > manage accounts. Change the protocol to XMPP and fill in your user name, domain and password. Check Create this new account on the server > add and register your account.

Off-The-Record (OTR) messaging

OTR enhances the security between two users even more. This is achieved by using AES, DHM and SHA-1. OTR is available for various XMPP clients, I will go through the setup using Pidgin (preinstalled chat client on linux).

Check your plugins first (OTR might already be installed), if it isn’t, download the plugin:

sudo apt-get install pidgin-otr

Activate OTR by clicking on Tools > Plugins, check the box and click on Configure Plugin. Next you need to generate a key for your desired account, select it and click on Generate. Pidgin might freeze for a little while because you don’t have enough random data collected in /dev/random – moving your mouse / typing will fix this.

Moving onwards, open a conversation window, OTR will be Not private, click on it and select Start private conversation. To authenticate your buddy click on Unverified > Authenticate buddy, you will be given three options which are described fairly well by pidgin.

This section is a compromised version of howtogeeks how/why to.

Administrating users

There are various options when it comes to administrating users, most of them are self-explanatory and listed below:

 

Final thoughts

In conclusion I would like to state that this has been one of my first IT projects – comments / constructive criticism and overall feedback are very welcome.

Optional:

Changing the database from default (mnesia) to mysql

First, we have to setup our mysql database, this can be done as stated here. To administer the database install phpmyadmin, follow the instructions and login as root (helenenhof.org/phpmyadmin).

sudo apt-get install phpmyadmin

Create a new user named ejabberd and fill in the remaining entries (host: localhost, generate a password), check Create database with the same name and grant user all privileges.

Download the mysql.sql file which is imported into the new database where it generates the database structure that is soon to be filled with (e.g.) user informations.

wget "https://raw.githubusercontent.com/processone/ejabberd/14.07/sql/mysql.sql"

Now it’s time to change the ejabberd.yml file according to our needs:

## auth_method: internal

auth_method: odbc

odbc_type: mysql
odbc_server: "localhost"
odbc_database: "ejabberd"
odbc_username: "ejabberd"
odbc_password: "password"
odbc_port: 3306

default_db: odbc

File Transfer Proxy with mod_proxy65

Uncomment mod_proxy65 and adjust its options according to meet your needs (access rights, shaper):

mod_proxy65:
  host: "proxy.helenenhof.org"
  hostname: "helenenhof.org"
  name: "File Transfer Proxy"
  port: 7777
  max_connections: 5
  access: trusted
  shaper: mod_proxy

 

One Reply to “How to setup a Jabber / XMPP server on Debian 8 (jessie) using ejabberd”

Leave a Reply

Your email address will not be published. Required fields are marked *