---
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
```
