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:
<span style="color: #800000;"><span style="color: #003300;">define_macro:</span> </span> 'CIPHERS': <span style="color: #000080;">"ECDH:DH:!3DES:!aNULL:!eNULL:!MEDIUM@STRENGTH:!AES128"</span> 'TLSOPTS': - <span style="color: #000080;">"no_sslv3"</span> <span style="color: #993300;"> # generated with: openssl dhparam -out dhparams.pem 2048</span> 'DHFILE': <span style="color: #000080;">"/etc/ejabberd/dhparams.pem"</span> <span style="color: #000000;">certfiles:</span> - "/etc/letsencrypt/live/*/fullchain.pem" - "/etc/letsencrypt/live/*/privkey.pem" <span style="color: #000000;">s2s_use_starttls:</span> required <span style="color: #000000;">s2s_protocol_options:</span> <span style="color: #993300;">'TLSOPTS'</span> <span style="color: #000000;">s2s_ciphers:</span> <span style="color: #993300;">'CIPHERS'</span> <span style="color: #000000;">s2s_dhfile:</span> <span style="color: #993300;">'DHFILE'</span> <span style="color: #000000;">c2s_dhfile:</span> <span style="color: #993300;">'DHFILE'</span> <span style="color: #000080;"><span style="color: #800000;"># Will be used for @HOST@ substitution as well</span> </span><span style="color: #003300;">hosts:</span><span style="color: #000080;"> - "example.ch" </span> <span style="color: #003300;">modules:</span> <span style="color: #800000;"># See <a href="https://docs.ejabberd.im/admin/configuration/#modules-overview">manual</a></span> <span style="color: #800000;"># Ad-Hoc Commands (<a href="https://xmpp.org/extensions/xep-0050.html">XEP-0050</a>)</span> <span style="color: #000000;"> mod_adhoc:</span> {} <span style="color: #800000;"># Additional ejabberdctl commands</span> <span style="color: #000000;"> mod_admin_extra:</span> {} <span style="color: #800000;"># Send global announcements</span> <span style="color: #000000;"> mod_announce:</span> <span style="color: #800000;"># recommends mod_adhoc</span> access: announce <span style="color: #800000;"># Transparently convert between vcard and pubsub avatars</span> <span style="color: #000000;"> mod_avatar:</span> {} <span style="color: #800000;"># Requires ejabberd >= 17.09, mod_vcard, mod_vcard_xupdate, mod_pusub</span> <span style="color: #800000;"> # Simple Communications Blocking (<a href="https://xmpp.org/extensions/xep-0191.html">XEP-0191</a>)</span> <span style="color: #000000;"> mod_blocking:</span> {} <span style="color: #800000;"># requires mod_privacy</span> <span style="color: #800000;"> # Exchange entity (client) capabilities, e.g. Jingle (<a href="http://xmpp.org/extensions/xep-0115.html">XEP-0115</a>)</span> <span style="color: #000000;"> mod_caps:</span> {} <span style="color: #800000;"> # Send messages to all clients of a user (<a href="http://xmpp.org/extensions/xep-0280.html">XEP-0280</a>)</span> <span style="color: #000000;"> mod_carboncopy:</span> {} <span style="color: #800000;"> # Queue and filter stanzas for inactive clients (improves mobile client battery life, <a href="http://xmpp.org/extensions/xep-0352.html">XEP-0352</a>)</span> <span style="color: #000000;"> mod_client_state:</span> {} <span style="color: #800000;"> # Server configuration with Ad-Hoc commands</span> <span style="color: #000000;"> mod_configure:</span> {} <span style="color: #800000;"># requires mod_adhoc</span> <span style="color: #800000;"> # Service discovery, e.g. for MUC, Pub/Sub, HTTP Upload (<a href="http://xmpp.org/extensions/xep-0030.html">XEP-0030</a>)</span> <span style="color: #000000;"> mod_disco:</span> {} <span style="color: #800000;"> # (XMPP over) BOSH: HTTP tunneling for web clients such as <a href="https://netfuture.ch/tag/jsxc">JSXC</a> (<a href="http://xmpp.org/extensions/xep-0124.html">XEP-0124</a>, <a href="http://xmpp.org/extensions/xep-0206.html">XEP-0206</a>)</span> <span style="color: #000000;"> mod_bosh:</span> {} <span style="color: #800000;"> # Last activity (<a href="http://xmpp.org/extensions/xep-0012.html">XEP-0012</a>)</span> <span style="color: #000000;"> mod_last:</span> {} <span style="color: #800000;"> # Message Archive Management (XEP-0313): Allows clients to catch up</span> <span style="color: #000000;"> mod_mam:</span> default: roster <span style="color: #800000;"> # Queue messages for offline users (<a href="http://xmpp.org/extensions/xep-0160.html">XEP-0160</a>)</span> <span style="color: #000000;"> mod_offline:</span> access_max_user_messages: max_user_offline_messages <span style="color: #800000;"> # XMPP Ping and periodic keepalives (XEP-0199)</span> <span style="color: #000000;"> mod_ping:</span> {} <span style="color: #800000;"> # Limit status spam (a full presence authorization requires 4 messages)</span> <span style="color: #800000;"> # See also <a href="https://blog.process-one.net/fighting-xmpp-abuse-and-spam-with-ejabberd-ejabberd-workshop-1/">Anti-Spam Workshop</a></span> <span style="color: #000000;"> mod_pres_counter:</span> count: 50 interval: 600 <span style="color: #800000;"> # Block some senders (<a href="http://xmpp.org/extensions/xep-0016.html">XEP-0016</a>)</span> <span style="color: #000000;"> mod_privacy:</span> {} <span style="color: #800000;"> # Private XML storage (<a href="http://xmpp.org/extensions/xep-0049.html">XEP-0049</a>)</span> <span style="color: #000000;"> mod_private:</span> {} <span style="color: #800000;"> # Allows clients to request push notifications</span> <span style="color: #000000;"> mod_push:</span> {} <span style="color: #800000;"># Requires ejabberd >= 17.08</span> <span style="color: #800000;"> # The roster. You want this.</span> <span style="color: #000000;"> mod_roster:</span> {} <span style="color: #800000;"> # If you want to pre-configure rosters for workgroups</span> <span style="color: #000000;"> mod_shared_roster:</span> {} <span style="color: #800000;"> # Allow users to create a vcard, visible to authorized peers (<a href="http://xmpp.org/extensions/xep-0054.html">XEP-0054</a>)</span> <span style="color: #000000;"> mod_vcard:</span> search: false <span style="color: #800000;"># Privacy</span> <span style="color: #800000;"> # vcard-based Avatars (<a href="http://xmpp.org/extensions/xep-0153.html">XEP-0153</a>)</span> <span style="color: #000000;"> mod_vcard_xupdate:</span> {} <span style="color: #800000;"> # Stream management (<a href="http://xmpp.org/extensions/xep-0198.html">XEP-0198</a>): Continuity after network interruptions</span> <span style="color: #000000;"> mod_stream_mgmt:</span> {} <span style="color: #800000;"> # Ask for a dialback, if the certificate does not match (<a href="http://xmpp.org/extensions/xep-0220.html">XEP-0220</a>)</span> <span style="color: #000000;"> mod_s2s_dialback:</span> {} <span style="color: #800000;"> # Additional services</span> <span style="color: #800000;"># Publish/subscribe, e.g. for <a href="https://movim.eu">Movim</a></span> <span style="color: #000000;"> mod_pubsub:</span> host: <span style="color: #000080;">"pubsub.@HOST@"</span> <span style="color: #800000;"># "hosts:" for multiple pubsub services</span> 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" <span style="color: #800000;"># Requires mod_caps. # Multi-User (group) Chat</span> <span style="color: #000000;"> mod_muc:</span> host: <span style="color: #000080;">"conference.@HOST@"</span> access: - allow access_admin: - allow: admin access_create: muc_create access_persistent: muc_create <span style="color: #800000;"> # File transfer via HTTP Upload</span> <span style="color: #000000;"> mod_http_upload:</span> host: <span style="color: #000080;">"userdata.@HOST@"</span> docroot: <span style="color: #000080;">"/srv/userdata/" <span style="color: #800000;"># Or wherever you would like to have them stored</span></span> put_url: <span style="color: #000080;">"https://userdata.@HOST@/ud"</span> custom_headers: "Access-Control-Allow-Origin": "*" "Access-Control-Allow-Methods": "OPTIONS, HEAD, GET, PUT" "Access-Control-Allow-Headers": "Content-Type"<span style="color: #800000;"> # Expire files on server after specified period</span> <span style="color: #000000;">mod_http_upload_quota:</span> max_days: 30 <span style="color: #003300;">listen:</span> - port: 5222 ip: <span style="color: #000080;">"::"</span> module: ejabberd_c2s starttls_required: true protocol_options: <span style="color: #993300;">'TLSOPTS'</span> dhfile: <span style="color: #993300;">'DHFILE'</span> ciphers: <span style="color: #993300;">'CIPHERS'</span>  max_stanza_size: 65536 shaper: c2s_shaper access: c2s - port: 5269 ip: <span style="color: #000080;">"::"</span> module: ejabberd_s2s_in max_stanza_size: 131072 shaper: s2s_shaper - port: 443 ip: <span style="color: #000080;">"::"</span> module: ejabberd_http tls: true request_handlers: <span style="color: #000080;">"/websocket"</span>: ejabberd_http_ws <span style="color: #000080;">"/ud"</span>: mod_http_upload http_bind: true <span style="color: #800000;"># Will map to "/http-bind"</span> - port: 3478 transport: udp module: ejabberd_stun auth_type: user  auth_realm: <span style="color: #000080;">"example.ch"</span> use_turn: true turn_ip: <span style="color: #000080;">"192.2.0.1"</span> <span style="color: #800000;"># Your IP address</span> - port: 3478 transport: tcp module: ejabberd_stun auth_type: user auth_realm: <span style="color: #000080;">"example.ch"</span> use_turn: true turn_ip: <span style="color: #000080;">"192.2.0.1" <span style="color: #800000;"># Your IP address</span></span>
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
).
<span style="color: #000000;">openssl dhparam</span> -out /etc/ejabberd/dhparams.pem 2048 <span style="color: #000000;">chown</span> 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.