Carbonio CE Upgrade

Carbonio CE 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, be it the (single) Node in a Single-Server installation, or all the Nodes in a Multi-Server installation.

The upgrade procedure consists of a preliminary task, followed by the proper upgrade, which is the same for each Node,

Depending on the packages upgraded, 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.

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 Manual Steps and Troubleshooting below contains information to prevent or fix these issues.

Upgrade Checklist

We define as current version 23.3.0, as previous version the version immediately before, i.e., 23.2.0, and as older versions any version of Carbonio CE released before these two.

Upgrade from older versions to 23.3.0

It is possible to upgrade from an older version to the current one, although we suggest to upgrade whenever a new version is available. However, this type of upgrade may not be as easy as a routine upgrade and you may need to manually execute CLI commands whenever you find yourself in one of the following situations.

In case of Multi-Server installation, make sure you are on the correct node before running the commands.

In case any -db package is in the upgrade list, execute the steps in Bootstrap Database.

If the upgrade of Docs Editor ends with errors, check section Upgrade of Docs-Editor.

If you are running a version up to 22.9.0, make sure to install the Administration Panel Packages along with the other upgrades.

Backup Node(s)

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.

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, which is SRV2 in our scenario.

  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

If you are on a Multi-Server, remember to start from the node featuring the Directory Server (SRV2 in our Six Nodes Scenario), 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 4. Register upgraded packages to Carbonio Mesh
# pending-setups -a
Step 5. Reboot

Once the upgrade has completed successfully, run command:

# reboot

Manual Steps and Troubleshooting

If you are upgrading from 23.2.0 to 23.3.0, you need to execute these steps only if they are mentioned in Sections Upgrade Checklist.

If you are upgrading from an older version (i.e., previous to 23.2.0), you need to verify in section Upgrade Checklist if any of these steps is needed: in other words, depending on the packages that will be upgraded, you might need to run them or not.

Bootstrap Database

Whenever a -db package is upgraded (currently they are carbonio-mailbox-db, carbonio-files-db, and carbonio-docs-connector-db), remember to bootstrap the corresponding Database, by running the command, respectively.

# PGPASSWORD=DB_ADM_PWD carbonio-files-db-bootstrap carbonio_adm

In the above command, DB_ADM_PWD is the the password of the carbonio_adm database role, that is, the one created during Step 6 of the Single-Server installation or the installation of SRV1: Postgres in the Multi-Server installation

Finally, since new version of Carbonio CE packages may include new services, it is strongly suggested to execute the command

# pending-setups -a

This will register the services to Carbonio Mesh, so they can immediately be used.


The secret needed to run the above command is stored in file /var/lib/service-discover/password which is accessible only by the root user.

Administration Panel Packages

If you are upgrading from a version previous to 22.10.0, make sure to install also the packages for the brand new Administration console. In a Multi-Server, the commands must be executed on the Proxy node.

# apt install carbonio-admin-console-ui carbonio-admin-ui
# dnf install carbonio-admin-console-ui carbonio-admin-ui

Upgrade of Docs-Editor

When installing recent version of the Docs-Editor, running the pending-setups -a might abruptly exit with an error message similar to:

Error writing config entry service-defaults/carbonio-docs-editor: Unexpected response code:
400 (Bad request: Request decoding failed: 1 error occurred:

      * invalid config key "Websocket"

To avoid this error, make sure that the installed package service-discover-base is at least version 1.10.12. You can verify this with the following commands.

# apt search service-discover-base
# dpkg -l service-discover-base
# dnf info service-discover-base
# rpm -q service-discover-base

If the version is older than 1.10.12, please upgrade the package.

After you verified that the version is the correct one, please run this command before pending-setups -a.

# systemctl restart service-discover.service