path: root/posts/2023-09-16-ejabberd.md

---
title: ejabberd server guide
---

Prerequisites:

- A domain name
- A server

This tutorial begins with a single virtualhost[^1]. For example purposes, `example.net` is the domain. Replace all instances of `example.net` with your own domain. 

[^1]: Virtualhosts allow more than one XMPP service to be run on one server. For example, one XMPP service with the domain `example.net` and another XMPP service with the domain `example.org`, both somewhat separated from each other as if they were run on different servers.

<div><div class="panel checklist">checklist!: <input type="checkbox" id="hide-checklist"><label for="hide-checklist">hide</label><div>

- [ ] add dns records
- [ ] open firewall ports
- [ ] set up web server
- [ ] get ssl certificates
- [ ] install ejabberd
- [ ] set up postgres database
- [ ] write/edit configuration
- [ ] start service
- [ ] create admin user
- [ ] change loglevel

</div></div>

## Step 1: Set up the DNS records

DNS A/AAAA records and SRV records are required for each service on the XMPP server.

A records:

- `example.net`
- `muc.example.net` (for group chats)
- `upload.example.net` (for HTTP file upload)
- `pubsub.example.net` (for the pubsub node)
- `proxy.example.net` (for file transfer proxy)
- `turn.example.net` (for STUN/TURN)

Each pointing to the IP address of the server that is going to run Ejabberd.

Create SRV records for each, pointing to a domain that resolves to the server, as so:

(All records are in the form
`_service._proto.name IN SRV priority weight port target`)

```
_xmpp-client._tcp   IN SRV  5 0 5222 example.net.
_xmpps-client._tcp  IN SRV  5 0 5223 example.net.
_xmpp-server._tcp   IN SRV  5 0 5269 example.net.
_xmpps-server._tcp  IN SRV  5 0 5270 example.net.
```

and 

```
_xmpp-client._tcp.muc   IN SRV  5 0 5222 example.net.
_xmpps-client._tcp.muc  IN SRV  5 0 5223 example.net.
_xmpp-server._tcp.muc   IN SRV  5 0 5269 example.net.
_xmpps-server._tcp.muc  IN SRV  5 0 5270 example.net.
```

for each of the subdomains (starting with `muc`). Exclude `turn.example.net`.

Lastly, add one set of SRV records, for STUN/TURN.

```
_stun._udp   IN SRV  5 0 3478 turn.example.net.
_stun._tcp   IN SRV  5 0 3478 turn.example.net.
_stuns._tcp  IN SRV  5 0 5349 turn.example.net.

_turn._udp   IN SRV  5 0 3478 turn.example.net.
_turn._tcp   IN SRV  5 0 3478 turn.example.net.
_turns._tcp  IN SRV  5 0 5349 turn.example.net.
```

Extra info: as a result of these SRV delegation records, hosting XMPP on a server other than the one at `example.net` is an option (i.e. if splitting services on one domain across servers). Further info can be found at [XEP-0368](https://xmpp.org/extensions/xep-0368.html). 

## Step 2: Open the firewall ports

Open ports:

TCP: `80` `443` `5222` `5223` `5269` `5270` `3478` `5349` `49152-65535`

UDP: `3478` `49152-65535`

`80` & `443` are for the web server, `5222`, `5223`, `5269` and `5270` are for XMPP, and the rest are for STUN/TURN.

## Step 3: Set up the web server and get your SSL certificates

- get (an) SSL certificate(s) for your domain, as well as several subdomains, all in all:
  - `example.net`
  - `muc.example.net`
  - `upload.example.net`
  - `pubsub.example.net`
  - `proxy.example.net`
  - `turn.example.net`
- proxypass http://127.0.0.1:5443 through to:
  - https://example.net/xmpp
  - https://example.net/.well-known/host-meta
  - https://example.net/.well-known/host-meta.json

  Make sure that for /xmpp you have what is necessary to proxy websockets too. If you're using Nginx, increase `client_max_body_size` for HTTP uploads.
- make sure the certificate files are readable and/or in a place that is readable by the `ejabberd` user.

To avoid using something like Nginx + Certbot, use the built-in [Ejabberd acme module](https://docs.ejabberd.im/admin/configuration/basic/#acme), but this article assumes it is desired to host other web services on the same system, in which case each HTTP service would be reverse proxied to a single HTTPS web service.

## Step 4: Install Ejabberd

Finally install the [system package](https://docs.ejabberd.im/admin/installation/#operating-system-packages). Ensure the build has PostgreSQL support.

Confirm the file `/etc/ejabberd/ejabberd.yml` exists, and is readable by the user that runs Ejabberd (almost definitely `ejabberd`), by, if necessary, copying over the example `ejabberd.yml` or `wget`/`curl`ing it from the [github repo](https://github.com/processone/ejabberd/blob/master/ejabberd.yml.example). If it is obtained from the repo, make sure the version corresponds to the version of Ejabberd packaged by your OS. 

## Step 5: Set up PostgreSQL database

A separate database should be created for each virtualhost, as this makes things clearer, and in addition, easier to migrate individual virtualhosts in the future. However, the ability to use only one, as described [here](https://docs.ejabberd.im/admin/configuration/database/#default-and-new-schemas), now exists as well. 

Follow standard PostgreSQL installation instructions for your OS. Once this has been done, connect to the database as an admin and:

1. create an Ejabberd database user with `CREATE USER ejabberd WITH PASSWORD 'your_password';`. Don't forget to change the password, and note it down.
2. create a database for the virtualhost with `CREATE DATABASE ejabberd_example OWNER ejabberd;`. Replace `example` with something corresponding to the virtualhost.
3. quit the `psql` shell, and import the database schema from GitHub with the command `curl -s https://raw.githubusercontent.com/processone/ejabberd/master/sql/pg.sql | sudo -u ejabberd psql ejabberd_example` (once again replace `example`).

## Step 6: Ejabberd configuration

Begin by replacing `localhost` under `hosts` with the virtualhost (e.g. `example.net`), then list the certfiles previously obtained under `certfiles`.

```
hosts:
  - example.net

certfiles:
  - "/etc/ejabberd/certs/*/*"
```

Now set `default_db: sql` at the root level of the YAML file. This should be followed by `host_config` and the database configuration for your virtualhost, as shown below. Customise each value to according to the setup.

```
host_config:
  example.net:
    sql_type: pgsql
    sql_server: "localhost"
    sql_port: 5432
    sql_username: "ejabberd"
    sql_password: "postgres_password"
    sql_database: "ejabberd_example"
    auth_method: sql
    auth_password_format: scram
```

Under `listen`, ensure all the correct services are enabled on each port, including s2s TLS on port `5270` (not default):

```
listen:
  -
    port: 5222
    module: ejabberd_c2s
    max_stanza_size: 262144
    shaper: c2s_shaper
    access: c2s
    starttls_required: true
  -
    port: 5223
    tls: true
    module: ejabberd_c2s
    max_stanza_size: 262144
    shaper: c2s_shaper
    access: c2s
    starttls_required: true
  -
    port: 5269
    module: ejabberd_s2s_in
    max_stanza_size: 524288
  -
    port: 5270
    tls: true
    module: ejabberd_s2s_in
    max_stanza_size: 524288
```

Next, enable the HTTP server and the STUN/TURN server modules. Set `turn_ipv4_address` and `ip` to the server's IPv4 address. TLS will be off for the HTTP server as it is reverse proxied through the previously set-up web server.

```
  -
    port: 5443
    module: ejabberd_http
    request_handlers:
      /xmpp/admin: ejabberd_web_admin
      /xmpp/bosh: mod_bosh
      /xmpp/upload: mod_http_upload
      /xmpp/ws: ejabberd_http_ws
      /.well-known/host-meta: mod_host_meta
      /.well-known/host-meta.json: mod_host_meta
  -
    port: 3478
    transport: udp
    module: ejabberd_stun
    use_turn: true
    turn_min_port: 49152
    turn_max_port: 65535
    # The server's public IPv4 address:
    turn_ipv4_address: 0.0.0.0
  -
    port: 5349
    transport: tcp
    module: ejabberd_stun
    use_turn: true
    tls: true
    turn_min_port: 49152
    turn_max_port: 65535
    ip: 0.0.0.0
    turn_ipv4_address: 0.0.0.0
```

Set `s2s_use_starttls: required` at the root.

At this point it is possible to set up some ACLs. `acls` are just the access control lists, set up `access_rules` corresponding to your needs, which will be what are passed to module settings. At the minimum an admin user is recommended. Example:

```
acl:
  admin:
    user: juliet@example.net
  capulet:
    - user: juliet@example.net
	- user: tybalt@example.net
  nurse:
    - user: angelica@example.net

access_rules:
  household: 
    allow: capulet
    allow: nurse
```

### Modules

Add abuse addresses under `mod_disco`. It is also possible to add other contact addresses according to [XEP-0157](https://xmpp.org/extensions/xep-0157.html):

```
modules:
# ...
  mod_disco:
    server_info:
    -
      modules: all
      name: "abuse-addresses"
      urls: ["mailto:abuse@example.net"]
```

Add `mod_host_meta`:

```
  mod_host_meta:
    bosh_service_url: "https://@HOST@/xmpp/bosh"
    websocket_url: "wss://@HOST@/xmpp/ws"
```

Edit `mod_mam`, and change `assume_mam_usage` to `false` and `default` to `never` if it is not desireable to default to archiving messages on the server:

```
  mod_mam:
    db_type: sql
    assume_mam_usage: never
    default: never
```

Add `mod_stun_disco` to advertise the STUN service to clients, changing `0.0.0.0` and `example.net` to the server's IP and hostname respectively:

```
  mod_stun_disco: 
    credentials_lifetime: 12h
    services:
        -
          host: 0.0.0.0
          port: 3478
          type: stun
          transport: udp
          restricted: false
        -
          host: 0.0.0.0
          port: 3478
          type: turn
          transport: udp
          restricted: true
        -
          host: turn.example.net
          port: 5349
          type: stuns
          transport: tcp
          restricted: false
        -
          host: turn.example.net
          port: 5349
          type: turns
          transport: tcp
          restricted: true
```

#### MUCs:

Set the host to the `muc` subdomain, otherwise it will attempt to use `conference.example.net`. Setting `mam: false` in `default_room_options` will disable server-side message archiving by default. 

```
  mod_muc:
    host: muc.example.net
    access:
      - allow
    access_admin:
      - allow: admin
    access_create: muc_create
    access_persistent: muc_create
    access_mam:
      - allow
    default_room_options:
      mam: false
```

#### File proxy:

```
  mod_proxy65:
    access: local
    max_connections: 5
```

#### HTTP file upload:

```
  mod_http_upload:
    put_url: https://@HOST@/xmpp/upload
    docroot: /var/www/ejabberdupload
    max_size: 1073741824
    custom_headers:
      "Access-Control-Allow-Origin": "https://@HOST@"
      "Access-Control-Allow-Methods": "GET,HEAD,PUT,OPTIONS"
      "Access-Control-Allow-Headers": "Content-Type"
```

Create the folder for the `docroot`, and ensure it is owned by the `ejabberd` user. Change `max_size` (the max upload size) to whatever is preferred.

#### PubSub:

```
  mod_pubsub:
    access_createnode: pubsub_createnode
    plugins:
      - flat
      - pep
    force_node_config:
      ## Avoid buggy clients to make their bookmarks public
      storage:bookmarks:
        access_model: whitelist
```

## Step 7: Start server and create admin user 

Start the Ejabberd server! 

Use `sudo -u ejabberd ejabberdctl register admin example.net password` to register `admin@example.net` with the password `password`.

There is a compliance tester at [compliance.conversations.im](https://compliance.conversations.im) to test the server. After everything has been set up correctly, optionally change the [`loglevel`](https://docs.ejabberd.im/admin/configuration/toplevel/#loglevel) at the root of the config.

There will be an admin page accessible at [https://example.net/xmpp/admin](https://example.net/xmpp/admin).

# Extra goodies!

## Web client

It is possible to set up conversejs using [`mod_conversejs`](https://docs.ejabberd.im/admin/configuration/modules/#mod-conversejs). It may be required to update the web server config to proxy the new endpoint (`/chat` below).

```
listen:
  -
    port: 5443
    module: ejabberd_http
    request_handlers:
      /xmpp/bosh: mod_bosh
      /xmpp/ws: ejabberd_http_ws
      /chat: mod_conversejs

modules:
  mod_conversejs:
    websocket_url: "ws://@HOST@/xmpp/ws"
    bosh_service_url: "https://@HOST@/xmpp/bosh"
```

## Further virtualhosts

For each further virtualhost a new database should be created, and added to the database part of the config. e.g.:

```
host_config:
  example.net:
    sql_type: pgsql
    sql_server: "localhost"
    sql_port: 5432
    sql_username: "ejabberd"
    sql_password: "postgres_password"
    sql_database: "ejabberd_net"
    auth_method: sql
    auth_password_format: scram
  example.org:
    sql_type: pgsql
    sql_server: "localhost"
    sql_port: 5432
    sql_username: "ejabberd"
    sql_password: "postgres_password"
    sql_database: "ejabberd_org"
    auth_method: sql
    auth_password_format: scram
```

There cannot be conflicts between declarations in the config file, so if `mod_muc`, `mod_proxy65`, `mod_http_upload` and `mod_pubsub` are declared under `modules` at the root, they (as well as other configuration differences between virtualhosts) must be deleted and replicated for each virtualhost under `append_host_config`, at the root. Example as so:

```
append_host_config:
  example.org:
    modules:
      mod_muc:
        host: muc.example.org
        access_create: org_users
        access_persistent: org_users
        access:
          - allow
        access_admin:
          - allow: admin
        default_room_options:
          mam: false
      mod_proxy65:
        access: org_users
        max_connections: 5
      mod_http_upload:
        access: org_users
        put_url: https://@HOST@/xmpp/upload
        docroot: /var/www/ejabberdupload
        max_size: 1073741824
        custom_headers:
          "Access-Control-Allow-Origin": "https://@HOST@"
          "Access-Control-Allow-Methods": "GET,HEAD,PUT,OPTIONS"
          "Access-Control-Allow-Headers": "Content-Type"
      mod_pubsub:
        access_createnode: org_users
        plugins:
          - flat
          - pep
        force_node_config:
          ## Avoid buggy clients to make their bookmarks public
          storage:bookmarks:
            access_model: whitelist
  example.net:
    modules:
      mod_muc:
        hosts: 
          - muc.example.net
        access_create: net_users
        access_persistent: net_users
        access:
          - allow
        access_admin:
          - allow: admin
        default_room_options:
          mam: false
      mod_proxy65:
        access: net_users
        max_connections: 5
      mod_http_upload:
        access: net_users
        put_url: https://@HOST@/xmpp/upload
        docroot: /var/www/ejabberdupload
        max_size: 1073741824
        custom_headers:
          "Access-Control-Allow-Origin": "https://@HOST@"
          "Access-Control-Allow-Methods": "GET,HEAD,PUT,OPTIONS"
          "Access-Control-Allow-Headers": "Content-Type"
      mod_pubsub:
        access_createnode: net_users
        plugins:
          - flat
          - pep
        force_node_config:
          ## Avoid buggy clients to make their bookmarks public
          storage:bookmarks:
            access_model: whitelist
```

As above, it is possible to disable access to certain services per virtualhost using ACLs, in order to e.g. prevent users on `example.net` from creating MUCs on `muc.example.org`.

## Separate TURN server (Coturn)

In this case, change `mod_stun_disco` to this, and don't enable the `listen` opts for STUN/TURN. Generate an auth secret and share it with the TURN server instance.

``` 
  mod_stun_disco:
    secret: "auth_secret"
    services:
      -
        host: turn.example.net
        type: stun
      -
        host: turn.example.net
        type: turn
```