Third-party Software Upgrades

Third-party Software Upgrades#

OS upgrade#

In order to upgrade from a Carbonio CE 24.5.0 on Ubuntu 20.04 (or RHEL 8) to Carbonio CE 24.7.1 on Ubuntu 22.04 (or RHEL 9) you need to follow the procedure in this section. Please read carefully the whole page before starting the upgrade.

The procedure must be carried out on each Node, starting from the one on which the Directory Server Role is installed, and it will require to reboot the Node and therefore a downtime of the Carbonio CE infrastructure must be planned.

The procedure is divided into phases:

  1. upgrade PostgreSQL from 12 to 16 (you can skip it if you already upgraded)

  2. upgrade Carbonio CE to 24.7.1

  3. upgrade Ubuntu LTS from 20.04 to 22.04 (Jammy Jellifish) or RHEL 8 to RHEL 9

  4. upgrade Carbonio CE's packages to match the correct repository

  5. complete the upgrade procedure

Phase 1#

Upgrade to PostgreSQL 16 is mandatory, because Ubuntu 22.04 does not support the current PostgreSQL 12 installed on Carbonio CE. Directions to upgrade PostgreSQL can be found in Section PostgreSQL 16 Upgrade.

Hint

PostgreSQL 12 will be supported only until 24 November 2024, so if you did not already upgrade to 16, you should do so as soon as possible.

Phase 2#

This phase is the same as a normal upgrade, so please refer to Section Upgrade to Carbonio CE 24.7.1.

Phase 3#

This phase requires to upgrade the Ubuntu 20.04 distribution to 22.04 or the RHEL 8 to RHEL 9 please refer to the Ubuntu and Red Hat upstream documentations.

Note

If you upgrade to Ubuntu 22 and use the Carbonio Monitoring role, please make sure to change the Grafana repository.

Phase 4#

Once you successfully carried out the first three phases, you can proceed to update the Carbonio CE packages to match the distribution. This phase requires some manual command to be executed.

During the Ubuntu upgrade, the file /etc/apt/sources.list.d/zextras.list will be modified. You need to make sure that it contains only the correct repository, that is, the line defining the repository

  1. contains the word jammy

  2. is not commented, i.e., it does not start with a # sign

During the RHAL upgrade, the file /etc/yum.repos.d/zextras.repo will be modified. You need to make sure that it contains only the correct repository, that is, the line defining the repository is:

baseurl=https://repo.zextras.io/release/rhel9

You can now stop the Carbonio CE services

# su - zextras -c "zmcontrol stop"

Finally update the package list, and the packages itself with these commands

# apt update && apt dist-upgrade

# dnf upgrade –best –allowerasing

Phase 5#

At the end of the upgrade you need to fix the permissions and start the services

# /opt/zextras/libexec/zmfixperms
# su - zextras -c "zmcontrol start"

PostgreSQL 16 Upgrade#

Please read carefully the whole section and the instructions for your Operating System.

Warning

The upgrade to PostgreSQL 16 is mandatory if you plan to upgrade Ubuntu 20.04 to 22.04, because in the newest release the support for PostgreSQL 12 has been dropped.

The upgrade to PostreSQL requires to execute a couple of CLI commands and should require little downtime. However, you should take into account that the time to migrate is proportional to all the data stored, so you should consider PostgreSQL to be offline for the time needed to carry out the migration.

The procedure differs slightly between Ubuntu 20.04, Ubuntu 22.04 (in the installation of the repository), while in RHEL 8 it is quite different. For this reason, we separate the directions of RHEL from Ubuntu.

In case after the upgrade you find in Postgres’ log files some error messages like the following one, please check the directions for a fix:

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

Ubuntu 20.04 and 22.04#

The commands in this section must be executed as the root user and, except for the Repository Configuration, are the same on both versions of Ubuntu.

Repository Configuration

The following two commands work on both versions of Ubuntu, but the second one is deprecated in Ubuntu 22.04 and will raise a warning. Hence, to make sure the process is flawless, refer to the Ubuntu 22.04 tab for the command if you are installing on that version.

# sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

# wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

# sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

# wget -O- "https://www.postgresql.org/media/keys/ACCC4CF8.asc" | \
gpg --dearmor | sudo tee /usr/share/keyrings/postgres.gpg > \
/dev/null

# chmod 644 /usr/share/keyrings/postgres.gpg
# sed -i 's/deb/deb [signed-by=\/usr\/share\/keyrings\/postgres.gpg] /' /etc/apt/sources.list.d/pgdg.list

Install Packages

# apt update
# apt -y install postgresql-16

Prepare for migration

In this step some checks and preparatory tasks are executed.

  1. Check installed PG clusters and version

    # pg_lsclusters

  2. Stop the running service

    # systemctl stop postgresql

  3. Rename the clean 16 DB

    # pg_renamecluster 16 main main_pristine

Upgrade and restart service

  1. Upgrade the old DB to the new “main” DB

    # pg_upgradecluster 12 main

  2. Start the service

    # systemctl start postgresql

  3. Check that everything is working properly

    # pg_lsclusters

(Optional) remove unused DB

At this point, all data have been migrated to DB 16, so, if you verify that Carbonio CE operates properly and all the data are present, you can remove the unused Databases.

Hint

You can keep the old Database, back it up, and remove it at a later point.

  1. Drop the old DB

    # pg_dropcluster 12 main --stop

  2. Drop the pristine DB

    #pg_dropcluster 16 main_pristine --stop

RHEL 8 and 9#

Repository Configuration

The PostgreSQL repositories are different in RHEL 8 and RHEL9; the rest of the procedure is exactly the same.

# dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

# dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm

Package installation and checks

  1. Install PostgreSQL16 packages

    # dnf install postgresql16 postgresql16-server

  2. Init the DB

    # /usr/pgsql-16/bin/postgresql-16-setup initdb

  3. Check that everything is correct and clusters are compatible. This command does not alter any existing data.

    # su - postgres -c '/usr/pgsql-16/bin/pg_upgrade -b \
/usr/pgsql-12/bin/ -B /usr/pgsql-16/bin/ -d \
/var/lib/pgsql/12/data/ -D /var/lib/pgsql/16/data/ -c'

Upgrade and migrate

  1. Stop the PostgreSQL 12 service

    # systemctl stop postgresql-12.service

  2. Run the upgrade

    # su - postgres -c '/usr/pgsql-16/bin/pg_upgrade -b \
/usr/pgsql-12/bin/ -B /usr/pgsql-16/bin/ -d \
/var/lib/pgsql/12/data/ -D /var/lib/pgsql/16/data/'

  3. Migrate the pg_hba.conf file from the previous version

    # mv /var/lib/pgsql/16/data/pg_hba.conf /var/lib/pgsql/16/data/pg_hba.conf_orig
# cp /var/lib/pgsql/12/data/pg_hba.conf /var/lib/pgsql/16/data/pg_hba.conf
# chown postgres:postgres /var/lib/pgsql/16/data/pg_hba.conf

  4. Start the new DB

    # systemctl start postgresql-16.service

  5. Disable the old DB and enable the new one

    # systemctl mask postgresql-12.service

# systemctl enable postgresql-16.service

(Optional) remove unused DB

At this point, all data have been migrated to DB 16, so, if you verify that Carbonio CE operates properly and all the data are present, you can remove the unused Databases.

  1. Check the new Database

    # su - postgres -c '/usr/pgsql-16/bin/vacuumdb --all --analyze-in-stages'

  2. Delete the old cluster’s data files

    # /var/lib/pgsql/delete_old_cluster.sh

Update pgpool-II on RHEL 8 and RHEL 9

You need to update also the pgpool-II package so it matches PostgresQL’s correct version, 16.

  1. First, remove the installed package (and repository definition if installed)

    # dnf remove pgpool-II pgdg-redhat-repo

  2. Install the correct pgpool version

    # dnf install https://www.pgpool.net/yum/rpms/4.5/redhat/rhel-8-x86_64/pgpool-II-pg16-4.5.1-1pgdg.rhel8.x86_64.rpm

    # dnf install https://www.pgpool.net/yum/rpms/4.5/redhat/rhel-9-x86_64/pgpool-II-pg16-4.5.1-1pgdg.rhel9.x86_64.rpm
Contents