Upgrade from Older Supported Versions

Upgrade from Older Supported Versions#

If you plan to upgrade from a version more recent than 24.1.0 included, you may encounter issues or need to carry out tasks or command that are reported in Section Known Issue (Older Releases).

There are two equivalent methods to upgrade a Carbonio infrastructure: automatically using Ansible, or manually, Node by Node. The Ansible procedure (see section Upgrade from 24.5.0) should work even if you did not install Carbonio using the Ansible procedure, but may require some additional task to be executed manually, while the latter allows you to follow closely, Node by Node, the upgrade process and interact when needed and is described here.

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

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 dist-upgrade

# dnf upgrade --best --allowerasing
Step 4. Register upgraded packages to Carbonio Mesh
# pending-setups -a
Step 5. Reboot

Once the upgrade has completed successfully, run command:

# reboot

Requirements & Preliminaries#

The upgrade to 24.7.1 impacts the following Roles, packages, or third-party software, which require some manual interaction before, during, or after the procedure.

Operating system

Carbonio can be installed on Ubuntu 22.04 and RHEL 9 (BETA support) since version 24.5.0. If you plan to upgrade both the OS and Carbonio, please refer to Section OS upgrade.

PostgreSQL 16 support

PostgreSQL can be upgraded from version 12 to version 16. This step is mandatory if you also plan to upgrade from Ubuntu 20.04 to Ubuntu 22.04, because version 12 is no longer available on Ubuntu 22.04. Please follow the instructions in section PostgreSQL 16 Upgrade.

Warning

PostgreSQL 12 will reach the End Of Life on 14th November 2024 end of the year, so make sure to plan its upgrade before that date!

Known Issue (Older Releases)#

During the upgrade from an older version, you may encounter one or more of the following issues that require a manual intervention.

Additionally, after the upgrade to 24.7.1, the Carbonio Admin Panel will still report the version of Carbonio to be 24.7.0. However, the CLI zmcontrol -v will report the correct version (24.7.1).

GPG Key of Grafana in Ubuntu 22.04

If you migrate from Ubuntu 20.04 to 22.04 and use Monitoring Role’s Grafana, you need to update the location on which its GPG key is stored to prevent warning during upgrades. Log in to the Node on which the Carbonio Monitoring Role is installed and execute the following commands.

  • Remove existent repository

    # add-apt-repository -r "deb https://packages.grafana.com/oss/deb
stable main"

  • Retrieve GPG key

    # wget -q -O - https://packages.grafana.com/gpg.key | \
gpg --dearmor | sudo tee /usr/share/keyrings/grafana.gpg > \
/dev/null

  • Add repository

    # echo "deb [signed-by=/usr/share/keyrings/grafana.gpg] \
https://packages.grafana.com/oss/deb stable main" | sudo tee -a \
/etc/apt/sources.list.d/grafana.list
New Package Installation

A new package must be installed on the Node featuring the Database Connector Role. Log in to that Node and execute command

# apt install carbonio-storages

# dnf install carbonio-storages
Carbonio Monitoring

While upgrading the carbonio-prometheus package, you will be prompted with the following text:

Configuration file '/etc/carbonio/carbonio-prometheus/prometheus.yml'
==> Modified (by you or by a script) since installation.
==> Package distributor has shipped an updated version.
What would you like to do about it ?  Your options are:
Y or I  : install the package maintainer's version
N or O  : keep your currently-installed version

You must replace the existing file with the new one, therefore answer Y or I.

Delegated Administrators

In this release, you need to initialise again the domain(s) for Delegation: for each domain that has active Delegations, in the Carbonio Admin Panel go to Domains ‣ Manage ‣ Delegated Domain Admins and click the INIT DOMAIN button.

Backup

If the Global Administrator receives an e-mail notification about some accounts not migrated to use the new backupEnabled attribute, run the following commands as the zextras user to fix the issue.

First, stop the backup migration service

zextras$ carbonio backup dostopservice migrate-backup-enabled-setting

Then, start the service again to trigger the migration

zextras$ carbonio backup dostartservice migrate-backup-enabled-setting
Postgresql Upgrade Issue

During the upgrade of PostgreSQL, an error might be raised in case the existent databases have been created with older version of libc:

2024-03-19 12:28:14.209 UTC [909825] HINT:  Rebuild all objects in this database that use the default collation and run ALTER DATABASE activesync REFRESH COLLATION VERSION, or build PostgreSQL with the right library version.
2024-03-19 12:28:19.669 UTC [909915] WARNING:  database "abq" has a collation version mismatch

In case you find in the log some messages similar to the one shown above, you need to recreate the collation and indexes of the databases using the following commands.

First, become the postgres user

# su - postgres

Then issue these two commands

$ psql -d abq -c "REINDEX DATABASE abq"
$ psql -d abq -c "ALTER DATABASE abq REFRESH COLLATION VERSION;"

These commands should probably be given for each of the databases, so you can copy & paste all the following commands:

psql -d abq -c "REINDEX DATABASE abq"
psql -d abq -c "ALTER DATABASE abq REFRESH COLLATION VERSION;"
psql -d powerstore -c "REINDEX DATABASE powerstore"
psql -d powerstore -c "ALTER DATABASE powerstore REFRESH COLLATION VERSION;"
psql -d activesync -c "REINDEX DATABASE activesync"
psql -d activesync -c "ALTER DATABASE activesync REFRESH COLLATION VERSION;"
psql -d auth -c "REINDEX DATABASE auth"
psql -d auth -c "ALTER DATABASE auth REFRESH COLLATION VERSION;"
psql -d "carbonio-docs-connector-db" -c "REINDEX DATABASE \"carbonio-docs-connector-db\""
psql -d "carbonio-docs-connector-db" -c "ALTER DATABASE \"carbonio-docs-connector-db\" REFRESH COLLATION VERSION;"
psql -d "carbonio-files-db" -c "REINDEX DATABASE \"carbonio-files-db\""
psql -d "carbonio-files-db" -c "ALTER DATABASE \"carbonio-files-db\" REFRESH COLLATION VERSION;"
psql -d carbonio_adm -c "REINDEX DATABASE carbonio_adm"
psql -d carbonio_adm -c "ALTER DATABASE carbonio_adm REFRESH COLLATION VERSION;"
psql -d core -c "REINDEX DATABASE core"
psql -d core -c "ALTER DATABASE core REFRESH COLLATION VERSION;"
psql -d ha -c "REINDEX DATABASE ha"
psql -d ha -c "ALTER DATABASE ha REFRESH COLLATION VERSION;"
psql -d postgres -c "REINDEX DATABASE postgres"
psql -d postgres -c "ALTER DATABASE postgres REFRESH COLLATION VERSION;"
psql -d template0 -c "REINDEX DATABASE template0"
psql -d template0 -c "ALTER DATABASE template0 REFRESH COLLATION VERSION;"
psql -d template1 -c "REINDEX DATABASE template1"
psql -d template1 -c "ALTER DATABASE template1 REFRESH COLLATION VERSION;"
RHEL Netcat Issue

In systems which feature RHEL 8 or RHEL 9, you might find in journalctl’s log an error about a missing library for netcat:

May 02 09:20:02 demo.example.com systemd[1]: Started Session 3 of User zextras.
May 02 09:20:02 demo.example.com bash[3910]: netcat: error while loading shared libraries: libbsd.so.0: cannot open shared object file: No such file or directory
May 02 09:20:02 demo.example.com systemd[1]: Started Session 4 of User zextras.
May 02 09:20:02 demo.example.com bash[3912]: netcat: error while loading shared libraries: libbsd.so.0: cannot open shared object file: No such file or directory

The solution is to install the libbsd package:

# dnf install libbsd
initDomainForDelegation fails

After performing the INIT DOMAIN operation (required for creating delegated administrators), the following error may occur.

zextras@:~$ carbonio admin initDomainForDelegation local.loc

Unknown Exception com.zextras.lib.http.HTTPClientException:
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">soap:Header<context
xmlns="urn:zimbra"/></soap:Header>soap:Bodysoap:Fault<faultcode>soap:Client</faultcode><faultstring>
no such distribution list:
__monitoring_admins@local.loc</faultstring><detail> <Error
xmlns="urn:zimbra"><Code>account.NO_SUCH_DISTRIBUTION_LIST</Code><Trace>qtp2021053848-1571:1721660801727:f88a830e260d85fa</Trace></Error></detail></soap:Fault></soap:Body></soap:Envelope>

The workaround is to manually generate the empty ACL groups BEFORE initializing the domain. This can be done with the following commands:

zextras$ carbonio prov cdl __monitoring_admins@local.loc zimbraIsAdminGroup TRUE
zextras$ carbonio prov cdl __helpdesk_admins@local.loc zimbraIsAdminGroup TRUE
zextras$ carbonio prov cdl __groups_admins@local.loc zimbraIsAdminGroup TRUE
zextras$ carbonio prov cdl __users_admins@local.loc zimbraIsAdminGroup TRUE
zextras$ carbonio prov cdl __delegated_admins@local.loc zimbraIsAdminGroup TRUE
zextras$ carbonio prov cdl __domain_admins@local.loc zimbraIsAdminGroup TRUE

After executing the suggested commands, you can then carry out the INIT DOMAIN operation, from either the Carbonio Admin Panel or the CLI.

Advanced modules not starting

There are a few corner cases that prevent the advanced modules, provided by the Service Roles, to be running. The problem is that the Node featuring the Mailstore & Provisioning Role can not communicate with the Database (PostgreSQL) or DB Connector (pgpool), depending on your setup. You can check if this is the case if you find in log file /opt/zextras/log/mailbox.log error messages like:

2024-07-29 10:13:58,575 ERROR [main] [] extensions -
Error getting connection from data source org.postgresql.ds.PGSimpleDataSource@4151251b org.jooq.exception.DataAccessException:
Error getting connection from data source org.postgresql.ds.PGSimpleDataSource@4151251b at com.zextras.modules.core.db.LazyDataSourceConnectionProvider.acquire(BaseDSLContextProvider.java:72) ~[?:?]

Caused by: org.postgresql.util.PSQLException: Connection to 127.78.0.25:20000 refused. Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections.

Caused by: java.net.ConnectException: Connection refused

2024-07-29 10:14:00,642 FATAL [main] [] extensions - Unable to initialize zextras: org.jooq.exception.DataAccessException:
Error getting connection from data source org.postgresql.ds.PGSimpleDataSource@4151251b at org.jooq_3.14.8.POSTGRES.debug (null:-1)

Caused by: org.postgresql.util.PSQLException: Connection to 127.78.0.25:20000 refused. Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections.

Caused by: java.net.ConnectException: Connection refused

In order to fix the problem, ensure that PostgreSQL is reachable and then restart the mailbox.

zextras$ zmmailboxdctl restart
Contents