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 with by means of a few commands, which are the same for Single-Server and Multi-Server installations, thought on the latter some more work on specific nodes is required.

Depending on the Carbonio setup and packages upgraded some incompatibilities may arise in third-party software, which lead to some additional manual steps to be carried out. Section Upgrade Troubleshooting below contains information to prevent or fix these issues.

Upgrade to Carbonio 22.11.0

If you are upgrading to Carbonio 22.11.0 and the upgrade includes the Directory Server Role, please read this section carefully, because you need to carry out some additional steps before attempting the upgrade and after the upgrade has successfully completed.


In Multi-server installations, these command must be executed on the Node on which the Directory Server is installed (SRV2 in our scenario).

These steps are required, because this update introduces backward-incompatible changes in the Directory Server infrastructure, namely it adds a few new attributes in the database.

Before the upgrade procedure

  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.

  3. Stop the Directory Server service

    zextras$ ldap stop

After the upgrade procedure

  1. Restart the Directory Server service

    zextras$ ldap start
  2. Make sure that Carbonio Mesh picks up all changes

    # pending-setups -a

Upgrade Procedure

The steps required to upgrade a Single-Server and a Multi-Server are basically three. In the case of Single-Server, some additional manual step may be required, see the instructions below, while in Multi-Server installations some manual step is required on some specific Node.

Step 1. Clean cached package list and information

# apt clean
# dnf clean all

Step 2. Download new package list

# apt update
# dnf update

Step 3. Install new packages

# apt upgrade
# dnf upgrade

These commands also take care of resolving all dependencies and install all the upgrades available, of both the system and Carbonio.

Specific Instructions for Multi-Server

If you have a Multi-Server installation, you must execute the upgrade on each node, following the same order used during the installation. In other words, if you installed your Multi-Server according to the scenario described in Multi-Server Installation, you should start the upgrade from SRV1, then SRV2, SRV3, SRV4, SRV5, and finally SRV6.

On all nodes, after the upgrade has completed, remember to run

# pending-setups -a

This command makes sure that all services will be registered correctly to Carbonio Mesh after they have been restarted after the upgrade.

AppServer Nodes

On nodes with the AppServer (SRV5 and SRV6 in our scenario), make sure that the mailbox token has correct permissions

# chmod a+r /etc/zextras/carbonio-mailbox/token

Then, as the zextras user, restart the mailbox service.

zextras$ zmcontrol stop
zextras$ zmcontrol start

Manual steps

Bootstrap databases

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

  • mailbox

    # PGPASSWORD=DB_ADM_PWD carbonio-mailbox-db-bootstrap carbonio_adm
  • Carbonio Files

    # PGPASSWORD=DB_ADM_PWD carbonio-files-db-bootstrap carbonio_adm
  • Carbonio Docs

    # PGPASSWORD=DB_ADM_PWD carbonio-docs-connector-db-bootstrap carbonio_adm

In the above commands, 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 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 console packages

If you are upgrading to version 22.10.0, make sure to install also the packages for the brand new Administration console:

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

Upgrade Troubleshooting

This section lists some troubleshooting options related to the upgrade process.

Preventing docs-connector Conflicts

If you are running a release prior to 22.10.0, there are chances that you have installed package docs-connector-ce, which was common between Carbonio and Carbonio CE. If you have it installed, make sure to remove it and that only the new package carbonio-docs-connector is installed, by removing the old package

# apt purge carbonio-docs-connector-ce
# dnf remove carbonio-docs-connector-ce

Then installing the new package

# apt install carbonio-docs-connector
# dnf install carbonio-docs-connector

Since this package installs a database component, bootstrap the corresponding database.

# PGPASSWORD=$DB_ADM_PWD carbonio-docs-connector-db-bootstrap carbonio_adm

Finally, restart the mailbox service.

zextras$ zmcontrol stop
zextras$ zmcontrol start

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