Difference between revisions of "Upgrade from 6.x to 7.0"
T.lamprecht (talk | contribs) |
T.lamprecht (talk | contribs) |
||
| (3 intermediate revisions by the same user not shown) | |||
| Line 40: | Line 40: | ||
*::apt dist-upgrade | *::apt dist-upgrade | ||
*:</pre> | *:</pre> | ||
| − | *: You can check the web-interface ( | + | *: You can check the web-interface (reload) at the top, or use <code>pmgversion</code>. Both must show a version with 6.4-4 (or newer), for example something like <code>pmg-api/6.4-4/...</code> for the CLI command. |
| + | *: If you still see an older version, you should ensure that you have valid [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories package repositories] configured. | ||
* Make a valid and tested backup of Proxmox Mail Gateway. | * 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 <code>pmgbackup backup</code>. | *: 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 <code>pmgbackup backup</code>. | ||
| Line 84: | Line 85: | ||
* Stop postfix and all Proxmox Mail Gateway services (emails will be queued by the servers trying to contact the Proxmox Mail Gateway) | * Stop postfix and all Proxmox Mail Gateway services (emails will be queued by the servers trying to contact the Proxmox Mail Gateway) | ||
| − | + | :<pre>systemctl stop postfix pmg-smtp-filter pmgpolicy pmgdaemon pmgproxy pmgmirror pmgtunnel</pre> | |
| − | * Mask postfix and all Proxmox Mailgateway services to prevent them from starting during the upgrade | + | * Mask postfix and all Proxmox Mailgateway services to prevent them from starting during the upgrade: |
| − | + | :<pre>systemctl mask postfix pmg-smtp-filter pmgpolicy pmgdaemon pmgproxy pmgmirror pmgtunnel</pre> | |
=== Upgrade the system === | === Upgrade the system === | ||
| Line 97: | Line 98: | ||
=== Upgrade the PostgreSQL database === | === Upgrade the PostgreSQL database === | ||
| − | * Before upgrading the | + | * Before upgrading the PostgreSQL main cluster, you need to remove the automatically created cluster in the new version. |
| − | + | :<pre>pg_dropcluster --stop 13 main</pre> | |
| − | * Upgrade the | + | * Upgrade the PostgreSQL main cluster from 11 to 13, using <code>pg_upgradecluster</code> |
** This step will need some '''time''' and enough '''free diskspace''' as it will create another database containing your rules, statistics, and quarantine information. | ** 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. | ** If possible, use the default setting of dumping the old databases and restoring them, to avoid problems. | ||
| − | + | :<pre>pg_upgradecluster -v 13 11 main</pre> | |
* Unmask postfix and all '''non-cluster''' Proxmox Mail Gateway services to enable them again. | * Unmask postfix and all '''non-cluster''' Proxmox Mail Gateway services to enable them again. | ||
| − | + | :<pre>systemctl unmask postfix pmg-smtp-filter pmgpolicy pmgdaemon pmgproxy</pre> | |
* Reboot and then check the journal to ensure that everything is running correctly again. | * Reboot and then check the journal to ensure that everything is running correctly again. | ||
| + | :<pre>reboot</pre> | ||
| − | + | * Reconnect to the node after it successfully rebooted | |
| − | * | + | * You can remove the old PostgreSQL version and its data now, if all is working as expected: |
| − | + | :<pre>apt purge postgresql-11 postgresql-client-11</pre> | |
== After the Proxmox Mail Gateway upgrade == | == After the Proxmox Mail Gateway upgrade == | ||
Revision as of 17:37, 17 July 2021
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 likepmg-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.
- 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
- 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 PostgreSQL main cluster, you need to remove the automatically created cluster in the new version.
pg_dropcluster --stop 13 main
- Upgrade the PostgreSQL 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
- Reconnect to the node after it successfully rebooted
- You can remove the old PostgreSQL version and its data now, if all is working as expected:
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:8006and 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"
- In making the LISTEN_IP configurable, the daemon now binds to both wildcard addresses (IPv4
- The ClamAV SafeBrowsing feature has been deprecated upstream some time ago
- The config option in
pmg.confis now considered deprecated and will be dropped with PMG 8.0. - The configuration template
freshclam.conf.inhas the relevant sections removed (rendering the configuration option useless). - If you've set the option (
grep safebrowsing /etc/pmg/pmg.confproduces output) - please remove it.
- The config option in
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.