Modern ejabberd configuration


ejabberd is one of the most widely used XMPP servers. It is easy to get it running for text-based messaging with a few configuration changes. However, to obtain a smoothly running modern feature set is harder. The configuration documentation is detailed, but even for a seasoned systems administrator or XMPP guru, a lot of questions remain. Here is an attempt at a simple how-to.

Single-host configuration

Configuration for a single virtual host for ejabberd 17.11.

/etc/ejabberd/ejabberd.yml

Replace the modules: section and other variables with the following:

define_macro:
 'CIPHERS': "ECDH:DH:!3DES:!aNULL:!eNULL:!MEDIUM@STRENGTH:!AES128"
 'TLSOPTS':
  - "no_sslv3"
  # generated with: openssl dhparam -out dhparams.pem 2048
  'DHFILE': "/etc/ejabberd/dhparams.pem" 

certfiles:
  - "/etc/letsencrypt/live/*/fullchain.pem"
  - "/etc/letsencrypt/live/*/privkey.pem"
s2s_use_starttls: required
s2s_protocol_options: 'TLSOPTS'
s2s_ciphers: 'CIPHERS'
s2s_dhfile: 'DHFILE'
c2s_dhfile: 'DHFILE'

# Will be used for @HOST@ substitution as well
hosts:
  - "example.ch"

modules: # See manual
  # Ad-Hoc Commands (XEP-0050)
  mod_adhoc: {}
  # Additional ejabberdctl commands
  mod_admin_extra: {}
  # Send global announcements
  mod_announce: # recommends mod_adhoc
    access: announce
  # Transparently convert between vcard and pubsub avatars
  mod_avatar: {} # Requires ejabberd >= 17.09, mod_vcard, mod_vcard_xupdate, mod_pusub
  # Simple Communications Blocking (XEP-0191)
  mod_blocking: {} # requires mod_privacy
  # Exchange entity (client) capabilities, e.g. Jingle (XEP-0115)
  mod_caps: {}
  # Send messages to all clients of a user (XEP-0280)
  mod_carboncopy: {}
  # Queue and filter stanzas for inactive clients (improves mobile client battery life, XEP-0352)
  mod_client_state: {}
  # Server configuration with Ad-Hoc commands
  mod_configure: {} # requires mod_adhoc
  # Service discovery, e.g. for MUC, Pub/Sub, HTTP Upload (XEP-0030)
  mod_disco: {}
  # (XMPP over) BOSH: HTTP tunneling for web clients such as JSXC (XEP-0124, XEP-0206)
  mod_bosh: {}
  # Last activity (XEP-0012)
  mod_last: {}
  # Message Archive Management (XEP-0313): Allows clients to catch up
  mod_mam:
    default: roster
  # Queue messages for offline users (XEP-0160)
  mod_offline:
    access_max_user_messages: max_user_offline_messages
  # XMPP Ping and periodic keepalives (XEP-0199)
  mod_ping: {}
  # Limit status spam (a full presence authorization requires 4 messages)
  # See also Anti-Spam Workshop
  mod_pres_counter:
    count: 50
    interval: 600
  # Block some senders (XEP-0016)
  mod_privacy: {}
  # Private XML storage (XEP-0049)
  mod_private: {}
  # Allows clients to request push notifications
  mod_push: {} # Requires ejabberd >= 17.08
  # The roster. You want this.
  mod_roster: {}
  # If you want to pre-configure rosters for workgroups
  mod_shared_roster: {}
  # Allow users to create a vcard, visible to authorized peers (XEP-0054)
  mod_vcard:
    search: false # Privacy
  # vcard-based Avatars (XEP-0153)
  mod_vcard_xupdate: {}
  # Stream management (XEP-0198): Continuity after network interruptions
  mod_stream_mgmt: {}
  # Ask for a dialback, if the certificate does not match (XEP-0220)
  mod_s2s_dialback: {}

  # Additional services

  # Publish/subscribe, e.g. for Movim
  mod_pubsub:
    host: "pubsub.@HOST@" # "hosts:" for multiple pubsub services
    access_createnode: local
    ignore_pep_from_offline: false
    last_item_cache: false
    max_items_node: 1000
    default_node_config:
      max_items: 1000
    plugins:
      - "flat"
      - "pep" # Requires mod_caps.
  # Multi-User (group) Chat
  mod_muc:
    host: "conference.@HOST@"
    access:
      - allow
    access_admin:
      - allow: admin
    access_create: muc_create
    access_persistent: muc_create
  # File transfer via HTTP Upload
  mod_http_upload:
    host: "userdata.@HOST@"
    docroot: "/srv/userdata/" # Or wherever you would like to have them stored
    put_url: "https://userdata.@HOST@/ud"
    custom_headers:
      "Access-Control-Allow-Origin": "*"
      "Access-Control-Allow-Methods": "OPTIONS, HEAD, GET, PUT"
      "Access-Control-Allow-Headers": "Content-Type"
  # Expire files on server after specified period
  mod_http_upload_quota:
    max_days: 30

listen:
  -
    port: 5222
    ip: "::"
    module: ejabberd_c2s
    starttls_required: true
    protocol_options: 'TLSOPTS'
    dhfile: 'DHFILE'
    ciphers: 'CIPHERS'
    max_stanza_size: 65536
    shaper: c2s_shaper
    access: c2s
  - 
    port: 5269
    ip: "::"
    module: ejabberd_s2s_in
    max_stanza_size: 131072
    shaper: s2s_shaper
  -
    port: 443
    ip: "::"
    module: ejabberd_http
    tls: true
    request_handlers:
      "/websocket": ejabberd_http_ws
      "/ud": mod_http_upload
    http_bind: true # Will map to "/http-bind"
  -
    port: 3478
    transport: udp
    module: ejabberd_stun
    auth_type: user
    auth_realm: "example.ch"
    use_turn: true
    turn_ip: "192.2.0.1" # Your IP address
  - 
    port: 3478
    transport: tcp
    module: ejabberd_stun
    auth_type: user
    auth_realm: "example.ch"
    use_turn: true
    turn_ip: "192.2.0.1" # Your IP address

DNS configuration

You will also require the following entries in the Domain Name System. xmpp.example.ch can be any name you like.

xmpp.example.ch.                         A     192.2.0.1
xmpp.example.ch.                         AAAA  2001:db8::1
userdata.example.ch.                     CNAME xmpp.example.ch.
turn.example.ch.                         CNAME xmpp.example.ch.
_xmpp-client._tcp.example.ch.            SRV   10 1 5222 xmpp.example.ch.
_xmpp-server._tcp.example.ch.            SRV   10 1 5269 xmpp.example.ch.
_xmpp-server._tcp.conference.example.ch. SRV   10 1 5269 xmpp.example.ch.
_xmpp-server._tcp.pubsub.example.ch.     SRV   10 1 5269 xmpp.example.ch.

Certificate requirements

Your certificate should cover example.ch, userdata.example.ch, conference.example.ch, and pubsub.example.ch (and turn.example.ch).

openssl dhparam -out /etc/ejabberd/dhparams.pem 2048
chown ejabberd /etc/ejabberd/dhparams.pem

Updated 2018-01-22: Added c2s_dhfile.

Updated 2018-02-23: Removed thumbnail (useless with modern encrypted uploads), switched to certfiles (available as of ejabberd 17.11), and included dhparam creation.

,

Let’s stay in touch!

Receive a mail whenever I publish a new post.

About 1-2 Mails per month, no Spam.

Follow me on the Fediverse

Netfuture: The future is networked
Netfuture: The future is networked
@blog@netfuture.ch

The future of networking

206 posts
6 followers

Web apps


Leave a Reply

Only people in my network can comment.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

To respond on your own website, enter the URL of your response which should contain a link to this post's permalink URL. Your response will then appear (possibly after moderation) on this page. Want to update or remove your response? Update or delete your post and re-enter your post's URL again. (Find out more about Webmentions.)