How to configure ejabberd to get 100% in XMPP compliance test

Your ejabberd XMPP server is a powerful piece of software. But configuring everything requires several steps. Your best place to start is this hands-on ejabberd installation tutorial and this ejabberd STUN/TURN tutorial. If you have specific questions, first be sure to consult the official ejabberd documentation.

Testing your ejabberd configuration can be a tricky task. Luckily, Daniel Gultsch and Rishi Raj created an XMPP compliance test that will assist you in this process.

ejabberd XMPP server passes most of the XMPP compliance test checks out-of-the box, in default configuration. My fresh installation started at 94%. To get a 100% result, you need to configure a few things to pass the remaining 3 tests.

I’m assuming the configuration from my previous two tutorials on setting up your ejabberd real time IM server and configuring ejabberd video & voice calling.

How to configure ejabberd to get 100% in XMPP compliance test

XEP-0363: HTTP File Upload (CORS Headers)

You need to configure ejabberd to add custom headers to pass this XMPP compliance test. I also recommend creating a dedicated directory at /var/www/upload. For HTTP file upload to work, you don’t need anything else except ejabberd XMPP server. No PHP scripts or web servers. Remember that file upload operates on port 5443. Make sure it’s allowed by your server’s firewall.

  mod_http_upload:
    put_url: https://@HOST@:5443/upload
    docroot: /var/www/upload
    custom_headers:
      "Access-Control-Allow-Origin": "https://@HOST@"
      "Access-Control-Allow-Methods": "GET,HEAD,PUT,OPTIONS"
      "Access-Control-Allow-Headers": "Content-Type"

Make sure /var/www/upload directory is owned by ejabberd. Execute the following command:

chown ejabberd:ejabberd /var/www/upload

Once you configure ejabberd XMPP server with custom_headers, it will pass this XMPP compliance test.

XEP-0156: Discovering Alternative XMPP Connection Methods (HTTP)

To pass this test you need a web daemon on your ejabberd XMPP server. It could be Nginx or Apache. One way or another, it should allow http and https access to two files:

  • https://example.com/.well-known/host-meta
  • https://example.com/.well-known/host-meta.json.

The first file is an XML document without any extension defined in its name. Fill it with the following code:

<?xml version='1.0' encoding='utf-8'?>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
  <Link rel="urn:xmpp:alt-connections:xbosh"
        href="https://example.com:5443/bosh" />
  <Link rel="urn:xmpp:alt-connections:websocket"
        href="wss://example.com:5443/ws" />
</XRD>

Substitute example.com with the domain name of your ejabberd XMPP server. The code above announces addresses for clients to connect using BOSH and WebSockets. Both services are available in the default ejabberd installation.

The second file is the same data encoded in JSON:

{
  "links": [
    {
      "rel": "urn:xmpp:alt-connections:xbosh",
      "href": "https://example.com:5443/bosh"
    },
    {
      "rel": "urn:xmpp:alt-connections:websocket",
      "href": "wss://example.com:5443/ws"
    }
  ]
}

You can test the accessibility of these files using your regular web browser. Once reachable, your ejabberd server will pass this XMPP compliance test.

XEP-0368: SRV records for XMPP over TLS

To pass this test you need to add four SRV records to your ejabberd XMPP server domain DNS. You already should have STUN/TURN records there, so what you need are these:

_xmpp-client._tcp IN example.com 5 0 5222 example.com 3600
_xmpp-server._tcp IN example.com 5 0 5269 example.com 3600
_xmpps-client._tcp IN example.com 5 0 5223 example.com 3600
_xmpps-server._tcp IN example.com 5 0 5270 example.com 3600

Depending on your domain provider, the form to create these SRV records will vary. Most often the items are as follows:

  • Service: xmpp-client, xmpp-server, xmpps-client, xmpps-server
  • Protocol: tcp
  • Priority: 5
  • Weight: 0
  • Port: 5222, 5269, 5223, 5270
  • Target: example.com
  • TTL: 3600 or Default

Remember to open the 4 ports listed above in your ejabberd XMPP server’s firewall. Allow up to 24 hours for the changes in the DNS to propagate. Then re-run the XMPP compliance test.

Conclusion

XMPP compliance test is a great way to know if your ejabberd is well configured and accessible. It will also give you an option to embed a nice badge certifying you passed all the tests. My personal XMPP server report used during these several tutorials looks like this.

In this ejabberd tutorial series:

Photo by Ali Yahya on Unsplash


Let us know what you think 💬


5 thoughts on “How to configure ejabberd to get 100% in XMPP compliance test

  1. Thank you very much for your guides, I now have my own xmpp server at 95% compliance.
    However I cannot figure out at all how to get XEP-0368 working.

    I’ve added the SRV records, but it still will not pass, do I need to do something with port 443 or direct it to 5223 or 5270 (via nginx)? As I think is the purpose of XEP-0368?

    Reading around the web it seems like there are more steps than just adding the SRV records, but I can’t actually find what it is. Any advice on what else was necessary would be appreciated.

    (On ejabberd 20.07)

    • There should be no issue. OMEMO is mostly a client-side protocol, so try first debugging there. For example, start a chat between two Conversations clients on Android and see if OMEMO works there with your server.

Leave a Comment


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