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. Regardless of the version currently installed, the successful upgrade will always bring Carbonio CE 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.

Note

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 CE.

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#

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.

Hint

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
    

    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

Upgrade Nodes#

If you are on a Multi-Server, remember to start from the node featuring the Directory Server Role, 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. Register upgraded packages to Carbonio Mesh
# pending-setups -a
Step 5. Reboot

Once the upgrade has completed successfully, run command:

# reboot

Troubleshooting#

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 libharfbuzz-icu.so.0()(64bit), 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
fi

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
#fi

Then, run the script again.