ejabberd 19.09

Jérôme Sautret
· 4 min read
Send by email

We are pleased to announce ejabberd version 19.09. The main focus has been to improve automatic certificate management stack (Let’s Encrypt). We also fixed bugs that had been introduced during previous big refactoring of the configuration management file, as well as the usual various bug fixes.

New Features and improvements

Better ACME support

In this release ACME support has been significantly improved. ACME is used to automatically obtain SSL certificates for the domains served by ejabberd.

The newest version of ACME (so called ACMEv2) is now supported. The implementation is now much more robust, and is able to perform certificate requests and renewals in a fully automated mode.

The automated mode is enabled by default, however, since ACME requires HTTP challenges (i.e. an ACME server will connect to ejabberd server on HTTP port 80 during certificate issuance), some configuration of ejabberd is still required. Namely, an HTTP listener for ejabberd_http module should be configured on non-TLS port with so called “ACME well known” request handler:

listen:
...
  -
    module: ejabberd_http
    port: 5280
    request_handlers:
      /.well-known/acme-challenge: ejabberd_acme
      ...
...

Note that the ACME protocol requires challenges to be sent on port 80. Since this is a privileged port, ejabberd cannot listen on it directly without root privileges. Thus you need some mechanism to forward port 80 to the port defined by the listener (port 5280 in the example above).

There are several ways to do this: using NAT or HTTP front-ends (e.g. sslh, nginx, haproxy and so on). Pick one that fits your installation the best, but DON’T run ejabberd as root.

If you see errors in the logs with ACME server problem reports, it’s highly recommended to change ca_url option of section acme to the URL pointing to some staging ACME environment, fix the problems until you obtain a certificate, and then change the URL back and retry using request-certificate ejabberdctl command (see below).

This is needed because ACME servers typically have rate limits, preventing you from requesting certificates too rapidly and you can get stuck for several hours or even days.

By default, ejabberd uses Let’s Encrypt authority. Thus, the default value of ca_url option is
https://acme-v02.api.letsencrypt.org/directory

and the staging URL will be https://acme-staging-v02.api.letsencrypt.org/directory

acme:
  ## Staging environment
  ca_url: https://acme-staging-v02.api.letsencrypt.org/directory
  ## Production environment (the default):
  # ca_url: https://acme-v02.api.letsencrypt.org/directory

The automated mode can be disabled by setting auto option of section acme to false:

acme:
  auto: false
  ...

In this case automated renewals are still enabled, however, in order to request a new certificate,
you need to run request-certificate ejabberdctl command:

$ ejabberdctl request-certificate all

If you only want to request certificates for a subset of the domains, run:

$ ejabberdctl request-certificate domain.tld,pubsub.domain.tld,server.com,conference.server.com...

You can view the certificates obtained using ACME:

$ ejabberdctl list-certificates
domain.tld /path/to/cert/file1 true
server.com /path/to/cert/file2 false
...

The output is mostly self-explained: every line contains the domain, the corresponding certificate file, and whether this certificate file is used or not. A certificate might not be used for several reasons: mostly because ejabberd detects a better certificate (i.e. not expired, or having a longer lifetime). It’s recommended to revoke unused certificates if they are not yet expired (see below).

At any point you can revoke a certificate: pick the certificate file from the listing above and run:

$ ejabberdctl revoke-certificate /path/to/cert/file

If the commands return errors, consult the log files for details.

Webadmin

Some people have reported having issues to connect to the web administration console. To solve that, the need to connect using a URL with domain corresponding to an XMPP domain has been reverted.

Technical changes

Erlang/OTP requirement

Erlang/OTP 19.3 is now the minimum supported Erlang version for this release.

Database schema changes

There is no change to perform on the database to move from ejabberd 19.08 to ejabberd 19.09. Still, as usual, please, make a backup before upgrading.

Download and install ejabberd 19.09

The source package and binary installers are available at ProcessOne. If you installed a previous version, there are no additional upgrade steps, but as a good practice, plase backup your data.

As usual, the release is tagged in the Git source code repository on Github. If you suspect that you’ve found a bug, please search or fill a bug report in Issues.

Full changelog
===========

* Admin
– The minimum required Erlang/OTP version is now 19.3
– Fix API call using OAuth (#2982)
– Rename MUC command arguments from Host to Service (#2976)

* Webadmin
– Don’t treat ‘Host’ header as a virtual XMPP host (#2989)
– Fix some links to Guide in WebAdmin and add new ones (#3003)
– Use select fields to input host in WebAdmin Backup (#3000)
– Check account auth provided in WebAdmin is a local host (#3000)

* ACME
– Improve ACME implementation
– Fix IDA support in ACME requests
– Fix unicode formatting in ACME module
– Log an error message on IDNA failure
– Support IDN hostnames in ACME requests
– Don’t attempt to create ACME directory on ejabberd startup
– Don’t allow requesting certificates for localhost or IP-like domains
– Don’t auto request certificate for localhost and IP-like domains
– Add listener for ACME challenge in example config

* Authentication
– JWT-only authentication for some users (#3012)

* MUC
– Apply default role after revoking admin affiliation (#3023)
– Custom exit message is not broadcast (#3004)
– Revert “Affiliations other than admin and owner cannot invite to members_only rooms” (#2987)
– When join new room with password, set pass and password_protected (#2668)
– Improve rooms_* commands to accept ‘global’ as MUC service argument (#2976)
– Rename MUC command arguments from Host to Service (#2976)

* SQL
– Fix transactions for Microsoft SQL Server (#2978)
– Spawn SQL connections on demand only

* Misc
– Add support for XEP-0328: JID Prep
– Added gsfonts for captcha
– Log Mnesia table type on creation
– Replicate Mnesia ‘bosh’ table when nodes are joined
– Fix certificate selection for s2s (#3015)
– Provide meaningful error when adding non-local users to shared roster (#3000)
– Websocket: don’t treat ‘Host’ header as a virtual XMPP host (#2989)
– Fix sm ack related c2s error (#2984)
– Don’t hide the reason why c2s connection has failed
– Unicode support
– Correctly handle unicode in log messages
– Fix unicode processing in ejabberd.yml

Written by Jérôme Sautret