github processone/ejabberd 24.12
on GitHub

one day ago

Release notes copied from the original ejabberd 24.12 announcement post:

🚀 ejabberd 24.12: The "evacuate_kindly" release

Here comes ejabberd 24.12, including a few improvements and bug fixes. This release comes a month and half after 24.10, with around 60 commits to the core repository alongside a few updates in dependencies.

Release Highlights:

  • XEP-0484: Fast Authentication Streamlining Tokens: Reduce the time it takes for authentication. This helps with a faster start for clients on mobile.
  • Deprecation schedule for Erlang/OTP older than 25.0
  • Commands API v3: We paved the way for API changes and improvements while allowing customers depending on older version to stay on a pinned version of the commands.

Among them, the evacuate_kindly command is a new tool which gave the funny codename to this release. It lets you stop and rerun ejabberd without letting users reconnect to let you perform your maintenance task peacefully. So, this is not an emergency exit from ejabberd, but instead testimony that this releasing is paving the way for a lot of new cool stuff in 2025.

Other contents:

  • Improvements in commands
  • Use non-standard STUN port
  • Disable the systemd watchdog by default
  • Define macro as environment variable
  • Elixir modules for authentication
  • Redis now supports Unix Domain Socket
  • New evacuate_kindly command
  • Acknowledgments
  • Improvements in ejabberd Business Edition
  • ChangeLog
  • ejabberd 24.12 download & feedback

If you are upgrading from a previous version, there are no required changes in the SQL schemas, configuration or hooks. There are some Commands API v3.

Below is a detailed breakdown of the improvements and enhancements:

XEP-0484: Fast Authentication Streamlining Tokens

We added support for XEP-0484: Fast Authentication Streamlining Tokens. This allows clients to request time limited tokens from servers, which then can be later used for faster authentication by requiring less round trips. To enable this feature, you need to add mod_auth_fast module in modules section.

Deprecation schedule for Erlang/OTP older than 25.0

It is expected that around April 2025, GitHub Actions will remove Ubuntu 20 and it will not be possible to run automatically dynamic tests for ejabberd using Erlang/OTP older than 25.0.

For that reason, the planned schedule is:

  • ejabberd 24.12

    • Usage of Erlang/OTP older than 25.0 is still supported, but discouraged
    • Anybody still using Erlang 24.3 down to 20.0 is encouraged to upgrade to a newer version. Erlang/OTP 25.0 and higher are supported. For instance, Erlang/OTP 26.3 is used for the binary installers and container images.

  • ejabberd 25.01 (or later)

    • Support for Erlang/OTP older than 25.0 is deprecated
    • Erlang requirement softly increased in configure.ac
    • Announce: no warranty ejabberd can compile, start or pass the Common Tests suite using Erlang/OTP older than 25.0
    • Provide instructions for anybody to manually re-enable it and run the tests

  • ejabberd 25.01+1 (or later)

    • Support for Erlang/OTP older than 25.0 is removed completely in the source code

Commands API v3

This ejabberd 24.12 release introduces ejabberd Commands API v3 because some commands have changed arguments and result formatting. You can continue using API v2; or you can update your API client to use API v3. Check the API Versions History.

Some commands that accepted accounts or rooms as arguments, or returned JIDs, have changed their arguments and results names and format to be consistent with the other commands:

  • Arguments that refer to a user account are now named user and host
  • Arguments that refer to a MUC room are now named room and service
  • As seen, each argument is now only the local or server part, not the JID
  • On the other hand, results that refer to user account or MUC room are now the JID

In practice, the commands that change in API v3 are:

If you want to update ejabberd to 24.12, but prefer to continue using an old API version with mod_http_api, you can set this new option: 

modules:
  mod_http_api:
    default_version: 2

Improvements in commands

There are a few improvements in some commands:

  • create_rooms_file: Improved, now it supports vhosts with different config
  • evacuate_kindly: New command to kick users and prevent login (#4309)
  • join_cluster: Improved explanation: this returns immediately (since 5a34020, 24.06)
  • mod_muc_admin: Renamed arguments name to room for consistency, with backwards support (no need to update API clients)

Use non-standard STUN port

STUN via UDP can easily be abused for reflection/amplification DDoS attacks. Suggest a non-standard port to make it harder for attackers to discover the service in ejabberd.yml.example.

Modern XMPP clients discover the port via XEP-0215, so there's no advantage in sticking to the standard port.

Disable the systemd watchdog by default

Some users reported ejabberd being restarted by systemd due to missing watchdog pings despite the actual service operating just fine. So far, we weren't able to track down the issue, so we'll no longer enable the watchdog in our example service unit.

Define macro as environment variable

ejabberd allows you to define macros in the configuration file since version 13.10. This allows to define a value once at the beginning of the configuration file, and use that macro to setup options values several times during the file.

Now it is possible to define the macro value as an environment variable. The environment variable name should be EJABBERD_MACRO_ + macro name.

For example, if you configured in ejabberd.yml: 

define_macro:
  LOGLEVEL: 4

loglevel: LOGLEVEL

Now you can define (and overwrite) that macro definition when starting ejabberd. For example, if starting ejabberd in interactive mode: 

EJABBERD_MACRO_LOGLEVEL=5 make relive

This is specially useful when using containers with slightly different values (different host, different port numbers...): instead of having a different configuration file for each container, now you can use a macro in your custom configuration file, and define different macro values as environment variable when starting each container. See some examples usages in CONTAINER's composer examples

Elixir modules for authentication

ejabberd modules can be written in the Elixir programming language since ejabberd 15.02. And now, ejabberd authentication methods can also be written in Elixir!

This means you can write a custom authentication method in Erlang or in Elixir, or write an external authentication script in any language you want.

There's an example authentication method in the lib/ directory. Place your custom authentication method in that directory, compile ejabberd, and configure it in ejabberd.yml: 

auth_method: 'Ejabberd.Auth.Example'

For consistency with that file naming scheme, the old mod_presence_demo.ex has been renamed to mod_example.ex. Other minor changes were done on the Elixir example code.

Redis now supports Unix Domain Socket

Support for Unix Domain Socket was added to listener's port option in ejabberd 20.07. And more recently, ejabberd 24.06 added support in sql_server when using MySQL or PostgreSQL.
That feature is useful to improve performance and security when those programs are running on the same machine as ejabberd.

Now the redis_server option also supports Unix Domain Socket.

The syntax is similar to the other options, simply setup unix: followed with the full path to the socket file. For example: 

redis_server: "unix:/var/run/redis/redis.socket"

Additionally, we took the opportunity to update from the wooga/eredis erlang library which hasn't been updated in the last six years, to the Nordix/eredis fork which is actively maintained.

New evacuate_kindly command

ejabberd has nowadays around 180 commands to perform many administrative tasks. Let's review some of their usage cases:

  • Did you modify the configuration file? Reload the configuration file and apply its changes

  • Did you apply some patch to ejabberd source code? Compile and install it, and then update the module binary in memory

  • Did you update ejabberd-contrib specs, or improved your custom module in .ejabberd-module? Call module_upgrade to compile and upgrade it into memory

  • Did you upgrade ejabberd, and that includes many changes? Compile and install it, then restart ejabberd completely

  • Do you need to stop a production ejabberd which has users connected? stop_kindly the server, informing users and rooms

  • Do you want to stop ejabberd gracefully? Then simply stop it

  • Do you need to stop ejabberd immediately, without worrying about the users? You can halt ejabberd abruptly

Now there is a new command, evacuate_kindly, useful when you need ejabberd running to perform some administrative task, but you don't want users connected while you perform those tasks.

It stops port listeners to prevent new client or server connections, informs users and rooms, and waits a few seconds or minutes, then restarts ejabberd. However, when ejabberd is started again, the port listeners are stopped: this allows to perform administrative tasks, for example in the database, without having to worry about users.

For example, assuming ejabberd is running and has users connected. First let's evacuate all the users: 

ejabberdctl evacuate_kindly 60 \"The server will stop in one minute.\"

Wait one minute, then ejabberd gets restarted with connections disabled.
Now you can perform any administrative tasks that you need.
Once everything is ready to accept user connections again, simply restart ejabberd: 

ejabberdctl restart

Acknowledgments

We would like to thank the contributions to the source code, documentation, and translation provided for this release by:

And also to all the people contributing in the ejabberd chatroom, issue tracker...

Improvements in ejabberd Business Edition

Customers of the ejabberd Business Edition, in addition to all those improvements and bugfixes, also get support for Prometheus.

Prometheus support

Prometheus can now be used as a backend for mod_mon in addition to statsd, influxdb, influxdb2, datadog and dogstatsd.

You can expose all mod_mon metrics to Prometheus by adding a http listener pointing to mod_prometheus, for example: 

  -
    port: 5280
    module: ejabberd_http
    request_handlers:
      "/metrics": mod_prometheus

You can then add a scrape config to Prometheus for ejabberd: 

scrape_configs:
  - job_name: "ejabberd"
    static_configs:
      - targets:
          - "ejabberd.domain.com:5280"

You can also limit the metrics to a specific virtual host by adding it's name to the path: 

scrape_configs:
  - job_name: "ejabberd"
    static_configs:
      - targets:
          - "ejabberd.domain.com:5280"
     metrics_path: /metrics/myvhost.domain.com

Fix

  • PubSub: fix issue on get_item_name with p1db storage backend.

ChangeLog

This is a more detailed list of changes in this ejabberd release:

Miscelanea

  • Elixir: support loading Elixir modules for auth (#4315)
  • Environment variables EJABBERD_MACRO to define macros
  • Fix problem starting ejabberd when first host uses SQL, other one mnesia
  • HTTP Websocket: Enable allow_unencrypted_sasl2 on websockets (#4323)
  • Relax checks for channels bindings for connections using external encryption
  • Redis: Add support for unix domain socket (#4318)
  • Redis: Use eredis 1.7.1 from Nordix when using mix/rebar3 and Erlang 21+
  • mod_auth_fast: New module with support XEP-0484: Fast Authentication Streamlining Tokens
  • mod_http_api: Fix crash when module not enabled (for example, in CT tests)
  • mod_http_api: New option default_version
  • mod_muc: Make rsm handling in disco items, correctly count skipped rooms
  • mod_offline: Only delete offline msgs when user has MAM enabled (#4287)
  • mod_priviled: Handle properly roster iq
  • mod_pubsub: Send notifications on PEP item retract
  • mod_s2s_bidi: Catch extra case in check for s2s bidi element
  • mod_scram_upgrade: Don't abort the upgrade
  • mod_shared_roster: The name of a new group is lowercased
  • mod_shared_roster: Get back support for groupid@vhost in displayed

Commands API

  • Change arguments and result to consistent names (API v3)
  • create_rooms_file: Improve to support vhosts with different config
  • evacuate_kindly: New command to kick users and prevent login (#4309)
  • join_cluster: Explain that this returns immediately (since 5a34020, 24.06)
  • mod_muc_admin: Rename argument name to room for consistency

Documentation

  • Fix some documentation syntax, add links to toplevel, modules and API
  • CONTAINER.md: Add kubernetes yaml examples to use with podman
  • SECURITY.md: Add security policy and reporting guidelines
  • ejabberd.service: Disable the systemd watchdog by default
  • ejabberd.yml.example: Use non-standard STUN port

WebAdmin

  • Shared group names are case sensitive, use original case instead of lowercase
  • Use lowercase username and server authentication credentials
  • Fix calculation of node's uptime days
  • Fix link to displayed group when it is from another vhost

Full Changelog

24.10...24.12

ejabberd 24.12 download & feedback

As usual, the release is tagged in the Git source code repository on GitHub.

The source package and installers are available in ejabberd Downloads page. To check the *.asc signature files, see How to verify ProcessOne downloads integrity.

For convenience, there are alternative download locations like the ejabberd DEB/RPM Packages Repository and the GitHub Release / Tags.

The ecs container image is available in docker.io/ejabberd/ecs and ghcr.io/processone/ecs. The alternative ejabberd container image is available in ghcr.io/processone/ejabberd.

If you consider that you've found a bug, please search or fill a bug report on GitHub Issues.

Check out latest releases or
releases around processone/ejabberd 24.12

Don't miss a new ejabberd release

NewReleases is sending notifications on new releases.

Get notifications