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.

Netfuture: The future is networked