Skip to content

# Upgrade Procedure for ejabberd

upgrade

Install a version of the program newer than the currently installed one. Not to be confused with update or convert schema.

update

Modify your program installation to match the requirements of the new program version. This usually involves updating your configuration, your database schema, your API client, your custom modules... Not to be confused with upgrade ejabberd or convert schema.

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.

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

7. 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

8. 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.

1. read the corresponding upgrade notes, make sure it does not explicitly states "soft upgrade is not supported".
2. apply the required changes in database from the upgrade note.
3. make sure node A is running
4. run leave_cluster on node B
5. stop old node B
6. install new version on B's host
7. start new node B
8. run join_cluster on node B, passing node A as parameter
9. make sure both nodes are running and working as expected
10. run leave_cluster on node A
11. stop old node A
12. install new version on A's host
13. start new node A
14. 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 update

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:

- Upgrading from ejabberd 26.02 to 26.03
- Upgrading from ejabberd 26.01 to 26.02
- Upgrading from ejabberd 25.10 to 26.01
- Upgrading from ejabberd 25.08 to 25.10
- Upgrading from ejabberd 25.07 to 25.08
- Upgrading from ejabberd 25.04 to 25.07
- Upgrading from ejabberd 25.03 to 25.04
- Upgrading from ejabberd 24.12 to 25.03
- Upgrading from ejabberd 24.10 to 24.12
- Upgrading from ejabberd 24.07 to 24.10
- Upgrading from ejabberd 24.06 to 24.07
- Upgrading from ejabberd 24.02 to 24.06
- Upgrading from ejabberd 23.10 to 24.02
- Upgrading from ejabberd 23.04 to 23.10
- Upgrading from ejabberd 23.01 to 23.04
- Upgrading from ejabberd 22.10 to 23.01
- Upgrading from ejabberd 22.05 to 22.10
- Upgrading from ejabberd 21.12 to 22.05
- Upgrading from ejabberd 21.07 to 21.12
- Upgrading from ejabberd 21.04 to 21.07
- Upgrading from ejabberd 21.01 to 21.04
- Upgrading from ejabberd 19.08 to 20.01
- Upgrading from ejabberd 19.05 to 19.08
- Upgrading from ejabberd 19.02 to 19.05
- Upgrading from ejabberd 18.12 to 19.02
- Upgrading from ejabberd 18.09 to 18.12
- Upgrading from ejabberd 18.06 to 18.09
- Upgrading from ejabberd 18.04 to 18.06
- Upgrading from ejabberd 18.03 to 18.04
- Upgrading from ejabberd 18.01 to 18.03
- Upgrading from ejabberd 17.11 to 18.01
- Upgrading from ejabberd 17.09 to 17.11
- Upgrading from ejabberd ≥17.06 and ≤17.08 to 17.09
- Upgrading from ejabberd 17.03 or 17.04 to 17.06
- Upgrading from ejabberd ≥16.08 and ≤17.01 to 17.03
- Upgrading from ejabberd 16.06 to 16.08
- Upgrading from ejabberd 16.04 to 16.06
- Upgrading from ejabberd 16.03 to 16.04
- Upgrading from ejabberd 16.02 to 16.03
- Upgrading from ejabberd 15.11 to 16.02
- Upgrading from ejabberd 2.1.1x to 16.02