Upgrade from 5.x to 6.0

From Proxmox Mail Gateway
Jump to navigation Jump to search

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:
  • 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
  • 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