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, either create and download it from the Webinterface, or do so on the CLI:

pmgbackup backup

• At least 1GB free disk space at root mount point.
• Check known upgrade issues

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.
• Certain operations (for example config changes) will only work once all nodes have been 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

General

As a Debian based Distribution, Proxmox Mail Gateway is affected by most issues and changes affecting Debian. So ensure to read the Upgrade specific issues for buster

Especially the OpenSSL default version and security level raised and Semantics for using environment variables for su changed

Postgres And Other Template Modifications

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.

Service Failure Caused By Apparmor Featureset Missmatch

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 you can mitigate the issue in two ways:

• preferred: uninstall apparmor: apt remove apparmor
• disable feature-pinning in apparmor by commenting out or deleting the line features-file=/usr/share/apparmor-features/features in /etc/apparmor/parser.conf

Logrotation (rsyslog)

If you've modified /etc/logrotate.d/rsyslog make sure to compare the file upon upgrade - the postrotate script changed. Without the new script logrotation does not work which also breaks the tracking center. The postrotate script needs to be:

/usr/lib/rsyslog/rsyslog-rotate

External links

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