Carbonio Upgrade#

Carbonio does not have any installer: whenever new versions are released, the Zextras repositories are updated and packages are available for installation along with the other system updates. Therefore, the upgrade procedure is usually a very quick activity, carried out by means of a few commands to be executed on each Node.

The upgrade procedure consists of a preliminary task, followed by the proper upgrade, which is the same for each Node. Regardless of the version currently installed, the successful upgrade will always bring Carbonio to the latest version available, currently 24.1.0.

Depending on the packages upgraded, and the version from which you are upgrading, some manual step may be required. Please read carefully section Upgrade Checklist before starting the upgrade, to see if you need to carry out some additional task.


Only the three previous versions are supported for upgrade. If you install from an older version, you may need to execute further tasks to ensure proper functioning of Carbonio.

Moreover, incompatibilities may arise in case the upgrade includes third-party software, which may lead to some additional manual steps to be carried out. Section Troubleshooting below contains information to prevent or fix these issues.

Upgrade Checklist#


Starting with version 23.6, the Single-Server installation of Carbonio is not supported anymore. If you have a Single-Server Installation, you must add a few Nodes to your installation and redistribute the Roles on them, to ensure you continue to productively use Carbonio.

This upgrade impacts the following Roles or packages, which require some manual interaction during the procedure.

There is a breaking change in this release, which requires some attention during the upgrade.

Some files have been moved from one package to another one. Since package managers forbid a file to belong to multiple packages, an error will be shown during the upgrade. You need to make sure that the package is installed, therefore these braking change leads to a slight different upgrade procedure, in Step 3. You can choose between two alternative procedures, either with automatic or manual conflict resolution. They are equivalent and will ensure that all the packages are correctly installed.


For improved security, to prevent any data loss, it is suggested to make a backup or take a snapshot (if you are using an hypervisor) of each Node before upgrading.

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

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

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


    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

Upgrade Nodes#

Remember to start the upgrade from the node featuring the Directory Server, then all the other in the same order of installation.

Step 1. Stop services

As the zextras user, run:

zextras$ zmcontrol stop
Step 2. Clean cached package list and information
# apt clean
# dnf clean all
Step 3. Update package list and install upgrades
# apt update && apt upgrade
# dnf upgrade
Step 3. (Pre 23.12.0 release) Update package list and install upgrades

This procedure (suitable for those upgrading from versions older than 23.12.0) fixes the conflicts and dependencies.

# apt update && apt upgrade --fix-broken
# apt autoremove
# rpm -e --nodeps carbonio-common-appserver-db
# dnf upgrade
Step 4. Bootstrap databases

This step must be performed exclusively on the DB Connection node.

  • Carbonio Advanced

    # PGPASSWORD=$DB_ADM_PWD carbonio-mailbox-db-bootstrap carbonio_adm
Step 5. Register upgraded packages to Carbonio Mesh
# pending-setups -a
Step 6. Reboot

Once the upgrade has completed successfully, run command:

# reboot


In this section you find solutions for some possible error during the upgrade procedure.

Failed Installation of carbonio-docs-editor#

When installing carbonio-docs-editor on RHEL 8-based distributions you may encounter this error:

Error:  Problem: package carbonio-docs-core-22.05.12-1.el8.x86_64 requires harfbuzz-icu,
but none of the providers can be installed
  - package carbonio-docs-core-22.05.12-1.el8.x86_64 requires, but none of the providers can be installed
  - package harfbuzz-icu-1.7.5-3.el8.x86_64 conflicts with harfbuzz
    provided by harfbuzz-1.7.5-3.el8.x86_64
  - cannot install the best candidate for the job
  - problem with installed package harfbuzz-1.7.5-3.el8.x86_64
(try to add '--allowerasing' to command line to replace conflicting packages or '--skip-broken' to skip uninstallable packages or '--nobest' to use not only best candidate packages)

You need to follow the advice in the last line and execute the command

# dnf install harfbuzz-icu --allowerasing

After the package has been installed, you can resume the upgrade.

Missing carbonio-docs-editor user#

On RHEL 8-based Multi-Server installations only, you may find the following error in all AppServers that do not have* the carbonio-docs-editor package installed.

chown: invalid spec: 'carbonio-docs-editor:'

In these cases you need to open the /opt/zextras/libexec/zmfixperms, which is the script that fails, with a text editor and find the lines:

if [ -d /opt/zextras/docs ]; then
  printMsg "Fixing permissions and ownership on /opt/zextras/docs"
  chown carbonio-docs-editor: /opt/zextras/docs

The workaround is to comment out these four lines, by prepending a # to each line, that will therefore become:

#if [ -d /opt/zextras/docs ]; then
#  printMsg "Fixing permissions and ownership on /opt/zextras/docs"
#  chown carbonio-docs-editor: /opt/zextras/docs

Then, run the script again.