Proxmox Mail Gateway - User contributions [en]

Upgrade from 6.x to 7.0

2026-06-08T06:38:37Z

L.Leahu-Vladucu: Consistently mention apt instead of apt-get for newer releases

= 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 [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian_container container on top of Debian Bullseye]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian On top of Debian Bullseye]
** By using the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_iso 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!'''

Old releases must use [https://forum.proxmox.com/threads/new-archive-cdn-for-end-of-life-eol-releases.178957/ the archive CDN for Proxmox] and [https://www.debian.org/distrib/archive for Debian], so make sure that all repositories in <code>/etc/apt/sources.list</code> and <code>/etc/apt/sources.list.d/*.list</code> use:
* <code>archive.debian.org</code> instead of <code>*.debian.org</code>
* <code>archive.proxmox.com</code> instead of <code>*.proxmox.com</code>
* In case certificate errors occur while running <code>apt update</code>, use HTTP instead of HTTPS for the repositories.

* Upgrade to the latest version of Proxmox Mail Gateway 6.4 first.
*:<pre>
*::apt update
*::apt dist-upgrade
*:</pre>
*: 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.
*: 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>.

* At least 4 GiB free disk space on root mount point.
* Check [[Upgrade_from_6.x_to_7.0#Potential_issues|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.
*:<pre>
*:: systemctl stop pmgmirror pmgtunnel
*:: systemctl mask pmgmirror pmgtunnel
*:</pre>
* 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 [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories 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 <code>deb http://security.debian.org buster/updates main</code> to <code>deb http://security.debian.org bullseye-security main</code> 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 <code>/etc/apt/sources.list.d/</code> to Bullseye accordingly.

In case [https://forum.proxmox.com/threads/new-archive-cdn-for-end-of-life-eol-releases.178957/ the archive CDN for Proxmox] and [https://www.debian.org/distrib/archive for Debian] have been used, please switch back to the normal [https://pve.proxmox.com/wiki/Package_Repositories Package Repositories].

=== 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)
:<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:
:<pre>systemctl mask postfix pmg-smtp-filter pmgpolicy pmgdaemon pmgproxy pmgmirror pmgtunnel</pre>

=== 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.
:<pre>pg_dropcluster --stop 13 main</pre>
* 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.
** 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.
:<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.
:<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 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 <code>0.0.0.0:8006</code> and IPv6 <code>[::]:8006</code>) by default.
*: Should you wish to prevent it from listening on IPv6, simply configure the IPv4 wildcard as LISTEN_IP in <code>/etc/default/pmgproxy</code>:
*: <code>LISTEN_IP="0.0.0.0"</code>
** Additionally, the logged IP address format changed for IPv4 in pmgproxy's access log (<code>/var/log/pmgproxy/pmgproxy.log</code>). They are now logged as IPv4-mapped IPv6 addresses, so instead of:
*: <code>192.168.16.68 - root@pam [10/04/2021:12:35:11 +0200] "GET /api2/json/config/ruledb/digest HTTP/1.1" 200 51</code>
*: the line now looks like:
*: <code>::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</code>
*:If you want to restore the old logging format, also set <code>LISTEN_IP="0.0.0.0"</code>

* The ClamAV SafeBrowsing feature has [https://blog.clamav.net/2021/04/are-you-still-attempting-to-download.html been deprecated upstream some time ago]
** The config option in <code>pmg.conf</code> is now considered deprecated and will be dropped with PMG 8.0.
** The configuration template <code>freshclam.conf.in</code> has the relevant sections removed (rendering the configuration option useless).
** If you've set the option (<code>grep safebrowsing /etc/pmg/pmg.conf</code> 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 [https://www.debian.org/releases/bullseye/amd64/release-notes/ch-information.en.html upgrade specific issues for Bullseye].

== Installations as Container on Proxmox VE ==

The newer version of <code>systemd</code> inside the container requires that the <code>nesting</code> feature has to be enabled for the container.
This is needed in order for many essential services to be able to run.
Keep in mind that this makes running privileged containers an even greater risk, thus it is recommended to only use unprivileged containers.

== 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 [https://www.debian.org/releases/bullseye/amd64/release-notes/ch-information.en.html#deprecated-components Deprecated Components] for migration instructions.

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

== External links ==

[https://www.debian.org/releases/bullseye/amd64/release-notes/ Release Notes for Debian 11.0 (bullseye), 64-bit PC]

[[Category: Upgrade]]

Upgrade from 5.x to 6.0

2026-06-08T06:37:34Z

L.Leahu-Vladucu: Consistently mention apt instead of apt-get for newer releases

= 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 [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_install_proxmox_mail_gateway_as_linux_container_appliance container on top of Debian Buster]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_install_proxmox_mail_gateway_on_debian On top of Debian Buster]
** By using the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_using_the_proxmox_mail_gateway_installation_cd_rom 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 ==

Old releases must use [https://forum.proxmox.com/threads/new-archive-cdn-for-end-of-life-eol-releases.178957/ the archive CDN for Proxmox] and [https://www.debian.org/distrib/archive for Debian], so make sure that all repositories in <code>/etc/apt/sources.list</code> and <code>/etc/apt/sources.list.d/*.list</code> use:
* <code>archive.debian.org</code> instead of <code>*.debian.org</code>
* <code>archive.proxmox.com</code> instead of <code>*.proxmox.com</code>
* In case certificate errors occur while running <code>apt update</code>, use HTTP instead of HTTPS for the repositories.

* 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 [[Upgrade_from_5.x_to_6.0#Potential_issues|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 [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories]
sed -i 's/stretch/buster/g' /etc/apt/sources.list

Make sure to also edit all files in <code>/etc/apt/sources.list.d/</code> accordingly. For a Installation from the ISO
with the enterprise repository the following command will work:
echo "deb http://archive.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 <code>pg_upgradecluster</code>
** 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 <code>pg_upgrade</code> instead of <code>pg_dump</code> and <code>pg_restore</code>), you need to <code>REINDEX</code> 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 [https://www.debian.org/releases/buster/amd64/release-notes/ch-information.en.html Upgrade specific issues for buster]

Especially the [https://www.debian.org/releases/buster/amd64/release-notes/ch-information.en.html#openssl-defaults OpenSSL default version and security level raised] and [https://www.debian.org/releases/buster/amd64/release-notes/ch-information.en.html#su-environment-variables Semantics for using environment variables for su changed]

== Postgres And Other Template Modifications ==
If you've modified the configuration template for postgresql (<code>/var/lib/pmg/templates/postgresql.conf</code>), make sure to compare and update your copy in <code>/etc/pmg/templates/</code>

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 (<code>linux-image-4.19.0-5-amd64</code> 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. <code>clamav</code>) do not start. Currently you can mitigate the issue in two ways:
* preferred: uninstall <code>apparmor</code>: <code>apt remove apparmor</code>
* disable feature-pinning in apparmor by commenting out or deleting the line <code>features-file=/usr/share/apparmor-features/features</code> in <code>/etc/apparmor/parser.conf</code>

== Logrotation (rsyslog) ==
If you've modified <code>/etc/logrotate.d/rsyslog</code> make sure to compare the file upon upgrade - the <code>postrotate</code> script changed. Without the new script logrotation does not work which also breaks the tracking center. The <code>postrotate</code> script needs to be:
/usr/lib/rsyslog/rsyslog-rotate

= External links =

*[https://www.debian.org/releases/buster/amd64/release-notes/ Release Notes for Debian 10.0 (buster), 64-bit PC]

[[Category: Upgrade]]

Upgrade from 6.x to 7.0

2026-05-22T14:13:30Z

L.Leahu-Vladucu: Update links to contain information regarding archive CDNs

= 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 [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian_container container on top of Debian Bullseye]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian On top of Debian Bullseye]
** By using the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_iso 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!'''

Old releases must use [https://forum.proxmox.com/threads/new-archive-cdn-for-end-of-life-eol-releases.178957/ the archive CDN for Proxmox] and [https://www.debian.org/distrib/archive for Debian], so make sure that all repositories in <code>/etc/apt/sources.list</code> and <code>/etc/apt/sources.list.d/*.list</code> use:
* <code>archive.debian.org</code> instead of <code>*.debian.org</code>
* <code>archive.proxmox.com</code> instead of <code>*.proxmox.com</code>
* In case certificate errors occur while running <code>apt-get update</code>, use HTTP instead of HTTPS for the repositories.

* Upgrade to the latest version of Proxmox Mail Gateway 6.4 first.
*:<pre>
*::apt update
*::apt dist-upgrade
*:</pre>
*: 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.
*: 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>.

* At least 4 GiB free disk space on root mount point.
* Check [[Upgrade_from_6.x_to_7.0#Potential_issues|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.
*:<pre>
*:: systemctl stop pmgmirror pmgtunnel
*:: systemctl mask pmgmirror pmgtunnel
*:</pre>
* 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 [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories 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 <code>deb http://security.debian.org buster/updates main</code> to <code>deb http://security.debian.org bullseye-security main</code> 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 <code>/etc/apt/sources.list.d/</code> to Bullseye accordingly.

In case [https://forum.proxmox.com/threads/new-archive-cdn-for-end-of-life-eol-releases.178957/ the archive CDN for Proxmox] and [https://www.debian.org/distrib/archive for Debian] have been used, please switch back to the normal [https://pve.proxmox.com/wiki/Package_Repositories Package Repositories].

=== 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)
:<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:
:<pre>systemctl mask postfix pmg-smtp-filter pmgpolicy pmgdaemon pmgproxy pmgmirror pmgtunnel</pre>

=== 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.
:<pre>pg_dropcluster --stop 13 main</pre>
* 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.
** 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.
:<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.
:<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 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 <code>0.0.0.0:8006</code> and IPv6 <code>[::]:8006</code>) by default.
*: Should you wish to prevent it from listening on IPv6, simply configure the IPv4 wildcard as LISTEN_IP in <code>/etc/default/pmgproxy</code>:
*: <code>LISTEN_IP="0.0.0.0"</code>
** Additionally, the logged IP address format changed for IPv4 in pmgproxy's access log (<code>/var/log/pmgproxy/pmgproxy.log</code>). They are now logged as IPv4-mapped IPv6 addresses, so instead of:
*: <code>192.168.16.68 - root@pam [10/04/2021:12:35:11 +0200] "GET /api2/json/config/ruledb/digest HTTP/1.1" 200 51</code>
*: the line now looks like:
*: <code>::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</code>
*:If you want to restore the old logging format, also set <code>LISTEN_IP="0.0.0.0"</code>

* The ClamAV SafeBrowsing feature has [https://blog.clamav.net/2021/04/are-you-still-attempting-to-download.html been deprecated upstream some time ago]
** The config option in <code>pmg.conf</code> is now considered deprecated and will be dropped with PMG 8.0.
** The configuration template <code>freshclam.conf.in</code> has the relevant sections removed (rendering the configuration option useless).
** If you've set the option (<code>grep safebrowsing /etc/pmg/pmg.conf</code> 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 [https://www.debian.org/releases/bullseye/amd64/release-notes/ch-information.en.html upgrade specific issues for Bullseye].

== Installations as Container on Proxmox VE ==

The newer version of <code>systemd</code> inside the container requires that the <code>nesting</code> feature has to be enabled for the container.
This is needed in order for many essential services to be able to run.
Keep in mind that this makes running privileged containers an even greater risk, thus it is recommended to only use unprivileged containers.

== 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 [https://www.debian.org/releases/bullseye/amd64/release-notes/ch-information.en.html#deprecated-components Deprecated Components] for migration instructions.

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

== External links ==

[https://www.debian.org/releases/bullseye/amd64/release-notes/ Release Notes for Debian 11.0 (bullseye), 64-bit PC]

[[Category: Upgrade]]

Upgrade from 5.x to 6.0

2026-05-22T14:07:10Z

L.Leahu-Vladucu: Update links to contain information regarding archive CDNs

= 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 [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_install_proxmox_mail_gateway_as_linux_container_appliance container on top of Debian Buster]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_install_proxmox_mail_gateway_on_debian On top of Debian Buster]
** By using the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_using_the_proxmox_mail_gateway_installation_cd_rom 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 ==

Old releases must use [https://forum.proxmox.com/threads/new-archive-cdn-for-end-of-life-eol-releases.178957/ the archive CDN for Proxmox] and [https://www.debian.org/distrib/archive for Debian], so make sure that all repositories in <code>/etc/apt/sources.list</code> and <code>/etc/apt/sources.list.d/*.list</code> use:
* <code>archive.debian.org</code> instead of <code>*.debian.org</code>
* <code>archive.proxmox.com</code> instead of <code>*.proxmox.com</code>
* In case certificate errors occur while running <code>apt-get update</code>, use HTTP instead of HTTPS for the repositories.

* 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 [[Upgrade_from_5.x_to_6.0#Potential_issues|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 [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories]
sed -i 's/stretch/buster/g' /etc/apt/sources.list

Make sure to also edit all files in <code>/etc/apt/sources.list.d/</code> accordingly. For a Installation from the ISO
with the enterprise repository the following command will work:
echo "deb http://archive.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 <code>pg_upgradecluster</code>
** 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 <code>pg_upgrade</code> instead of <code>pg_dump</code> and <code>pg_restore</code>), you need to <code>REINDEX</code> 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 [https://www.debian.org/releases/buster/amd64/release-notes/ch-information.en.html Upgrade specific issues for buster]

Especially the [https://www.debian.org/releases/buster/amd64/release-notes/ch-information.en.html#openssl-defaults OpenSSL default version and security level raised] and [https://www.debian.org/releases/buster/amd64/release-notes/ch-information.en.html#su-environment-variables Semantics for using environment variables for su changed]

== Postgres And Other Template Modifications ==
If you've modified the configuration template for postgresql (<code>/var/lib/pmg/templates/postgresql.conf</code>), make sure to compare and update your copy in <code>/etc/pmg/templates/</code>

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 (<code>linux-image-4.19.0-5-amd64</code> 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. <code>clamav</code>) do not start. Currently you can mitigate the issue in two ways:
* preferred: uninstall <code>apparmor</code>: <code>apt remove apparmor</code>
* disable feature-pinning in apparmor by commenting out or deleting the line <code>features-file=/usr/share/apparmor-features/features</code> in <code>/etc/apparmor/parser.conf</code>

== Logrotation (rsyslog) ==
If you've modified <code>/etc/logrotate.d/rsyslog</code> make sure to compare the file upon upgrade - the <code>postrotate</code> script changed. Without the new script logrotation does not work which also breaks the tracking center. The <code>postrotate</code> script needs to be:
/usr/lib/rsyslog/rsyslog-rotate

= External links =

*[https://www.debian.org/releases/buster/amd64/release-notes/ Release Notes for Debian 10.0 (buster), 64-bit PC]

[[Category: Upgrade]]