Upgrade from 6.x to 7.0

Introduction

Proxmox Mail Gateway 7.x is based on the new major version of Debian (Bullseye). 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 required, 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 Bullseye.

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

• A new installation (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 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 Bullseye
  • On top of Debian Bullseye
  • By using the ISO image
• Restore the backup which you made before the upgrade.
• Change the IP address and hostname.
• For clustered setups:
  • On the master, remove all nodes from the cluster
  • Upgrade the master
  • Set the nodes up fresh, then join them to the upgraded master-node (recreate the cluster).

In-Place Upgrade

Preconditions

The following actions need to be carried out from the command line.

Perform the actions via console or SSH. If you use SSH you should use a terminal multiplexer (for example, tmux or screen) to ensure the upgrade can continue even if the SSH connection gets interrupted.

Do not carry out the upgrade via the web-interface (GUI) console, as that will get interrupted during the upgrade!

• Upgrade to the latest version of Proxmox Mail Gateway 6.4 first.

  apt update
  apt dist-upgrade

  You can check the web-interface (reload) at the top, or use pmgversion. Both must show a version with 6.4-4 (or newer), for example something like pmg-api/6.4-4/... for the CLI command.

  If you still see an older version, you should ensure that you have valid package repositories configured.

• Make a valid and tested backup of Proxmox Mail Gateway.

  You can either create and download one from the web-interface, store it on your Proxmox Backup Server or create it from the CLI with pmgbackup backup.

• At least 4 GiB free disk space on root mount point.
• Check known upgrade issues

In-place upgrades are carried out using APT. Familiarity with APT is required to proceed with this upgrade mechanism.

Actions step-by-step

Please first ensure that your Mail Gateway 6 system is up-to-date and that a valid backup has been created before starting the upgrade process. If you need to adapt the configuration, do this now. In case you have a cluster, wait for all config-changes to be synced to all nodes before continuing.

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 will be provided by the other nodes, which aren't currently being upgraded.
• Certain operations (for example config changes) will only work once all nodes have been upgraded.

Update the configured APT repositories

Change the apt sources to Bullseye - see Package Repositories Update all Debian repository entries to Bullseye.

sed -i 's/buster\/updates/bullseye-security/g;s/buster/bullseye/g' /etc/apt/sources.list

Note that for Bullseye, Debian changed its security update repository from deb http://security.debian.org buster/updates main to deb http://security.debian.org bullseye-security main for more consistency. The above command accounts for this change already.

Update the enterprise repository to Bullseye:

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

Make sure to also update any extra files that you added to /etc/apt/sources.list.d/ to Bullseye accordingly.

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

Upgrade the system

apt update
apt dist-upgrade

It is not necessary to reboot yet.

Upgrade the PostgreSQL database

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

pg_dropcluster --stop 13 main

• Upgrade the postgres main cluster from 11 to 13, using pg_upgradecluster
  • This step will need some time and enough free diskspace as it will create another database containing your rules, statistics, and quarantine information.
  • If possible, use the default setting of dumping the old databases and restoring them, to avoid problems.

pg_upgradecluster -v 13 11 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 then check the journal to ensure that everything is running correctly again.

reboot

• Remove the old postgres version and its data:

apt purge postgresql-11 postgresql-client-11

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

Known issues and deprecations

• New default bind address for pmgproxy, unifying the default behavior with Proxmox Backup Server and Proxmox VE
  • In making the LISTEN_IP configurable, the daemon now binds to both wildcard addresses (IPv4 0.0.0.0:8006 and IPv6 [::]:8006) by default.

  Should you wish to prevent it from listening on IPv6, simply configure the IPv4 wildcard as LISTEN_IP in /etc/default/pmgproxy:

  LISTEN_IP="0.0.0.0"

  • Additionally, the logged IP address format changed for IPv4 in pmgproxy's access log (/var/log/pmgproxy/pmgproxy.log). They are now logged as IPv4-mapped IPv6 addresses, so instead of:

  192.168.16.68 - root@pam [10/04/2021:12:35:11 +0200] "GET /api2/json/config/ruledb/digest HTTP/1.1" 200 51

  the line now looks like:

  ::ffff:192.168.16.68 - root@pam [10/04/2021:12:35:11 +0200] "GET /api2/json/config/ruledb/digest HTTP/1.1" 200 51

  If you want to restore the old logging format, also set LISTEN_IP="0.0.0.0"

• The ClamAV SafeBrowsing feature has been deprecated upstream some time ago
  • The config option in pmg.conf is now considered deprecated and will be dropped with PMG 8.0.
  • The configuration template freshclam.conf.in has the relevant sections removed (rendering the configuration option useless).
  • If you've set the option (grep safebrowsing /etc/pmg/pmg.conf produces output) - please remove it.

Potential issues

General

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

non-usr-merged layouts

Most Proxmox Mail Gateway installations still have /bin and /usr/bin as separate directories - this is deprecated as of Debian Bullseye/11 and will become unsupported in Debian Bookworm/12.

See Deprecated Components for migration instructions.

Usually creating a backup of the system and installing the usrmerge package is all that is needed.

External links

Release Notes for Debian 11.0 (bullseye), 64-bit PC