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.09

/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" 
  # Concatenate the private key and the keychain into one file (ejabberd requirement)
  'CERTFILE': "/etc/ejabberd/combo.key"

# 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"
    thumbnail: true # needs the identify command from ImageMagick installed
  # Expire files on server after specified period
  mod_http_upload_quota:
    max_days: 30

s2s_use_starttls: required
s2s_protocol_options: 'TLSOPTS'
s2s_dhfile: 'DHFILE'
s2s_ciphers: 'CIPHERS'
s2s_certfile: 'CERTFILE'

certfile: 'CERTFILE'

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). The the private key (yes!), the certificate itself, and any intermediate certificates required for your certificate authority should be concatenated into /etc/ejabberd/combo.key. This file should only be readable by the user ejabberd:

cat /etc/ssl/private/example.key /etc/ssl/example.cer /etc/ssl/intermediate-ca.cer > /etc/ejabberd/combo.key
chown ejabberd:ejabberd /etc/ejabberd/combo.key
chmod 640 /etc/ejabberd/combo.key

Schreibe einen Kommentar