-
chevron_right
ProcessOne: ejabberd 24.12
news.movim.eu / PlanetJabber • 19 December • 10 minutes
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
andhost
-
Arguments that refer to a MUC room are now named
room
andservice
- 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:
- get_room_affiliations
- muc_register_nick
- muc_unregister_nick
- set_room_affiliation
- status_list
- status_list_host
- subscribe_room
- subscribe_room_many
- unsubscribe_room
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 argumentsname
toroom
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&aposs 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&apost able to track down the issue, so we&aposll 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&aposs 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&aposs 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: &aposEjabberd.Auth.Example&apos
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&aposs
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&apost 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&aposs 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 intall 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&apost 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&aposs 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:
- Holger Weiß for PEP and other fixes
- Marcos de Vera Piquero for Elixir auth support
- Mark Zealey for WebSockets fix
- Mr. EddX , updated the Bulgarian translation
- Nautilusx , updated the German translation
- ButterflyOfFire , updated the French translation
- Ermete Melchiorre , updated the Italian translation
- Wellington Uemura , updated the Portuguese (Brazil)
- Besnik Bleta , updated the Albanian translation
- Sketch6580 , updated the Chinese translation
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&aposs 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 optiondefault_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&apost abort the upgrade -
mod_shared_roster
: The name of a new group is lowercased -
mod_shared_roster
: Get back support forgroupid@vhost
indisplayed
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 argumentname
toroom
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&aposs uptime days
- Fix link to displayed group when it is from another vhost
Full Changelog
https://github.com/processone/ejabberd/compare/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&aposve found a bug, please search or fill a bug report on GitHub Issues .