Manual From Older Versions#
This section guides you in the upgrade from a Carbonio version older than 24.12 to the latest available version, 25.3.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:
From release 24.12.0, the DB connector Role is no longer supported and needs to be removed, therefore before starting the upgrade procedure please read carefully section Pgpool Removal and execute the procedure described there.
-
Since the 24.3.0 release, two major improvements have become available for Carbonio:
support for new Operating Systems (OS): Ubuntu 22.04 and RHEL 9
support for PostgreSQL 16. Carbonio no longer supports PostgreSQL 12, which must be upgraded to version 16 before upgrading Carbonio to 25.3.0. Check section Upgrade to PostgreSQL 16 for directions.
You need to carry out the procedure on each Node, starting with the one featuring the Mesh & Directory.
During the upgrade of Carbonio, 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.3.0 release of Carbonio is the last version supporting Ubuntu 20.04 LTS, which goes EOL in May 2025.
We strongly recommend upgrading to Ubuntu 22.04 LTS to ensure continued compatibility and support. Future versions of Carbonio will not support Ubuntu 20.04 LTS.
Checklist#
The new packages or packages that should be moved on different nodes, should be installed or moved during the upgrade procedure:
carbonio-user-management
carbonio-storages
carbonio-catalog
carbonio-message-broker
Upgrade Carbonio#
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 Role installed.
-
Make a dump of the LDAP Database, especially if the upgrade includes the Directory Server. This can be done using the command (as the
zextrasuser)zextras$ /opt/zextras/libexec/zmslapcat /tmpNote
The dump will be saved in the
/tmp/directory, so make sure to copy it to a safe location. Make a backup copy of file
/opt/zextras/conf/localconfig.xmland store it in a safe place-
It is necessary that all services, especially OpenLDAP, be running during the whole procedure
zextras$ zmcontrol statuszextras$ zmcontrol statusHint
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.
Remember to start the upgrade from the Node featuring the Directory Server, then all the other Nodes in the same order of installation.
Clean cached package list, metadata, and information.
# apt clean
# dnf clean all
Update package list.
# apt update
# dnf check-update
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 Role, instead of the Proxy Role. To
intall 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 installed with both Roles, we suggest that you remove it from the Node featuring the Proxy Role:
# apt remove carbonio-user-management
# dnf remove carbonio-user-management
carbonio-storages
On the Node featuring the Mesh & Directory Role, install
package carbonio-storages by executing command
# apt install carbonio-storages
# dnf install carbonio-storages
carbonio-catalog
On the Node featuring the Proxy Role, install package
carbonio-catalog by executing command
# apt install carbonio-catalog
# dnf install carbonio-catalog
carbonio-message-broker
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 & Directory Node.
This situation was previously required by the Work Stream Collaboration (Chats) (WSC) Role, where it was installed, but now is used by the whole Carbonio.
In case you already installed Work Stream Collaboration (Chats), remove the
carbonio-message-broker from the Work Stream Collaboration (Chats) Node, then
install it on the Mesh & Directory Node.
If you never installed WSC, make sure you install this package on the Mesh & Directory Node.
To verify if the package is installed, execute the following command on the Work Stream Collaboration (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 WSC 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
Install upgrades.
# apt upgrade
# dnf upgrade --best --allowerasing
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
# pending-setups -a
Once the upgrade has completed successfully, run command:
# reboot
Other Upgrades#
If you want to upgrade PostgreSQL, but not the OS, you need to follow directions in Upgrade to PostgreSQL 16 before upgrading Carbonio
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.