Upgrade from 5.x to 6.0

Introduction

Proxmox Mail Gateway 6.x is based on a new major version of Debian. Carefully plan the upgrade, make and verify backups before beginning, and test extensively. Depending on the existing configuration, several manual steps — including some downtime — may be required.

Note: A valid and tested backup is always needed before starting the upgrade process. Test the backup beforehand in a test lab setup.

In case the system is customized and/or uses additional packages or any other third party repositories/packages, ensure those packages are also upgraded to and compatible with Debian Buster.

In general, there are two ways to upgrade a Proxmox Mail Gateway 5.x system to Proxmox Mail Gateway 6.x:

• A new installation (and restoring the configuration and database from the backup)
• An in-place upgrade via apt (step-by-step)

In both cases emptying the browser cache and reloading the GUI page is required after the upgrade.

New Installation

• Install Proxmox Mail Gateway in one of the following three ways:
  • As a container on top of Debian Buster
  • On top of Debian Buster
  • By using the ISO image
• Restore the backup you have made before the upgrade.
• Change the IP address and the hostname.
• For clustered setups:
  • setup the slaves again
  • then join them to the upgraded master-node (recreate the cluster).

In-place Upgrade

Preconditions

• Upgrade to the latest version of Proxmox Mail Gateway 5.2.

apt update
apt dist-upgrade

• Make a valid and tested backup of Proxmox Mail Gateway

pmgbackup backup

• At least 1GB free disk space at root mount point.

In-place upgrades are done with apt. Familiarity with apt is required to proceed with this upgrade mechanism.

Actions step-by-step

Please ensure first that your Mail Gateway 5 system is up-to-date before starting the upgrade process.

Update the configured APT repositories

Change the apt sources to Buster - see Package Repositories

sed -i 's/stretch/buster/g' /etc/apt/sources.list

Make sure to also edit all files in /etc/apt/sources.list.d/ accordingly. For a Installation from the ISO with the enterprise repository the following command will work:

echo "deb https://enterprise.proxmox.com/debian/pmg buster pmg-enterprise" > /etc/apt/sources.list.d/pmg-enterprise.list

Stop and Mask Services Before Upgrade

This is necessary to prevent changes to the database before and during the upgrade.

• Stop postfix and all Proxmox Mail Gateway services (emails will be queued by the servers trying to contact the Proxmox Mail Gateway)

systemctl stop postfix pmg-smtp-filter pmgpolicy pmgdaemon pmgproxy pmgmirror pmgtunnel

• Mask postfix and all Proxmox Mailgateway services to prevent them from starting during the upgrade

systemctl mask postfix pmg-smtp-filter pmgpolicy pmgdaemon pmgproxy pmgmirror pmgtunnel

For Clusters

• If you have a cluster, stop and mask all cluster-daemons on all nodes before you start the upgrade of the first node.

systemctl stop pmgmirror pmgtunnel
systemctl mask pmgmirror pmgtunnel

• Then proceed by upgrading all nodes sequentially.
• The mail gateway service is provided by the other nodes, currently not being upgraded.

Upgrade The System

apt update
apt dist-upgrade

It is not necessary to reboot yet.

Upgrade postgres Database

• Before you upgrade the postgres main cluster, you need to remove the automatically created cluster in the new version.

pg_dropcluster --stop 11 main

• Upgrade the postgres main cluster from 9.6 to 11 by using pg_upgradecluster
  • If possible, use the default setting of dumping the old databases and restoring them to avoid problems.

pg_upgradecluster -v 11 9.6 main

• If you want to do an in-place upgrade (using pg_upgrade instead of pg_dump and pg_restore), you need to REINDEX all databases due to an incompatibility in glibc:
  • https://postgresql.verite.pro/blog/2018/08/27/glibc-upgrade.html
  • https://lists.debian.org/debian-glibc/2019/03/msg00030.html
  • https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=927129

• Unmask postfix and all non-cluster Proxmox Mail Gateway services to enable them again.

systemctl unmask postfix pmg-smtp-filter pmgpolicy pmgdaemon pmgproxy

• Reboot and control the journal to ensure that everything runs correctly.

reboot

• Remove the old postgres version and its data:

apt purge postgresql-9.6 postgresql-client-9.6 postgresql-contrib-9.6

After the Proxmox Mail Gateway upgrade

After upgrading, unmask and start all cluster-daemons on all nodes. This applies to upgrades of a single node as well as to upgrades of all nodes in a clustered setup:

systemctl unmask pmgmirror pmgtunnel
systemctl start pmgmirror pmgtunnel

Potential issues

• If you've modified the configuration template for postgresql (/var/lib/pmg/templates/postgresql.conf), make sure to compare and update your copy in /etc/pmg/templates/

• Also compare all other templates you've overriden for new changes through the packages

• Debian Buster installs apparmor, if you still have the Debian stock kernel installed (linux-image-4.19.0-5-amd64 recommends apparmor), due to a mismatch between the apparmor featureset in the stock kernel and the pve-kernel (which Proxmox Mailgateway uses) certain important services (e.g. clamav) do not start. Currently uninstall apparmor in that situation:

apt remove apparmor

External links

• Release Notes for Debian 10.0 (buster), 64-bit PC