Skip to content

Upgrade Procedure for ejabberd

This document contains administration procedure for each version upgrade. Only upgrade from version N to N+1 is documented and supported. If you upgrade from an older version than previous one, you have to review all upgrade notes and apply each steps one by one for the possible database changes. You also have to stop your old ejabberd server, and start the new one.

Until release note explicitly state you must restart the server for upgrade, you should be able to run soft upgrade using a cluster. If you don't have cluster, upgrade from older release than previous one, or have explicit note soft upgrade does not work, then you have to fallback to standalone upgrade process.

Generic upgrade process

This is the simplest process, and require service restart.

  • read the corresponding upgrade notes
  • apply the required changes in database from the upgrade note.
  • stop old node
  • archive content of mnesia database directory (database, i.e. /opt/ejabberd-XX.YY/database, /usr/local/var/lib/ejabberd, ...)
  • install new version
  • extract database archive in new path

  • if systemctl is used to manage ejabberd, copy the new service file and reload systemctl: 

    cp ejabberd-21.12/bin/ejabberd.service /etc/systemd/system/
systemctl daemon-reload

  • start new node

Soft upgrade process

This process needs you to run in cluster, with at least two nodes. In this case, we assume you run node A and B with version N, and will upgrade to version N+1.

  • read the corresponding upgrade notes, make sure it does not explicitly states "soft upgrade is not supported".
  • apply the required changes in database from the upgrade note.
  • make sure node A is running
  • run leave_cluster on node B
  • stop old node B
  • install new version on B's host
  • start new node B
  • run join_cluster on node B, passing node A as parameter
  • make sure both nodes are running and working as expected
  • run leave_cluster on node A
  • stop old node A
  • install new version on A's host
  • start new node A
  • run join_cluster on node A, passing node B as parameter

Module update process

Instead of upgrading all ejabberd to a brand new version, maybe you just want to update a few modules with bugfixes... in that case you can update only specific modules.

This process is only recommended for bugfixes that involve functional changes, and do not involve structural or memory changes (those ones are usually detected and applied at server start only).

How to do this?

  1. Apply the fixes to your source code, compile and reinstall ejabberd, so the new *.beam files replace the old ones
  2. In the ejabberd Web Admin go to Nodes -> your node -> Update
  3. This will detect what *.beam files have changed in the installation
  4. Select which modules you want to update now, and click Update
  5. This will load into memory the corresponding *.beam files

If you prefer to use commands, check update_list + update.

Notice this does not restart modules or any other tasks. If the fix you plan to apply requires a module restart, you can use this alternative: restart_module.

Note on database schema upgrade

ejabberd automatically updates the Mnesia table definitions at startup when needed. If you also use an external database (like MySQL, ...) for storage of some modules, check in the corresponding upgrade notes of the new ejabberd version if you need to update those tables yourself manually.

Specific version upgrade notes

The corresponsing ugprade notes are available in the release notes of each release, and also available in the Archive section: