From Older Versions

From Older Versions#

This section guides you in the upgrade from a Carbonio CE version older than 24.12 to the latest available version, 25.6.0, which contains a number of technical and performance improvements, bug fixes, and security fixes.

Note

Upgrading from very old versions should work, but may require a lot of manual tasks to be carried out before, during, and after the procedure, and might become an extremely long and error-prone process.

Requirements and Limitations#

Before proceeding with the upgrade, please read carefully this whole section.

The following rules apply to any of the paths you decide to choose for the upgrade:

  • Since release 24.3.0, two major improvements have become available for Carbonio CE:

    1. support for new Operating Systems (OS): Ubuntu 22.04 and RHEL 9

    2. support for PostgreSQL 16. Carbonio CE no longer supports PostgreSQL 12, which must be upgraded to version 16 before upgrading Carbonio CE to 25.6.0. Check section Upgrade to PostgreSQL 16 for directions.

  • Since release 25.6.0, support for Ubuntu 24.04 has been added, while support for Ubuntu 20.04 has been dropped: Carbonio CE does no longer work on Ubuntu 20.04

  • You need to carry out the procedure on each Node, starting with the one featuring the Mesh and Directory

  • During the upgrade of Carbonio CE, you might need to carry out manual tasks, for example because you need to modify some configuration file or some error or warning is shown. Please refer to Section Known Issues (Older Releases) in Upgrade Troubleshooting for directions on how to tackle and fix them.

Warning

The 25.6.0 release of Carbonio CE dropped support for Ubuntu 20.04 LTS, which is EOL since May 2025.

We strongly recommend upgrading to Ubuntu 22.04 LTS or even Ubuntu 24.04 LTS to ensure continued compatibility and support. .

Checklist#

The following packages should be renamed or moved to different nodes during the upgrade procedure:

  1. carbonio-user-management

  2. carbonio-storages

  3. carbonio-catalog

  4. carbonio-message-broker

  5. carbonio-message-dispatcher

Upgrade Carbonio CE#

Preliminary Tasks

As a preliminary task, we backup the LDAP data of the Directory Server. On a Multi-Server installation, execute the following commands on the Node with the Directory Server Component installed.

  1. Make a dump of the LDAP Database, especially if the upgrade includes the Directory Server. This can be done using the command (as the zextras user)

    zextras$ /opt/zextras/libexec/zmslapcat /tmp

    Note

    The dump will be saved in the /tmp/ directory, so make sure to copy it to a safe location.

  2. Make a backup copy of file /opt/zextras/conf/localconfig.xml and store it in a safe place

  3. It is necessary that all services, especially OpenLDAP, be running during the whole procedure

    zextras$ zmcontrol status

    zextras$ zmcontrol status

    Hint

    On RHEL 9, use the new systemd commands that replace the zmcontrol command (see the dedicated box).

    If in the output some service appears as not running, start it.

If you are on a Multi-Server, remember to start from the Node featuring the Directory Server Component, then all the other Nodes in the same order of installation.

Step 1. Clean package list

Clean cached package list, metadata, and information.

# apt clean

# dnf clean all
Step 2. Upgrade Node

Update package list.

# apt update

# dnf check-update
Step 3. Install or move packages

The following packages needs to be moved from one Node to another or installed on the given Node.

carbonio-user-management

In release 25.3.0, this package must be installed as part of the Mesh & Directory Component, instead of the Proxy Component. To install it on the Mesh & Directory Node, execute as the root user

# apt install carbonio-user-management

# dnf install carbonio-user-management

While the user management features works even if the package is installed with both Components, we suggest that you remove it from the Node featuring the Proxy Component:

# apt remove carbonio-user-management

# dnf remove carbonio-user-management
carbonio-catalog

On the Node featuring the Proxy Component, install package carbonio-catalog by executing command

# apt install carbonio-catalog

# dnf install carbonio-catalog
carbonio-message-broker
Installation of package carbonio-message-broker

If you are upgrading from 24.9 versions or older, make sure that the carbonio-message-broker package is installed on the Mesh and Directory Node.

This situation was previously required by the Chats Component, where it was installed, but now is used by the whole Carbonio CE.

In case you already installed Chats, remove the carbonio-message-broker from the Chats Node, then install it on the Mesh & Directory Node.

If you never installed Chats, make sure you install this package on the Mesh & Directory Node.

To verify if the package is installed, execute the following command on the Chats (if installed) and the Mesh & Directory Node.

# dpkg -l carbonio-message-broker

The output should be (version may vary):

ii  carbonio-message-broker 0.2.0-1jammy amd64   Carbonio message broker

# rpm -q carbonio-message-broker

The output should be (version may vary):

carbonio-message-broker-0.2.0-1.el8.x86_64

If the package is installed on the Chats Node (if you have it installed), remove it.

# apt remove carbonio-message-broker

# dnf remove carbonio-message-broker

If the package is not installed on the Mesh & Directory Node, install it manually:

# apt install carbonio-message-broker

# dnf install carbonio-message-broker
carbonio-message-dispatcher

On the Node installing the Chats Component, remove package carbonio-message-dispatcher and install carbonio-message-dispatcher-ce.

# apt remove carbonio-message-dispatcher
# apt install carbonio-message-dispatcher-ce
Step 4. Upgrade Node

Update package list and install upgrades.

# apt upgrade

# dnf upgrade --best --allowerasing
Step 5. (Optional) Remove unused packages

After the latest packages have been installed, you can remove unused packages still installed on your system. If unsure, skip this step.

# apt autoremove

# dnf autoremove
Step 6. Register upgraded packages to Carbonio Mesh
# pending-setups -a
Step 7. Migration of new Dispatcher package

To complete the installation of the new carbonio-message-dispatcher-ce package, execute these commands

# PGPASSWORD=$DB_ADM_PWD carbonio-message-dispatcher-migration \
  carbonio_adm 127.78.0.10 20000

Restart the service

# systemctl restart carbonio-message-dispatcher
Step 8. Reboot

Once the upgrade has completed successfully, run command:

# reboot

Other Upgrades#

  1. If you want to upgrade PostgreSQL, but not the OS, you need to follow directions in Upgrade to PostgreSQL 16 before upgrading Carbonio CE

  2. If you want to upgrade the OS, you must upgrade PostgreSQL as well, since PostgreSQL 12 is not supported in either Ubuntu 22.04 or RHEL 9. This is the most time-consuming resource, because you need to carry out multiple tasks. Please refer to Section OS Upgrade for directions.

Contents