Proxmox Mail Gateway - User contributions [en]

Upgrade from 7 to 8

2026-01-28T13:46:40Z

Stoiko Ivanov: /* Systemd-boot (for ZFS on root and UEFI systems only) */

= Introduction =
Proxmox Mail Gateway 8.x is based on the new major version of Debian (Bookworm). 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 Bookworm.

In general, there are two ways to upgrade a Proxmox Mail Gateway 7.x system to Proxmox Mail Gateway 8.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 Bookworm]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian On top of Debian Bookworm]
** 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.

* Perform these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** 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.
** '''Important''': Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgraded to the latest version of Proxmox Mail Gateway 7., see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bullseye repos setup) to upgrade to latest 7.3
** Verify version:
*: You can check the web-interface (reload) at the top, or use <code>pmgversion</code>. Both must show a version with 7.3-6 (or newer), for example something like <code>pmg-api/7.3-6/...</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 5 GB free disk space on root mount point.
* Check [[#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 7 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.

=== Continuously use the '''pmg7to8''' checklist script ===

A small checklist program named '''<code>pmg7to8</code>''' is included in the latest Proxmox Mail Gateway 7.3 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pmg7to8

This script only '''checks''' and reports things. By default, no changes to the system are made and thus, none of the issues will be automatically fixed.
You should keep in mind that Proxmox Mail Gateway can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

It is recommended to re-run the script after each attempt to fix an issue. This ensures that the actions taken actually fixed the respective warning.

=== 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 Bookworm - see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories]
Update all Debian repository entries to Bookworm.

sed -i 's/bullseye/bookworm/g' /etc/apt/sources.list

Update the enterprise repository to Bookworm:

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

For the no-subscription repository, see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories].
Rather than commenting out/removing the PMG 7.x repositories, as was previously mentioned, you could also run the following command to update to the Proxmox Mail Gateway 8 repositories:
sed -i -e 's/bullseye/bookworm/g' /etc/apt/sources.list.d/pmg-install-repo.list

Make sure to also update any extra files that you added to <code>/etc/apt/sources.list.d/</code> to Bookworm 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)
:<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

During the above step, you will be asked to approve changes to configuration files, where the default config has been updated by their respective package.

It's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup.

Common configuration files with changes, and the recommended choices are:
* <code>/etc/issue</code> -> Proxmox Mail Gateway will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/clamav/clamd.conf </code> and <code>/etc/clamav/freshclam.conf</code> -> Those two configuration files are managed by Proxmox Mail Gateway directly, at will be re-generate on any relevant change and on boot.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/ssh/sshd_config</code> -> If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.

* <code>/etc/default/grub</code> -> Here you may want to take special care, as this is normally only asked for if you changed it manually, e.g., for adding some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)

It is not necessary to reboot the Proxmox Mail Gateway host yet after the dist-upgrade finished.

=== Adapt modified configuration templates to new shipped versions ===

If configuration templates are used in <code>/etc/pmg/templates</code>, you will see a prompt about the changes in the new version that are not yet incorporated. Review the changes carefully and ensure that only the changes you want are shown in the diff.

=== Disable ClamAV On-Access Scanner Service ===

The new ClamAV on-access scanning service is not useful for Proxmox Mail Gateway setups and is disabled for new installations as it not only slows down the entire system, but also affects the spam and virus detection mechanisms managed by Proxmox Mail Gateway.

During upgrades, the service may get enabled and will then be marked as failed.
It is recommended to disable this service:
systemctl disable clamav-clamonacc.service

=== 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 15 main</pre>
* Upgrade the PostgreSQL main cluster from 13 to 15, using <code>pg_upgradecluster</code>
** This step will need some '''time''' and enough '''free disk space''' 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 15 13 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-13 postgresql-client-13</pre>

== After the Proxmox Mail Gateway upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Unmasking & Starting Cluster Services ===

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.
Thus, ensure to read the [https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html upgrade specific issues for Bookworm].

Please also check the known issue list for the Proxmox Mail Gateway 8.X minor releases:
* https://pmg.proxmox.com/wiki/Roadmap#8.0-known-issues

== Breaking Changes ==

* Changed defaults for Bayes and AWL
** Since the two options cause worse results when enabled in most average installations their defaults changed in 8.0, and they are now disabled
*: If your installation explicitly disabled, or enabled the feature nothing will change
*: In case your installation never set the setting the old default will now be written to <code>/etc/pmg/pmg.conf</code> to keep your system consistent.

* The ClamAV antivirus daemon <code>clamav-daemon</code> now uses socket-activation
*: To disable the service you need to disable <code>clamav-daemon.service</code> and <code>clamav-daemon.socket</code>

* Postgresql config change
*: the <code>stats_temp_directory</code> server variable is no longer supported
*: the postgresql.conf template shipped with Proxmox Mail Gateway accounts for the change
*: if you have modified the template (or copied it without modification) in /etc/pmg/templates/ - make sure to remove the line and/or remove the complete template override (if you don't have any modifications)

=== Upgrade wants to remove package 'proxmox-mail-gateway' ===

If you have installed Proxmox Mail Gateway on top of a plain Debian Bookworm (without using the Proxmox Mail Gateway ISO), you may have installed the package 'linux-image-amd64', which conflicts with current 8.x setups. To solve this, you have to remove this package with
apt remove linux-image-amd64
before the dist-upgrade.

== Network ==

=== Network Interface Name Change ===

Due to the new kernel recognizing more features of some hardware, like for example virtual functions, and since interface naming often derives from the PCI(e) address, some NICs may change their name, in which case the network configuration needs to be adapted.

This can also happen in virtualized environments (and has been reported with Xen for this upgrade)

In general, it's recommended to either have an independent remote connection to the Proxmox Mail Gateways's host console, for example, through the hypervisor in case of a VM or container setup, IPMI or iKVM, or physical access for managing the server even
when its own network doesn't come up after a major upgrade or network change.

=== Network Fails on Boot Due to NTPsec Hook ===

Some users reported that after the upgrade their network failed to come up cleanly on boot, but worked if triggered manually (e.g., using <code>ifreload -a</code>), when ntpsec was installed.

We're still investigating for a definitive root cause, but it seems that an udev hook which the <code>/etc/network/if-up.d/ntpsec-ntpdate</code> might hang on some hardware, albeit due to changes not directly related to ntpsec.

The simplest solution might be switching to that via <code>apt install chrony</code>.

== Systemd-boot (for ZFS on root and UEFI systems only) ==

Systems booting via UEFI from a ZFS on root setup should install the <code>systemd-boot</code> package after the upgrade. You will get a Warning from the <code>pmg7to8</code> script after the upgrade if your system is affected - in all other cases you can safely ignore this point.

The <code>systemd-boot</code> was split out from the <code>systemd</code> package for Debian Bookworm based releases. It won't get installed automatically upon upgrade from Proxmox Mail Gateway 7.3 as it can cause trouble on systems not booting from UEFI with ZFS on root setup by the Proxmox Mail Gateway installer.

Systems which have ZFS on root and boot in UEFI mode will need to manually install it if they need to initialize a new ESP (see the output of <code>proxmox-boot-tool status</code>).

Note that the system remains bootable even without the package installed.

It is not recommended installing <code>systemd-boot</code> on systems which don't need it, as it would replace <code>grub</code> as bootloader in its <code>postinst</code> script.

= External links =

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

[[Category: Upgrade]]

Upgrade from 8 to 9

2025-10-23T10:11:52Z

Stoiko Ivanov: /* PostgreSQL */

= Introduction =
Proxmox Mail Gateway 9.x is based on the new major version of Debian (Trixie). 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 Trixie.

In general, there are two ways to upgrade a Proxmox Mail Gateway 8.x system to Proxmox Mail Gateway 9.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 Trixie]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian On top of Debian Trixie]
** 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 these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** If you use SSH, you should use a terminal multiplexer (for example, <code>tmux</code> or <code>screen</code>) to ensure the upgrade can continue even if the SSH connection gets interrupted.
** '''Important''': Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgrade to the latest version of Proxmox Mail Gateway 8.2, see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bookworm repos setup) to upgrade to latest 8.2
** Verify version:
*: You can check the web-interface (reload) at the top, or use <code>pmgversion</code>. Both must show a version with 8.2.5 (or newer), for example something like <code>pmg-api/8.2.5/...</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>.

* Ensure that you have at least 10 GB free disk space on the root mount point:
df -h /
* Check [[#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 ==

First, ensure that your Mail Gateway 8 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.

=== Continuously use the '''pmg8to9''' checklist script ===

A small checklist program named '''<code>pmg8to9</code>''' is included in the latest Proxmox Mail Gateway 8.2 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pmg8to9

; This script only checks and reports things.
: By default, no changes to the system are made and thus, none of the issues will be automatically fixed.
: You should keep in mind that Proxmox Mail Gateway can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

; It is recommended to re-run the script after each attempt to fix an issue.
: This ensures that the actions taken actually fixed the respective warning.

=== 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 ===
First, make sure that the system is using the latest Proxmox Mail Gateway packages:

apt update
apt dist-upgrade
pmgversion -v

The last command should report a version of at least <code>8.2.5</code> or newer.

==== Ensure Repository Archive Keyring is Installed ====

To ensure your system trusts the new APT archive keyring for our Debian Trixie-based releases, install the <code>proxmox-archive-keyring</code> package before switching the repositories to Trixie.

apt install proxmox-archive-keyring

==== Update Debian Base Repositories to Trixie ====
Update all repository entries to Trixie:

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

Ensure that there are no remaining Debian Bookworm specific repositories left. Check all files in the </code>/etc/apt/sources.list.d/</code> folder (like <code>pmg-enterprise.list</code>) and also the top-level <code>/etc/apt/sources.list</code> file. If you are already using sources in the new deb822 format, you will also need to check <code>.sources</code> files in the same location.

{{note|Instead of removing older repositories, you can also disable them. In <code>.list</code> files simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: false</code> to any stanza you want to disable.|reminder}}

See the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories] section in the reference docs for the correct Proxmox Mail Gateway / Debian Trixie repositories.

==== Add the Proxmox Mail Gateway 9 Package Repository ====

Update the enterprise repository to Trixie in the new deb822 format with the following command:

cat > /etc/apt/sources.list.d/pmg-enterprise.sources << EOF
Types: deb
URIs: https://enterprise.proxmox.com/debian/pmg
Suites: trixie
Components: pmg-enterprise
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

After you added the new enterprise repository as above, check that <code>apt</code> picks it up correctly. You can do so by first running <code>apt update</code> followed by <code>apt policy</code>. Make sure that no errors are shown and that <code>apt policy</code> only outputs the desired repositories. Then you can remove the old <code>/etc/apt/sources.list.d/pmg-enterprise.list</code> file. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.

If using the no-subscription repository, see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories]. You should be able to add the Proxmox Mail Gateway 9 no-subscription repository with this command:

cat > /etc/apt/sources.list.d/proxmox.sources << EOF
Types: deb
URIs: http://download.proxmox.com/debian/pmg
Suites: trixie
Components: pmg-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

As with the enterprise repository, make sure that <code>apt</code> picks it up correctly with <code>apt update</code> followed by <code>apt policy</code>. Then remove the previous Proxmox Mail Gateway 8 no-subscription repository from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pmg-install-repo.list</code> or any other <code>.list</code> file you may have added it to. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.

Make sure to check that all the <code>.list</code> files you added in <code>/etc/apt/sources.list.d/</code> got switched over to Trixie correctly.

=== 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 ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth.
A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the upgrade can be finished in less than 5 minutes.

{{Note|While the packages are being upgraded certain operations and requests to the API might fail (for example, logging in as a system user in the <code>pam</code> realm)|reminder}}

apt update
apt dist-upgrade

While running the <code>apt dist-upgrade</code> command, you may be asked to approve changes to configuration files and some service restarts among other prompts. This includes:

* The output of <code>apt-listchanges</code>: You can simply exit it by pressing <kbd>q</kbd>.
* Selecting your default keyboard settings: Simply use the arrow keys to navigate to the one applicable in your case and hit enter.
* Questions about service restarts (like <code>Restart services during package upgrades without asking?</code>): Use the default if unsure, as the reboot after the upgrade will restart all services cleanly anyway.
* Questions about (default) configuration changes: It's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup. Common configuration files with changes, and the recommended choices are:
*; <code>/etc/issue</code>
*: Proxmox Mail Gateway will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.
*; <code>/etc/ssh/sshd_config</code>
*: If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.
*; <code>/etc/clamav/clamd.conf</code> and <code>/etc/clamav/freshclam.conf</code>
*: Those two configuration files are managed by Proxmox Mail Gateway directly, at will be re-generate on any relevant change and on boot.
*: Using the default "No" (keep your currently-installed version) is safe here.
*; <code>/etc/default/grub</code>
*: Here you may want to take special care, as this is normally only asked for if you changed it manually; for example, if you added some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)
*; <code>/etc/postfix/master.cf.proto</code>, <code>/etc/postfix/main.cf.proto</code>
*: These files are not used by Proxmox Mail Gateway - they are the templates for setting up multi-instance postfix instances, which was never used by Proxmox Mail Gateway.
*: See the [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=838528 bugreport at bugs.debian.org] for more context.
*: We recommend to select "Yes" (install the new version), in order to not get asked again for a future upgrade.
*; <code>/etc/crontab</code> and other <code>cron</code> related files on installations on containers on Proxmox VE
*: The crontab gets randomized by Proxmox VE to prevent all jobs running at the same time in all containers.
*: Using the default "No" (keep your currently-installed version) is preferred here.
*; <code>postgresql</code> may print warnings regarding about <code>collation version mismatch</code>
*: These are transitory and will disappear once the cluster has been upgraded to the new version.

'''''Important''''': If configuration templates are used in <code>/etc/pmg/templates</code>, you will see a prompt about the changes in the new version that are not yet incorporated. Review the changes carefully and ensure that only the changes you want are shown in the diff.

It is not yet necessary to reboot your Proxmox Mail Gateway host at this point. Before doing so, first upgrade PostgreSQL database.

=== Upgrade the PostgreSQL database ===

* Upgrade the PostgreSQL main cluster from 15 to 17, using <code>pg_upgradecluster</code>
** Ensure you run this step in a shell, which does not have non-standard locales set. easiest to achieve this is running a fresh <code>su -</code> session and checking that no locale related variables are set to a not installed locale:
su -
env |grep -E 'LC|LANG'
The output should be empty.
** This step will need some '''time''' and enough '''free disk space''' 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 17 15 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 ===

Reboot the host with e command below. Then check the journal to ensure that everything is running correctly again.

reboot

Reconnect to the node after it successfully rebooted.

== After the Proxmox Mail Gateway upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Unmasking & Starting Cluster Services ===

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

=== Remove old PostreSQL Version ===

You can remove the old PostgreSQL version and its data now, if all is working as expected:

apt purge postgresql-15 postgresql-client-15

=== Optional: Modernize apt Repository Sources ===

You can migrate existing repository sources to the recommended deb822 style format, by running:

apt modernize-sources

By answering the following prompt with "n" you can check the changes the command would make before applying them. To apply them simply run the command again and respond to the prompt with "Y".

The command will also keep the old <code>.list</code> files around by appending <code>.bak</code> to them. So you will have the new <code>.sources</code> files and the old repository configurations in the <code>.list.bak</code> files. You can remove the leftover backup files once you verified that everything works smoothly with the new format.

{{note|ensure that all external and third-party repositories (e.g. the one provided by [https://pmg.proxmox.com/wiki/index.php/Install_Avast avast] have provided the keys in the correct places).
|reminder}}

= 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/trixie/release-notes/upgrading.en.html upgrade specific issues for Trixie].

Please also check the known issue list for the Proxmox Mail Gateway 9.X minor releases as this gets updated with future minor releases:
* https://pmg.proxmox.com/wiki/Roadmap#9.0-known-issues

== PostgreSQL ==

=== Setting Locale Failed During Postgres Cluster Upgrade ===

If you are performing the upgrade via SSH (as advised), running <code>pg_upgradecluster -v 17 15 main</code> may fail if your environment variables contain locales that do not exist on your PMG host:
<syntaxhighlight lang="bash">
# [...]
perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
....
Error: The locale requested by the environment is invalid:
...
Error: Could not create target cluster
</syntaxhighlight>

These environment variables may be set automatically depending on your shell's configuration or SSH settings. Most commonly, <code>ssh</code> can pass local environment variables along to your remote host when connecting. See <code>[https://manpages.debian.org/trixie/openssh-client/ssh_config.5.en.html man ssh_config]</code> and <code>[https://manpages.debian.org/trixie/openssh-server/sshd_config.5.en.html man sshd_config]</code> for more information.

To fix this follow the steps in [[#Upgrade_the_PostgreSQL_database|Upgrade the PostgresSQL Cluster]].

== Changed paths for the mobile quarantine interface ==

With the new mobile interface for the quarantine the requests issued when accessing it have changed.
If you have configured a reverse proxy in front of PMG for accessing the quarantine you might need to adapt the configuration.

The necessary changes for <code>nginx</code> were recorded in the [[Quarantine Web Interface Via Nginx Proxy|Quarantine Web Interface Via Nginx Proxy wiki page]],

== Breaking Changes ==

* [https://www.debian.org/releases/trixie/release-notes/issues.en.html#timezones-split-off-into-tzdata-legacy-package Legacy timezones were split off.]
*: This should not be an issue as Proxmox Mail Gateway never offered the deprecated timezones for selection.
*: However, if you've manually configured one such timezone and <code>postgresql</code> does not start, install the <code>tzdata-legacy</code> package.
* The external <code>avast</code> Virus Scanner [https://pmg.proxmox.com/wiki/index.php/Install_Avast with integration in Promxox Mail Gateway] has not yet released a version for Debian Trixie.
*: If you are using it consider delaying the upgrade until it becomes available

=== Upgrade wants to remove package 'proxmox-mail-gateway' ===

If you have installed Proxmox Mail Gateway on top of a plain Debian Trixie (without using the Proxmox Mail Gateway ISO), you may have installed the package <code>linux-image-amd64</code>, which conflicts with current 9.x setups.

To solve this, you have to remove this package with <code>apt remove linux-image-amd64</code> before the dist-upgrade.

== Network ==

=== Network Interface Name Change ===

The new kernel can recognize more hardware features such as virtual function of PCI(e) devices. Since network names are usually derived from PIC(e) addresses and features recognized by the kernel, the network configuration might need to be adapted to match the new interface names.

In such cases, the network connection to a Proxmox Datacenter Manager host might be lost during or after the upgrade process. Hence, it is generally recommended to have either physical access or an independent remote connection to the host (for example, via IPMI or iKVM).

The latest version of Proxmox Mail Gateway 8.2 and 9.0 provide a package called <code>proxmox-network-interface-pinning</code> that you can install.
This package offers a CLI tool that helps you pin all network interfaces to NIC-based names and update the network configuration simultaneously.

== Systemd-boot meta-package changes the bootloader configuration automatically and should be uninstalled ==
With Debian Trixie the <code>systemd-boot</code> package got split up a bit further into <code>systemd-boot-efi</code> (containing the EFI-binary used for booting), <code>systemd-boot-tools</code> (containing <code>bootctl</code>) and the <code>systemd-boot</code> meta-package (containing hooks which run upon upgrades of itself and other packages and install systemd-boot as bootloader).

As Proxmox Systems usually use <code>systemd-boot</code> for booting only in some configurations (ZFS on root and UEFI booted without secure boot), which are managed by <code>proxmox-boot-tool</code>, the meta-package <code>systemd-boot</code> should be removed.

The package was automatically shipped for systems installed from the PMG 8.0 to PMG 8.2 ISOs, as it contained <code>bootctl</code> in bookworm.
If the <code>pmg8to9</code> checklist script suggests it, the <code>systemd-boot</code> meta-package is safe to remove unless you manually installed it and are using <code>systemd-boot</code> as a bootloader. Should <code>systemd-boot-efi</code> and <code>systemd-boot-tools</code> be required, <code>pmg8to9</code> will warn you accordingly.

The <code>pmg8to9</code> checklist script will change its output depending on the state of the upgrade, and should be [[#Continuously_use_the_pmg8to9_checklist_script|run continuously before and after the upgrade]]. It will print which packages should be removed or added at the appropriate time. The only situation where you should keep the meta-package <code>systemd-boot</code> installed is if you manually setup <code>systemd-boot</code> for your system.

See also [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1110177 the filed bug for systemd-boot].

= External links =

[https://www.debian.org/releases/trixie/release-notes/ Release Notes for Debian 13.0 (trixie)]

[[Category: Upgrade]]

Quarantine Web Interface Via Nginx Proxy

2025-10-23T10:06:56Z

Stoiko Ivanov: re-add framework7 to allowed urls until PMG 8.0 is EOL /* Creating a site to proxy requests for quarantine */

== Introduction ==

Proxmox Mail Gateway can be configured to quarantine mail, instead of delivering potentially dangerous content to users directly.
If a mail is detected as spam users themselves can decide whether they want to keep or delete it in the user quarantine interface.
(for dangerous content, as mail containing viruses, or potentially dangerous attachments, the administrator needs to decide whether
to pass the mail on or delete it).

In certain environments it is desired to provide the user quarantine interface at a specific host and port,
e.g. in order to only allow access to the interface from outside on port 443, or to provide a different and
trusted certificate to your users.

The following Howto describes a small nginx configuration, which only exposes the paths necessary for user quarantine interface access,
while preventing access to other parts of the API.

Keep in mind that this provides mostly cosmetic protection, since all paths in the Proxmox Mail Gateway API, apart from the login path
are only available to authenticated users anyways. The unprotected login path needs to be forwarded for the quarantine access as well.

For creating a general reverse proxy for the complete web interface refer to the [https://pve.proxmox.com/wiki/Web_Interface_Via_Nginx_Proxy Howto in the Proxmox VE wiki].

== Installing nginx ==

The Howto creates a configuration suitable for nginx. You can install nginx on your Proxmox Mail Gateway using <nowiki>apt</nowiki>
apt install nginx

== Creating a site to proxy requests for quarantine ==

The following configuration is a minimal working nginx-site to proxy all requests necessary for accessing the quarantine interface for users.
You should adapt it to your site's requirements. This includes:
* changing the path to the used certificates
* setting the proper <code>server_name</code>
* adapting the ssl-configuration parameters to current best practices
* if the proxy server is running directly on PMG:
** you probably want to disable the <code>default</code> site configuration <code>/etc/nginx/sites-enabled/default</code>.
** if you're using the integrated ACME implementation with the standalone plugin you need to remove the server on port 80 below, since the ACME implementation needs to bind to it during certificate renewal
* if the proxy server is running on another host adapting the url for the <code>proxy_pass</code> directives
* You will also need to adapt the settings in the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmgconfig_spamdetector_quarantine Spam Detector Quarantine Options in the PMG GUI] to reflect the hostname and port of the proxy.

To get the site running write the config to <code>/etc/nginx/sites-available/pmg-quarantine.conf</code> and symlink it to <code>/etc/nginx/sites-enabled</code>:
ln -rs /etc/nginx/sites-available/pmg-quarantine.conf /etc/nginx/sites-enabled/

<nowiki>
server {
listen 80 default_server;
rewrite ^(.*) https://$host$1 permanent;
}

server {
listen 443 ssl;
server_name _;
ssl_certificate /etc/pmg/pmg-api.pem;
ssl_certificate_key /etc/pmg/pmg-api.pem;
proxy_redirect off;

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header PVEClientIP $remote_addr;
proxy_buffering off;
client_max_body_size 0;
proxy_connect_timeout 3600s;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
send_timeout 3600s;

# proxy requests for static components
location ~ /proxmoxlib.js$|/favicon.ico$|/pve2/|/fontawesome/|/framework7|/pwt|/mobile {
proxy_pass https://localhost:8006;
}
location /quarantine {
proxy_pass https://localhost:8006;
}

location /api2 {
location ~ /api2/(extjs|json|htmlmail)/(access/ticket$|version$) {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/nodes/.+/subscription$ {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/quarantine {
proxy_pass https://localhost:8006;
}
return 403;
}

location / {
return 403;
}
}
</nowiki>

Quarantine Web Interface Via Nginx Proxy

2025-10-23T09:45:59Z

Stoiko Ivanov: adapt to nginx config to new yew based mobile gui /* Creating a site to proxy requests for quarantine */

== Introduction ==

Proxmox Mail Gateway can be configured to quarantine mail, instead of delivering potentially dangerous content to users directly.
If a mail is detected as spam users themselves can decide whether they want to keep or delete it in the user quarantine interface.
(for dangerous content, as mail containing viruses, or potentially dangerous attachments, the administrator needs to decide whether
to pass the mail on or delete it).

In certain environments it is desired to provide the user quarantine interface at a specific host and port,
e.g. in order to only allow access to the interface from outside on port 443, or to provide a different and
trusted certificate to your users.

The following Howto describes a small nginx configuration, which only exposes the paths necessary for user quarantine interface access,
while preventing access to other parts of the API.

Keep in mind that this provides mostly cosmetic protection, since all paths in the Proxmox Mail Gateway API, apart from the login path
are only available to authenticated users anyways. The unprotected login path needs to be forwarded for the quarantine access as well.

For creating a general reverse proxy for the complete web interface refer to the [https://pve.proxmox.com/wiki/Web_Interface_Via_Nginx_Proxy Howto in the Proxmox VE wiki].

== Installing nginx ==

The Howto creates a configuration suitable for nginx. You can install nginx on your Proxmox Mail Gateway using <nowiki>apt</nowiki>
apt install nginx

== Creating a site to proxy requests for quarantine ==

The following configuration is a minimal working nginx-site to proxy all requests necessary for accessing the quarantine interface for users.
You should adapt it to your site's requirements. This includes:
* changing the path to the used certificates
* setting the proper <code>server_name</code>
* adapting the ssl-configuration parameters to current best practices
* if the proxy server is running directly on PMG:
** you probably want to disable the <code>default</code> site configuration <code>/etc/nginx/sites-enabled/default</code>.
** if you're using the integrated ACME implementation with the standalone plugin you need to remove the server on port 80 below, since the ACME implementation needs to bind to it during certificate renewal
* if the proxy server is running on another host adapting the url for the <code>proxy_pass</code> directives
* You will also need to adapt the settings in the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmgconfig_spamdetector_quarantine Spam Detector Quarantine Options in the PMG GUI] to reflect the hostname and port of the proxy.

To get the site running write the config to <code>/etc/nginx/sites-available/pmg-quarantine.conf</code> and symlink it to <code>/etc/nginx/sites-enabled</code>:
ln -rs /etc/nginx/sites-available/pmg-quarantine.conf /etc/nginx/sites-enabled/

<nowiki>
server {
listen 80 default_server;
rewrite ^(.*) https://$host$1 permanent;
}

server {
listen 443 ssl;
server_name _;
ssl_certificate /etc/pmg/pmg-api.pem;
ssl_certificate_key /etc/pmg/pmg-api.pem;
proxy_redirect off;

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header PVEClientIP $remote_addr;
proxy_buffering off;
client_max_body_size 0;
proxy_connect_timeout 3600s;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
send_timeout 3600s;

# proxy requests for static components
location ~ /proxmoxlib.js$|/favicon.ico$|/pve2/|/fontawesome/|/pwt|/mobile {
proxy_pass https://localhost:8006;
}
location /quarantine {
proxy_pass https://localhost:8006;
}

location /api2 {
location ~ /api2/(extjs|json|htmlmail)/(access/ticket$|version$) {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/nodes/.+/subscription$ {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/quarantine {
proxy_pass https://localhost:8006;
}
return 403;
}

location / {
return 403;
}
}
</nowiki>

Roadmap

2025-10-01T14:37:09Z

Stoiko Ivanov: /* Fresh installation from the Proxmox VE container template does not work with dhcp as network configuration */

<div class="toclimit-3">__TOC__</div>

=Roadmap=
*<s>SpamAssassin 4</s> done
*Continuous security and bug fix updates
=Release History=
See also [https://forum.proxmox.com/forums/announcements.7/ Announcement forum]

== Proxmox Mail Gateway 9.0 ==
'''Released 01. October 2025'''

* Based on Debian Trixie (13.1)
* SpamAssassin 4.0.2 (with updated rulesets)
* ClamAV 1.4.3
* PostgreSQL 17
* Latest 6.14.11-2 Kernel as new stable default
* ZFS 2.3.4

=== Highlights ===

* New major release based on the great Debian Trixie.
* New Quarantine UI on mobile browsers based on the modern Rust-based Yew framework.
* Seamless upgrade from Proxmox Mail Gateway 8.2, see [[Upgrade from 8 to 9]]
* Single-Sign-On (SSO) with OpenID Connect, and multiple authentication realms for PMG: These were introduced with PMG 8.2 and were since significantly improved based on the feedback from our customers and community.
* Synchronize the configuration templates of the core service <code>postfix</code> with the latest recommendations from upstream.
* Adapt the Content-Type filters to the renaming of relevant MIME-types for Microsoft executable formats.

=== Changelog Overview ===

==== Enhancements in the Web Interface (GUI) ====
* New Quarantine UI on mobile browers based on the Rust based Yew framework, in place of the one based on framework7.
* The non-mobile Quarantine UI offers a button to switch to the mobile version and recommends switching on displays which are too narrow for comfortable work with it.
* An XSS vulnerability for the HTTP proxy setting was fixed. See the corresponding Proxmox Security Advisory [https://forum.proxmox.com/threads/proxmox-mail-gateway-security-advisories.149333/post-798035 PSA-2025-00015-1] for further information.
* It is now possible to define an authentication realm as default instead of the hard-coded internal <code>pmg</code> realm.
* OpenID Connect realms can now be configured in the GUI, including the <code>username-claim</code>, and the default role to be assigned to auto-created users.
* All labels and widgets containing the terms "blacklist" and "whitelist" were renamed to "blocklist" and "welcomelist," respectively ([https://bugzilla.proxmox.com/show_bug.cgi?id=3755 issue 3755]).
* Allow selecting multiple mails in the <code>postfix</code> queue administration widget for delivery or deletion ([https://bugzilla.proxmox.com/show_bug.cgi?id=3450 issue 3450]).
* Improve the configuration and display of DNSBL sites in the Mail Proxy (<code>postscreen_dnsbl_sites</code>)([https://bugzilla.proxmox.com/show_bug.cgi?id=3284 issue 3284]).
* Make the SpamInfo text selectable in the Spam Quarantine interface.
* Improved handling of translations:
** Add support for plural forms and ngettext usage.
** Translations can now contain comments that are extracted from the source code and provide useful context for translators.
* Updated translations, among others:
** Czech (new!)
** Arabic
** Bulgarian
** French
** German
** Italian
** Japanese
** Korean
** Polish
** Russian
** Simplified Chinese
** Spanish
** Swedish
** Traditional Chinese
** Ukrainian

==== Enhancements in the Mail Gateway API Backend ====

* Improvements of OpenID Connect realms, which were introduced in Proxmox Mail Gateway 8.2:
** Fix an error when logging in the first time to a secondary node as a user in an OIDC realm with enabled auto-creation.
** The validation for OIDC <code>client-id</code> and <code>client-key</code> was aligned with the [https://www.rfc-editor.org/rfc/rfc6749#appendix-A relevant RFC].
** The <code>pmg</code> realm is not hard-coded as the default realm anymore, allowing to select a different default realm.
* The <code>pmgqm</code> utility used for sending spam reports to users now supports timespans between 1 and 24 hours in addition to <code>today</code>,<code>yesterday</code> and <code>week</code>([https://bugzilla.proxmox.com/show_bug.cgi?id=2452 issue 2452]).
* Fix an issue where a disallowed value for the Destination TLS policy was accepted by the backend.
* Leading and trailing whitespace in the <code>__MSGID__</code> macro in the rule system (containing the <code>Message-ID</code> header) is now trimmed.
* The TLS-inbound domains are now added to the Proxmox Mail Gateway system report used in Enterprise support.
* Mails generated by Proxmox Mail Gateway now have a <code>Date</code> header allowing them to have a valid DKIM signature.
* The Date header for autogenerated mails is set with a fixed locale to have it compliant with [https://www.rfc-editor.org/rfc/rfc5322 RFC5322].
* An issue of <code>pmgtunnel</code> exiting with errors due to not correctly adapting to changes in the network information parsing code was repaired by fixing its handling of child processes.
* With the upgrade to Debian Trixie, the <code>application/x-ms-dos-executable</code> MIME-Type was renamed to <code>application/vnd.microsoft.portable-executable</code> and <code>application/x-msdownload</code>. As <code>exe</code> files are filtered out in the default ruleset and are usually considered special when handling mails, the existing rules are automatically adapted.
* The <code>postfix</code> MTA package used by PMG was significantly reworked and improved upstream. PMG was adapted to the changes:
** <code>postfix</code> is now explicitly configured to run without <code>chroot</code> confinement ([https://bugzilla.proxmox.com/show_bug.cgi?id=5323 issue 5323]).
*: The processes were running without <code>chroot</code> since version 5.0, the change now is only making this explicit in the configuration files.
*: The change is in accordance with [https://salsa.debian.org/postfix-team/postfix-dev/-/blob/debian/master/debian/README.Debian?ref_type=heads#L44 Debian's recommendation] and in line with [https://www.postfix.org/COMPATIBILITY_README.html#chroot upstream].
** The <code>postfix@-</code> default instance was dropped in favor of directly using <code>postfix</code>
** Deprecations in the shipped postfix configuration templates were fixed, and the [https://www.postfix.org/COMPATIBILITY_README.html compatibility level] was raised to 3.11.
* The Debian repository sources shipped for the <code>pmg-enterprise</code> repository were adapted to the preferred Deb822 format.
* A change in the upstream <code>clamav-freshclam</code> package caused the daemon not to be enabled automatically since PMG 8.1. Now the <code>pmg-api</code> package enables the service in its <code>postinst</code> maintainer script.
* The <code>pmgproxy</code> and <code>pmgdaemon</code> HTTP API servers were adapted to the paths used by the new Yew-based mobile quarantine UI.
* The locale files served by the HTTP API servers now return their modification times to facilitate caching.
* Spam reports send to users and the system status report sent to administrators now have a <code>text/plain</code> version in addition to <code>text/html</code>([https://bugzilla.proxmox.com/show_bug.cgi?id=4023 issue 4023]) ([https://bugzilla.proxmox.com/show_bug.cgi?id=1621 issue 1621]).
* Adding a custom ACME provider via the <code>pmgconfig</code> command line utility was fixed for Proxmox Mail Gateway ([https://bugzilla.proxmox.com/show_bug.cgi?id=6748 issue 6748]).
* Improvements to handling external mail-sources via <code>fetchmail</code>:
** <code>fetchmail</code> changed the semantics of TLS related parameters in version <code>6.4.0</code>. The issue of not being able to connect to a system via plaintext session without StartTLS/implicit TLS was fixed ([https://bugzilla.proxmox.com/show_bug.cgi?id=6798 issue 6798]).
** Changing the configuration of <code>fetchmail</code> accounts now triggers a restart of the <code>fetchmail</code> daemon, resulting in the changes being live directly.
** The <code>fetchmail</code> package used for downloading mails via POP/IMAP to be processed by Proxmox Mail Gateway now ships a systemd-unit file instead of a legacy sysv-init script. This is a change to Debian upstream's version.
* Fix a spurious warning by the <code>pmgproxy</code> API server daemon, when sending a <code>Cookie</code> header without a valid authentication ticket.
* Fix a spurious warning during early boot due to <code>/run/pmg-smtp-filter.cfg</code> not being in place yet.
* Ensure the <code>pmgspamreport.timer</code> and <code>pmgreport.timer</code> units are run after their prerequisites have started on reboot
* Allow all <code>admin</code> users to see the list of known MIME-Types, when adding ContentType filter objects ([https://bugzilla.proxmox.com/show_bug.cgi?id=5438 issue 5438]).
* Allow providing a list of <code>postfix</code> queue-ids and action (<code>deliver,delete</code>) to the <code>/nodes/{node}/postfix/queue/{queue}</code> to delete or flush multiple mails at once ([https://bugzilla.proxmox.com/show_bug.cgi?id=3450 issue 3450]).

==== Installation ISO ====

* Install the microcode package matching the current platform.
*: This ensures that new Proxmox Mail Gateway installations get available fixes for CPU security issues and other CPU bugs.
*: This also means that installations now have the <code>non-free-firmware</code> repository enabled.
*: To get microcode updates that were released after the ISO was built, hosts have to be updated regularly. Microcode updates need a reboot to go into effect.
* Ignore network interfaces without a valid MAC address instead of aborting the installation.
* Check that the configured LVM swapsize is not greater than half the disk size ([https://bugzilla.proxmox.com/show_bug.cgi?id=5887 issue 5887]).
* Handle the case where the DHCP lease includes the search domain in the Host Name option.
* Improve error reporting for disk and RAID checks.
* Improvements to the text-based installer and <code>proxmox-auto-install-assistant</code>:
** Improve error reporting when encountering an invalid CIDR.
** Add plausibility checks for subnet masks and IPv4 address.
* Improvements to the automated installation:
** Handle the case where the answer file provides an empty search domain.
** Check the number of disks for RAID configurations already when parsing the answer file to catch invalid configurations earlier.
** Warn if the answer file contains deprecated <code>snake_case</code> keys.
** Check for duplicate disks in the answer file.
* Improve robustness of installing on Btrfs.
* Align the plausibility checks performed by the GUI and TUI installers in case of an installation on Btrfs and a single disk.
* Improve the visibility of CLI errors by printing an additional newline.
* Provide <code>--verify-root-password</code> as option for <code>proxmox-auto-install-assistant</code>, to catch mistakes before installation.
* Set the <code>postfix</code> compatibility level to <code>3.6</code> for all products.
*: Note that this affects all products **apart from Proxmox Mail Gateway**, which sets it to <code>3.11</code> through the templating system.
* The timezone is now set earlier before configuring <code>postfix</code> to ensure it's set correctly if <code>postfix</code> runs in <code>chroot</code>.
*: Note that this affects all products **apart from Proxmox Mail Gateway**, which runs <code>postfix</code> without <code>chroot</code>.
* Do not create the deprecated <code>/etc/timezone</code> in alignment with [https://metadata.ftp-master.debian.org/changelogs//main/t/tzdata/tzdata_2025b-4_changelog Debian upstream].
* Ensure that <code>clamav-freshclam</code> is enabled after installation - see the [https://salsa.debian.org/clamav-team/clamav/-/merge_requests/7 patch submitted upstream for more information].

==== Notable changes ====

<div id="9.0-known-issues"></div>

=== Known Issues & Breaking Changes ===

==== The Test Repository Is Now Named pmg-test ====

For consistency with existing repositories, the <code>pmgtest</code> repository is now spelled <code>pmg-test</code>.

==== Breaking Changes in the Proxmox Mail Gateway API ====

* The "Google Safe Browsing" option for <code>ClamAV</code>, which is deprecated since PMG 7.0, in <code>pmg.conf</code> was dropped.
* The superfluous fields <code>network_address</code> and <code>prefix_size</code> returned by the <code>/config/mynetworks</code> API call were dropped, as <code>cidr</code> contains the same information.
* The <code>ReportSpam</code>, <code>Attach</code>, and <code>Counter</code> actions, which were not exposed since at least PMG 5.0, and deprecated in PMG 7.2, were dropped from the database handling code.
* Changing the password of a user via <code>PUT /access/users/{userid}</code> has been dropped in favor of the <code>/access/password</code> API call. The GUI is using <code>/access/password</code> since at least 2017.
* Adding and removing entries in the block- and welcomelists of users are now done by the master node in a cluster ([https://bugzilla.proxmox.com/show_bug.cgi?id=4392 issue 4392]).
* The API has renamed all black-/whitelist API calls to block-/welcomelist respectively ([https://bugzilla.proxmox.com/show_bug.cgi?id=3755 issue 3755]).
*: The old API calls are still present for backward compatibility but will be dropped with the next major release.
*: As these calls were also used in the templates for the spamreport e-mails sent to users, which are often modified by administrators, we recommend adapting your overridden configuration templates.
* The <code>pmail_raw</code> variable available to the template for the spam reports sent to users has been renamed to <code>pmail_plain</code> to match the other variables formatted for plain-text reports.
*: This variable was never used by a template shipped by Promxox Mail Gateway, thus it is very unlikely to have been used in a modification.

==== Potential changes in network interface names ====

Proxmox Mail Gateway 9 can now transparently handle many network interface name changes.

These changes may occur when upgrading from Proxmox Mail Gateway 8.x to Proxmox Mail Gateway 9.0 due to new naming scheme policies or the added support for new NIC features. For example, this may happen when upgrading from Kernel 6.8 to Kernel 6.14.
If the previous primary name remains available as an alternative name, manual intervention may not be necessary since Proxmox Mail Gateway 9.0 allows the use of alternative names in network configurations and firewall rules.

However, in some cases, the previous primary name might not be available as an alternative name after the upgrade. In such cases, manual reconfiguration after the upgrade is currently still necessary.

Before upgrading, you can use the <code>proxmox-network-interface-pinning</code> CLI tool to pin network interfaces to custom names.
For details, see the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_overriding_network_device_names Overriding Network Device Names] section in the reference documentation.

==== AppArmor 4 ====

Proxmox Mail Gateway 9 ships with AppArmor version 4.1.
Since this version is relatively new, you might see regressions in packages, for example <code>clamav</code>, or software that is not part of the core Proxmox Mail Gateway distribution, for example the CUPS printing daemon.

Most issues with older profiles can be resolved by configuring AppArmor to use the 3.0 ABI by adding the <code>abi <abi/3.0>,</code> rule to the relevant profile.
For more details, see the [https://gitlab.com/apparmor/apparmor/-/wikis/apparmorpolicyfeaturesABI AppArmor Wiki].

==== systemd logs "System is tainted: unmerged-bin" after boot ====

It is recommended to ignore this message. See the [https://www.debian.org/releases/trixie/release-notes/issues.en.html#systemd-message-system-is-tainted-unmerged-bin Debian Trixie release notes] for more details.

== Proxmox Mail Gateway 9.0 BETA ==
'''Released 24. September 2025'''

{{Note|This is a test version that is not yet intended for production use. The release notes will be continuously updated during the beta phase.}}

* Based on Debian Trixie (13.1)
* SpamAssassin 4.0.2 (with updated rulesets)
* ClamAV 1.4.3
* PostgreSQL 17
* Latest 6.14.11-2 Kernel as new stable default
* ZFS 2.3.4

=== Highlights ===

* New major release based on the great Debian Trixie.
* New Quarantine UI on mobile browsers based on the modern Rust-based Yew framework.
* Seamless upgrade from Proxmox Mail Gateway 8.2, see [[Upgrade from 8 to 9]]
* Single-Sign-On (SSO) with OpenID Connect, and multiple authentication realms for PMG, which were introduced with PMG 8.2 got significantly improved based on the feedback from our customers and community.
* Synchronize the configuration templates of the core service <code>postfix</code> with the latest recommendations from upstream.
* Adapt the Content-Type filters to the renaming of relevant MIME-types for Microsoft executable formats.

=== Changelog Overview ===

<div id="9.0-rule-system-enhancements"></div>
==== Enhancements in the Rule System ====

==== Enhancements in the Web Interface (GUI) ====
* New Quarantine UI on mobile browers based on the Rust based Yew framework, in place of the one based on framework7.
* The non-mobile Quarantine UI offers a button to switch to the mobile version and recommends switching on displays which are too narrow for comfortable work with it.
* An XSS vulnerability for the HTTP proxy setting was fixed. See the corresponding Proxmox Security Advisory [https://forum.proxmox.com/threads/proxmox-mail-gateway-security-advisories.149333/post-798035 PSA-2025-00015-1] for further information.
* It is now possible to define an authentication realm as default instead of the hard-coded internal <code>pmg</code> realm.
* OpenID Connect realms can now be configured in the GUI, including the <code>username-claim</code>, and the default role to be assigned to auto-created users.
* All labels and widgets containing the terms "blacklist" and "whitelist" were renamed to "blocklist" and "welcomelist," respectively ([https://bugzilla.proxmox.com/show_bug.cgi?id=3755 issue 3755]).
* Improve the configuration and display of DNSBL sites in the Mail Proxy (<code>postscreen_dnsbl_sites</code>)([https://bugzilla.proxmox.com/show_bug.cgi?id=3284 issue 3284]).
* Make the SpamInfo text selectable in the Spam Quarantine interface.
* Improved handling of translations:
** Add support for plural forms and ngettext usage.
** Translations can now contain comments that are extracted from the source code and provide useful context for translators.
* Updated translations, among others:
** Czech (new!)
** Arabic
** Bulgarian
** French
** German
** Italian
** Japanese
** Korean
** Polish
** Russian
** Simplified Chinese
** Spanish
** Swedish
** Traditional Chinese
** Ukrainian

==== Enhancements in the Mail Gateway API Backend ====

* Improvements of OpenID Connect realms, which were introduced in Proxmox Mail Gateway 8.2:
** Fix an error when logging in the first time to a secondary node as a user in an OIDC realm with enabled auto-creation.
** The validation for OIDC <code>client-id</code> and <code>client-key</code> was aligned with the [https://www.rfc-editor.org/rfc/rfc6749#appendix-A relevant RFC].
** The <code>pmg</code> realm is not hardcoded as the default realm anymore, allowing to select a different default realm.
* The <code>pmgqm</code> utility used for sending spam reports to users now supports timespans between 1 and 24 hours in addition to <code>today</code>,<code>yesterday</code> and <code>week</code>([https://bugzilla.proxmox.com/show_bug.cgi?id=2452 issue 2452]).
* Fix an issue where a disallowed value for the Destination TLS policy was accepted by the backend.
* Leading and trailing whitespace in the <code>__MSGID__</code> macro in the rule system (containing the <code>Message-ID</code> header) is now trimmed.
* The TLS-inbound domains are now added to the Proxmox Mail Gateway system report used in Enterprise support.
* Mails generated by Proxmox Mail Gateway now have a <code>Date</code> header allowing them to have a valid DKIM signature.
* The Date header for autogenerated mails is set with a fixed locale to have it compliant with [https://www.rfc-editor.org/rfc/rfc5322 RFC5322].
* An issue of <code>pmgtunnel</code> exiting with errors due to not correctly adapting to changes in the network information parsing code was repaired by fixing its handling of child processes.
* With the upgrade to Debian Trixie, the <code>application/x-ms-dos-executable</code> MIME-Type was renamed to <code>application/vnd.microsoft.portable-executable</code> and <code>application/x-msdownload</code>. As <code>exe</code> files are filtered out in the default ruleset and are usually considered special when handling mails, the existing rules are automatically adapted.
* The <code>postfix</code> MTA package used by PMG was significantly reworked and improved upstream. PMG was adapted to the changes:
** <code>postfix</code> is now explicitly configured to run without <code>chroot</code> confinement ([https://bugzilla.proxmox.com/show_bug.cgi?id=5323 issue 5323]).
*: The processes were running without <code>chroot</code> since version 5.0, the change now is only making this explicit in the configuration files.
*: The change is in accordance with [https://salsa.debian.org/postfix-team/postfix-dev/-/blob/debian/master/debian/README.Debian?ref_type=heads#L44 Debian's recommendation] and in line with [https://www.postfix.org/COMPATIBILITY_README.html#chroot upstream].
** The <code>postfix@-</code> default instance was dropped in favor of directly using <code>postfix</code>
** Deprecations in the shipped postfix configuration templates were fixed, and the [https://www.postfix.org/COMPATIBILITY_README.html compatibility level] was raised to 3.11.
* The Debian repository sources shipped for the <code>pmg-enterprise</code> repository were adapted to the preferred Deb822 format.
* A change in the upstream <code>clamav-freshclam</code> package caused the daemon not to be enabled automatically since PMG 8.1. Now the <code>pmg-api</code> package enables the service in its <code>postinst</code> maintainer script.
* The <code>pmgproxy</code> and <code>pmgdaemon</code> HTTP API servers were adapted to the paths used by the new Yew-based mobile quarantine UI.
* The locale files served by the HTTP API servers now return their modification times to facilitate caching.
* Spamreports send to users and the system status report sent to administrators now have a <code>text/plain</code> version in addition to <code>text/html</code>([https://bugzilla.proxmox.com/show_bug.cgi?id=4023 issue 4023]) ([https://bugzilla.proxmox.com/show_bug.cgi?id=1621 issue 1621]).
* Adding a custom ACME provider via the <code>pmgconfig</code> command line utility was fixed for Proxmox Mail Gateway ([https://bugzilla.proxmox.com/show_bug.cgi?id=6748 issue 6748]).
* The <code>fetchmail</code> package used for downloading mails via POP/IMAP to be processed by Proxmox Mail Gateway now ships a systemd-unit file instead of a legacy sysv-init script. This is a change to Debian upstream's version.
* Fix a spurious warning by the <code>pmgproxy</code> API server daemon, when sending a <code>Cookie</code> header without a valid authentication ticket.
* Fix a spurious warning during early boot due to <code>/run/pmg-smtp-filter.cfg</code> not being in place yet.
* Ensure the <code>pmgspamreport.timer</code> and <code>pmgreport.timer</code> units are run after their prerequisites have started on reboot
* Allow all <code>admin</code> users to see the list of known MIME-Types, when adding ContentType filter objects ([https://bugzilla.proxmox.com/show_bug.cgi?id=5438 issue 5438]).

==== Installation ISO ====

* Install the microcode package matching the current platform.
*: This ensures that new Proxmox Mail Gateway installations get available fixes for CPU security issues and other CPU bugs.
*: This also means that installations now have the <code>non-free-firmware</code> repository enabled.
*: To get microcode updates that were released after the ISO was built, hosts have to be updated regularly. Microcode updates need a reboot to go into effect.
* Ignore network interfaces without a valid MAC address instead of aborting the installation.
* Check that the configured LVM swapsize is not greater than half the disk size ([https://bugzilla.proxmox.com/show_bug.cgi?id=5887 issue 5887]).
* Handle the case where the DHCP lease includes the search domain in the Host Name option.
* Improve error reporting for disk and RAID checks.
* Improvements to the text-based installer and <code>proxmox-auto-install-assistant</code>:
** Improve error reporting when encountering an invalid CIDR.
** Add plausibility checks for subnet masks and IPv4 address
* Improvements to the automated installation:
** Handle the case where the answer file provides an empty search domain.
** Check the number of disks for RAID configurations already when parsing the answer file to catch invalid configurations earlier.
** Warn if the answer file contains deprecated <code>snake_case</code> keys.
** Check for duplicate disks in the answer file.
* Improve robustness of installing on Btrfs.
* Align the plausibility checks performed by the GUI and TUI installers in case of an installation on Btrfs and a single disk.
* Improve the visibility of CLI errors by printing an additional newline.
* Provide <code>--verify-root-password</code> as option for <code>proxmox-auto-install-assistant</code>, to catch mistakes before installation.
* Set the <code>postfix</code> compatibility level to <code>3.6</code> for all products
* The timezone is now set earlier before configuring <code>postfix</code> to ensure it's set correctly if <code>postfix</code> runs in <code>chroot</code>.
*: Note that this affects all products **apart from Proxmox Mail Gateway**, which runs <code>postfix</code> without <code>chroot</code>
* Do not create the deprecated <code>/etc/timezone</code> in alignment with [https://metadata.ftp-master.debian.org/changelogs//main/t/tzdata/tzdata_2025b-4_changelog Debian upstream].
* Ensure that <code>clamav-freshclam</code> is enabled after installation - see the [https://salsa.debian.org/clamav-team/clamav/-/merge_requests/7 patch submitted upstream for more information].

==== Notable changes ====

<div id="9.0-known-issues"></div>

=== Known Issues & Breaking Changes ===

==== The Test Repository Is Now Named pmg-test ====

For consistency with existing repositories, the <code>pmgtest</code> repository is now spelled <code>pmg-test</code>.

==== Breaking Changes in the Proxmox Mail Gateway API ====

* The "Google Safe Browsing" option for <code>ClamAV</code>, which is deprecated since PMG 7.0, in <code>pmg.conf</code> was dropped.
* The superfluous fields <code>network_address</code> and <code>prefix_size</code> returned by the <code>/config/mynetworks</code> API call were dropped, as <code>cidr</code> contains the same information.
* The <code>ReportSpam</code>, <code>Attach</code>, <code>Counter</code> actions, which were not exposed since at least PMG 5.0, and deprecated in PMG 7.2, were dropped from the database handling code.
* Changing the password of a user via <code>PUT /access/users/{userid}</code> has been dropped in favor of the <code>/access/password</code> API call. The GUI is using <code>/access/password</code> since at least 2017.
* Adding and removing entries in the block- and welcomelists of users are now done by the master node in a cluster ([https://bugzilla.proxmox.com/show_bug.cgi?id=4392 issue 4392]).
* The API has renamed all black-/whitelist API calls to block-/welcomelist respectively ([https://bugzilla.proxmox.com/show_bug.cgi?id=3755 issue 3755]).
*: The old API calls are still present for backward compatibility but will be dropped with the next major release.
*: As these calls were also used in the templates for the spamreport e-mails sent to users, which are often modified by administrators, we recommend adapting your overridden configuration templates.
* The <code>pmail_raw</code> variable available to the template for the spam reports sent to users has been renamed to <code>pmail_plain</code> to match the other variables formatted for plain-text reports.
*: This variable was never used by a templated shipped by Promxox Mail Gateway, thus it is very unlikely to have been used in a modification.

==== Potential changes in network interface names ====

Proxmox Mail Gateway 9 can now transparently handle many network interface name changes.

These changes may occur when upgrading from Proxmox Mail Gateway 8.x to Proxmox Mail Gateway 9.0 due to new naming scheme policies or the added support for new NIC features. For example, this may happen when upgrading from Kernel 6.8 to Kernel 6.14.
If the previous primary name remains available as an alternative name, manual intervention may not be necessary since Proxmox Mail Gateway 9.0 allows the use of alternative names in network configurations and firewall rules.

However, in some cases, the previous primary name might not be available as an alternative name after the upgrade. In such cases, manual reconfiguration after the upgrade is currently still necessary.

Before upgrading, you can use the <code>pve-network-interface-pinning</code> CLI tool to pin network interfaces to custom names.
For details, see the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_overriding_network_device_names Overriding Network Device Names] section in the reference documentation.

==== AppArmor 4 ====

Proxmox Mail Gateway 9 ships with AppArmor version 4.1.
Since this version is relatively new, you might see regressions in packages that are not part of the core Proxmox Mail Gateway distribution, for example, <code>clamav</code> or the CUPS printing daemon.

Most issues with older profiles can be resolved by configuring AppArmor to use the 3.0 ABI by adding the <code>abi <abi/3.0>,</code> rule to the relevant profile.
For more details, see the [https://gitlab.com/apparmor/apparmor/-/wikis/apparmorpolicyfeaturesABI AppArmor Wiki].

==== systemd logs "System is tainted: unmerged-bin" after boot ====

It is recommended to ignore this message. See the [https://www.debian.org/releases/trixie/release-notes/issues.en.html#systemd-message-system-is-tainted-unmerged-bin Debian Trixie release notes] for more details.

== Proxmox Mail Gateway 8.2 ==
'''Released 27. February 2025'''

* Based on Debian Bookworm (12.9)
* SpamAssassin 4.0.1 (with updated rulesets)
* ClamAV 1.0.7
* PostgreSQL 15.11
* Latest 6.8 Kernel as new stable default
* Newer 6.11 Kernel as opt-in
* ZFS 2.2.7

=== Highlights ===

* Support for multiple authentication realms, known from Proxmox VE and Proxmox Backup Server.
* Single-Sign-On (SSO) with the new OpenID Connect access realm type as first new realm.
*: External authorization servers can now be integrated for management access with Proxmox Mail Gateway, either using existing public services or your own identity and access management solution, for example, Keycloak, Zitadel or LemonLDAP::NG.
* Support for automated and unattended installation of Proxmox Mail Gateway.
*: Proxmox VE now ships a tool that prepares a Proxmox Mail Gateway ISO for automated installation.
*: The prepared ISO retrieves all required settings for automated installation from an answer file.
*: The answer file can be provided directly in the ISO, on an additional disk such as a USB flash drive, or over the network.
* Rule System: New option for the Content-Type What Objects, to ignore externally provided type information from the filename and header, and rely solely on file signature based detection.
* Rule System: New option for Match Field What Object, to restrict matching on the top header section, instead of also matching headers in attached emails.
* Mails generated by the Proxmox Mail Gateway processing stack can now be signed with DKIM.
* The Proxmox team has been tracking security-relevant issues in our software explicitly and publishes them in the [https://forum.proxmox.com/threads/149333/ Community Forum] since January 2024.
* Seamless upgrade from Proxmox Mail Gateway 7.3, see [https://pmg.proxmox.com/wiki/index.php/Upgrade_from_7_to_8 Upgrade from 7 to 8].

=== Changelog Overview ===

<div id="8.2-rule-system-enhancements"></div>
==== Enhancements in the Rule System ====
* Add an option to the Match Field What Object to only consider the headers of the top mail-part, instead of also comparing the headers of all attachments (including emails forwarded as attachment [https://bugzilla.proxmox.com/show_bug.cgi?id=2709 issue 2709]).
* Optionally restrict Content-Type What Object to only match based on the signature detected in the content of the file, disregarding the <code>Content-Type:</code> and the recommended filename header information ([https://bugzilla.proxmox.com/show_bug.cgi?id=2691 issue 2691] [https://bugzilla.proxmox.com/show_bug.cgi?id=5618 issue 5618]).

==== Enhancements in the Web Interface (GUI) ====
* The end-user quarantine interface now has a short help page explaining its purpose and the available keyboard shortcuts ([https://bugzilla.proxmox.com/show_bug.cgi?id=4311 issue 4311]).
* The listing of Who, What and When Objects can now optionally also display the description set for each object group, without explicitly selecting it.
* Fix an XSS issue in the Mail Queue view.
*: See [https://forum.proxmox.com/threads/149333/post-730687 PSA-2024-00015-1] for details.
* Fix the display message when removing a rule object, to not include the html-escaped icon.
* Fix a typo in the suggested default text when creating new notification objects.
* Remove whitespace before or after the subscription key when adding a new one, as they usually are copy-pasted.
* Fix the public-key DNS record displaying for DKIM selectors larger than 2048 bit.
* Clarify the label for DKIM domain selection.
* Enable autocompletion hints for the username, password, and TFA input fields to improve compatibility with password managers ([https://bugzilla.proxmox.com/show_bug.cgi?id=5251 issue 5251]).
* Show only installed services in the node's system panel by default, but optionally allow to show all services ([https://bugzilla.proxmox.com/show_bug.cgi?id=5611 issue 5611]).
* Fix an issue where clicking on an external link to the GUI would display a login screen, even if the current session was still valid.
* Fix an issue where the date picker would choose the wrong date after changing to a different month.
* Fix an issue where edit windows would not be correctly masked while loading.
* Display the end-of-life message as a notice up until three weeks before the end-of-life date, and display it as a warning from that point on.
* Move the "Reset" button for edit windows to an icon-only button in the title bar ([https://bugzilla.proxmox.com/show_bug.cgi?id=5277 issue 5277]).
*: This reduces the risk of misclicking and accidentally resetting form data.
* Improved translations, among others:
** Bulgarian (NEW!)
** French
** German
** Italian
** Japanese
** Korean
** Russian
** Simplified Chinese
** Spanish
** Traditional Chinese
** Ukrainian

==== Enhancements in the Mail Gateway API Backend ====
* You can now configure the <code>From</code> header information used for mails from the system itself:
** When sending admin reports
** Notifications from a notify action
** Backup jobs
** Bounces for messages refused for part of the recipients if before queue filtering is used and NDR on block is enabled.
*: For spam reports and quarantine links this could already be set in the Spam Quarantine options.
*: The emails still use an empty envelope from address, or for some cases <code>postmaster</code>
*: If this is set to contain an email address with a domain name, and DKIM signing based on header is enabled, the mails are now signed with DKIM ([https://bugzilla.proxmox.com/show_bug.cgi?id=4658 issue 4658]).
* Fix enabling custom SpamAssassin scores on systems where <code>/var/cache</code> is on a different filesystem from <code>/etc</code>.
*: Any pending changes will be preserved across the upgrade.
* Fix a post-authentication privileged file read vulnerability in the Proxmox Mail Gateway API.
*: See [https://forum.proxmox.com/threads/proxmox-mail-gateway-security-advisories.149333/post-705346 PSA-2024-00009-1] for details.
* Make the static email containing the quarantine access link into a template, helping deployments with predominantly non-English speaking users ([https://bugzilla.proxmox.com/show_bug.cgi?id=4211 issue 4211]).
* Support having a <code>text/plain</code> alternative part for report emails generated by PMG, like the daily admin report and the spam quarantine report send to users.
* Fix the default examples for the Who Objects to use a domain (<code>fromthisdomain.example</code>) reserved for documentation and examples ([https://bugzilla.proxmox.com/show_bug.cgi?id=5972 issue 5972]).
* Include the failure to DKIM sign a mail in the Tracking Center output, by adding the internal queue-id to the log message.
* Prevent a mail from being delivered multiple times when a user clicks on the deliver-button in their spam report multiple times ([https://bugzilla.proxmox.com/show_bug.cgi?id=6126 issue 6126]).
* Include the receiver email address when logging release or deletion from the quarantine.
* Fix the custom check script interface to also allow negative spam-scores as result.
* Fix an issue where comments set for LDAP profiles did not preserve percent encodings.
* Clarify that links are not displayed as links, but as plain-text when enabling the <code>allowhrefs</code> option.
* Use a lower level perl routine for setting file-contents to reduce write amplification.
* Use double-hyphen as argument prefix instead of the outdated single-hyphen in CLI commands documentation.
* Fix an issue where the documentation for CLI aliases did not mention the complete aliased command.
* Reload all Proxmox Mail Gateway services when the <code>proxmox-spamassassin</code> package is updated to a new version.

==== Access Control ====
* Realm System ported from Proxmox VE.
*: Enables you to configure multiple external authentication realms for users in the administration backend.
* Single-Sign-On (SSO) with the new OpenID Connect access realm type as first new realm.
*: External authorization servers can now be integrated for management access with Proxmox Mail Gateway, either using existing public services or your own identity and access management solution, for example, Keycloak, Zitadel or LemonLDAP::NG.
*: With the ability to auto-create users upon first logging it.
*: Roles for auto-created users can be queried from a configurable role-claim on your OpenID Connect service, or use a fixed role for all auto-created user of a realm.
*: Initial login for an auto-created user in a cluster needs to be done on the primary/master node.

==== Notable bugfixes and general improvements ====

* Since the release of Proxmox Mail Gateway 8.1 the Proxmox team has begun [https://forum.proxmox.com/forums/security-advisories.26/ tracking explicit security issues publicly in our forum]. The thread lists all security issues since January 2024.
*: Following the posts there is highly recommended.
* Fix an RCE vulnerability in the shim bootloader used for Secure Boot support.
*: See [https://forum.proxmox.com/threads/proxmox-virtual-environment-security-advisories.149331/post-678937 PSA-2024-00007-1] for details.
* Fix unexpected behavior in handling single-part attachments in the rule system.
*: See [https://forum.proxmox.com/threads/proxmox-mail-gateway-security-advisories.149333/post-728656 PSA-2024-00012-1] for details.
* Fix the <code>pmg7to8</code> tool to identify the newer released <code>proxmox-kernel</code> series (6.5, 6.8, 6.11) as expected kernel versions.
* Add a section to the <code>pmg7to8</code> tool for checking potential issues in the currently configured ruleset.
* Increase the minimum password length to 8, following NIST recommendation and the change in the installer
* Include information about the routing table in the <code>pmg-system-report</code> tool used for Enterprise Support information collection.
* Add anchors to subsections of the documentation to provide links to the specific point where an option is documented.
* Document the steps needed to activate a custom SpamAssassin configuration ([https://bugzilla.proxmox.com/show_bug.cgi?id=3979 issue 3979]).

==== Installation ISO ====
* Support for automated and unattended installation of Proxmox Mail Gateway, as already released for Proxmox VE 8.2 and Proxmox Backup Server 3.2.
*: Introduce the <code>proxmox-auto-install-assistant</code> tool that prepares an ISO for automated installation.
*: The automated installation ISO reads all required settings from an answer file in TOML format.
*: One option to provide the answer file is to directly add it to the ISO. Alternatively, the installer can retrieve it from a specifically-labeled partition or via HTTPS from a specific URL.
*: If the answer file is retrieved via HTTPS, URL and fingerprint can be directly added to the ISO, or obtained via DHCP or DNS.
*: See the [https://pve.proxmox.com/wiki/Automated_Installation wiki page on Automated Installation] for more details.
* Ship the recent version 7.20 of memtestx86+, adding support for current CPU Generations (Intel's Arrow Lake and Ryzen 9000 series) as well as preliminary NUMA support.
* Fix an issue where setting ZFS compression to <code>off</code> did not have any effect, due to a change in upstream defaults.
* Improve the layout of widgets in the GTK-based installer for consistent margins and alignment.
* Add a post-installation notification mechanism for automated installations ([https://bugzilla.proxmox.com/show_bug.cgi?id=5536 issue 5536]).
*: This mechanism can be configured with the new <code>post-installation-webhook</code> section in the answer file.
* Add support for running a custom script on first boot after automated installation ([https://bugzilla.proxmox.com/show_bug.cgi?id=5579 issue 5579]).
*: The script can be provided in the ISO or fetched from an URL.
* Allow users to set hashed passwords in the <code>proxmox-auto-installer</code> answer file.
* Allow users to customize the label of the partition from which the automated installer fetches the answer file.
* Add ability to detect and rename an existing ZFS pool named <code>rpool</code> during the installation.
* Improve the email address validation to include a broader set of email address formats.
*: This implements the email validation check specified in the [https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address HTML specification].
* The text-based installer now fails if no supported NIC was found, similar to graphical installer.
* Improve UI consistency by adding the missing background layer for the initial setup error screen in the text-based installer.
* Improve usability for small screens by adding a tabbed view for the advanced options at the disk selection step in the text-based installer.
*: This change only affects screens with a screen width of less than or equal to 80 columns.
* Fix an issue with ISOs generated with the <code>proxmox-auto-install-assistant</code> which caused the user to end up in the GRUB shell when booting from a block device (e.g. an USB flash drive) in UEFI mode.
* Fix a bug which caused some kernel parameters related to the automated installer to be removed incorrectly.
* Fix a bug which caused the installer to not detect Secure Boot in some cases.
* Ask the user for patience while making the system bootable if multiple disks are configured, as this may take longer than expected.
* Preserve the <code>nomodeset</code> kernel command-line parameter.
*: A missing <code>nomodeset</code> parameter has caused display rendering issues when booting the finished Proxmox Mail Gateway installation on some systems ([https://bugzilla.proxmox.com/show_bug.cgi?id=4230#c38 see this comment for more information]).
* Improve user-visible error and log messages in the installer.
* Improve documentation for the <code>proxmox-auto-install-assistant</code>.
* Improve error reporting by printing the full error message when the installation fails in <code>proxmox-auto-installer</code>.
* Improve error reporting by printing the full error message when mounting and unmounting the installation file system fails in <code>proxmox-chroot</code>.
* Improve debugging and testing by enumerating the installation environment anew (e.g. when running the command <code>dump-env</code>).
* Send the correct content-type charset <code>utf-8</code> when fetching answer files from an HTTP server during automated installation.
* Switch the text-based installer rendering backend from termion to crossterm.
* Raise minimum root password length from 5 to 8 characters for all installers.
*: This change is done in accordance with current [https://pages.nist.gov/800-63-4/sp800-63b.html#passwordver NIST recommendations].
* Print more user-visible information about the reasons the auto installation failed.
* Allow RAID levels to be set case-insensitively in the answer file for the auto-installer.
* Prevent the auto-installer from printing progress messages while there has been no progress.
* Disallow configuring BTRFS as root filesystem for Proxmox products that do not currently support it.
* Correctly acknowledge the user's preference whether to reboot on error during auto installation ([https://bugzilla.proxmox.com/show_bug.cgi?id=5984 issue 5984]).
* Allow binary executables (in addition to shell scripts) to be used as the first-boot executable for the auto-installer.
* Allow properties in the answer file of the auto-installer to be either in <code>snake_case</code> or <code>kebab-case</code>.
*: The <code>kebab-case</code> variant is preferred to be more consistent with other Proxmox configuration file formats.
*: The <code>snake_case</code> variant will be gradually deprecated and removed in future major version releases.
* Validate the locale and first-boot-hook settings while preparing the auto-installer ISO instead of failing the installation due to wrong settings.
* Prevent printing non-critical kernel logging messages, which drew over the TUI installer's interface.
* Keep network configuration detected via DHCP in the GUI Installer, even when not clicking <code>Next</code> first ([https://bugzilla.proxmox.com/show_bug.cgi?id=2502 issue 2502]).

<div id="8.2-known-issues"></div>
=== Known Issues & Breaking Changes ===

==== Kernel 6.8 ====

The Proxmox Mail Gateway 8.2 releases will install and use the 6.8 Linux kernel by default. A major kernel version change can have a few hardware-specific side effects. The kernel version 6.8 has been the default kernel for Proxmox Mail Gateway installations since April 2024, so most existing installations should already be using it.

Most issues with new kernel versions do not affect virtual machines and container guests, so virtualized Promox Mail Gateway installations are not affected.

===== Kernel: Change in Network Interface Names =====

Upgrading kernels always carries the risk of changes in network interface names, which can lead to invalid network configurations after a reboot.
In this case, you must either update the network configuration to reflect the name changes, or pin the network interface to its name beforehand.

See [https://pve.proxmox.com/pve-docs/pve-admin-guide.html#network_override_device_names the Proxmox VE reference documentation] on how to pin the interface names based on MAC Addresses.

Currently, the following models are known to be affected at higher rates:
* Models using <code>i40e</code>. Their names can get an additional port suffix like <code>p0</code> added.

== Proxmox Mail Gateway 8.1 ==
'''Released 29. February 2024'''

* Based on Debian Bookworm (12.5)
* SpamAssassin 4.0.0 (with updated rulesets)
* ClamAV 1.0.3
* PostgreSQL 15.6
* Latest 6.5 Kernel as new stable default
* ZFS 2.2.2

=== Highlights ===

* Extend the rule system to allow selection of the <strong>match-if mode</strong> for entries in What/Who/When Objects, and multiple Objects in Rules, providing flexible control over whether all, any, none, or some but not all must match.
*: See the [[#8.1-rule-system-enhancements|enhancements in the rule system section]] for more details and examples.
* Optional DKIM signing based on the <code>From</code> header (also known as <code>RFC5322.From</code>), instead of the Envelope sender (also known as <code>RFC5321.From</code>) ([https://bugzilla.proxmox.com/show_bug.cgi?id=2971 issue 2971]).

* Secure Boot support.
*: Proxmox Mail Gateway now includes a signed shim bootloader trusted by most hardware's UEFI implementations. All necessary components of the boot chain are available in variants signed by Proxmox.
*: The Proxmox Mail Gateway installer can now be run in environments where Secure Boot is required and enabled, and the resulting installation can boot in such environments.
*: Existing Proxmox Mail Gateway installations can be switched over to Secure Boot without reinstallation by executing some manual steps, see the [https://pve.proxmox.com/pve-docs/chapter-sysadmin.html#sysboot_secure_boot documentation] for details.
*: How to use custom secure boot keys has been documented in the [https://pve.proxmox.com/wiki/Secure_Boot_Setup Secure Boot Setup] page in the Proxmox VE wiki. For using DKMS modules with secure boot see the [https://pve.proxmox.com/pve-docs/chapter-sysadmin.html#sysboot_secure_boot reference documentation].

* Seamless upgrade from Proxmox Mail Gateway 7.3, see [https://pmg.proxmox.com/wiki/index.php/Upgrade_from_7_to_8 Upgrade from 7 to 8]

=== Changelog Overview ===

<div id="8.1-rule-system-enhancements"></div>
==== Enhancements in the Rule System ====
* Make the rule system more flexible by introducing a match-if-mode for objects and groups. The match-if-mode of an object (or group) determines whether any, all, not all or none of its children must match for the whole object (or group) to match. This allows to implement complex rules, for example:
** Exclude certain recipients from a rule, while still considering all later rules for them.
** Treat emails differently if they contain particular attachments and are detected as spam or contain a virus.
** Match attachments with a filename ending in <code>.pdf</code>, but being detected as executable by the content-type filter.
** Matching a mail sent from one address and containing a phrase in the subject.
* Disclaimers can now be added on top of the message, instead of only at the bottom ([https://bugzilla.proxmox.com/show_bug.cgi?id=2606 issue 2606]).
* The separator <code>--</code> for disclaimers can now be optionally omitted ([https://bugzilla.proxmox.com/show_bug.cgi?id=2430 issue 2430]).
* Adapt the number of parallel worker processes for the SMTP filter to increased memory requirements and availability.
* Make the timeout for processing a mail consistent between before- and after-queue filtering, and make it configurable.
* Prevent duplicate mail delivery when filtering runs into a timeout.
* Fix the synchronization of the user wants- and blocklists if the last address is removed for a user ([https://bugzilla.proxmox.com/show_bug.cgi?id=4392 issue 4392]).
* Further improve input validation for regular expressions in the rule system ([https://bugzilla.proxmox.com/show_bug.cgi?id=4811 issue 4811]).
* Fix an error in the collection of virus occurrence statistics.
* The spam report e-mails now correctly handle addresses with characters that need to be escaped for the API and GUI.
* Display the descriptions for rules from the advanced KAM ruleset in the spam info grid in the quarantine view.
* Improve the output of <code>pmgdb dump</code> used for gathering information about the ruleset:
** Add information about the type of What Objects
** Add optional <code>--rules</code> parameter to restrict output to rules that are active or inactive
** Visually emphasize whether a rule is active
** Remove unnecessary filler words from output

==== Enhancements in the Web Interface (GUI) ====

* Make it easier to manage large deployments by adding a filter- and search-box for ([https://bugzilla.proxmox.com/show_bug.cgi?id=4510 issue 4510]):
*: Relay Domains
*: Transport
*: Networks
*: Objects in the rule system
* Add icons to the backup destination panel for improved UX.
* Fix an issue where the OK button would stay disabled when editing an ACME DNS challenge plugin ([https://bugzilla.proxmox.com/show_bug.cgi?id=4531 issue 4531]).
* Fix TLS 1.3-only configuration for the API proxy server ([https://bugzilla.proxmox.com/show_bug.cgi?id=4859 issue 4859]).
* Fix spelling errors in the GUI and improve gettext instances so that they can be better translated.
* Improved translations, among others:
** Croatian (NEW!)
** Georgian (NEW!)
** Arabic
** Catalan
** German
** Italian
** Polish
** Simplified Chinese
** Spanish
** Traditional Chinese
** Ukrainian
** The language code for Korean was corrected from <code>kr</code> to <code>ko</code> in alignment with ISO 639-1, while maintaining a symbolic link for backward compatibility for now.
** Several remaining occurrences of the <code>GiB</code> unit in the GUI can now be translated ([https://bugzilla.proxmox.com/show_bug.cgi?id=4551 issue 4551]).

==== Access Control ====

* Allow usernames shorter than 4 characters, in accordance with Proxmox VE and Proxmox Backup Server ([https://bugzilla.proxmox.com/show_bug.cgi?id=4818 issue 4818])

==== Notable bug fixes and general improvements ====

* Harden the Postfix configuration for the external port to address the [https://www.postfix.org/smtp-smuggling.html SMTP Smuggling] security issue, by implementing all recommendations from upstream.
* Switch the default time-stamp format expected by the Tracking Center to the RFC3339 based information in the logs in Proxmox Mail Gateway 8.0 and newer. While this was initially meant as a small clean-up a few issues around the switch between DST and regular time were fixed with the changes.
* Secure Boot support.
*: Proxmox Mail Gateway now ships a shim bootloader signed by a CA trusted by most hardware's UEFI implementation. In addition, it ships variants of the GRUB bootloader, MOK utilities and kernel images signed by Proxmox and trusted by the shim bootloader.
*: New installation will support Secure Boot out of the box if it is enabled.
*: Existing installations can be adapted to Secure Boot by installing optional packages, and possibly reformatting and re-initializing the ESP(s), without the need for a complete reinstallation. See [https://pve.proxmox.com/wiki/Secure_Boot_Setup the wiki article for more details].
* Fix cluster setups recreated after restoring a backup with statistics ([https://bugzilla.proxmox.com/show_bug.cgi?id=5189 issue 5189]).
* The kernel shipped by Proxmox is shared for all products. This is now reflected in the renaming from <code>pve-kernel</code> and <code>pve-headers</code> to <code>proxmox-kernel</code> and <code>proxmox-headers</code> respectively in all relevant packages.
* The new <code>proxmox-default-kernel</code> and <code>proxmox-default-headers</code> meta-packages will depend on the currently recommended kernel-series.
* Many edge-cases encountered during the upgrade from Proxmox Mail Gateway 7.3 to 8 by our user-base are now detected and warned about in the improved <code>pmg7to8</code> checks:
** Notify when a template was copied to <code>/etc/pmg/templates</code> without any modifications, to prevent missing important changes to config files.
** Warn if [https://github.com/dell/dkms DKMS] modules are detected, as many of them do not upgrade smoothly to the newer kernel versions in Mail Gateway 8.
** Warn if version 7 of the Mail Gateway system does not have the correct meta-package of <code>grub</code> installed. The correct meta-package is required to actually upgrade the installed bootloader to the newest version.
* Support for adding custom ACME enabled CA's which require authentication through '''E'''xternal '''A'''ccount '''B'''inding (EAB) on the command line ([https://bugzilla.proxmox.com/show_bug.cgi?id=4497 issue 4497]).
* Fix non-interactive use of the <code>pmgsh</code> utility ([https://bugzilla.proxmox.com/show_bug.cgi?id=4815 issue 4815]).
* Improve the parsing of config and system files, used in many places of the code. This fixes an issue with displaying the network interfaces without a correct hostname entry in <code>/etc/hosts</code> and aims to prevent similar issues in the future.
* Prevent cluster synchronization from failing due to a change in fingerprint parsing in OpenSSL.
* Add support for having a Proxmox Backup Server remote on an alternate port ([https://bugzilla.proxmox.com/show_bug.cgi?id=4944 issue 4944]).
* Reduce log severity for periodic informational messages from <code>error</code> to <code>info</code>.
* Changelogs for new package versions shown in the UI are now all gathered with <code>apt changelog</code>, as this is now supported by the Proxmox repositories.
* Add information about the configured domains for DKIM signing to the report generated for support cases.
* The documentation on firmware updates provided by the operating system has been extended and revised, helping administrators to identify if their setup is optimal.

==== Installation ISO ====

* The ISO is able to run on Secure Boot enabled machines.
* The text-based UI got significant improvement based on the feedback received from the first release in Proxmox Mail Gateway 8.0.
* The current link-state of each network interface is now displayed in the network configuration view, helping in identifying the correct NIC for the management interface ([https://bugzilla.proxmox.com/show_bug.cgi?id=4869 issue 4869]).
* If provided by the DHCP server, the hostname field is already filled out with the information from the lease.
* The correct meta-package of <code>grub</code> is now installed based on the boot mode (<code>grub-pc</code> or <code>grub-efi-amd64</code>). This ensures that the bootloader on disk gets updated when there is an upgrade for the <code>grub</code> package.
* The text-based UI is now also available over a serial console, for headless systems with a serial port.
* The root dataset on ZFS installations now uses <code>acltype=posixacl</code> in line with [https://openzfs.github.io/openzfs-docs/Getting%20Started/Debian/Debian%20Bookworm%20Root%20on%20ZFS.html upstream's recommendation].
* Kernel parameters passed on the command line during install are now also set in the target system ([https://bugzilla.proxmox.com/show_bug.cgi?id=4747 issue 4747]).
* Fix the warning that is shown in case the address family (IPv4, IPv6) of the host IP and DNS server do not match.
* The text-based UI now sets the correct disk-size for the selected disk, instead of limiting the installation to the size of the first disk in the list ([https://bugzilla.proxmox.com/show_bug.cgi?id=4856 issue 4856]).
* For better UX, the text-based UI now also displays a count-down before automatically rebooting.
* The screensaver in the graphical installer is now disabled.
* The graphical installer now displays the units used for disk-based options.
* The kernel command-line parameter <code>vga788</code> is now set for both the graphical debug and all text-based UI installation options. This improves compatibility of the installer with certain hardware combinations.
* Remove the checksum-options of <code>off</code> and <code>fletcher2</code> for ZFS, for being dangerous and deprecated respectively.
* Improve the layout in the graphical installer to ensure correct margins and alignment of widgets.
* Set a timeout for country detection, preventing the installer from hanging at that step ([https://bugzilla.proxmox.com/show_bug.cgi?id=4872 issue 4872]).
* General improvements for running external commands in the installer backend in order to prevent lockups.
* Improve validation of hostname length and allowed characters set in the installer ([https://bugzilla.proxmox.com/show_bug.cgi?id=5230 issue 5230]).

<div id="8.1-known-issues"></div>
=== Known Issues & Breaking Changes ===
==== Kernel ====
* Some SAS2008 controllers need a workaround to get detected since kernel 6.2, see the [https://forum.proxmox.com/threads/no-sas2008-after-upgrade.129499/page-4#post-607858 forum thread] for details.

* The TPM (Trusted Platform Module) hardware random number generator (RNG) is now disabled on all AMD systems equipped with a firmware-based TPM (fTPM) device. This change was implemented due to such RNGs causing stutters in many systems. Affected systems should switch the RNG source from <code>/dev/hwrng</code> to an alternative, like <code>/dev/urandom</code>.
: Reference: [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=554b841d470338a3b1d6335b14ee1cd0c8f5d754 kernel commit "tpm: Disable RNG for all AMD fTPMs"]

* Some Dell models, which appear to include all those using a BCM5720 network card, have a compatibility issue with the <code>tg3</code> driver in the kernel based on version 6.5.11.
*: From our current understanding 14th Generation Dell Servers (T140, R240, R640,...) are affected, while others (e.g., R630, R620, R610,...) do not seem to be affected. We are currently investigating this issue. In the meantime, we recommend pinning the kernel to version 6.2 on affected hosts.
*: Some users report that disabling the <code>X2APIC</code> option in the BIOS resolved this issue as a workaround.

== Proxmox Mail Gateway 8.0 ==
'''Released 29. June 2023'''

* Based on Debian Bookworm (12.0)
* Latest 6.2 Kernel as stable default
* ZFS 2.1.12
* SpamAssassin 4.0.0 (with updated rulesets)
* ClamAV 1.0.1
* PostgreSQL 15.3

=== Highlights ===

* New major release based on the great Debian Bookworm.

* Seamless upgrade from Proxmox Mail Gateway 7.3, see [[Upgrade from 7 to 8]]
*: New <code>pmg7to8</code> pre-flight checking script analyzing the system for common misconfigurations and missed steps during the upgrade

* Add new text-based UI mode for the installation ISO, written in Rust using the [https://github.com/gyscos/cursive Cursive] TUI (Text User Interface) library:
*: You can use the new TUI mode to work around issues with launching the GTK based graphical installer, sometimes observed on both very new and rather old hardware.
*: The new text mode executes the same code for the actual installation as the existing graphical mode.

=== Changelog Overview ===

==== Enhancements in the Rule System ====

* When adding a "Match Field" ''What'' object, check that the provided regular expression is a valid regular expression.

* Disable SpamAssassin's naive-Bayesian-style classifier and the auto-whitelisting plugin by default.
*: Both features lead to worse detection rates in the Spam Filter in most setups.
*: Bayes needs manual training and thorough consideration, as well as continuous maintenance.
*: Existing setups are kept without change on upgrade.
*: For new setups the old behavior can be enabled through the GUI.


==== Enhancements in the Web Interface (GUI) ====
* Improved Dark color theme:
*: The Dark color theme, introduced in Proxmox Mail Gateway 7.3, received a lot of positive feedback from our community, which resulted in further improvements.
* Improved translations, among others:
** Ukrainian (NEW)

** Japanese

** Simplified Chinese

** Traditional Chinese

** The size units (Bytes, KB, MiB,...) are now passed through the translation framework as well, allowing localized variants (e.g., for French).

** The language selection is now localized and displayed in the currently selected language

* Disable advanced statistic filters by default, as their behavior may not be immediately clear without consulting the documentation first.

* HTML-encode rule names before rendering as additional hardening against XSS.

* The tracking center can now parse the new syslog format for dates that was introduced in Debian Bookworm.
*: The logging format of <code>rsyslog</code> was changed to include Timezone information (RFC3339) in the logs, making the Tracking Center more robust across DST changes and year changes.


==== Access control ====
* Add TFA/TOTP lockout to protect against an attacker who has obtained the user password and attempts to guess the second factor:
*: If TFA fails too many times in a row, this user account is locked out of TFA for an hour. If TOTP fails too many times in a row, TOTP is disabled for the user account. Using a recovery key will unlock a user account. 

==== Installation ISO ====

* Add new text-based UI mode for the installation ISO, written in Rust using the [https://github.com/gyscos/cursive Cursive] TUI (Text User Interface) library:
*: You can use the new TUI mode to work around issues with launching the GTK based graphical installer, sometimes observed on both very new and rather old hardware.
*: The new text mode executes the same code for the actual installation as the existing graphical mode.
* The version of BusyBox shipped with the ISO was updated to version 1.36.1.
* Detection of unreasonable system time.
: If the system time is older than the time the installer was created, the system notifies the user with a warning.

* <code>ethtool</code> is now shipped with the ISO and installed on all systems.
* <code>systemd-boot</code> is provided by its own package instead of <code>systemd</code> in Debian Bookworm and is installed with the new ISO.
* The installation ISO now ships the dependencies for extracting text from attachments using SpamAssassin 4, eliminating the need to install the packages manually.

==== Notable bugfixes and general improvements ====

* Add a <code>pmg7to8</code> CLI tool to assist in upgrading from Proxmox Mail Gateway 7.3 to 8.

* Fix an issue where an invalid regular expression in a "Match Field" ''What'' object would cause <code>pmg-smtp-filter</code> to exit and restart, possibly leading to wrongly denied mails. Instead, <code>pmg-smtp-filter</code> now logs a warning if it encounters an invalid regular expression.

* During package installation or upgrade, ignore certain transient or obvious errors to avoid leaving the package in a broken state.

* Fix an issue where the Proxmox Mail Gateway system report would wrongly indicate a DNS misconfiguration.

* When authenticating via PAM, pass the <code>PAM_RHOST</code> item. With this, it is possible to manually configure PAM such that certain users (for example root@pam) can only log in from certain hosts.


<div id="8.0-known-issues"></div>
=== Known Issues & Breaking Changes ===

* The advanced statistics filter is now disabled by default.
*: To avoid changing the behavior of a Proxmox Mail Gateway 7.3 instance on upgrade, the upgrade process will set the <code>advfilter</code> option to <code>1</code> if no explicit value is set.

* SpamAssassin's naive-Bayesian-style classifier and the auto-whitelisting plugin are now disabled by default.
*:To avoid changing the behavior of a Proxmox Mail Gateway 7.3 instance on upgrade, the upgrade process will set each of the <code>use_awl</code>/<code>use_bayes</code> options to <code>1</code> if no explicit value is set.

== Proxmox Mail Gateway 7.3 ==
'''Released 28. March 2023'''

* Based on Debian Bullseye (11.6)
* Latest 5.15 Kernel as stable default
* Newer 6.2 kernel as opt-in
* ZFS 2.1.9
* SpamAssassin 4.0.0 (new major version)
* PostgreSQL 13.10

=== Highlights ===

* Proxmox Mail Gateway now provides a dark theme for the administrative and quarantine web interfaces.
* SpamAssassin 4.0.0 was integrated, along with many of its new capabilities, like (optionally) scanning document contents (docx, pdf, images,...), or resolving URLs from url-shorteners.

=== Changelog Overview ===

==== Enhancements in the Rule System ====
* New major release SpamAssassin 4.0.0, with many new features:
** Detection of spam inside of attachments. This is implemented for the file types <code>.pdf</code>, <code>.odt</code>, <code>.docx</code>, <code>.doc</code>, <code>.rtf</code>, as well as images (through OCR).
*:: Attachment scanning can be enabled using the Web UI (<code>Spam Detector</code> -> <code>Options</code>), which sets the <code>extract_text</code> option in the <code>spam</code> section of <code>/etc/pmg/pmg.conf</code>.
*:: The dependencies required for attachment scanning are marked as optional, but recommended dependency for the <code>pmg-api</code> package.
*:: This means that on systems that did not change the apt preference the new dependencies should be pulled in automatically on upgrade, otherwise you might need to manually install them.
*: Note that attachment scanning, and OCR in particular, increases CPU time spent per mail. Depending on email volume and available CPU power, you may see a significant increase in load.
** Follow and analyze URL-shortener links.
** Improved support for using information from DMARC-policies.
** Improved handling of internationalized (IDN) domain names.
* Adaptation of the SpamAssassin integration for version 4.0.0:
: The SpamAssassin configuration files shipped with the <code>pmg-api</code> package were adapted to the new features.
: <code>extract_text</code> was added as new option for the spam detector to disable content scanning, while most other new options are triggered with the <code>use_rbl</code> option.
: On deployments with modified templates, the upgrade process will ask how changes should be merged. This provides an opportunity to re-evaluate which modifications are still needed.
* Support enforcing TLS-only connections for mails from certain domains:
: It is now possible to enforce TLS encryption for inbound mail, complementing the already-present TLS policy functionality for outbound mail.
* Improved handling of SMTPUTF8:
: Based on the user feedback on UTF-8 support for the rule system introduced in Proxmox Mail Gateway 7.2, it is now possible to disable SMTPUTF8 through the API and GUI.
: The detection for SMTPUTF8 was aligned with the implementation in <code>postfix</code>.
* The What objects "Match Archive Filename" now also use the optional filename from the GZIP header for matching.
* Support trusted network entries with host bits set in the CIDR:
: Quite a few deployments did use a CIDR with host-bits set, for example 192.0.2.5/24 instead of 192.0.2.0/24. This is now translated internally and handled correctly.
* Ordering of multiple rules with the same priority is now stable, despite not being a recommended setup.

==== Enhancements in the Web Interface (GUI) ====

* Add a fully-integrated "Proxmox Dark" color theme variant of the long-time Crisp light theme.
: By default, the <code>prefers-color-scheme</code> media query from the Browser/OS will be used to decide the default color scheme.
: Users can override the theme via a newly added <code>Color Theme</code> menu in the user menu.
* Add "Proxmox Dark" color theme to the Proxmox Mail Gateway reference documentation.
: The <code>prefers-color-scheme</code> media query from the Browser/OS will be used to decide if the light or dark color scheme should be used.
: The new dark theme is also available in the [https://pmg.proxmox.com/pmg-docs/api-viewer/index.html#/nodes/{node}/version Proxmox Mail Gateway API Viewer].
* Task logs can now be downloaded directly as text files for further inspection.
* The language chooser now displays, for each available language, both its native name as well as its name translated to the currently active language.
* HTML-encode API results before rendering as additional hardening against XSS.
* Automatically redirect HTTP requests to HTTPS for convenience.
: This avoids "Connection reset" browser errors that can be confusing, especially after setting up a Proxmox Mail Gateway host the first time.
* Invalid entries in advanced fields now cause the advanced panel to unfold, providing direct feedback.
* Improved translations, among others:
** Arabic
** French
** German
** Italian
** Japanese
** Russian
** Slovenian
** Simplified Chinese
** Traditional Chinese

==== Notable General Improvements and Bug Fixes ====
* The documentation has now a chapter describing the statistics part of the GUI and API.
* Mail delivery from quarantine uses new code for sending locally generated mail, with the following improvements:
** support for IPv6-only deployments and delivery status notifications.
** Correct decoding of addresses containing UTF-8.
* The cleanup before restoring the configuration from a backup was improved, preventing issues when restoring without rebooting the system.
* Logging of errors when sending locally generated mail was improved.
* Errors in files related to TLS-policy are now also reported in the syslog.
* The output of <code>pmgdb dump</code> is now able to handle UTF-8 characters in rule names, object names, and comments.

==== Installation ISO ====

* the version of BusyBox shipped with the ISO was updated to version 1.36.0.
* The EFI System Partition (ESP) defaults to 1 GiB of size if the root disk partition (<code>hdsize</code>) is bigger than 100 GB.
* UTC can now be selected as timezone during installation.

<div id="7.3-known-issues"></div>

=== Known Issues & Breaking Changes ===

* The ISO does not ship the optional dependencies for extracting text from attachments - If you installed from the ISO and want to use the feature, you can simply install them manually
apt install antiword docx2txt odt2txt poppler-utils tesseract-ocr unrtf

== Proxmox Mail Gateway 7.2 ==
'''Released 30. November 2022'''

* Based on Debian Bullseye (11.5)
* Latest 5.15 Kernel as stable default (5.15.74)
* Newer 5.19 kernel as opt-in
* ZFS 2.1.6
* SpamAssassin 3.4.6 (with updated rule-set)
* PostgreSQL 13.8

'''Changelog Overview'''

* Enhancements in the Rule system:
** Improved handling of international emails
*** Support for UTF-8 characters in the rule system (e.g. matching non-ASCII subjects).
*** Better handling of [https://www.rfc-editor.org/rfc/rfc6531 SMTPUTF8 emails] (the smtp-dialogue already contains non-ASCII data, the headers contain UTF-8 data without MIME encoding).
** Proper encoding for template-variable information in the Notifications and Modify Field actions.
** MatchField now matches all occurrences of a header - not only the first one - especially relevant for <code>Received</code> headers.
** Deprecated the <code>Attach</code>, <code>Counter</code> and <code>ReportSpam</code> Actions.
*: While they were present in the code of Proxmox Mail Gateway, they were never exposed in the GUI or API.
*: All three have now been deprecated and will be removed with version 8.0.

* Improved Quarantine UX:
** Quarantine interface for Administrators: many of the recent features for end-users in the Spam Quarantine have been ported to the administrator view:
*** Allow selection of multiple mails.
*** Context menu in the mail-listing.
*** Display the Receiver information in the Attachment and Virus quarantines and the Mail Info widget.
** Augmented the information visualization in the Spam information grid.
*** The weight (number of points) and the type of impact (positive or negative) of SpamAssassin rules is now shown with colors and font-weights to make them easier to grasp.
*** The rule IDs and scores are using a monospaced font for better comparison of values.
** Colorized <code>Deliver</code> and <code>Delete</code> actions improves intuitive handling of the common actions.
** Display of attachments in the Spam and Virus quarantines (for a more complete overview of the mail).
** Attachment and Virus quarantines can now optionally be filtered by Receiver - especially helpful in larger deployments.
** Display of descriptions for locally defined SpamAssassin rules.
** Fix displaying the quarantine interface on narrow screens: Part of the action buttons were cut off and not reachable through scrolling.

* Enhancements in the web interface (GUI):
** The Postfix queue interface now displays the mail's headers in a decoded way - so that you see it as in your mail user agent.
** The Statistic time selector now does not show non-existent day/month combinations (e.g. the 31. Day of February).
** Better spacing of the Field labels in the rule object edit windows.
** Improved translations, among others:
*** Dutch
*** German
*** Italian
*** Polish
*** Traditional Chinese
*** Turkish

* Support Proxmox Offline Mirroring & Subscription Handling
** Proxmox Offline Mirror: The tool supports subscriptions and repository mirrors for air-gapped systems. The newly added [https://pom.proxmox.com proxmox-offline-mirror] utility can now be used to keep Proxmox Mail Gateway hosts, without access to the public internet up-to-date and running with a valid subscription.

* Notable General Improvements and Bugfixes:
** Add IP networks uniquely to template variables (<code>postfix.mynetworks</code>)
*: If you had multiple entries in your transport directory, all pointing to the same host, they were added multiple times to the variable used in the configuration system.
** Support for Proxmox Backup Server Namespaces.
** Spam report emails now correctly display the <code>From</code> header, even if it contains a comma (e.g. <code>"Lastname, Firstname" <firstname.lastname@domain.example></code>).
** The left-over config file <code>/etc/apt/apt.conf.d/75pmgconf</code> was removed, enabling the automatic removal of obsolete kernel packages, which can take up significant amounts of space.
** SpamAssassin updates now handle updates to multiple channels correctly on the first run.
** Improved parsing of email attributes from LDAP profiles.
** Changing the directory to '/' before running <code>psql</code> as <code>postgres</code>user - preventing the printing of harmless but confusing warnings with various Proxmox Mail Gateway CLI utilities.
** Support disabling TLS 1.2 and configuring TLS 1.3 ciphers for <code>pmgproxy</code> - following the change for <code>pveproxy</code> in Proxmox VE.
'''Upgrade from 6.4'''

See [[Upgrade from 6.x to 7.0]]
== Proxmox Mail Gateway 7.1 ==
'''Released 30. November 2021'''
* Based on Debian Bullseye (11.1)
* Kernel 5.13
* ZFS 2.1
* SpamAssassin 3.4.6 (with updated rule-set)
* PostgreSQL 13.5

'''Changelog Overview'''

* Enhancements in the web interface (GUI)
** Improved configuration editing of LDAP backends: Changes can now be applied without having to specify a password.
** The APT repository configuration, rather than being restricted to 'root', is now visible and editable by all users with 'Administrator' privileges.
** Improved translations, among others:
*** Arabic
*** Basque
*** Brazilian Portuguese
*** French
*** German
*** Simplified Chinese
*** Traditional Chinese
*** Turkish

* Two-Factor Authentication
** Two-factor authentication (TFA) for the web interface. Shares the TFA implementation from Proxmox Backup Server, written in rust.
** Support for multiple types of second factors:
*** WebAuthn, which supports a wide range of security devices, like hardware keys or trusted platform modules.
*** Time-based One-Time Password (TOTP), a short code derived from a shared secret and the current time, it changes every 30 seconds.
*** Single use Recovery Keys.

* Backend and API
** Improved support for setups using DHCP for their network configuration:
*: While email still requires working DNS records, you can now manage and configure the IP of your Proxmox Mail Gateway in your DHCP configuration.
** When adding a new entry to a Who object, a duplicate check is performed before saving.
** Better handling of trailing dot in domain-names:
*: Proxmox Mail Gateway uses the first search domain from <code>/etc/resolv.conf</code> as domain name - it can now handle entries with a trailing dot.
** Delivery status notification (DSN, RFC 3461) support for outbound email with enabled before-queue filtering.
'''Upgrade from 6.4'''

See [[Upgrade from 6.x to 7.0]]

== Proxmox Mail Gateway 7.0 ==
'''Released 15. July 2021'''
* Based on Debian Bullseye (11)
* SpamAssassin 3.4.6 (with updated rule-set)
* Kernel 5.11
* PostgreSQL 13

'''Changelog Overview'''

* Enhancements in the web interface (GUI)
** Make dashboard status panel more detailed, showing, among other things, uptime, kernel version, CPU info and a high level repository status overview.
** New APT repository management panel in the <code>Administration</code> tab shows an in-depth status and a list of all configured repositories.
**: Basic repository management, for example, activating or deactivating a repository, is also supported.
** Updated ExtJS JavaScript framework to latest GPL release 7.0
** Added advanced task-log filtering
** Improved translations, including:
*** Arabic
*** French
*** German
*** Japanese
*** Polish
*** Turkish

* ACME/Let's Encrypt
** Support the use of wildcard domains with the DNS plugins
** API: nodeconfig: validate ACME config before writing

* API
** pmgproxy: allow setting LISTEN_IP parameter
** The "Authentication mode" setting of <code>LDAP</code> for the quarantine interface no longer contains the ticket-link in the report-mails - thus, quarantine users need to provide their LDAP credentials to access the quarantine.

* Installer:
** Rework the installer environment to use <code>switch_root</code> instead of <code>chroot</code>, when transitioning from initrd to the actual installer.
**: This improves module and firmware loading, and slightly reduces memory usage during installation.
** Automatically detect HiDPI screens, and increase console font and GUI scaling accordingly. This improves UX for workstations with Proxmox VE (for example, for passthrough).
** Improve ISO detection:
*** Support ISOs backed by devices using USB Attached SCSI (UAS), which modern USB3 flash drives often do.
*** Linearly increase the delay of subsequent scans for a device with an ISO image, bringing the total check time from 20s to 45s. This allows for the detection of very slow devices, while continuing faster in general.
** Use <code>zstd</code> compression for the initrd image and the squashfs images.
** Update to busybox 1.33.1 as the core-utils provider.

* libarchive-perl
** The perl-bindings to <code>libarchive</code> have been updated to match <code>libarchive</code> version 3.4.3 (shipped in Debian Bullseye) - the library interface was kept backwards-compatible

* libxdgmime-perl
** The perl-bindings to [https://gitlab.freedesktop.org/xdg/xdgmime xdgmime] have been updated to match current upstream - the library interface was kept backwards-compatible

<div id="7.0-breaking-changes"></div>
'''Breaking Changes'''
* New default bind address for pmgproxy, unifying the default behavior with Proxmox VE and Proxmox Backup Server
** 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. Instead of:
*: <code>192.0.2.1- root@pam [01/06/2021:01:19:03 +0200] "GET /api2/json/config/ruledb/digest HTTP/1.1" 200 51</code>
*: the line now looks like:
*: <code>::ffff:192.0.2.1- root@pam [01/06/2021:01:19:03 +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>

* ClamAV has [https://blog.clamav.net/2021/04/are-you-still-attempting-to-download.html deprecated the SafeBrowsing feature]:
** These options have been removed from the shipped <code>freshclam.conf.in</code> template.
** The <code>safebrowsing</code> config key in <code>/etc/pmg/pmg.conf</code> is currently ignored and will be dropped at some point in the future.

* Changes to the database layout:
** The <code>host</code> column of the <code>cgreylist</code> table, which has not been used since Proxmox Mailgateway 6.2, has been dropped from the schema and will be dropped from existing databases during the upgrade.

* API deprecations, moves and removals
** The <code>upgrade</code> parameter of the <code>/nodes/{node}/termproxy</code> API method has been replaced by providing <code>upgrade</code> as <code>cmd</code> parameter.
** The <code>domain</code> parameter of the <code>/config/tlspolicy</code> API method has been replaced by the <code>destination</code> parameter.
** The <code>/quarantine/whitelist/{address}</code> and <code>/quarantine/blacklist/{address}</code> API methods, that take the address as part of the path, have been deprecated in favor of explicitly providing the parameter in the request to <code>/quarantine/whitelist</code> and <code>/quarantine/blacklist</code> respectively.
** The API methods for detailed statistics per e-mail address, which take the address as part of the path (<code>/statistics/contact/{contact}</code>, <code>/statistics/sender/{sender}</code> and <code>/statistics/receiver/{receiver}</code> have been deprecated in favor of <code>/statistics/detail</code>, which takes the address as an explicit parameter.

<div id="7.0-known-issues"></div>
'''Known Issues'''
* '''Network''': Due to the updated systemd version, and for most upgrades, the newer kernel version (5.4 to 5.11), some network interfaces might change upon reboot:
** Some may change their name. For example, due to newly supported functions, a change from <code>enp33s0f0</code> to <code>enp33s0f0np0</code> could occur.
**: We observed such changes with high-speed Mellanox models.
** [https://sources.debian.org/src/bridge-utils/1.7-1/debian/NEWS/#L3-L23 Bridge MAC address selection has changed in Debian Bullseye] - it is now generated based on the interface name and the <code>machine-id (5)</code> of the system.
**: Note that by default, Proxmox Mail Gateway does not use a Linux Bridge for networking, so most setups are unaffected.
* '''Machine-id''': Systems installed using the Proxmox Mail Gateway 5.0 to 5.4 ISO may have a non-unique machine-id. These systems will have their machine-id re-generated automatically on upgrade, to avoid a potentially duplicated bridge MAC and other issues.
: If you do the upgrade remotely, make sure you have a backup method of connecting to the host (for example, IPMI/iKVM, tiny-pilot, another network accessible by a cluster node, or physical access), in case the network used for SSH access becomes unreachable, due to the network failing to come up after a reboot.

'''Upgrade from 6.4'''

See [[Upgrade from 6.x to 7.0]]

==Proxmox Mail Gateway 6.4==
'''Released 30. March 2021'''
* Based on Debian Buster (10.9)
* SpamAssassin 3.4.5 (with update ruleset)
* Kernel 5.4.106
* ACME integration
** Proxmox Mail Gateway now offers full integration of the ACME protocol via the GUI, enabling administrators to create valid and trusted certificates for their domains with the Let's Encrypt certificate authority, in the same way as with Proxmox VE.
** Full support for the <code>http-01</code> and <code>dns-01</code> challenges, with all plugins from [https://github.com/acmesh-official/acme.sh acme.sh].
** Easily configurable from the GUI.
* General Certificate Management via the GUI
** It is now possible to upload custom certificates from the web interface, or set up a cluster-wide ACME account to automatically get and renew certificates from an ACME provider.
* Support for external SpamAssassin update channels (regular automated updates).
** By providing a short configuration file containing a SpamAssassin rule channel's URL and GPG key, Proxmox Mail Gateway will now fetch verified updates from that channel, along with the updates from updates.spamassassin.org.
** The KAM ruleset channel is now available, and a suitable configuration file is shipped with <code>proxmox-spamassassin</code>.
* Improved Quarantine Management
** The admin view of the Spam Quarantine can now display quarantined mail of all users at once.
** All Quarantine views (admin and user) allow you to filter for subject or sender.
** The spam quarantine can now process huge amounts of mails at once (> 3200).
* TLS-logging improvements to the Tracking Center
** The Tracking Center now shows when an outbound connection is established over TLS.
* Enhancements to the Integration of Proxmox Backup Server
** It is now possible to get notified about the result of a scheduled backup to a configured Proxmox Backup Server Remote.
** Inclusion of the (potentially large) statistics database is now configurable per Remote.
* Notable Bugfixes:
** Support for '/' in the local part of an e-mail address (quarantine and statistics view).

==Proxmox Mail Gateway 6.3==
'''Released 19. November 2020'''

* Based on Debian Buster (10.6)
* Updated SpamAssassin rules
* Kernel 5.4.73
* Proxmox Backup Server Integration<br/>Proxmox Mail Gateway is fully supported by the new Proxmox Backup Server 1.0, released on November 11, 2020:
** Backing up to multiple remote backup servers: You can define multiple remote instances of Proxmox Backup Server to store backups on. In case of a large-scale disaster, they can be quickly restored.
** Scheduled Backups: You can schedule regular backups via the GUI, which will then be automatically triggered by a systemd-timer unit. This removes the need for manual backup creation and individual, scripted solutions.
* Quarantine Link via login-page<br />Users can request mails containing a link to their quarantineview, if enabled by the Admin. This enables users to edit their individual blocklists, even if no mails are in their quarantine. Until now this was only possible for sites using LDAP.
* Improvements to the Tracking Center<br />To further improve user experience in the tracking center, pmg-log-tracker handles certain cases better:
** The case sensitivity has been removed from the search box.
** In case the pmg-smtp-filter fails to process emails due to misconfiguration, they are now marked as rejected.
* Notable Bugfixes:
** DKIM signing now uses the longest matching domain for the 'd=' tag.
** Mails held in the Attachment Quarantine are assigned a new Message-ID - fixing interoperability with certain downstream servers (for example, MS Exchange), which silently discard messages with duplicate Message-IDs.

==Proxmox Mail Gateway 6.2==
'''Released 28. April 2020'''

* Based on Debian Buster (10.3)
** Proxmox Mail Gateway is based on the latest stable release of Debian 10.3 (Buster).
* SpamAssassin 3.4.4
** Proxmox ships the latest upstream release of Apache SpamAssassin with a updated and enhance ruleset (KAM rules added)
* Kernel 5.4
** Proxmox Mail Gateway shares the kernel with Proxmox VE and is based on the 5.4 series from Ubuntu 20.04
* pmg-log-tracker in Rust
** <code>pmg-log-tracker</code> has been extended and reimplemented in the Rust programming language. <code>pmg-log-tracker</code> is the binary at the core of the Message Tracking Center, providing live searchable and grouped logs in the GUI.
** The new <code>pmg-log-tracker</code> has support for parsing and grouping logs in before-queue filtering mode.
** The refresh of the code base of <code>pmg-log-tracker</code> provides an optimized performance and more stability.

* Support for before-queue filtering in the GUI
** With the added support for displaying before-queue filtering logs in the GUI and fixing some minor glitches in that area, the before-queue filtering can now be comfortably enabled in the GUI.

* Improved IPv6 support
** The Mail Proxy's SPF checker also verifies SPF records for those remote mail servers connecting via IPv6.
** Greylisting support for IPv6 addresses (with variable netmask, defaulting to '/64') - needs to be explicitly enabled.
** Who-objects containing IPv6 literal address work now.

* Customizable netmask length for greylist matching
** Instead of fixing a greylist network to a '/24' the administrator can now configure which hosts should be considered as belonging to the same network by setting a larger (or smaller) prefix.
** This can help with receiving mail from some cloud-providers, who send out one mail from different ip addresses within a large network, which usually leads to a rather long delay and sometimes even to a legitimate mail being rejected.
** Due to the changed database layout partial upgrades of clusters will prevent nodes running the older version from syncing the greylist database until they are upgraded.

* Better UX for the User Spam Quarantine interface
** If selected in the Quarantine view, the From header and the Subject are now displayed on top of the mail body.
** It is now possible to delete mail addresses containing certain special characters (for example '/') from a users' black- or whitelist.
** Users can set their preferred language directly in the quarantine interface instead of having to log out to change the setting.
** Fixed a bug in the selection of multiple e-mails.

* Handling of changes to overridden templates with <code>ucf</code>
** Starting with this release all service configuration templates, copied and modified in <code>/etc/pmg/templates</code> get registered with <code>ucf</code>. Should a overridden template change with a new package version the administrator is asked and can accept or reject the changes.
** All users who have templates in <code>/etc/pmg/templates</code> will be asked about the current changes for the initial registration.

* New What Object: 'Match Archive Filename'
** In addition to match files in archives (zip, tar.gz, rar,...) based on the file's content-type, it is also possible to look for particular filename patterns inside of archives.
** This completes the feature matrix of matching files based on content-type or filename, as plain attachments, or inside archives.

* Support for downstream LMTP servers
** In certain setups there is no advantage in having a dedicated SMTP server for receiving e-mails from Proxmox Mail Gateway, since all used functionality is provided by a MTA, which speaks IMAP and LMTP (e.g., Dovecot).
** It is now possible to configure Proxmox Mail Gateway to send e-mails directly to a LMTP relay, both as default transport and only as transport for certain domains.

* Improvements to recently added features
** Before-queue filtering and DKIM signing, both implemented with Proxmox Mail Gateway 6.1, have a better user experience and are considered stable now.
** Some remaining glitches and bugs fixed for both.
** DKIM selector handling can handle the existence of multiple selectors and in the GUI, users can comfortably switch between the active selector.

* TLS policy selection for internal downstream servers
** It is now possible to specify a desired level of encryption and authentication for the opportunistic TLS-encryption (STARTTLS) for downstream servers entered in your transports.
** This can help to ensure that your internal communication is not sent in the clear over the network. It can also be used to work around broken TLS implementations in legacy downstream servers.

* Improvements to general usability
** The unbounded growth of the Quarantine disk usage for non-master nodes in clustered setups is fixed.
** It's now possible to switch to incremental updates of the AV signatures for ClamAV via GUI, alleviating the problem that both methods fail in certain cases for some users.
==Proxmox Mail Gateway 6.1==
'''Released 27. November 2019'''

* Based on Debian Buster (10.2)
** Proxmox Mail Gateway is based on the latest stable release of Debian 10.2 (Buster).
* Updated SpamAssassin rules
* Kernel 5.3
** Proxmox Mail Gateway shares the kernel with Proxmox VE and is based on the 5.3 series from Ubuntu 19.10

* DKIM-Signing
** Support for adding DomainKeys Identified Mail (DKIM) Signatures (RFC 6376) to outbound emails
** Configuration via GUI
** Signing happens after processing the email with the rule system, thus ensuring that it leaves the Proxmox Mail Gateway with a valid signature
** Flexible control of which domains should get signed with sensible defaults (the relay domains)
** Inside a cluster, one common selector minimizes the overhead for adding required DNS entries

* Attachment Quarantine
** The <code>Remove Attachments</code> action can now optionally deliver the complete email to the Attachment Quarantine
** The Attachment Quarantine offers a comfortable GUI for selectively downloading parts of the email for further analysis, or delivering the mail to the original recipient
** Accessible only by the administrators, it offers safety from accidentally open malicious executables, doc-files, and other attachments infected with malware

* Adjustable SpamAssassin Rule Scores via GUI
** Adapt the scores of individual SpamAssassin rules directly in the GUI
** Enables you to adapt the scoring to your environment, thus achieving better ham/spam detection rates
** Mostly for adding a bit of weight to rules, which are good indicators for Spam in your environment
** Selectively disable Rules, which cause false positives for your environment

* Improved handling of Configuration and Rule changes in clustered environments
** The Filtering Engine gets notified about a range of configuration changes which require a reload
** The notification is propagated during the cluster sync
** This reduces the situations where you had to manually restart <code>pmg-smtp-filter</code>

* Experimental Support for Before Queue filtering
** Proxmox Mail Gateway can now optionally reject an email during the SMTP dialogue, instead of accepting it and silently discarding unwanted email
** This is a requirement in certain situations
** By answering with a permanent failure code (<code>554</code>), there is no need to generate a Non-Delivery Report, which could cause your system to get blacklisted, due to Backscatter
** Currently incompatible with the Tracking Center, thus needs to be explicitly enabled in <code>/etc/pmg/pmg.conf</code>

* Improvements to general usability
** Clarification of ambiguously used terms in the GUI and documentation
** More detailed documentation of the Service Configuration Templates
** Downloading of emails larger than 2 MB as <nowiki>eml</nowiki> from the Spam Quarantine now works
** API-Viewer now usable from inside every running PMG installation at https://pmg.local:8006/api-viewer/index.html or just online via https://pmg.proxmox.com/pmg-docs/api-viewer/index.html

==Proxmox Mail Gateway 6.0==
'''Released 27. August 2019'''

*Proxmox Mail Gateway is based on the latest stable release of Debian 10.0 (Buster)
*This major version update provides an easy to follow step-by-step upgrade path - https://pmg.proxmox.com/wiki/index.php/Upgrade_from_5.x_to_6.0
*Rule name logging - each final action now logs the name of the rule which triggered it to the system log
*The system logs get displayed faster in the GUI because they now use the Proxmox `mini-journalreader` instead of `journalctl`
*ClamAV 0.101.4 (fix for https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=934359)
*Postgres 11 (new major version backing the rule system)
*OpenSSL 1.1.1c with support for TLS 1.3
*Updated shipped SpamAssassin Ruleset
*Countless bugfixes and improvements in the GUI labels

==Proxmox Mail Gateway 5.2==
'''Released 20. March 2019'''

*Mobile Quarantine Interface
**based on the small and modern framework7
**Deliver/Delete/Whitelist/Blacklist mails in your Quarantine from your mobile device
*Improvements in the LDAP integration
**allow the use of FQDNs instead of IPs in the WebUI
**add support for certificate verification (and enable it for new deployments)
**add support for LDAP+starttls
*PMG-Appliance template
**Install PMG as a (unprivileged) Linux Container (e.g. in PVE)
**Introduces the new 'proxmox-mailgateway-container' metapackage, which does not depend on a kernel, and results in a vastly reduced size (and fewer updates)
*Improvements in Logging
**pmg-smtp-filter now logs each SA-Rules score in addition to the rule names - simplifying the analysis of the spam filter's performance without the need to access the mail's source
*Improvements in the WebUI's TLS configuration
*pmgproxy can now be configured via '/etc/default/pmgproxy' to disable/enable certain ciphers, compression, cipher selection preference.
*new command: `pmg-system-report`
**Provides a overview of key characteristics of PMG's setup and performance
**Improves the initial diagnosis for our Enterprise support
*.eml download from the (non-mobile) Quarantine Interface
**Lets you download the complete source of a quarantined message in .eml format for further analysis
*Add support for custom checks
**Enable users to integrate their own custom check logic by providing a defined interface, which can optionally be enabled, and runs a custom check before the mail gets handed to the virus scanner and rule system.
*Improvements of Blacklist/Whitelist handling in the Quarantine Interface
**multiselect for removing multiple entries at once
*proxmox-spamassassin
**Update the shipped rulesets
*PMG-Cluster: full IPv6 support
*ISO works on Citrix XenServer
*Documentation available via https://pmg.proxmox.com/pmg-docs
*Bugfixes

==Proxmox Mail Gateway 5.1==
'''Released 05. October 2018'''

*Allow to configure TLS policy via GUI
*New 'helpdesk' role
*Support SMTPUTF8 protocol feature
*GUI improvements
*Update Debian Stretch 9.5
*Update kernel to 4.15
*Bugfixes

==Proxmox Mail Gateway 5.0==
'''Released 23. January 2018'''

*Fully licensed under the open source license AGPL
*Based on Debian Stretch 9.3 with a 4.13.13 kernel
*ISO installer supports all ZFS raid levels
*ExtJS based user interface
*New API
*Integrated documentation
*Subscription-based enterprise support options (similar to the Proxmox VE support subscription model)
*Bug fixes

== Old Releases ==
*Proxmox Mail Gateway 4.1
*Proxmox Mail Gateway 4.0
*Proxmox Mail Gateway 3.1
*Proxmox Mail Gateway 3.0
*Proxmox Mail Gateway 2.6
*Proxmox Mail Gateway 2.5
*Proxmox Mail Gateway 2.4
*Proxmox Mail Gateway 2.3
*Proxmox Mail Gateway 2.2
*Proxmox Mail Gateway 2.1
*Proxmox Mail Gateway 2.0
*Proxmox Mail Gateway 1.7
*Proxmox Mail Gateway 1.6
*Proxmox Mail Gateway 1.5
*Proxmox Mail Gateway 1.4
*Proxmox Mail Gateway 1.3
*Proxmox Mail Gateway 1.2
*Proxmox Mail Gateway 1.1
*Proxmox Mail Gateway 1.0 (April 2005)

Roadmap

2025-10-01T12:06:31Z

Stoiko Ivanov: add PMG 9.0 release notes /* Proxmox Mail Gateway 9.0 BETA */

<div class="toclimit-3">__TOC__</div>

=Roadmap=
*<s>SpamAssassin 4</s> done
*Continuous security and bug fix updates
=Release History=
See also [https://forum.proxmox.com/forums/announcements.7/ Announcement forum]

== Proxmox Mail Gateway 9.0 ==
'''Released 01. October 2025'''

* Based on Debian Trixie (13.1)
* SpamAssassin 4.0.2 (with updated rulesets)
* ClamAV 1.4.3
* PostgreSQL 17
* Latest 6.14.11-2 Kernel as new stable default
* ZFS 2.3.4

=== Highlights ===

* New major release based on the great Debian Trixie.
* New Quarantine UI on mobile browsers based on the modern Rust-based Yew framework.
* Seamless upgrade from Proxmox Mail Gateway 8.2, see [[Upgrade from 8 to 9]]
* Single-Sign-On (SSO) with OpenID Connect, and multiple authentication realms for PMG: These were introduced with PMG 8.2 and were since significantly improved based on the feedback from our customers and community.
* Synchronize the configuration templates of the core service <code>postfix</code> with the latest recommendations from upstream.
* Adapt the Content-Type filters to the renaming of relevant MIME-types for Microsoft executable formats.

=== Changelog Overview ===

==== Enhancements in the Web Interface (GUI) ====
* New Quarantine UI on mobile browers based on the Rust based Yew framework, in place of the one based on framework7.
* The non-mobile Quarantine UI offers a button to switch to the mobile version and recommends switching on displays which are too narrow for comfortable work with it.
* An XSS vulnerability for the HTTP proxy setting was fixed. See the corresponding Proxmox Security Advisory [https://forum.proxmox.com/threads/proxmox-mail-gateway-security-advisories.149333/post-798035 PSA-2025-00015-1] for further information.
* It is now possible to define an authentication realm as default instead of the hard-coded internal <code>pmg</code> realm.
* OpenID Connect realms can now be configured in the GUI, including the <code>username-claim</code>, and the default role to be assigned to auto-created users.
* All labels and widgets containing the terms "blacklist" and "whitelist" were renamed to "blocklist" and "welcomelist," respectively ([https://bugzilla.proxmox.com/show_bug.cgi?id=3755 issue 3755]).
* Allow selecting multiple mails in the <code>postfix</code> queue administration widget for delivery or deletion ([https://bugzilla.proxmox.com/show_bug.cgi?id=3450 issue 3450]).
* Improve the configuration and display of DNSBL sites in the Mail Proxy (<code>postscreen_dnsbl_sites</code>)([https://bugzilla.proxmox.com/show_bug.cgi?id=3284 issue 3284]).
* Make the SpamInfo text selectable in the Spam Quarantine interface.
* Improved handling of translations:
** Add support for plural forms and ngettext usage.
** Translations can now contain comments that are extracted from the source code and provide useful context for translators.
* Updated translations, among others:
** Czech (new!)
** Arabic
** Bulgarian
** French
** German
** Italian
** Japanese
** Korean
** Polish
** Russian
** Simplified Chinese
** Spanish
** Swedish
** Traditional Chinese
** Ukrainian

==== Enhancements in the Mail Gateway API Backend ====

* Improvements of OpenID Connect realms, which were introduced in Proxmox Mail Gateway 8.2:
** Fix an error when logging in the first time to a secondary node as a user in an OIDC realm with enabled auto-creation.
** The validation for OIDC <code>client-id</code> and <code>client-key</code> was aligned with the [https://www.rfc-editor.org/rfc/rfc6749#appendix-A relevant RFC].
** The <code>pmg</code> realm is not hard-coded as the default realm anymore, allowing to select a different default realm.
* The <code>pmgqm</code> utility used for sending spam reports to users now supports timespans between 1 and 24 hours in addition to <code>today</code>,<code>yesterday</code> and <code>week</code>([https://bugzilla.proxmox.com/show_bug.cgi?id=2452 issue 2452]).
* Fix an issue where a disallowed value for the Destination TLS policy was accepted by the backend.
* Leading and trailing whitespace in the <code>__MSGID__</code> macro in the rule system (containing the <code>Message-ID</code> header) is now trimmed.
* The TLS-inbound domains are now added to the Proxmox Mail Gateway system report used in Enterprise support.
* Mails generated by Proxmox Mail Gateway now have a <code>Date</code> header allowing them to have a valid DKIM signature.
* The Date header for autogenerated mails is set with a fixed locale to have it compliant with [https://www.rfc-editor.org/rfc/rfc5322 RFC5322].
* An issue of <code>pmgtunnel</code> exiting with errors due to not correctly adapting to changes in the network information parsing code was repaired by fixing its handling of child processes.
* With the upgrade to Debian Trixie, the <code>application/x-ms-dos-executable</code> MIME-Type was renamed to <code>application/vnd.microsoft.portable-executable</code> and <code>application/x-msdownload</code>. As <code>exe</code> files are filtered out in the default ruleset and are usually considered special when handling mails, the existing rules are automatically adapted.
* The <code>postfix</code> MTA package used by PMG was significantly reworked and improved upstream. PMG was adapted to the changes:
** <code>postfix</code> is now explicitly configured to run without <code>chroot</code> confinement ([https://bugzilla.proxmox.com/show_bug.cgi?id=5323 issue 5323]).
*: The processes were running without <code>chroot</code> since version 5.0, the change now is only making this explicit in the configuration files.
*: The change is in accordance with [https://salsa.debian.org/postfix-team/postfix-dev/-/blob/debian/master/debian/README.Debian?ref_type=heads#L44 Debian's recommendation] and in line with [https://www.postfix.org/COMPATIBILITY_README.html#chroot upstream].
** The <code>postfix@-</code> default instance was dropped in favor of directly using <code>postfix</code>
** Deprecations in the shipped postfix configuration templates were fixed, and the [https://www.postfix.org/COMPATIBILITY_README.html compatibility level] was raised to 3.11.
* The Debian repository sources shipped for the <code>pmg-enterprise</code> repository were adapted to the preferred Deb822 format.
* A change in the upstream <code>clamav-freshclam</code> package caused the daemon not to be enabled automatically since PMG 8.1. Now the <code>pmg-api</code> package enables the service in its <code>postinst</code> maintainer script.
* The <code>pmgproxy</code> and <code>pmgdaemon</code> HTTP API servers were adapted to the paths used by the new Yew-based mobile quarantine UI.
* The locale files served by the HTTP API servers now return their modification times to facilitate caching.
* Spam reports send to users and the system status report sent to administrators now have a <code>text/plain</code> version in addition to <code>text/html</code>([https://bugzilla.proxmox.com/show_bug.cgi?id=4023 issue 4023]) ([https://bugzilla.proxmox.com/show_bug.cgi?id=1621 issue 1621]).
* Adding a custom ACME provider via the <code>pmgconfig</code> command line utility was fixed for Proxmox Mail Gateway ([https://bugzilla.proxmox.com/show_bug.cgi?id=6748 issue 6748]).
* Improvements to handling external mail-sources via <code>fetchmail</code>:
** <code>fetchmail</code> changed the semantics of TLS related parameters in version <code>6.4.0</code>. The issue of not being able to connect to a system via plaintext session without StartTLS/implicit TLS was fixed ([https://bugzilla.proxmox.com/show_bug.cgi?id=6798 issue 6798]).
** Changing the configuration of <code>fetchmail</code> accounts now triggers a restart of the <code>fetchmail</code> daemon, resulting in the changes being live directly.
** The <code>fetchmail</code> package used for downloading mails via POP/IMAP to be processed by Proxmox Mail Gateway now ships a systemd-unit file instead of a legacy sysv-init script. This is a change to Debian upstream's version.
* Fix a spurious warning by the <code>pmgproxy</code> API server daemon, when sending a <code>Cookie</code> header without a valid authentication ticket.
* Fix a spurious warning during early boot due to <code>/run/pmg-smtp-filter.cfg</code> not being in place yet.
* Ensure the <code>pmgspamreport.timer</code> and <code>pmgreport.timer</code> units are run after their prerequisites have started on reboot
* Allow all <code>admin</code> users to see the list of known MIME-Types, when adding ContentType filter objects ([https://bugzilla.proxmox.com/show_bug.cgi?id=5438 issue 5438]).
* Allow providing a list of <code>postfix</code> queue-ids and action (<code>deliver,delete</code>) to the <code>/nodes/{node}/postfix/queue/{queue}</code> to delete or flush multiple mails at once ([https://bugzilla.proxmox.com/show_bug.cgi?id=3450 issue 3450]).

==== Installation ISO ====

* Install the microcode package matching the current platform.
*: This ensures that new Proxmox Mail Gateway installations get available fixes for CPU security issues and other CPU bugs.
*: This also means that installations now have the <code>non-free-firmware</code> repository enabled.
*: To get microcode updates that were released after the ISO was built, hosts have to be updated regularly. Microcode updates need a reboot to go into effect.
* Ignore network interfaces without a valid MAC address instead of aborting the installation.
* Check that the configured LVM swapsize is not greater than half the disk size ([https://bugzilla.proxmox.com/show_bug.cgi?id=5887 issue 5887]).
* Handle the case where the DHCP lease includes the search domain in the Host Name option.
* Improve error reporting for disk and RAID checks.
* Improvements to the text-based installer and <code>proxmox-auto-install-assistant</code>:
** Improve error reporting when encountering an invalid CIDR.
** Add plausibility checks for subnet masks and IPv4 address.
* Improvements to the automated installation:
** Handle the case where the answer file provides an empty search domain.
** Check the number of disks for RAID configurations already when parsing the answer file to catch invalid configurations earlier.
** Warn if the answer file contains deprecated <code>snake_case</code> keys.
** Check for duplicate disks in the answer file.
* Improve robustness of installing on Btrfs.
* Align the plausibility checks performed by the GUI and TUI installers in case of an installation on Btrfs and a single disk.
* Improve the visibility of CLI errors by printing an additional newline.
* Provide <code>--verify-root-password</code> as option for <code>proxmox-auto-install-assistant</code>, to catch mistakes before installation.
* Set the <code>postfix</code> compatibility level to <code>3.6</code> for all products.
*: Note that this affects all products **apart from Proxmox Mail Gateway**, which sets it to <code>3.11</code> through the templating system.
* The timezone is now set earlier before configuring <code>postfix</code> to ensure it's set correctly if <code>postfix</code> runs in <code>chroot</code>.
*: Note that this affects all products **apart from Proxmox Mail Gateway**, which runs <code>postfix</code> without <code>chroot</code>.
* Do not create the deprecated <code>/etc/timezone</code> in alignment with [https://metadata.ftp-master.debian.org/changelogs//main/t/tzdata/tzdata_2025b-4_changelog Debian upstream].
* Ensure that <code>clamav-freshclam</code> is enabled after installation - see the [https://salsa.debian.org/clamav-team/clamav/-/merge_requests/7 patch submitted upstream for more information].

==== Notable changes ====

<div id="9.0-known-issues"></div>

=== Known Issues & Breaking Changes ===

==== The Test Repository Is Now Named pmg-test ====

For consistency with existing repositories, the <code>pmgtest</code> repository is now spelled <code>pmg-test</code>.

==== Breaking Changes in the Proxmox Mail Gateway API ====

* The "Google Safe Browsing" option for <code>ClamAV</code>, which is deprecated since PMG 7.0, in <code>pmg.conf</code> was dropped.
* The superfluous fields <code>network_address</code> and <code>prefix_size</code> returned by the <code>/config/mynetworks</code> API call were dropped, as <code>cidr</code> contains the same information.
* The <code>ReportSpam</code>, <code>Attach</code>, and <code>Counter</code> actions, which were not exposed since at least PMG 5.0, and deprecated in PMG 7.2, were dropped from the database handling code.
* Changing the password of a user via <code>PUT /access/users/{userid}</code> has been dropped in favor of the <code>/access/password</code> API call. The GUI is using <code>/access/password</code> since at least 2017.
* Adding and removing entries in the block- and welcomelists of users are now done by the master node in a cluster ([https://bugzilla.proxmox.com/show_bug.cgi?id=4392 issue 4392]).
* The API has renamed all black-/whitelist API calls to block-/welcomelist respectively ([https://bugzilla.proxmox.com/show_bug.cgi?id=3755 issue 3755]).
*: The old API calls are still present for backward compatibility but will be dropped with the next major release.
*: As these calls were also used in the templates for the spamreport e-mails sent to users, which are often modified by administrators, we recommend adapting your overridden configuration templates.
* The <code>pmail_raw</code> variable available to the template for the spam reports sent to users has been renamed to <code>pmail_plain</code> to match the other variables formatted for plain-text reports.
*: This variable was never used by a template shipped by Promxox Mail Gateway, thus it is very unlikely to have been used in a modification.

==== Potential changes in network interface names ====

Proxmox Mail Gateway 9 can now transparently handle many network interface name changes.

These changes may occur when upgrading from Proxmox Mail Gateway 8.x to Proxmox Mail Gateway 9.0 due to new naming scheme policies or the added support for new NIC features. For example, this may happen when upgrading from Kernel 6.8 to Kernel 6.14.
If the previous primary name remains available as an alternative name, manual intervention may not be necessary since Proxmox Mail Gateway 9.0 allows the use of alternative names in network configurations and firewall rules.

However, in some cases, the previous primary name might not be available as an alternative name after the upgrade. In such cases, manual reconfiguration after the upgrade is currently still necessary.

Before upgrading, you can use the <code>proxmox-network-interface-pinning</code> CLI tool to pin network interfaces to custom names.
For details, see the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_overriding_network_device_names Overriding Network Device Names] section in the reference documentation.

==== Fresh installation from the Proxmox VE container template does not work with dhcp as network configuration ====

Installations done with the Proxmox VE <code>pct</code> appliance template will currently not work when configured to use DHCP for network configuration.
This is related to <code>isc-dhcp-client</code> package being EOL, and due to the use of <code>ifupdown2</code> for network configuration in Promxox Mail Gateway.
Installations upgraded from version 8.2, and installations using static IP configuration (as is recommended in general) are not affected. See also the
the related bug-reports: [https://bugzilla.proxmox.com/show_bug.cgi?id=6644 issue 6644], [https://bugzilla.proxmox.com/show_bug.cgi?id=6777 issue 6777], [https://bugzilla.proxmox.com/show_bug.cgi?id=6784 issue 6784].

==== AppArmor 4 ====

Proxmox Mail Gateway 9 ships with AppArmor version 4.1.
Since this version is relatively new, you might see regressions in packages, for example <code>clamav</code>, or software that is not part of the core Proxmox Mail Gateway distribution, for example the CUPS printing daemon.

Most issues with older profiles can be resolved by configuring AppArmor to use the 3.0 ABI by adding the <code>abi <abi/3.0>,</code> rule to the relevant profile.
For more details, see the [https://gitlab.com/apparmor/apparmor/-/wikis/apparmorpolicyfeaturesABI AppArmor Wiki].

==== systemd logs "System is tainted: unmerged-bin" after boot ====

It is recommended to ignore this message. See the [https://www.debian.org/releases/trixie/release-notes/issues.en.html#systemd-message-system-is-tainted-unmerged-bin Debian Trixie release notes] for more details.

== Proxmox Mail Gateway 9.0 BETA ==
'''Released 24. September 2025'''

{{Note|This is a test version that is not yet intended for production use. The release notes will be continuously updated during the beta phase.}}

* Based on Debian Trixie (13.1)
* SpamAssassin 4.0.2 (with updated rulesets)
* ClamAV 1.4.3
* PostgreSQL 17
* Latest 6.14.11-2 Kernel as new stable default
* ZFS 2.3.4

=== Highlights ===

* New major release based on the great Debian Trixie.
* New Quarantine UI on mobile browsers based on the modern Rust-based Yew framework.
* Seamless upgrade from Proxmox Mail Gateway 8.2, see [[Upgrade from 8 to 9]]
* Single-Sign-On (SSO) with OpenID Connect, and multiple authentication realms for PMG, which were introduced with PMG 8.2 got significantly improved based on the feedback from our customers and community.
* Synchronize the configuration templates of the core service <code>postfix</code> with the latest recommendations from upstream.
* Adapt the Content-Type filters to the renaming of relevant MIME-types for Microsoft executable formats.

=== Changelog Overview ===

<div id="9.0-rule-system-enhancements"></div>
==== Enhancements in the Rule System ====

==== Enhancements in the Web Interface (GUI) ====
* New Quarantine UI on mobile browers based on the Rust based Yew framework, in place of the one based on framework7.
* The non-mobile Quarantine UI offers a button to switch to the mobile version and recommends switching on displays which are too narrow for comfortable work with it.
* An XSS vulnerability for the HTTP proxy setting was fixed. See the corresponding Proxmox Security Advisory [https://forum.proxmox.com/threads/proxmox-mail-gateway-security-advisories.149333/post-798035 PSA-2025-00015-1] for further information.
* It is now possible to define an authentication realm as default instead of the hard-coded internal <code>pmg</code> realm.
* OpenID Connect realms can now be configured in the GUI, including the <code>username-claim</code>, and the default role to be assigned to auto-created users.
* All labels and widgets containing the terms "blacklist" and "whitelist" were renamed to "blocklist" and "welcomelist," respectively ([https://bugzilla.proxmox.com/show_bug.cgi?id=3755 issue 3755]).
* Improve the configuration and display of DNSBL sites in the Mail Proxy (<code>postscreen_dnsbl_sites</code>)([https://bugzilla.proxmox.com/show_bug.cgi?id=3284 issue 3284]).
* Make the SpamInfo text selectable in the Spam Quarantine interface.
* Improved handling of translations:
** Add support for plural forms and ngettext usage.
** Translations can now contain comments that are extracted from the source code and provide useful context for translators.
* Updated translations, among others:
** Czech (new!)
** Arabic
** Bulgarian
** French
** German
** Italian
** Japanese
** Korean
** Polish
** Russian
** Simplified Chinese
** Spanish
** Swedish
** Traditional Chinese
** Ukrainian

==== Enhancements in the Mail Gateway API Backend ====

* Improvements of OpenID Connect realms, which were introduced in Proxmox Mail Gateway 8.2:
** Fix an error when logging in the first time to a secondary node as a user in an OIDC realm with enabled auto-creation.
** The validation for OIDC <code>client-id</code> and <code>client-key</code> was aligned with the [https://www.rfc-editor.org/rfc/rfc6749#appendix-A relevant RFC].
** The <code>pmg</code> realm is not hardcoded as the default realm anymore, allowing to select a different default realm.
* The <code>pmgqm</code> utility used for sending spam reports to users now supports timespans between 1 and 24 hours in addition to <code>today</code>,<code>yesterday</code> and <code>week</code>([https://bugzilla.proxmox.com/show_bug.cgi?id=2452 issue 2452]).
* Fix an issue where a disallowed value for the Destination TLS policy was accepted by the backend.
* Leading and trailing whitespace in the <code>__MSGID__</code> macro in the rule system (containing the <code>Message-ID</code> header) is now trimmed.
* The TLS-inbound domains are now added to the Proxmox Mail Gateway system report used in Enterprise support.
* Mails generated by Proxmox Mail Gateway now have a <code>Date</code> header allowing them to have a valid DKIM signature.
* The Date header for autogenerated mails is set with a fixed locale to have it compliant with [https://www.rfc-editor.org/rfc/rfc5322 RFC5322].
* An issue of <code>pmgtunnel</code> exiting with errors due to not correctly adapting to changes in the network information parsing code was repaired by fixing its handling of child processes.
* With the upgrade to Debian Trixie, the <code>application/x-ms-dos-executable</code> MIME-Type was renamed to <code>application/vnd.microsoft.portable-executable</code> and <code>application/x-msdownload</code>. As <code>exe</code> files are filtered out in the default ruleset and are usually considered special when handling mails, the existing rules are automatically adapted.
* The <code>postfix</code> MTA package used by PMG was significantly reworked and improved upstream. PMG was adapted to the changes:
** <code>postfix</code> is now explicitly configured to run without <code>chroot</code> confinement ([https://bugzilla.proxmox.com/show_bug.cgi?id=5323 issue 5323]).
*: The processes were running without <code>chroot</code> since version 5.0, the change now is only making this explicit in the configuration files.
*: The change is in accordance with [https://salsa.debian.org/postfix-team/postfix-dev/-/blob/debian/master/debian/README.Debian?ref_type=heads#L44 Debian's recommendation] and in line with [https://www.postfix.org/COMPATIBILITY_README.html#chroot upstream].
** The <code>postfix@-</code> default instance was dropped in favor of directly using <code>postfix</code>
** Deprecations in the shipped postfix configuration templates were fixed, and the [https://www.postfix.org/COMPATIBILITY_README.html compatibility level] was raised to 3.11.
* The Debian repository sources shipped for the <code>pmg-enterprise</code> repository were adapted to the preferred Deb822 format.
* A change in the upstream <code>clamav-freshclam</code> package caused the daemon not to be enabled automatically since PMG 8.1. Now the <code>pmg-api</code> package enables the service in its <code>postinst</code> maintainer script.
* The <code>pmgproxy</code> and <code>pmgdaemon</code> HTTP API servers were adapted to the paths used by the new Yew-based mobile quarantine UI.
* The locale files served by the HTTP API servers now return their modification times to facilitate caching.
* Spamreports send to users and the system status report sent to administrators now have a <code>text/plain</code> version in addition to <code>text/html</code>([https://bugzilla.proxmox.com/show_bug.cgi?id=4023 issue 4023]) ([https://bugzilla.proxmox.com/show_bug.cgi?id=1621 issue 1621]).
* Adding a custom ACME provider via the <code>pmgconfig</code> command line utility was fixed for Proxmox Mail Gateway ([https://bugzilla.proxmox.com/show_bug.cgi?id=6748 issue 6748]).
* The <code>fetchmail</code> package used for downloading mails via POP/IMAP to be processed by Proxmox Mail Gateway now ships a systemd-unit file instead of a legacy sysv-init script. This is a change to Debian upstream's version.
* Fix a spurious warning by the <code>pmgproxy</code> API server daemon, when sending a <code>Cookie</code> header without a valid authentication ticket.
* Fix a spurious warning during early boot due to <code>/run/pmg-smtp-filter.cfg</code> not being in place yet.
* Ensure the <code>pmgspamreport.timer</code> and <code>pmgreport.timer</code> units are run after their prerequisites have started on reboot
* Allow all <code>admin</code> users to see the list of known MIME-Types, when adding ContentType filter objects ([https://bugzilla.proxmox.com/show_bug.cgi?id=5438 issue 5438]).

==== Installation ISO ====

* Install the microcode package matching the current platform.
*: This ensures that new Proxmox Mail Gateway installations get available fixes for CPU security issues and other CPU bugs.
*: This also means that installations now have the <code>non-free-firmware</code> repository enabled.
*: To get microcode updates that were released after the ISO was built, hosts have to be updated regularly. Microcode updates need a reboot to go into effect.
* Ignore network interfaces without a valid MAC address instead of aborting the installation.
* Check that the configured LVM swapsize is not greater than half the disk size ([https://bugzilla.proxmox.com/show_bug.cgi?id=5887 issue 5887]).
* Handle the case where the DHCP lease includes the search domain in the Host Name option.
* Improve error reporting for disk and RAID checks.
* Improvements to the text-based installer and <code>proxmox-auto-install-assistant</code>:
** Improve error reporting when encountering an invalid CIDR.
** Add plausibility checks for subnet masks and IPv4 address
* Improvements to the automated installation:
** Handle the case where the answer file provides an empty search domain.
** Check the number of disks for RAID configurations already when parsing the answer file to catch invalid configurations earlier.
** Warn if the answer file contains deprecated <code>snake_case</code> keys.
** Check for duplicate disks in the answer file.
* Improve robustness of installing on Btrfs.
* Align the plausibility checks performed by the GUI and TUI installers in case of an installation on Btrfs and a single disk.
* Improve the visibility of CLI errors by printing an additional newline.
* Provide <code>--verify-root-password</code> as option for <code>proxmox-auto-install-assistant</code>, to catch mistakes before installation.
* Set the <code>postfix</code> compatibility level to <code>3.6</code> for all products
* The timezone is now set earlier before configuring <code>postfix</code> to ensure it's set correctly if <code>postfix</code> runs in <code>chroot</code>.
*: Note that this affects all products **apart from Proxmox Mail Gateway**, which runs <code>postfix</code> without <code>chroot</code>
* Do not create the deprecated <code>/etc/timezone</code> in alignment with [https://metadata.ftp-master.debian.org/changelogs//main/t/tzdata/tzdata_2025b-4_changelog Debian upstream].
* Ensure that <code>clamav-freshclam</code> is enabled after installation - see the [https://salsa.debian.org/clamav-team/clamav/-/merge_requests/7 patch submitted upstream for more information].

==== Notable changes ====

<div id="9.0-known-issues"></div>

=== Known Issues & Breaking Changes ===

==== The Test Repository Is Now Named pmg-test ====

For consistency with existing repositories, the <code>pmgtest</code> repository is now spelled <code>pmg-test</code>.

==== Breaking Changes in the Proxmox Mail Gateway API ====

* The "Google Safe Browsing" option for <code>ClamAV</code>, which is deprecated since PMG 7.0, in <code>pmg.conf</code> was dropped.
* The superfluous fields <code>network_address</code> and <code>prefix_size</code> returned by the <code>/config/mynetworks</code> API call were dropped, as <code>cidr</code> contains the same information.
* The <code>ReportSpam</code>, <code>Attach</code>, <code>Counter</code> actions, which were not exposed since at least PMG 5.0, and deprecated in PMG 7.2, were dropped from the database handling code.
* Changing the password of a user via <code>PUT /access/users/{userid}</code> has been dropped in favor of the <code>/access/password</code> API call. The GUI is using <code>/access/password</code> since at least 2017.
* Adding and removing entries in the block- and welcomelists of users are now done by the master node in a cluster ([https://bugzilla.proxmox.com/show_bug.cgi?id=4392 issue 4392]).
* The API has renamed all black-/whitelist API calls to block-/welcomelist respectively ([https://bugzilla.proxmox.com/show_bug.cgi?id=3755 issue 3755]).
*: The old API calls are still present for backward compatibility but will be dropped with the next major release.
*: As these calls were also used in the templates for the spamreport e-mails sent to users, which are often modified by administrators, we recommend adapting your overridden configuration templates.
* The <code>pmail_raw</code> variable available to the template for the spam reports sent to users has been renamed to <code>pmail_plain</code> to match the other variables formatted for plain-text reports.
*: This variable was never used by a templated shipped by Promxox Mail Gateway, thus it is very unlikely to have been used in a modification.

==== Potential changes in network interface names ====

Proxmox Mail Gateway 9 can now transparently handle many network interface name changes.

These changes may occur when upgrading from Proxmox Mail Gateway 8.x to Proxmox Mail Gateway 9.0 due to new naming scheme policies or the added support for new NIC features. For example, this may happen when upgrading from Kernel 6.8 to Kernel 6.14.
If the previous primary name remains available as an alternative name, manual intervention may not be necessary since Proxmox Mail Gateway 9.0 allows the use of alternative names in network configurations and firewall rules.

However, in some cases, the previous primary name might not be available as an alternative name after the upgrade. In such cases, manual reconfiguration after the upgrade is currently still necessary.

Before upgrading, you can use the <code>pve-network-interface-pinning</code> CLI tool to pin network interfaces to custom names.
For details, see the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_overriding_network_device_names Overriding Network Device Names] section in the reference documentation.

==== AppArmor 4 ====

Proxmox Mail Gateway 9 ships with AppArmor version 4.1.
Since this version is relatively new, you might see regressions in packages that are not part of the core Proxmox Mail Gateway distribution, for example, <code>clamav</code> or the CUPS printing daemon.

Most issues with older profiles can be resolved by configuring AppArmor to use the 3.0 ABI by adding the <code>abi <abi/3.0>,</code> rule to the relevant profile.
For more details, see the [https://gitlab.com/apparmor/apparmor/-/wikis/apparmorpolicyfeaturesABI AppArmor Wiki].

==== systemd logs "System is tainted: unmerged-bin" after boot ====

It is recommended to ignore this message. See the [https://www.debian.org/releases/trixie/release-notes/issues.en.html#systemd-message-system-is-tainted-unmerged-bin Debian Trixie release notes] for more details.

== Proxmox Mail Gateway 8.2 ==
'''Released 27. February 2025'''

* Based on Debian Bookworm (12.9)
* SpamAssassin 4.0.1 (with updated rulesets)
* ClamAV 1.0.7
* PostgreSQL 15.11
* Latest 6.8 Kernel as new stable default
* Newer 6.11 Kernel as opt-in
* ZFS 2.2.7

=== Highlights ===

* Support for multiple authentication realms, known from Proxmox VE and Proxmox Backup Server.
* Single-Sign-On (SSO) with the new OpenID Connect access realm type as first new realm.
*: External authorization servers can now be integrated for management access with Proxmox Mail Gateway, either using existing public services or your own identity and access management solution, for example, Keycloak, Zitadel or LemonLDAP::NG.
* Support for automated and unattended installation of Proxmox Mail Gateway.
*: Proxmox VE now ships a tool that prepares a Proxmox Mail Gateway ISO for automated installation.
*: The prepared ISO retrieves all required settings for automated installation from an answer file.
*: The answer file can be provided directly in the ISO, on an additional disk such as a USB flash drive, or over the network.
* Rule System: New option for the Content-Type What Objects, to ignore externally provided type information from the filename and header, and rely solely on file signature based detection.
* Rule System: New option for Match Field What Object, to restrict matching on the top header section, instead of also matching headers in attached emails.
* Mails generated by the Proxmox Mail Gateway processing stack can now be signed with DKIM.
* The Proxmox team has been tracking security-relevant issues in our software explicitly and publishes them in the [https://forum.proxmox.com/threads/149333/ Community Forum] since January 2024.
* Seamless upgrade from Proxmox Mail Gateway 7.3, see [https://pmg.proxmox.com/wiki/index.php/Upgrade_from_7_to_8 Upgrade from 7 to 8].

=== Changelog Overview ===

<div id="8.2-rule-system-enhancements"></div>
==== Enhancements in the Rule System ====
* Add an option to the Match Field What Object to only consider the headers of the top mail-part, instead of also comparing the headers of all attachments (including emails forwarded as attachment [https://bugzilla.proxmox.com/show_bug.cgi?id=2709 issue 2709]).
* Optionally restrict Content-Type What Object to only match based on the signature detected in the content of the file, disregarding the <code>Content-Type:</code> and the recommended filename header information ([https://bugzilla.proxmox.com/show_bug.cgi?id=2691 issue 2691] [https://bugzilla.proxmox.com/show_bug.cgi?id=5618 issue 5618]).

==== Enhancements in the Web Interface (GUI) ====
* The end-user quarantine interface now has a short help page explaining its purpose and the available keyboard shortcuts ([https://bugzilla.proxmox.com/show_bug.cgi?id=4311 issue 4311]).
* The listing of Who, What and When Objects can now optionally also display the description set for each object group, without explicitly selecting it.
* Fix an XSS issue in the Mail Queue view.
*: See [https://forum.proxmox.com/threads/149333/post-730687 PSA-2024-00015-1] for details.
* Fix the display message when removing a rule object, to not include the html-escaped icon.
* Fix a typo in the suggested default text when creating new notification objects.
* Remove whitespace before or after the subscription key when adding a new one, as they usually are copy-pasted.
* Fix the public-key DNS record displaying for DKIM selectors larger than 2048 bit.
* Clarify the label for DKIM domain selection.
* Enable autocompletion hints for the username, password, and TFA input fields to improve compatibility with password managers ([https://bugzilla.proxmox.com/show_bug.cgi?id=5251 issue 5251]).
* Show only installed services in the node's system panel by default, but optionally allow to show all services ([https://bugzilla.proxmox.com/show_bug.cgi?id=5611 issue 5611]).
* Fix an issue where clicking on an external link to the GUI would display a login screen, even if the current session was still valid.
* Fix an issue where the date picker would choose the wrong date after changing to a different month.
* Fix an issue where edit windows would not be correctly masked while loading.
* Display the end-of-life message as a notice up until three weeks before the end-of-life date, and display it as a warning from that point on.
* Move the "Reset" button for edit windows to an icon-only button in the title bar ([https://bugzilla.proxmox.com/show_bug.cgi?id=5277 issue 5277]).
*: This reduces the risk of misclicking and accidentally resetting form data.
* Improved translations, among others:
** Bulgarian (NEW!)
** French
** German
** Italian
** Japanese
** Korean
** Russian
** Simplified Chinese
** Spanish
** Traditional Chinese
** Ukrainian

==== Enhancements in the Mail Gateway API Backend ====
* You can now configure the <code>From</code> header information used for mails from the system itself:
** When sending admin reports
** Notifications from a notify action
** Backup jobs
** Bounces for messages refused for part of the recipients if before queue filtering is used and NDR on block is enabled.
*: For spam reports and quarantine links this could already be set in the Spam Quarantine options.
*: The emails still use an empty envelope from address, or for some cases <code>postmaster</code>
*: If this is set to contain an email address with a domain name, and DKIM signing based on header is enabled, the mails are now signed with DKIM ([https://bugzilla.proxmox.com/show_bug.cgi?id=4658 issue 4658]).
* Fix enabling custom SpamAssassin scores on systems where <code>/var/cache</code> is on a different filesystem from <code>/etc</code>.
*: Any pending changes will be preserved across the upgrade.
* Fix a post-authentication privileged file read vulnerability in the Proxmox Mail Gateway API.
*: See [https://forum.proxmox.com/threads/proxmox-mail-gateway-security-advisories.149333/post-705346 PSA-2024-00009-1] for details.
* Make the static email containing the quarantine access link into a template, helping deployments with predominantly non-English speaking users ([https://bugzilla.proxmox.com/show_bug.cgi?id=4211 issue 4211]).
* Support having a <code>text/plain</code> alternative part for report emails generated by PMG, like the daily admin report and the spam quarantine report send to users.
* Fix the default examples for the Who Objects to use a domain (<code>fromthisdomain.example</code>) reserved for documentation and examples ([https://bugzilla.proxmox.com/show_bug.cgi?id=5972 issue 5972]).
* Include the failure to DKIM sign a mail in the Tracking Center output, by adding the internal queue-id to the log message.
* Prevent a mail from being delivered multiple times when a user clicks on the deliver-button in their spam report multiple times ([https://bugzilla.proxmox.com/show_bug.cgi?id=6126 issue 6126]).
* Include the receiver email address when logging release or deletion from the quarantine.
* Fix the custom check script interface to also allow negative spam-scores as result.
* Fix an issue where comments set for LDAP profiles did not preserve percent encodings.
* Clarify that links are not displayed as links, but as plain-text when enabling the <code>allowhrefs</code> option.
* Use a lower level perl routine for setting file-contents to reduce write amplification.
* Use double-hyphen as argument prefix instead of the outdated single-hyphen in CLI commands documentation.
* Fix an issue where the documentation for CLI aliases did not mention the complete aliased command.
* Reload all Proxmox Mail Gateway services when the <code>proxmox-spamassassin</code> package is updated to a new version.

==== Access Control ====
* Realm System ported from Proxmox VE.
*: Enables you to configure multiple external authentication realms for users in the administration backend.
* Single-Sign-On (SSO) with the new OpenID Connect access realm type as first new realm.
*: External authorization servers can now be integrated for management access with Proxmox Mail Gateway, either using existing public services or your own identity and access management solution, for example, Keycloak, Zitadel or LemonLDAP::NG.
*: With the ability to auto-create users upon first logging it.
*: Roles for auto-created users can be queried from a configurable role-claim on your OpenID Connect service, or use a fixed role for all auto-created user of a realm.
*: Initial login for an auto-created user in a cluster needs to be done on the primary/master node.

==== Notable bugfixes and general improvements ====

* Since the release of Proxmox Mail Gateway 8.1 the Proxmox team has begun [https://forum.proxmox.com/forums/security-advisories.26/ tracking explicit security issues publicly in our forum]. The thread lists all security issues since January 2024.
*: Following the posts there is highly recommended.
* Fix an RCE vulnerability in the shim bootloader used for Secure Boot support.
*: See [https://forum.proxmox.com/threads/proxmox-virtual-environment-security-advisories.149331/post-678937 PSA-2024-00007-1] for details.
* Fix unexpected behavior in handling single-part attachments in the rule system.
*: See [https://forum.proxmox.com/threads/proxmox-mail-gateway-security-advisories.149333/post-728656 PSA-2024-00012-1] for details.
* Fix the <code>pmg7to8</code> tool to identify the newer released <code>proxmox-kernel</code> series (6.5, 6.8, 6.11) as expected kernel versions.
* Add a section to the <code>pmg7to8</code> tool for checking potential issues in the currently configured ruleset.
* Increase the minimum password length to 8, following NIST recommendation and the change in the installer
* Include information about the routing table in the <code>pmg-system-report</code> tool used for Enterprise Support information collection.
* Add anchors to subsections of the documentation to provide links to the specific point where an option is documented.
* Document the steps needed to activate a custom SpamAssassin configuration ([https://bugzilla.proxmox.com/show_bug.cgi?id=3979 issue 3979]).

==== Installation ISO ====
* Support for automated and unattended installation of Proxmox Mail Gateway, as already released for Proxmox VE 8.2 and Proxmox Backup Server 3.2.
*: Introduce the <code>proxmox-auto-install-assistant</code> tool that prepares an ISO for automated installation.
*: The automated installation ISO reads all required settings from an answer file in TOML format.
*: One option to provide the answer file is to directly add it to the ISO. Alternatively, the installer can retrieve it from a specifically-labeled partition or via HTTPS from a specific URL.
*: If the answer file is retrieved via HTTPS, URL and fingerprint can be directly added to the ISO, or obtained via DHCP or DNS.
*: See the [https://pve.proxmox.com/wiki/Automated_Installation wiki page on Automated Installation] for more details.
* Ship the recent version 7.20 of memtestx86+, adding support for current CPU Generations (Intel's Arrow Lake and Ryzen 9000 series) as well as preliminary NUMA support.
* Fix an issue where setting ZFS compression to <code>off</code> did not have any effect, due to a change in upstream defaults.
* Improve the layout of widgets in the GTK-based installer for consistent margins and alignment.
* Add a post-installation notification mechanism for automated installations ([https://bugzilla.proxmox.com/show_bug.cgi?id=5536 issue 5536]).
*: This mechanism can be configured with the new <code>post-installation-webhook</code> section in the answer file.
* Add support for running a custom script on first boot after automated installation ([https://bugzilla.proxmox.com/show_bug.cgi?id=5579 issue 5579]).
*: The script can be provided in the ISO or fetched from an URL.
* Allow users to set hashed passwords in the <code>proxmox-auto-installer</code> answer file.
* Allow users to customize the label of the partition from which the automated installer fetches the answer file.
* Add ability to detect and rename an existing ZFS pool named <code>rpool</code> during the installation.
* Improve the email address validation to include a broader set of email address formats.
*: This implements the email validation check specified in the [https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address HTML specification].
* The text-based installer now fails if no supported NIC was found, similar to graphical installer.
* Improve UI consistency by adding the missing background layer for the initial setup error screen in the text-based installer.
* Improve usability for small screens by adding a tabbed view for the advanced options at the disk selection step in the text-based installer.
*: This change only affects screens with a screen width of less than or equal to 80 columns.
* Fix an issue with ISOs generated with the <code>proxmox-auto-install-assistant</code> which caused the user to end up in the GRUB shell when booting from a block device (e.g. an USB flash drive) in UEFI mode.
* Fix a bug which caused some kernel parameters related to the automated installer to be removed incorrectly.
* Fix a bug which caused the installer to not detect Secure Boot in some cases.
* Ask the user for patience while making the system bootable if multiple disks are configured, as this may take longer than expected.
* Preserve the <code>nomodeset</code> kernel command-line parameter.
*: A missing <code>nomodeset</code> parameter has caused display rendering issues when booting the finished Proxmox Mail Gateway installation on some systems ([https://bugzilla.proxmox.com/show_bug.cgi?id=4230#c38 see this comment for more information]).
* Improve user-visible error and log messages in the installer.
* Improve documentation for the <code>proxmox-auto-install-assistant</code>.
* Improve error reporting by printing the full error message when the installation fails in <code>proxmox-auto-installer</code>.
* Improve error reporting by printing the full error message when mounting and unmounting the installation file system fails in <code>proxmox-chroot</code>.
* Improve debugging and testing by enumerating the installation environment anew (e.g. when running the command <code>dump-env</code>).
* Send the correct content-type charset <code>utf-8</code> when fetching answer files from an HTTP server during automated installation.
* Switch the text-based installer rendering backend from termion to crossterm.
* Raise minimum root password length from 5 to 8 characters for all installers.
*: This change is done in accordance with current [https://pages.nist.gov/800-63-4/sp800-63b.html#passwordver NIST recommendations].
* Print more user-visible information about the reasons the auto installation failed.
* Allow RAID levels to be set case-insensitively in the answer file for the auto-installer.
* Prevent the auto-installer from printing progress messages while there has been no progress.
* Disallow configuring BTRFS as root filesystem for Proxmox products that do not currently support it.
* Correctly acknowledge the user's preference whether to reboot on error during auto installation ([https://bugzilla.proxmox.com/show_bug.cgi?id=5984 issue 5984]).
* Allow binary executables (in addition to shell scripts) to be used as the first-boot executable for the auto-installer.
* Allow properties in the answer file of the auto-installer to be either in <code>snake_case</code> or <code>kebab-case</code>.
*: The <code>kebab-case</code> variant is preferred to be more consistent with other Proxmox configuration file formats.
*: The <code>snake_case</code> variant will be gradually deprecated and removed in future major version releases.
* Validate the locale and first-boot-hook settings while preparing the auto-installer ISO instead of failing the installation due to wrong settings.
* Prevent printing non-critical kernel logging messages, which drew over the TUI installer's interface.
* Keep network configuration detected via DHCP in the GUI Installer, even when not clicking <code>Next</code> first ([https://bugzilla.proxmox.com/show_bug.cgi?id=2502 issue 2502]).

<div id="8.2-known-issues"></div>
=== Known Issues & Breaking Changes ===

==== Kernel 6.8 ====

The Proxmox Mail Gateway 8.2 releases will install and use the 6.8 Linux kernel by default. A major kernel version change can have a few hardware-specific side effects. The kernel version 6.8 has been the default kernel for Proxmox Mail Gateway installations since April 2024, so most existing installations should already be using it.

Most issues with new kernel versions do not affect virtual machines and container guests, so virtualized Promox Mail Gateway installations are not affected.

===== Kernel: Change in Network Interface Names =====

Upgrading kernels always carries the risk of changes in network interface names, which can lead to invalid network configurations after a reboot.
In this case, you must either update the network configuration to reflect the name changes, or pin the network interface to its name beforehand.

See [https://pve.proxmox.com/pve-docs/pve-admin-guide.html#network_override_device_names the Proxmox VE reference documentation] on how to pin the interface names based on MAC Addresses.

Currently, the following models are known to be affected at higher rates:
* Models using <code>i40e</code>. Their names can get an additional port suffix like <code>p0</code> added.

== Proxmox Mail Gateway 8.1 ==
'''Released 29. February 2024'''

* Based on Debian Bookworm (12.5)
* SpamAssassin 4.0.0 (with updated rulesets)
* ClamAV 1.0.3
* PostgreSQL 15.6
* Latest 6.5 Kernel as new stable default
* ZFS 2.2.2

=== Highlights ===

* Extend the rule system to allow selection of the <strong>match-if mode</strong> for entries in What/Who/When Objects, and multiple Objects in Rules, providing flexible control over whether all, any, none, or some but not all must match.
*: See the [[#8.1-rule-system-enhancements|enhancements in the rule system section]] for more details and examples.
* Optional DKIM signing based on the <code>From</code> header (also known as <code>RFC5322.From</code>), instead of the Envelope sender (also known as <code>RFC5321.From</code>) ([https://bugzilla.proxmox.com/show_bug.cgi?id=2971 issue 2971]).

* Secure Boot support.
*: Proxmox Mail Gateway now includes a signed shim bootloader trusted by most hardware's UEFI implementations. All necessary components of the boot chain are available in variants signed by Proxmox.
*: The Proxmox Mail Gateway installer can now be run in environments where Secure Boot is required and enabled, and the resulting installation can boot in such environments.
*: Existing Proxmox Mail Gateway installations can be switched over to Secure Boot without reinstallation by executing some manual steps, see the [https://pve.proxmox.com/pve-docs/chapter-sysadmin.html#sysboot_secure_boot documentation] for details.
*: How to use custom secure boot keys has been documented in the [https://pve.proxmox.com/wiki/Secure_Boot_Setup Secure Boot Setup] page in the Proxmox VE wiki. For using DKMS modules with secure boot see the [https://pve.proxmox.com/pve-docs/chapter-sysadmin.html#sysboot_secure_boot reference documentation].

* Seamless upgrade from Proxmox Mail Gateway 7.3, see [https://pmg.proxmox.com/wiki/index.php/Upgrade_from_7_to_8 Upgrade from 7 to 8]

=== Changelog Overview ===

<div id="8.1-rule-system-enhancements"></div>
==== Enhancements in the Rule System ====
* Make the rule system more flexible by introducing a match-if-mode for objects and groups. The match-if-mode of an object (or group) determines whether any, all, not all or none of its children must match for the whole object (or group) to match. This allows to implement complex rules, for example:
** Exclude certain recipients from a rule, while still considering all later rules for them.
** Treat emails differently if they contain particular attachments and are detected as spam or contain a virus.
** Match attachments with a filename ending in <code>.pdf</code>, but being detected as executable by the content-type filter.
** Matching a mail sent from one address and containing a phrase in the subject.
* Disclaimers can now be added on top of the message, instead of only at the bottom ([https://bugzilla.proxmox.com/show_bug.cgi?id=2606 issue 2606]).
* The separator <code>--</code> for disclaimers can now be optionally omitted ([https://bugzilla.proxmox.com/show_bug.cgi?id=2430 issue 2430]).
* Adapt the number of parallel worker processes for the SMTP filter to increased memory requirements and availability.
* Make the timeout for processing a mail consistent between before- and after-queue filtering, and make it configurable.
* Prevent duplicate mail delivery when filtering runs into a timeout.
* Fix the synchronization of the user wants- and blocklists if the last address is removed for a user ([https://bugzilla.proxmox.com/show_bug.cgi?id=4392 issue 4392]).
* Further improve input validation for regular expressions in the rule system ([https://bugzilla.proxmox.com/show_bug.cgi?id=4811 issue 4811]).
* Fix an error in the collection of virus occurrence statistics.
* The spam report e-mails now correctly handle addresses with characters that need to be escaped for the API and GUI.
* Display the descriptions for rules from the advanced KAM ruleset in the spam info grid in the quarantine view.
* Improve the output of <code>pmgdb dump</code> used for gathering information about the ruleset:
** Add information about the type of What Objects
** Add optional <code>--rules</code> parameter to restrict output to rules that are active or inactive
** Visually emphasize whether a rule is active
** Remove unnecessary filler words from output

==== Enhancements in the Web Interface (GUI) ====

* Make it easier to manage large deployments by adding a filter- and search-box for ([https://bugzilla.proxmox.com/show_bug.cgi?id=4510 issue 4510]):
*: Relay Domains
*: Transport
*: Networks
*: Objects in the rule system
* Add icons to the backup destination panel for improved UX.
* Fix an issue where the OK button would stay disabled when editing an ACME DNS challenge plugin ([https://bugzilla.proxmox.com/show_bug.cgi?id=4531 issue 4531]).
* Fix TLS 1.3-only configuration for the API proxy server ([https://bugzilla.proxmox.com/show_bug.cgi?id=4859 issue 4859]).
* Fix spelling errors in the GUI and improve gettext instances so that they can be better translated.
* Improved translations, among others:
** Croatian (NEW!)
** Georgian (NEW!)
** Arabic
** Catalan
** German
** Italian
** Polish
** Simplified Chinese
** Spanish
** Traditional Chinese
** Ukrainian
** The language code for Korean was corrected from <code>kr</code> to <code>ko</code> in alignment with ISO 639-1, while maintaining a symbolic link for backward compatibility for now.
** Several remaining occurrences of the <code>GiB</code> unit in the GUI can now be translated ([https://bugzilla.proxmox.com/show_bug.cgi?id=4551 issue 4551]).

==== Access Control ====

* Allow usernames shorter than 4 characters, in accordance with Proxmox VE and Proxmox Backup Server ([https://bugzilla.proxmox.com/show_bug.cgi?id=4818 issue 4818])

==== Notable bug fixes and general improvements ====

* Harden the Postfix configuration for the external port to address the [https://www.postfix.org/smtp-smuggling.html SMTP Smuggling] security issue, by implementing all recommendations from upstream.
* Switch the default time-stamp format expected by the Tracking Center to the RFC3339 based information in the logs in Proxmox Mail Gateway 8.0 and newer. While this was initially meant as a small clean-up a few issues around the switch between DST and regular time were fixed with the changes.
* Secure Boot support.
*: Proxmox Mail Gateway now ships a shim bootloader signed by a CA trusted by most hardware's UEFI implementation. In addition, it ships variants of the GRUB bootloader, MOK utilities and kernel images signed by Proxmox and trusted by the shim bootloader.
*: New installation will support Secure Boot out of the box if it is enabled.
*: Existing installations can be adapted to Secure Boot by installing optional packages, and possibly reformatting and re-initializing the ESP(s), without the need for a complete reinstallation. See [https://pve.proxmox.com/wiki/Secure_Boot_Setup the wiki article for more details].
* Fix cluster setups recreated after restoring a backup with statistics ([https://bugzilla.proxmox.com/show_bug.cgi?id=5189 issue 5189]).
* The kernel shipped by Proxmox is shared for all products. This is now reflected in the renaming from <code>pve-kernel</code> and <code>pve-headers</code> to <code>proxmox-kernel</code> and <code>proxmox-headers</code> respectively in all relevant packages.
* The new <code>proxmox-default-kernel</code> and <code>proxmox-default-headers</code> meta-packages will depend on the currently recommended kernel-series.
* Many edge-cases encountered during the upgrade from Proxmox Mail Gateway 7.3 to 8 by our user-base are now detected and warned about in the improved <code>pmg7to8</code> checks:
** Notify when a template was copied to <code>/etc/pmg/templates</code> without any modifications, to prevent missing important changes to config files.
** Warn if [https://github.com/dell/dkms DKMS] modules are detected, as many of them do not upgrade smoothly to the newer kernel versions in Mail Gateway 8.
** Warn if version 7 of the Mail Gateway system does not have the correct meta-package of <code>grub</code> installed. The correct meta-package is required to actually upgrade the installed bootloader to the newest version.
* Support for adding custom ACME enabled CA's which require authentication through '''E'''xternal '''A'''ccount '''B'''inding (EAB) on the command line ([https://bugzilla.proxmox.com/show_bug.cgi?id=4497 issue 4497]).
* Fix non-interactive use of the <code>pmgsh</code> utility ([https://bugzilla.proxmox.com/show_bug.cgi?id=4815 issue 4815]).
* Improve the parsing of config and system files, used in many places of the code. This fixes an issue with displaying the network interfaces without a correct hostname entry in <code>/etc/hosts</code> and aims to prevent similar issues in the future.
* Prevent cluster synchronization from failing due to a change in fingerprint parsing in OpenSSL.
* Add support for having a Proxmox Backup Server remote on an alternate port ([https://bugzilla.proxmox.com/show_bug.cgi?id=4944 issue 4944]).
* Reduce log severity for periodic informational messages from <code>error</code> to <code>info</code>.
* Changelogs for new package versions shown in the UI are now all gathered with <code>apt changelog</code>, as this is now supported by the Proxmox repositories.
* Add information about the configured domains for DKIM signing to the report generated for support cases.
* The documentation on firmware updates provided by the operating system has been extended and revised, helping administrators to identify if their setup is optimal.

==== Installation ISO ====

* The ISO is able to run on Secure Boot enabled machines.
* The text-based UI got significant improvement based on the feedback received from the first release in Proxmox Mail Gateway 8.0.
* The current link-state of each network interface is now displayed in the network configuration view, helping in identifying the correct NIC for the management interface ([https://bugzilla.proxmox.com/show_bug.cgi?id=4869 issue 4869]).
* If provided by the DHCP server, the hostname field is already filled out with the information from the lease.
* The correct meta-package of <code>grub</code> is now installed based on the boot mode (<code>grub-pc</code> or <code>grub-efi-amd64</code>). This ensures that the bootloader on disk gets updated when there is an upgrade for the <code>grub</code> package.
* The text-based UI is now also available over a serial console, for headless systems with a serial port.
* The root dataset on ZFS installations now uses <code>acltype=posixacl</code> in line with [https://openzfs.github.io/openzfs-docs/Getting%20Started/Debian/Debian%20Bookworm%20Root%20on%20ZFS.html upstream's recommendation].
* Kernel parameters passed on the command line during install are now also set in the target system ([https://bugzilla.proxmox.com/show_bug.cgi?id=4747 issue 4747]).
* Fix the warning that is shown in case the address family (IPv4, IPv6) of the host IP and DNS server do not match.
* The text-based UI now sets the correct disk-size for the selected disk, instead of limiting the installation to the size of the first disk in the list ([https://bugzilla.proxmox.com/show_bug.cgi?id=4856 issue 4856]).
* For better UX, the text-based UI now also displays a count-down before automatically rebooting.
* The screensaver in the graphical installer is now disabled.
* The graphical installer now displays the units used for disk-based options.
* The kernel command-line parameter <code>vga788</code> is now set for both the graphical debug and all text-based UI installation options. This improves compatibility of the installer with certain hardware combinations.
* Remove the checksum-options of <code>off</code> and <code>fletcher2</code> for ZFS, for being dangerous and deprecated respectively.
* Improve the layout in the graphical installer to ensure correct margins and alignment of widgets.
* Set a timeout for country detection, preventing the installer from hanging at that step ([https://bugzilla.proxmox.com/show_bug.cgi?id=4872 issue 4872]).
* General improvements for running external commands in the installer backend in order to prevent lockups.
* Improve validation of hostname length and allowed characters set in the installer ([https://bugzilla.proxmox.com/show_bug.cgi?id=5230 issue 5230]).

<div id="8.1-known-issues"></div>
=== Known Issues & Breaking Changes ===
==== Kernel ====
* Some SAS2008 controllers need a workaround to get detected since kernel 6.2, see the [https://forum.proxmox.com/threads/no-sas2008-after-upgrade.129499/page-4#post-607858 forum thread] for details.

* The TPM (Trusted Platform Module) hardware random number generator (RNG) is now disabled on all AMD systems equipped with a firmware-based TPM (fTPM) device. This change was implemented due to such RNGs causing stutters in many systems. Affected systems should switch the RNG source from <code>/dev/hwrng</code> to an alternative, like <code>/dev/urandom</code>.
: Reference: [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=554b841d470338a3b1d6335b14ee1cd0c8f5d754 kernel commit "tpm: Disable RNG for all AMD fTPMs"]

* Some Dell models, which appear to include all those using a BCM5720 network card, have a compatibility issue with the <code>tg3</code> driver in the kernel based on version 6.5.11.
*: From our current understanding 14th Generation Dell Servers (T140, R240, R640,...) are affected, while others (e.g., R630, R620, R610,...) do not seem to be affected. We are currently investigating this issue. In the meantime, we recommend pinning the kernel to version 6.2 on affected hosts.
*: Some users report that disabling the <code>X2APIC</code> option in the BIOS resolved this issue as a workaround.

== Proxmox Mail Gateway 8.0 ==
'''Released 29. June 2023'''

* Based on Debian Bookworm (12.0)
* Latest 6.2 Kernel as stable default
* ZFS 2.1.12
* SpamAssassin 4.0.0 (with updated rulesets)
* ClamAV 1.0.1
* PostgreSQL 15.3

=== Highlights ===

* New major release based on the great Debian Bookworm.

* Seamless upgrade from Proxmox Mail Gateway 7.3, see [[Upgrade from 7 to 8]]
*: New <code>pmg7to8</code> pre-flight checking script analyzing the system for common misconfigurations and missed steps during the upgrade

* Add new text-based UI mode for the installation ISO, written in Rust using the [https://github.com/gyscos/cursive Cursive] TUI (Text User Interface) library:
*: You can use the new TUI mode to work around issues with launching the GTK based graphical installer, sometimes observed on both very new and rather old hardware.
*: The new text mode executes the same code for the actual installation as the existing graphical mode.

=== Changelog Overview ===

==== Enhancements in the Rule System ====

* When adding a "Match Field" ''What'' object, check that the provided regular expression is a valid regular expression.

* Disable SpamAssassin's naive-Bayesian-style classifier and the auto-whitelisting plugin by default.
*: Both features lead to worse detection rates in the Spam Filter in most setups.
*: Bayes needs manual training and thorough consideration, as well as continuous maintenance.
*: Existing setups are kept without change on upgrade.
*: For new setups the old behavior can be enabled through the GUI.


==== Enhancements in the Web Interface (GUI) ====
* Improved Dark color theme:
*: The Dark color theme, introduced in Proxmox Mail Gateway 7.3, received a lot of positive feedback from our community, which resulted in further improvements.
* Improved translations, among others:
** Ukrainian (NEW)

** Japanese

** Simplified Chinese

** Traditional Chinese

** The size units (Bytes, KB, MiB,...) are now passed through the translation framework as well, allowing localized variants (e.g., for French).

** The language selection is now localized and displayed in the currently selected language

* Disable advanced statistic filters by default, as their behavior may not be immediately clear without consulting the documentation first.

* HTML-encode rule names before rendering as additional hardening against XSS.

* The tracking center can now parse the new syslog format for dates that was introduced in Debian Bookworm.
*: The logging format of <code>rsyslog</code> was changed to include Timezone information (RFC3339) in the logs, making the Tracking Center more robust across DST changes and year changes.


==== Access control ====
* Add TFA/TOTP lockout to protect against an attacker who has obtained the user password and attempts to guess the second factor:
*: If TFA fails too many times in a row, this user account is locked out of TFA for an hour. If TOTP fails too many times in a row, TOTP is disabled for the user account. Using a recovery key will unlock a user account. 

==== Installation ISO ====

* Add new text-based UI mode for the installation ISO, written in Rust using the [https://github.com/gyscos/cursive Cursive] TUI (Text User Interface) library:
*: You can use the new TUI mode to work around issues with launching the GTK based graphical installer, sometimes observed on both very new and rather old hardware.
*: The new text mode executes the same code for the actual installation as the existing graphical mode.
* The version of BusyBox shipped with the ISO was updated to version 1.36.1.
* Detection of unreasonable system time.
: If the system time is older than the time the installer was created, the system notifies the user with a warning.

* <code>ethtool</code> is now shipped with the ISO and installed on all systems.
* <code>systemd-boot</code> is provided by its own package instead of <code>systemd</code> in Debian Bookworm and is installed with the new ISO.
* The installation ISO now ships the dependencies for extracting text from attachments using SpamAssassin 4, eliminating the need to install the packages manually.

==== Notable bugfixes and general improvements ====

* Add a <code>pmg7to8</code> CLI tool to assist in upgrading from Proxmox Mail Gateway 7.3 to 8.

* Fix an issue where an invalid regular expression in a "Match Field" ''What'' object would cause <code>pmg-smtp-filter</code> to exit and restart, possibly leading to wrongly denied mails. Instead, <code>pmg-smtp-filter</code> now logs a warning if it encounters an invalid regular expression.

* During package installation or upgrade, ignore certain transient or obvious errors to avoid leaving the package in a broken state.

* Fix an issue where the Proxmox Mail Gateway system report would wrongly indicate a DNS misconfiguration.

* When authenticating via PAM, pass the <code>PAM_RHOST</code> item. With this, it is possible to manually configure PAM such that certain users (for example root@pam) can only log in from certain hosts.


<div id="8.0-known-issues"></div>
=== Known Issues & Breaking Changes ===

* The advanced statistics filter is now disabled by default.
*: To avoid changing the behavior of a Proxmox Mail Gateway 7.3 instance on upgrade, the upgrade process will set the <code>advfilter</code> option to <code>1</code> if no explicit value is set.

* SpamAssassin's naive-Bayesian-style classifier and the auto-whitelisting plugin are now disabled by default.
*:To avoid changing the behavior of a Proxmox Mail Gateway 7.3 instance on upgrade, the upgrade process will set each of the <code>use_awl</code>/<code>use_bayes</code> options to <code>1</code> if no explicit value is set.

== Proxmox Mail Gateway 7.3 ==
'''Released 28. March 2023'''

* Based on Debian Bullseye (11.6)
* Latest 5.15 Kernel as stable default
* Newer 6.2 kernel as opt-in
* ZFS 2.1.9
* SpamAssassin 4.0.0 (new major version)
* PostgreSQL 13.10

=== Highlights ===

* Proxmox Mail Gateway now provides a dark theme for the administrative and quarantine web interfaces.
* SpamAssassin 4.0.0 was integrated, along with many of its new capabilities, like (optionally) scanning document contents (docx, pdf, images,...), or resolving URLs from url-shorteners.

=== Changelog Overview ===

==== Enhancements in the Rule System ====
* New major release SpamAssassin 4.0.0, with many new features:
** Detection of spam inside of attachments. This is implemented for the file types <code>.pdf</code>, <code>.odt</code>, <code>.docx</code>, <code>.doc</code>, <code>.rtf</code>, as well as images (through OCR).
*:: Attachment scanning can be enabled using the Web UI (<code>Spam Detector</code> -> <code>Options</code>), which sets the <code>extract_text</code> option in the <code>spam</code> section of <code>/etc/pmg/pmg.conf</code>.
*:: The dependencies required for attachment scanning are marked as optional, but recommended dependency for the <code>pmg-api</code> package.
*:: This means that on systems that did not change the apt preference the new dependencies should be pulled in automatically on upgrade, otherwise you might need to manually install them.
*: Note that attachment scanning, and OCR in particular, increases CPU time spent per mail. Depending on email volume and available CPU power, you may see a significant increase in load.
** Follow and analyze URL-shortener links.
** Improved support for using information from DMARC-policies.
** Improved handling of internationalized (IDN) domain names.
* Adaptation of the SpamAssassin integration for version 4.0.0:
: The SpamAssassin configuration files shipped with the <code>pmg-api</code> package were adapted to the new features.
: <code>extract_text</code> was added as new option for the spam detector to disable content scanning, while most other new options are triggered with the <code>use_rbl</code> option.
: On deployments with modified templates, the upgrade process will ask how changes should be merged. This provides an opportunity to re-evaluate which modifications are still needed.
* Support enforcing TLS-only connections for mails from certain domains:
: It is now possible to enforce TLS encryption for inbound mail, complementing the already-present TLS policy functionality for outbound mail.
* Improved handling of SMTPUTF8:
: Based on the user feedback on UTF-8 support for the rule system introduced in Proxmox Mail Gateway 7.2, it is now possible to disable SMTPUTF8 through the API and GUI.
: The detection for SMTPUTF8 was aligned with the implementation in <code>postfix</code>.
* The What objects "Match Archive Filename" now also use the optional filename from the GZIP header for matching.
* Support trusted network entries with host bits set in the CIDR:
: Quite a few deployments did use a CIDR with host-bits set, for example 192.0.2.5/24 instead of 192.0.2.0/24. This is now translated internally and handled correctly.
* Ordering of multiple rules with the same priority is now stable, despite not being a recommended setup.

==== Enhancements in the Web Interface (GUI) ====

* Add a fully-integrated "Proxmox Dark" color theme variant of the long-time Crisp light theme.
: By default, the <code>prefers-color-scheme</code> media query from the Browser/OS will be used to decide the default color scheme.
: Users can override the theme via a newly added <code>Color Theme</code> menu in the user menu.
* Add "Proxmox Dark" color theme to the Proxmox Mail Gateway reference documentation.
: The <code>prefers-color-scheme</code> media query from the Browser/OS will be used to decide if the light or dark color scheme should be used.
: The new dark theme is also available in the [https://pmg.proxmox.com/pmg-docs/api-viewer/index.html#/nodes/{node}/version Proxmox Mail Gateway API Viewer].
* Task logs can now be downloaded directly as text files for further inspection.
* The language chooser now displays, for each available language, both its native name as well as its name translated to the currently active language.
* HTML-encode API results before rendering as additional hardening against XSS.
* Automatically redirect HTTP requests to HTTPS for convenience.
: This avoids "Connection reset" browser errors that can be confusing, especially after setting up a Proxmox Mail Gateway host the first time.
* Invalid entries in advanced fields now cause the advanced panel to unfold, providing direct feedback.
* Improved translations, among others:
** Arabic
** French
** German
** Italian
** Japanese
** Russian
** Slovenian
** Simplified Chinese
** Traditional Chinese

==== Notable General Improvements and Bug Fixes ====
* The documentation has now a chapter describing the statistics part of the GUI and API.
* Mail delivery from quarantine uses new code for sending locally generated mail, with the following improvements:
** support for IPv6-only deployments and delivery status notifications.
** Correct decoding of addresses containing UTF-8.
* The cleanup before restoring the configuration from a backup was improved, preventing issues when restoring without rebooting the system.
* Logging of errors when sending locally generated mail was improved.
* Errors in files related to TLS-policy are now also reported in the syslog.
* The output of <code>pmgdb dump</code> is now able to handle UTF-8 characters in rule names, object names, and comments.

==== Installation ISO ====

* the version of BusyBox shipped with the ISO was updated to version 1.36.0.
* The EFI System Partition (ESP) defaults to 1 GiB of size if the root disk partition (<code>hdsize</code>) is bigger than 100 GB.
* UTC can now be selected as timezone during installation.

<div id="7.3-known-issues"></div>

=== Known Issues & Breaking Changes ===

* The ISO does not ship the optional dependencies for extracting text from attachments - If you installed from the ISO and want to use the feature, you can simply install them manually
apt install antiword docx2txt odt2txt poppler-utils tesseract-ocr unrtf

== Proxmox Mail Gateway 7.2 ==
'''Released 30. November 2022'''

* Based on Debian Bullseye (11.5)
* Latest 5.15 Kernel as stable default (5.15.74)
* Newer 5.19 kernel as opt-in
* ZFS 2.1.6
* SpamAssassin 3.4.6 (with updated rule-set)
* PostgreSQL 13.8

'''Changelog Overview'''

* Enhancements in the Rule system:
** Improved handling of international emails
*** Support for UTF-8 characters in the rule system (e.g. matching non-ASCII subjects).
*** Better handling of [https://www.rfc-editor.org/rfc/rfc6531 SMTPUTF8 emails] (the smtp-dialogue already contains non-ASCII data, the headers contain UTF-8 data without MIME encoding).
** Proper encoding for template-variable information in the Notifications and Modify Field actions.
** MatchField now matches all occurrences of a header - not only the first one - especially relevant for <code>Received</code> headers.
** Deprecated the <code>Attach</code>, <code>Counter</code> and <code>ReportSpam</code> Actions.
*: While they were present in the code of Proxmox Mail Gateway, they were never exposed in the GUI or API.
*: All three have now been deprecated and will be removed with version 8.0.

* Improved Quarantine UX:
** Quarantine interface for Administrators: many of the recent features for end-users in the Spam Quarantine have been ported to the administrator view:
*** Allow selection of multiple mails.
*** Context menu in the mail-listing.
*** Display the Receiver information in the Attachment and Virus quarantines and the Mail Info widget.
** Augmented the information visualization in the Spam information grid.
*** The weight (number of points) and the type of impact (positive or negative) of SpamAssassin rules is now shown with colors and font-weights to make them easier to grasp.
*** The rule IDs and scores are using a monospaced font for better comparison of values.
** Colorized <code>Deliver</code> and <code>Delete</code> actions improves intuitive handling of the common actions.
** Display of attachments in the Spam and Virus quarantines (for a more complete overview of the mail).
** Attachment and Virus quarantines can now optionally be filtered by Receiver - especially helpful in larger deployments.
** Display of descriptions for locally defined SpamAssassin rules.
** Fix displaying the quarantine interface on narrow screens: Part of the action buttons were cut off and not reachable through scrolling.

* Enhancements in the web interface (GUI):
** The Postfix queue interface now displays the mail's headers in a decoded way - so that you see it as in your mail user agent.
** The Statistic time selector now does not show non-existent day/month combinations (e.g. the 31. Day of February).
** Better spacing of the Field labels in the rule object edit windows.
** Improved translations, among others:
*** Dutch
*** German
*** Italian
*** Polish
*** Traditional Chinese
*** Turkish

* Support Proxmox Offline Mirroring & Subscription Handling
** Proxmox Offline Mirror: The tool supports subscriptions and repository mirrors for air-gapped systems. The newly added [https://pom.proxmox.com proxmox-offline-mirror] utility can now be used to keep Proxmox Mail Gateway hosts, without access to the public internet up-to-date and running with a valid subscription.

* Notable General Improvements and Bugfixes:
** Add IP networks uniquely to template variables (<code>postfix.mynetworks</code>)
*: If you had multiple entries in your transport directory, all pointing to the same host, they were added multiple times to the variable used in the configuration system.
** Support for Proxmox Backup Server Namespaces.
** Spam report emails now correctly display the <code>From</code> header, even if it contains a comma (e.g. <code>"Lastname, Firstname" <firstname.lastname@domain.example></code>).
** The left-over config file <code>/etc/apt/apt.conf.d/75pmgconf</code> was removed, enabling the automatic removal of obsolete kernel packages, which can take up significant amounts of space.
** SpamAssassin updates now handle updates to multiple channels correctly on the first run.
** Improved parsing of email attributes from LDAP profiles.
** Changing the directory to '/' before running <code>psql</code> as <code>postgres</code>user - preventing the printing of harmless but confusing warnings with various Proxmox Mail Gateway CLI utilities.
** Support disabling TLS 1.2 and configuring TLS 1.3 ciphers for <code>pmgproxy</code> - following the change for <code>pveproxy</code> in Proxmox VE.
'''Upgrade from 6.4'''

See [[Upgrade from 6.x to 7.0]]
== Proxmox Mail Gateway 7.1 ==
'''Released 30. November 2021'''
* Based on Debian Bullseye (11.1)
* Kernel 5.13
* ZFS 2.1
* SpamAssassin 3.4.6 (with updated rule-set)
* PostgreSQL 13.5

'''Changelog Overview'''

* Enhancements in the web interface (GUI)
** Improved configuration editing of LDAP backends: Changes can now be applied without having to specify a password.
** The APT repository configuration, rather than being restricted to 'root', is now visible and editable by all users with 'Administrator' privileges.
** Improved translations, among others:
*** Arabic
*** Basque
*** Brazilian Portuguese
*** French
*** German
*** Simplified Chinese
*** Traditional Chinese
*** Turkish

* Two-Factor Authentication
** Two-factor authentication (TFA) for the web interface. Shares the TFA implementation from Proxmox Backup Server, written in rust.
** Support for multiple types of second factors:
*** WebAuthn, which supports a wide range of security devices, like hardware keys or trusted platform modules.
*** Time-based One-Time Password (TOTP), a short code derived from a shared secret and the current time, it changes every 30 seconds.
*** Single use Recovery Keys.

* Backend and API
** Improved support for setups using DHCP for their network configuration:
*: While email still requires working DNS records, you can now manage and configure the IP of your Proxmox Mail Gateway in your DHCP configuration.
** When adding a new entry to a Who object, a duplicate check is performed before saving.
** Better handling of trailing dot in domain-names:
*: Proxmox Mail Gateway uses the first search domain from <code>/etc/resolv.conf</code> as domain name - it can now handle entries with a trailing dot.
** Delivery status notification (DSN, RFC 3461) support for outbound email with enabled before-queue filtering.
'''Upgrade from 6.4'''

See [[Upgrade from 6.x to 7.0]]

== Proxmox Mail Gateway 7.0 ==
'''Released 15. July 2021'''
* Based on Debian Bullseye (11)
* SpamAssassin 3.4.6 (with updated rule-set)
* Kernel 5.11
* PostgreSQL 13

'''Changelog Overview'''

* Enhancements in the web interface (GUI)
** Make dashboard status panel more detailed, showing, among other things, uptime, kernel version, CPU info and a high level repository status overview.
** New APT repository management panel in the <code>Administration</code> tab shows an in-depth status and a list of all configured repositories.
**: Basic repository management, for example, activating or deactivating a repository, is also supported.
** Updated ExtJS JavaScript framework to latest GPL release 7.0
** Added advanced task-log filtering
** Improved translations, including:
*** Arabic
*** French
*** German
*** Japanese
*** Polish
*** Turkish

* ACME/Let's Encrypt
** Support the use of wildcard domains with the DNS plugins
** API: nodeconfig: validate ACME config before writing

* API
** pmgproxy: allow setting LISTEN_IP parameter
** The "Authentication mode" setting of <code>LDAP</code> for the quarantine interface no longer contains the ticket-link in the report-mails - thus, quarantine users need to provide their LDAP credentials to access the quarantine.

* Installer:
** Rework the installer environment to use <code>switch_root</code> instead of <code>chroot</code>, when transitioning from initrd to the actual installer.
**: This improves module and firmware loading, and slightly reduces memory usage during installation.
** Automatically detect HiDPI screens, and increase console font and GUI scaling accordingly. This improves UX for workstations with Proxmox VE (for example, for passthrough).
** Improve ISO detection:
*** Support ISOs backed by devices using USB Attached SCSI (UAS), which modern USB3 flash drives often do.
*** Linearly increase the delay of subsequent scans for a device with an ISO image, bringing the total check time from 20s to 45s. This allows for the detection of very slow devices, while continuing faster in general.
** Use <code>zstd</code> compression for the initrd image and the squashfs images.
** Update to busybox 1.33.1 as the core-utils provider.

* libarchive-perl
** The perl-bindings to <code>libarchive</code> have been updated to match <code>libarchive</code> version 3.4.3 (shipped in Debian Bullseye) - the library interface was kept backwards-compatible

* libxdgmime-perl
** The perl-bindings to [https://gitlab.freedesktop.org/xdg/xdgmime xdgmime] have been updated to match current upstream - the library interface was kept backwards-compatible

<div id="7.0-breaking-changes"></div>
'''Breaking Changes'''
* New default bind address for pmgproxy, unifying the default behavior with Proxmox VE and Proxmox Backup Server
** 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. Instead of:
*: <code>192.0.2.1- root@pam [01/06/2021:01:19:03 +0200] "GET /api2/json/config/ruledb/digest HTTP/1.1" 200 51</code>
*: the line now looks like:
*: <code>::ffff:192.0.2.1- root@pam [01/06/2021:01:19:03 +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>

* ClamAV has [https://blog.clamav.net/2021/04/are-you-still-attempting-to-download.html deprecated the SafeBrowsing feature]:
** These options have been removed from the shipped <code>freshclam.conf.in</code> template.
** The <code>safebrowsing</code> config key in <code>/etc/pmg/pmg.conf</code> is currently ignored and will be dropped at some point in the future.

* Changes to the database layout:
** The <code>host</code> column of the <code>cgreylist</code> table, which has not been used since Proxmox Mailgateway 6.2, has been dropped from the schema and will be dropped from existing databases during the upgrade.

* API deprecations, moves and removals
** The <code>upgrade</code> parameter of the <code>/nodes/{node}/termproxy</code> API method has been replaced by providing <code>upgrade</code> as <code>cmd</code> parameter.
** The <code>domain</code> parameter of the <code>/config/tlspolicy</code> API method has been replaced by the <code>destination</code> parameter.
** The <code>/quarantine/whitelist/{address}</code> and <code>/quarantine/blacklist/{address}</code> API methods, that take the address as part of the path, have been deprecated in favor of explicitly providing the parameter in the request to <code>/quarantine/whitelist</code> and <code>/quarantine/blacklist</code> respectively.
** The API methods for detailed statistics per e-mail address, which take the address as part of the path (<code>/statistics/contact/{contact}</code>, <code>/statistics/sender/{sender}</code> and <code>/statistics/receiver/{receiver}</code> have been deprecated in favor of <code>/statistics/detail</code>, which takes the address as an explicit parameter.

<div id="7.0-known-issues"></div>
'''Known Issues'''
* '''Network''': Due to the updated systemd version, and for most upgrades, the newer kernel version (5.4 to 5.11), some network interfaces might change upon reboot:
** Some may change their name. For example, due to newly supported functions, a change from <code>enp33s0f0</code> to <code>enp33s0f0np0</code> could occur.
**: We observed such changes with high-speed Mellanox models.
** [https://sources.debian.org/src/bridge-utils/1.7-1/debian/NEWS/#L3-L23 Bridge MAC address selection has changed in Debian Bullseye] - it is now generated based on the interface name and the <code>machine-id (5)</code> of the system.
**: Note that by default, Proxmox Mail Gateway does not use a Linux Bridge for networking, so most setups are unaffected.
* '''Machine-id''': Systems installed using the Proxmox Mail Gateway 5.0 to 5.4 ISO may have a non-unique machine-id. These systems will have their machine-id re-generated automatically on upgrade, to avoid a potentially duplicated bridge MAC and other issues.
: If you do the upgrade remotely, make sure you have a backup method of connecting to the host (for example, IPMI/iKVM, tiny-pilot, another network accessible by a cluster node, or physical access), in case the network used for SSH access becomes unreachable, due to the network failing to come up after a reboot.

'''Upgrade from 6.4'''

See [[Upgrade from 6.x to 7.0]]

==Proxmox Mail Gateway 6.4==
'''Released 30. March 2021'''
* Based on Debian Buster (10.9)
* SpamAssassin 3.4.5 (with update ruleset)
* Kernel 5.4.106
* ACME integration
** Proxmox Mail Gateway now offers full integration of the ACME protocol via the GUI, enabling administrators to create valid and trusted certificates for their domains with the Let's Encrypt certificate authority, in the same way as with Proxmox VE.
** Full support for the <code>http-01</code> and <code>dns-01</code> challenges, with all plugins from [https://github.com/acmesh-official/acme.sh acme.sh].
** Easily configurable from the GUI.
* General Certificate Management via the GUI
** It is now possible to upload custom certificates from the web interface, or set up a cluster-wide ACME account to automatically get and renew certificates from an ACME provider.
* Support for external SpamAssassin update channels (regular automated updates).
** By providing a short configuration file containing a SpamAssassin rule channel's URL and GPG key, Proxmox Mail Gateway will now fetch verified updates from that channel, along with the updates from updates.spamassassin.org.
** The KAM ruleset channel is now available, and a suitable configuration file is shipped with <code>proxmox-spamassassin</code>.
* Improved Quarantine Management
** The admin view of the Spam Quarantine can now display quarantined mail of all users at once.
** All Quarantine views (admin and user) allow you to filter for subject or sender.
** The spam quarantine can now process huge amounts of mails at once (> 3200).
* TLS-logging improvements to the Tracking Center
** The Tracking Center now shows when an outbound connection is established over TLS.
* Enhancements to the Integration of Proxmox Backup Server
** It is now possible to get notified about the result of a scheduled backup to a configured Proxmox Backup Server Remote.
** Inclusion of the (potentially large) statistics database is now configurable per Remote.
* Notable Bugfixes:
** Support for '/' in the local part of an e-mail address (quarantine and statistics view).

==Proxmox Mail Gateway 6.3==
'''Released 19. November 2020'''

* Based on Debian Buster (10.6)
* Updated SpamAssassin rules
* Kernel 5.4.73
* Proxmox Backup Server Integration<br/>Proxmox Mail Gateway is fully supported by the new Proxmox Backup Server 1.0, released on November 11, 2020:
** Backing up to multiple remote backup servers: You can define multiple remote instances of Proxmox Backup Server to store backups on. In case of a large-scale disaster, they can be quickly restored.
** Scheduled Backups: You can schedule regular backups via the GUI, which will then be automatically triggered by a systemd-timer unit. This removes the need for manual backup creation and individual, scripted solutions.
* Quarantine Link via login-page<br />Users can request mails containing a link to their quarantineview, if enabled by the Admin. This enables users to edit their individual blocklists, even if no mails are in their quarantine. Until now this was only possible for sites using LDAP.
* Improvements to the Tracking Center<br />To further improve user experience in the tracking center, pmg-log-tracker handles certain cases better:
** The case sensitivity has been removed from the search box.
** In case the pmg-smtp-filter fails to process emails due to misconfiguration, they are now marked as rejected.
* Notable Bugfixes:
** DKIM signing now uses the longest matching domain for the 'd=' tag.
** Mails held in the Attachment Quarantine are assigned a new Message-ID - fixing interoperability with certain downstream servers (for example, MS Exchange), which silently discard messages with duplicate Message-IDs.

==Proxmox Mail Gateway 6.2==
'''Released 28. April 2020'''

* Based on Debian Buster (10.3)
** Proxmox Mail Gateway is based on the latest stable release of Debian 10.3 (Buster).
* SpamAssassin 3.4.4
** Proxmox ships the latest upstream release of Apache SpamAssassin with a updated and enhance ruleset (KAM rules added)
* Kernel 5.4
** Proxmox Mail Gateway shares the kernel with Proxmox VE and is based on the 5.4 series from Ubuntu 20.04
* pmg-log-tracker in Rust
** <code>pmg-log-tracker</code> has been extended and reimplemented in the Rust programming language. <code>pmg-log-tracker</code> is the binary at the core of the Message Tracking Center, providing live searchable and grouped logs in the GUI.
** The new <code>pmg-log-tracker</code> has support for parsing and grouping logs in before-queue filtering mode.
** The refresh of the code base of <code>pmg-log-tracker</code> provides an optimized performance and more stability.

* Support for before-queue filtering in the GUI
** With the added support for displaying before-queue filtering logs in the GUI and fixing some minor glitches in that area, the before-queue filtering can now be comfortably enabled in the GUI.

* Improved IPv6 support
** The Mail Proxy's SPF checker also verifies SPF records for those remote mail servers connecting via IPv6.
** Greylisting support for IPv6 addresses (with variable netmask, defaulting to '/64') - needs to be explicitly enabled.
** Who-objects containing IPv6 literal address work now.

* Customizable netmask length for greylist matching
** Instead of fixing a greylist network to a '/24' the administrator can now configure which hosts should be considered as belonging to the same network by setting a larger (or smaller) prefix.
** This can help with receiving mail from some cloud-providers, who send out one mail from different ip addresses within a large network, which usually leads to a rather long delay and sometimes even to a legitimate mail being rejected.
** Due to the changed database layout partial upgrades of clusters will prevent nodes running the older version from syncing the greylist database until they are upgraded.

* Better UX for the User Spam Quarantine interface
** If selected in the Quarantine view, the From header and the Subject are now displayed on top of the mail body.
** It is now possible to delete mail addresses containing certain special characters (for example '/') from a users' black- or whitelist.
** Users can set their preferred language directly in the quarantine interface instead of having to log out to change the setting.
** Fixed a bug in the selection of multiple e-mails.

* Handling of changes to overridden templates with <code>ucf</code>
** Starting with this release all service configuration templates, copied and modified in <code>/etc/pmg/templates</code> get registered with <code>ucf</code>. Should a overridden template change with a new package version the administrator is asked and can accept or reject the changes.
** All users who have templates in <code>/etc/pmg/templates</code> will be asked about the current changes for the initial registration.

* New What Object: 'Match Archive Filename'
** In addition to match files in archives (zip, tar.gz, rar,...) based on the file's content-type, it is also possible to look for particular filename patterns inside of archives.
** This completes the feature matrix of matching files based on content-type or filename, as plain attachments, or inside archives.

* Support for downstream LMTP servers
** In certain setups there is no advantage in having a dedicated SMTP server for receiving e-mails from Proxmox Mail Gateway, since all used functionality is provided by a MTA, which speaks IMAP and LMTP (e.g., Dovecot).
** It is now possible to configure Proxmox Mail Gateway to send e-mails directly to a LMTP relay, both as default transport and only as transport for certain domains.

* Improvements to recently added features
** Before-queue filtering and DKIM signing, both implemented with Proxmox Mail Gateway 6.1, have a better user experience and are considered stable now.
** Some remaining glitches and bugs fixed for both.
** DKIM selector handling can handle the existence of multiple selectors and in the GUI, users can comfortably switch between the active selector.

* TLS policy selection for internal downstream servers
** It is now possible to specify a desired level of encryption and authentication for the opportunistic TLS-encryption (STARTTLS) for downstream servers entered in your transports.
** This can help to ensure that your internal communication is not sent in the clear over the network. It can also be used to work around broken TLS implementations in legacy downstream servers.

* Improvements to general usability
** The unbounded growth of the Quarantine disk usage for non-master nodes in clustered setups is fixed.
** It's now possible to switch to incremental updates of the AV signatures for ClamAV via GUI, alleviating the problem that both methods fail in certain cases for some users.
==Proxmox Mail Gateway 6.1==
'''Released 27. November 2019'''

* Based on Debian Buster (10.2)
** Proxmox Mail Gateway is based on the latest stable release of Debian 10.2 (Buster).
* Updated SpamAssassin rules
* Kernel 5.3
** Proxmox Mail Gateway shares the kernel with Proxmox VE and is based on the 5.3 series from Ubuntu 19.10

* DKIM-Signing
** Support for adding DomainKeys Identified Mail (DKIM) Signatures (RFC 6376) to outbound emails
** Configuration via GUI
** Signing happens after processing the email with the rule system, thus ensuring that it leaves the Proxmox Mail Gateway with a valid signature
** Flexible control of which domains should get signed with sensible defaults (the relay domains)
** Inside a cluster, one common selector minimizes the overhead for adding required DNS entries

* Attachment Quarantine
** The <code>Remove Attachments</code> action can now optionally deliver the complete email to the Attachment Quarantine
** The Attachment Quarantine offers a comfortable GUI for selectively downloading parts of the email for further analysis, or delivering the mail to the original recipient
** Accessible only by the administrators, it offers safety from accidentally open malicious executables, doc-files, and other attachments infected with malware

* Adjustable SpamAssassin Rule Scores via GUI
** Adapt the scores of individual SpamAssassin rules directly in the GUI
** Enables you to adapt the scoring to your environment, thus achieving better ham/spam detection rates
** Mostly for adding a bit of weight to rules, which are good indicators for Spam in your environment
** Selectively disable Rules, which cause false positives for your environment

* Improved handling of Configuration and Rule changes in clustered environments
** The Filtering Engine gets notified about a range of configuration changes which require a reload
** The notification is propagated during the cluster sync
** This reduces the situations where you had to manually restart <code>pmg-smtp-filter</code>

* Experimental Support for Before Queue filtering
** Proxmox Mail Gateway can now optionally reject an email during the SMTP dialogue, instead of accepting it and silently discarding unwanted email
** This is a requirement in certain situations
** By answering with a permanent failure code (<code>554</code>), there is no need to generate a Non-Delivery Report, which could cause your system to get blacklisted, due to Backscatter
** Currently incompatible with the Tracking Center, thus needs to be explicitly enabled in <code>/etc/pmg/pmg.conf</code>

* Improvements to general usability
** Clarification of ambiguously used terms in the GUI and documentation
** More detailed documentation of the Service Configuration Templates
** Downloading of emails larger than 2 MB as <nowiki>eml</nowiki> from the Spam Quarantine now works
** API-Viewer now usable from inside every running PMG installation at https://pmg.local:8006/api-viewer/index.html or just online via https://pmg.proxmox.com/pmg-docs/api-viewer/index.html

==Proxmox Mail Gateway 6.0==
'''Released 27. August 2019'''

*Proxmox Mail Gateway is based on the latest stable release of Debian 10.0 (Buster)
*This major version update provides an easy to follow step-by-step upgrade path - https://pmg.proxmox.com/wiki/index.php/Upgrade_from_5.x_to_6.0
*Rule name logging - each final action now logs the name of the rule which triggered it to the system log
*The system logs get displayed faster in the GUI because they now use the Proxmox `mini-journalreader` instead of `journalctl`
*ClamAV 0.101.4 (fix for https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=934359)
*Postgres 11 (new major version backing the rule system)
*OpenSSL 1.1.1c with support for TLS 1.3
*Updated shipped SpamAssassin Ruleset
*Countless bugfixes and improvements in the GUI labels

==Proxmox Mail Gateway 5.2==
'''Released 20. March 2019'''

*Mobile Quarantine Interface
**based on the small and modern framework7
**Deliver/Delete/Whitelist/Blacklist mails in your Quarantine from your mobile device
*Improvements in the LDAP integration
**allow the use of FQDNs instead of IPs in the WebUI
**add support for certificate verification (and enable it for new deployments)
**add support for LDAP+starttls
*PMG-Appliance template
**Install PMG as a (unprivileged) Linux Container (e.g. in PVE)
**Introduces the new 'proxmox-mailgateway-container' metapackage, which does not depend on a kernel, and results in a vastly reduced size (and fewer updates)
*Improvements in Logging
**pmg-smtp-filter now logs each SA-Rules score in addition to the rule names - simplifying the analysis of the spam filter's performance without the need to access the mail's source
*Improvements in the WebUI's TLS configuration
*pmgproxy can now be configured via '/etc/default/pmgproxy' to disable/enable certain ciphers, compression, cipher selection preference.
*new command: `pmg-system-report`
**Provides a overview of key characteristics of PMG's setup and performance
**Improves the initial diagnosis for our Enterprise support
*.eml download from the (non-mobile) Quarantine Interface
**Lets you download the complete source of a quarantined message in .eml format for further analysis
*Add support for custom checks
**Enable users to integrate their own custom check logic by providing a defined interface, which can optionally be enabled, and runs a custom check before the mail gets handed to the virus scanner and rule system.
*Improvements of Blacklist/Whitelist handling in the Quarantine Interface
**multiselect for removing multiple entries at once
*proxmox-spamassassin
**Update the shipped rulesets
*PMG-Cluster: full IPv6 support
*ISO works on Citrix XenServer
*Documentation available via https://pmg.proxmox.com/pmg-docs
*Bugfixes

==Proxmox Mail Gateway 5.1==
'''Released 05. October 2018'''

*Allow to configure TLS policy via GUI
*New 'helpdesk' role
*Support SMTPUTF8 protocol feature
*GUI improvements
*Update Debian Stretch 9.5
*Update kernel to 4.15
*Bugfixes

==Proxmox Mail Gateway 5.0==
'''Released 23. January 2018'''

*Fully licensed under the open source license AGPL
*Based on Debian Stretch 9.3 with a 4.13.13 kernel
*ISO installer supports all ZFS raid levels
*ExtJS based user interface
*New API
*Integrated documentation
*Subscription-based enterprise support options (similar to the Proxmox VE support subscription model)
*Bug fixes

== Old Releases ==
*Proxmox Mail Gateway 4.1
*Proxmox Mail Gateway 4.0
*Proxmox Mail Gateway 3.1
*Proxmox Mail Gateway 3.0
*Proxmox Mail Gateway 2.6
*Proxmox Mail Gateway 2.5
*Proxmox Mail Gateway 2.4
*Proxmox Mail Gateway 2.3
*Proxmox Mail Gateway 2.2
*Proxmox Mail Gateway 2.1
*Proxmox Mail Gateway 2.0
*Proxmox Mail Gateway 1.7
*Proxmox Mail Gateway 1.6
*Proxmox Mail Gateway 1.5
*Proxmox Mail Gateway 1.4
*Proxmox Mail Gateway 1.3
*Proxmox Mail Gateway 1.2
*Proxmox Mail Gateway 1.1
*Proxmox Mail Gateway 1.0 (April 2005)

File:Proxmox-Mail-Gateway-Statistics.png

2025-10-01T11:12:01Z

Stoiko Ivanov: Stoiko Ivanov uploaded a new version of File:Proxmox-Mail-Gateway-Statistics.png

File:Proxmox-Mail-Gateway-Statistics.png

2025-10-01T11:09:38Z

Stoiko Ivanov: Stoiko Ivanov uploaded a new version of File:Proxmox-Mail-Gateway-Statistics.png

Main Page

2025-10-01T10:56:20Z

Stoiko Ivanov: /* Upgrading Proxmox Mail Gateway */

__NOTOC__
[[Image:Proxmox-Mail-Gateway-Statistics.png|thumb|300px|right|rightthumb|Proxmox Mail Gateway Statistics]]
'''Proxmox Mail Gateway''' is an open-source email security platform based on Debian GNU/Linux. It protects your mail server from spam, viruses, trojans and phishing emails. The full featured mail proxy is deployed between the firewall and the internal mail server and allows to control all incoming and outgoing email traffic from a single platform with a central web-based management interface. Proxmox Mail Gateway is open-source software, licensed under the GNU AGPL, v3.

The project is developed and maintained by [https://www.proxmox.com/en/ Proxmox Server Solutions GmbH].

For an overview of the Proxmox Mail Gateway key features see the [https://www.proxmox.com/en/proxmox-mail-gateway/features Proxmox website].

=Download=
[https://www.proxmox.com/downloads Download] the latest ISO image files.

Alternate download: https://enterprise.proxmox.com/iso

= Installation =

The installation medium (CD or USB) is a complete operating system, including everything you need to install and run Proxmox Mail Gateway in only a few minutes. It can be installed bare-metal on dedicated hardware or in a virtual machine on all leading virtualization platforms. You can also install it on top of an existing Debian installation.

See the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_installation Installation of Proxmox Mail Gateway] chapter in the reference documentation for details.

For basic setup guidance and some helpful tips see [[Getting started with Proxmox Mail Gateway]].

= Upgrading Proxmox Mail Gateway =
System software updates are downloaded from the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories] and should be applied frequently to receive the most recent bug/security fixes and to obtain the newest features.

You can also upgrade existing Proxmox Mail Gateway installations to the next major release:

* [[Upgrade from 8 to 9|Upgrade from Proxmox Mail Gateway 8 to 9]]
* [[:Category:Upgrade|Upgrade Guides for older Releases]]

=Documentation=
The Proxmox Mail Gateway documentation is freely available in different formats such as HTML, PDF or EPUB, see [https://pmg.proxmox.com/pmg-docs/ Proxmox Mail Gateway Reference Documentation]. You can also access the documentation via the management interface of your Proxmox Mail Gateway installation by clicking on the contextual help buttons.

The developer documentation explains how to get involved in the development process of the Proxmox Mail Gateway, see [[Developer Documentation]]

=Release History and Roadmap=
Take a look on the [[Roadmap]] for existing and upcoming features.

Upgrade from 8 to 9

2025-10-01T10:55:31Z

Stoiko Ivanov:

= Introduction =
Proxmox Mail Gateway 9.x is based on the new major version of Debian (Trixie). 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 Trixie.

In general, there are two ways to upgrade a Proxmox Mail Gateway 8.x system to Proxmox Mail Gateway 9.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 Trixie]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian On top of Debian Trixie]
** 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 these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** If you use SSH, you should use a terminal multiplexer (for example, <code>tmux</code> or <code>screen</code>) to ensure the upgrade can continue even if the SSH connection gets interrupted.
** '''Important''': Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgrade to the latest version of Proxmox Mail Gateway 8.2, see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bookworm repos setup) to upgrade to latest 8.2
** Verify version:
*: You can check the web-interface (reload) at the top, or use <code>pmgversion</code>. Both must show a version with 8.2.5 (or newer), for example something like <code>pmg-api/8.2.5/...</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>.

* Ensure that you have at least 10 GB free disk space on the root mount point:
df -h /
* Check [[#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 ==

First, ensure that your Mail Gateway 8 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.

=== Continuously use the '''pmg8to9''' checklist script ===

A small checklist program named '''<code>pmg8to9</code>''' is included in the latest Proxmox Mail Gateway 8.2 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pmg8to9

; This script only checks and reports things.
: By default, no changes to the system are made and thus, none of the issues will be automatically fixed.
: You should keep in mind that Proxmox Mail Gateway can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

; It is recommended to re-run the script after each attempt to fix an issue.
: This ensures that the actions taken actually fixed the respective warning.

=== 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 ===
First, make sure that the system is using the latest Proxmox Mail Gateway packages:

apt update
apt dist-upgrade
pmgversion -v

The last command should report a version of at least <code>8.2.5</code> or newer.

==== Ensure Repository Archive Keyring is Installed ====

To ensure your system trusts the new APT archive keyring for our Debian Trixie-based releases, install the <code>proxmox-archive-keyring</code> package before switching the repositories to Trixie.

apt install proxmox-archive-keyring

==== Update Debian Base Repositories to Trixie ====
Update all repository entries to Trixie:

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

Ensure that there are no remaining Debian Bookworm specific repositories left. Check all files in the </code>/etc/apt/sources.list.d/</code> folder (like <code>pmg-enterprise.list</code>) and also the top-level <code>/etc/apt/sources.list</code> file. If you are already using sources in the new deb822 format, you will also need to check <code>.sources</code> files in the same location.

{{note|Instead of removing older repositories, you can also disable them. In <code>.list</code> files simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: false</code> to any stanza you want to disable.|reminder}}

See the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories] section in the reference docs for the correct Proxmox Mail Gateway / Debian Trixie repositories.

==== Add the Proxmox Mail Gateway 9 Package Repository ====

Update the enterprise repository to Trixie in the new deb822 format with the following command:

cat > /etc/apt/sources.list.d/pmg-enterprise.sources << EOF
Types: deb
URIs: https://enterprise.proxmox.com/debian/pmg
Suites: trixie
Components: pmg-enterprise
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

After you added the new enterprise repository as above, check that <code>apt</code> picks it up correctly. You can do so by first running <code>apt update</code> followed by <code>apt policy</code>. Make sure that no errors are shown and that <code>apt policy</code> only outputs the desired repositories. Then you can remove the old <code>/etc/apt/sources.list.d/pmg-enterprise.list</code> file. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.

If using the no-subscription repository, see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories]. You should be able to add the Proxmox Mail Gateway 9 no-subscription repository with this command:

cat > /etc/apt/sources.list.d/proxmox.sources << EOF
Types: deb
URIs: http://download.proxmox.com/debian/pmg
Suites: trixie
Components: pmg-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

As with the enterprise repository, make sure that <code>apt</code> picks it up correctly with <code>apt update</code> followed by <code>apt policy</code>. Then remove the previous Proxmox Mail Gateway 8 no-subscription repository from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pmg-install-repo.list</code> or any other <code>.list</code> file you may have added it to. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.

Make sure to check that all the <code>.list</code> files you added in <code>/etc/apt/sources.list.d/</code> got switched over to Trixie correctly.

=== 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 ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth.
A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the upgrade can be finished in less than 5 minutes.

{{Note|While the packages are being upgraded certain operations and requests to the API might fail (for example, logging in as a system user in the <code>pam</code> realm)|reminder}}

apt update
apt dist-upgrade

While running the <code>apt dist-upgrade</code> command, you may be asked to approve changes to configuration files and some service restarts among other prompts. This includes:

* The output of <code>apt-listchanges</code>: You can simply exit it by pressing <kbd>q</kbd>.
* Selecting your default keyboard settings: Simply use the arrow keys to navigate to the one applicable in your case and hit enter.
* Questions about service restarts (like <code>Restart services during package upgrades without asking?</code>): Use the default if unsure, as the reboot after the upgrade will restart all services cleanly anyway.
* Questions about (default) configuration changes: It's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup. Common configuration files with changes, and the recommended choices are:
*; <code>/etc/issue</code>
*: Proxmox Mail Gateway will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.
*; <code>/etc/ssh/sshd_config</code>
*: If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.
*; <code>/etc/clamav/clamd.conf</code> and <code>/etc/clamav/freshclam.conf</code>
*: Those two configuration files are managed by Proxmox Mail Gateway directly, at will be re-generate on any relevant change and on boot.
*: Using the default "No" (keep your currently-installed version) is safe here.
*; <code>/etc/default/grub</code>
*: Here you may want to take special care, as this is normally only asked for if you changed it manually; for example, if you added some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)
*; <code>/etc/postfix/master.cf.proto</code>, <code>/etc/postfix/main.cf.proto</code>
*: These files are not used by Proxmox Mail Gateway - they are the templates for setting up multi-instance postfix instances, which was never used by Proxmox Mail Gateway.
*: See the [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=838528 bugreport at bugs.debian.org] for more context.
*: We recommend to select "Yes" (install the new version), in order to not get asked again for a future upgrade.
*; <code>/etc/crontab</code> and other <code>cron</code> related files on installations on containers on Proxmox VE
*: The crontab gets randomized by Proxmox VE to prevent all jobs running at the same time in all containers.
*: Using the default "No" (keep your currently-installed version) is preferred here.
*; <code>postgresql</code> may print warnings regarding about <code>collation version mismatch</code>
*: These are transitory and will disappear once the cluster has been upgraded to the new version.

'''''Important''''': If configuration templates are used in <code>/etc/pmg/templates</code>, you will see a prompt about the changes in the new version that are not yet incorporated. Review the changes carefully and ensure that only the changes you want are shown in the diff.

It is not yet necessary to reboot your Proxmox Mail Gateway host at this point. Before doing so, first upgrade PostgreSQL database.

=== Upgrade the PostgreSQL database ===

* Upgrade the PostgreSQL main cluster from 15 to 17, using <code>pg_upgradecluster</code>
** Ensure you run this step in a shell, which does not have non-standard locales set. easiest to achieve this is running a fresh <code>su -</code> session and checking that no locale related variables are set to a not installed locale:
su -
env |grep -E 'LC|LANG'
The output should be empty.
** This step will need some '''time''' and enough '''free disk space''' 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 17 15 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 ===

Reboot the host with e command below. Then check the journal to ensure that everything is running correctly again.

reboot

Reconnect to the node after it successfully rebooted.

== After the Proxmox Mail Gateway upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Unmasking & Starting Cluster Services ===

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

=== Remove old PostreSQL Version ===

You can remove the old PostgreSQL version and its data now, if all is working as expected:

apt purge postgresql-15 postgresql-client-15

=== Optional: Modernize apt Repository Sources ===

You can migrate existing repository sources to the recommended deb822 style format, by running:

apt modernize-sources

By answering the following prompt with "n" you can check the changes the command would make before applying them. To apply them simply run the command again and respond to the prompt with "Y".

The command will also keep the old <code>.list</code> files around by appending <code>.bak</code> to them. So you will have the new <code>.sources</code> files and the old repository configurations in the <code>.list.bak</code> files. You can remove the leftover backup files once you verified that everything works smoothly with the new format.

{{note|ensure that all external and third-party repositories (e.g. the one provided by [https://pmg.proxmox.com/wiki/index.php/Install_Avast avast] have provided the keys in the correct places).
|reminder}}

= 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/trixie/release-notes/upgrading.en.html upgrade specific issues for Trixie].

Please also check the known issue list for the Proxmox Mail Gateway 9.X minor releases as this gets updated with future minor releases:
* https://pmg.proxmox.com/wiki/Roadmap#9.0-known-issues

== PostgreSQL ==

=== Setting Locale Failed During Postgres Cluster Upgrade ===

If you are performing the upgrade via SSH (as advised), running <code>pg_upgradecluster -v 17 15 main</code> may fail if your environment variables contain locales that do not exist on your PMG host:
<syntaxhighlight lang="bash">
# [...]
perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
....
Error: The locale requested by the environment is invalid:
...
Error: Could not create target cluster
</syntaxhighlight>

These environment variables may be set automatically depending on your shell's configuration or SSH settings. Most commonly, <code>ssh</code> can pass local environment variables along to your remote host when connecting. See <code>[https://manpages.debian.org/trixie/openssh-client/ssh_config.5.en.html man ssh_config]</code> and <code>[https://manpages.debian.org/trixie/openssh-server/sshd_config.5.en.html man sshd_config]</code> for more information.

To fix this follow the steps in [[#Upgrade_the_PostgreSQL_database|Upgrade the PostgresSQL Cluster]].

== Breaking Changes ==

* [https://www.debian.org/releases/trixie/release-notes/issues.en.html#timezones-split-off-into-tzdata-legacy-package Legacy timezones were split off.]
*: This should not be an issue as Proxmox Mail Gateway never offered the deprecated timezones for selection.
*: However, if you've manually configured one such timezone and <code>postgresql</code> does not start, install the <code>tzdata-legacy</code> package.
* The external <code>avast</code> Virus Scanner [https://pmg.proxmox.com/wiki/index.php/Install_Avast with integration in Promxox Mail Gateway] has not yet released a version for Debian Trixie.
*: If you are using it consider delaying the upgrade until it becomes available

=== Upgrade wants to remove package 'proxmox-mail-gateway' ===

If you have installed Proxmox Mail Gateway on top of a plain Debian Trixie (without using the Proxmox Mail Gateway ISO), you may have installed the package <code>linux-image-amd64</code>, which conflicts with current 9.x setups.

To solve this, you have to remove this package with <code>apt remove linux-image-amd64</code> before the dist-upgrade.

== Network ==

=== Network Interface Name Change ===

The new kernel can recognize more hardware features such as virtual function of PCI(e) devices. Since network names are usually derived from PIC(e) addresses and features recognized by the kernel, the network configuration might need to be adapted to match the new interface names.

In such cases, the network connection to a Proxmox Datacenter Manager host might be lost during or after the upgrade process. Hence, it is generally recommended to have either physical access or an independent remote connection to the host (for example, via IPMI or iKVM).

The latest version of Proxmox Mail Gateway 8.2 and 9.0 provide a package called <code>proxmox-network-interface-pinning</code> that you can install.
This package offers a CLI tool that helps you pin all network interfaces to NIC-based names and update the network configuration simultaneously.

== Systemd-boot meta-package changes the bootloader configuration automatically and should be uninstalled ==
With Debian Trixie the <code>systemd-boot</code> package got split up a bit further into <code>systemd-boot-efi</code> (containing the EFI-binary used for booting), <code>systemd-boot-tools</code> (containing <code>bootctl</code>) and the <code>systemd-boot</code> meta-package (containing hooks which run upon upgrades of itself and other packages and install systemd-boot as bootloader).

As Proxmox Systems usually use <code>systemd-boot</code> for booting only in some configurations (ZFS on root and UEFI booted without secure boot), which are managed by <code>proxmox-boot-tool</code>, the meta-package <code>systemd-boot</code> should be removed.

The package was automatically shipped for systems installed from the PMG 8.0 to PMG 8.2 ISOs, as it contained <code>bootctl</code> in bookworm.
If the <code>pmg8to9</code> checklist script suggests it, the <code>systemd-boot</code> meta-package is safe to remove unless you manually installed it and are using <code>systemd-boot</code> as a bootloader. Should <code>systemd-boot-efi</code> and <code>systemd-boot-tools</code> be required, <code>pmg8to9</code> will warn you accordingly.

The <code>pmg8to9</code> checklist script will change its output depending on the state of the upgrade, and should be [[#Continuously_use_the_pmg8to9_checklist_script|run continuously before and after the upgrade]]. It will print which packages should be removed or added at the appropriate time. The only situation where you should keep the meta-package <code>systemd-boot</code> installed is if you manually setup <code>systemd-boot</code> for your system.

See also [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1110177 the filed bug for systemd-boot].

= External links =

[https://www.debian.org/releases/trixie/release-notes/ Release Notes for Debian 13.0 (trixie)]

[[Category: Upgrade]]

Upgrade from 8 to 9

2025-09-25T08:12:40Z

Stoiko Ivanov: /* Update the configured APT repositories */

<div class="sticky-box warn-box">Note: Proxmox Mail Gateway 9.0 is currently in BETA! Please report any problems in the [https://bugzilla.proxmox.com/ bug tracker] or the [https://forum.proxmox.com/ community forum]</div>
= Introduction =
Proxmox Mail Gateway 9.x is based on the new major version of Debian (Trixie). 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 Trixie.

In general, there are two ways to upgrade a Proxmox Mail Gateway 8.x system to Proxmox Mail Gateway 9.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 Trixie]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian On top of Debian Trixie]
** 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 these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** If you use SSH, you should use a terminal multiplexer (for example, <code>tmux</code> or <code>screen</code>) to ensure the upgrade can continue even if the SSH connection gets interrupted.
** '''Important''': Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgraded to the latest version of Proxmox Mail Gateway 8., see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bookworm repos setup) to upgrade to latest 8.2
** Verify version:
*: You can check the web-interface (reload) at the top, or use <code>pmgversion</code>. Both must show a version with 8.2.5 (or newer), for example something like <code>pmg-api/8.2.5/...</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>.

* Ensure that you have at least 10 GB free disk space on the root mount point:
df -h /
* Check [[#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 8 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.

=== Continuously use the '''pmg8to9''' checklist script ===

A small checklist program named '''<code>pmg8to9</code>''' is included in the latest Proxmox Mail Gateway 8.2 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pmg8to9

This script only '''checks''' and reports things. By default, no changes to the system are made and thus, none of the issues will be automatically fixed.
You should keep in mind that Proxmox Mail Gateway can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

It is recommended to re-run the script after each attempt to fix an issue. This ensures that the actions taken actually fixed the respective warning.

=== 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 ===
First, make sure that the system is using the latest Proxmox Mail Gateway packages:

apt update
apt dist-upgrade
pmgversion -v

The last command should report a version of at least <code>8.2.5</code> or newer.

==== Ensure Repository Archive Keyring is Installed ====

To ensure your system trusts the new APT archive keyring for our Debian Trixie-based releases, install the <code>proxmox-archive-keyring</code> package before switching the repositories to Trixie.

apt install proxmox-archive-keyring

==== Update Debian Base Repositories to Trixie ====
Update all repository entries to Trixie:

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

Ensure that there are no remaining Debian Bookworm specific repositories left. Check all files in the </code>/etc/apt/sources.list.d/</code> folder (like <code>pmg-enterprise.list</code>) and also the top-level <code>/etc/apt/sources.list</code> file. If you are already using sources in the new deb822 format, you will also need to check <code>.sources</code> files in the same location.

{{note|Instead of removing older repositories, you can also disable them. In <code>.list</code> files simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: false</code> to any stanza you want to disable.|reminder}}

See the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories] section in the reference docs for the correct Proxmox Mail Gateway / Debian Trixie repositories.

==== Add the Proxmox Mail Gateway 9 Package Repository ====



During the BETA phase only the <code>pmg-test</code> repository is available, see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories]. You should be able to add it with this command:

cat > /etc/apt/sources.list.d/proxmox-beta.sources << EOF
Types: deb
URIs: http://download.proxmox.com/debian/pmg
Suites: trixie
Components: pmg-test
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

Make sure that <code>apt</code> picks it up correctly with <code>apt update</code> followed by <code>apt policy</code>. Then remove the previous Proxmox Mail Gateway 8 repositories from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pmg-install-repo.list</code> or any other <code>.list</code> file you may have added it to. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.
Instead of removing older repositories, you can also disable them. In <code>.list</code> simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: false</code> to any stanza you want to disable.


Make sure to check that all the <code>.list</code> files you added in <code>/etc/apt/sources.list.d/</code> got switched over to Trixie correctly.

=== 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 ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth.
A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the upgrade can be finished in less than 5 minutes.

{{Note|While the packages are being upgraded certain operations and requests to the API might fail (for example, logging in as a system user in the <code>pam</code> realm)|reminder}}

apt update
apt dist-upgrade

While running the <code>apt dist-upgrade</code> command, you may be asked to approve changes to configuration files and some service restarts among other prompts. This includes:

* The output of <code>apt-listchanges</code>: You can simply exit it by pressing <kbd>q</kbd>.
* Selecting your default keyboard settings: Simply use the arrow keys to navigate to the one applicable in your case and hit enter.
* Questions about service restarts (like <code>Restart services during package upgrades without asking?</code>): Use the default if unsure, as the reboot after the upgrade will restart all services cleanly anyway.
* Questions about (default) configuration changes: It's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup. Common configuration files with changes, and the recommended choices are:
** <code>/etc/issue</code> -> Proxmox Mail Gateway will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.
** <code>/etc/ssh/sshd_config</code> -> If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.
** <code>/etc/clamav/clamd.conf</code> and <code>/etc/clamav/freshclam.conf</code> -> Those two configuration files are managed by Proxmox Mail Gateway directly, at will be re-generate on any relevant change and on boot.
*: Using the default "No" (keep your currently-installed version) is safe here.
** <code>/etc/default/grub</code> -> Here you may want to take special care, as this is normally only asked for if you changed it manually, e.g., for adding some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)
** <code>/etc/postfix/master.cf.proto</code>, <code>/etc/postfix/main.cf.proto</code> -> These files are not used by Proxmox Mail Gateway - they are the templates for setting up multi-instance postfix instances, which was never used by Proxmox Mail Gateway. See the [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=838528 bugreport at bugs.debian.org] for more context.
*: We recommend to select "Yes" (install the new version), in order to not get asked again for a future upgrade.
** <code>/etc/crontab</code> and other <code>cron</code> related files on installations on containers on Proxmox VE: The crontab gets randomized by Proxmox VE to prevent all jobs running at the same time in all containers.
*: Using the default "No" (keep your currently-installed version) is preferred here.
** <code>postgresql</code> may print warnings regarding about <code>collation version mismatch</code> - These are transitory and will disappear once the cluster has been upgraded to the new version.

'''''Important''''': If configuration templates are used in <code>/etc/pmg/templates</code>, you will see a prompt about the changes in the new version that are not yet incorporated. Review the changes carefully and ensure that only the changes you want are shown in the diff.

It is not yet necessary to reboot your Proxmox Mail Gateway host at this point. Before doing so, first upgrade PostgreSQL database.

=== Upgrade the PostgreSQL database ===

* Upgrade the PostgreSQL main cluster from 15 to 17, using <code>pg_upgradecluster</code>
** This step will need some '''time''' and enough '''free disk space''' 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 17 15 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 ===

Reboot the host with e command below. Then check the journal to ensure that everything is running correctly again.

reboot

Reconnect to the node after it successfully rebooted.

== After the Proxmox Mail Gateway upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Unmasking & Starting Cluster Services ===

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

=== Remove old PostreSQL Version ===

You can remove the old PostgreSQL version and its data now, if all is working as expected:

apt purge postgresql-15 postgresql-client-15

=== Optional: Modernize apt Repository Sources ===

You can migrate existing repository sources to the recommended deb822 style format, by running:

apt modernize-sources

By answering the following prompt with "n" you can check the changes the command would make before applying them. To apply them simply run the command again and respond to the prompt with "Y".

The command will also keep the old <code>.list</code> files around by appending <code>.bak</code> to them. So you will have the new <code>.sources</code> files and the old repository configurations in the <code>.list.bak</code> files. You can remove the leftover backup files once you verified that everything works smoothly with the new format.

{{note|ensure that all external and third-party repositories (e.g. the one provided by [https://pmg.proxmox.com/wiki/index.php/Install_Avast avast] have provided the keys in the correct places).
|reminder}}

= 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/trixie/release-notes/upgrading.en.html upgrade specific issues for Trixie].

Please also check the known issue list for the Proxmox Mail Gateway 9.X minor releases as this gets updated with future minor releases:
* https://pmg.proxmox.com/wiki/Roadmap#9.0-known-issues

== Breaking Changes ==

* [https://www.debian.org/releases/trixie/release-notes/issues.en.html#timezones-split-off-into-tzdata-legacy-package Legacy Timezones were split off] This should not be an issue as Proxmox Mail Gateway never offered the deprecated timezones for selection.
but if you've manually configured one and <code>postgresql</code> does not start, install the <code>tzdata-legacy</code> package.
* The external <code>avast</code> Virus Scanner [https://pmg.proxmox.com/wiki/index.php/Install_Avast with integration in Promxox Mail Gateway] has not yet released a version for Debian Trixie. If you are using it consider delaying the upgrade until it becomes available

=== Upgrade wants to remove package 'proxmox-mail-gateway' ===

If you have installed Proxmox Mail Gateway on top of a plain Debian Trixie (without using the Proxmox Mail Gateway ISO), you may have installed the package 'linux-image-amd64', which conflicts with current 9.x setups. To solve this, you have to remove this package with
apt remove linux-image-amd64
before the dist-upgrade.

== Network ==

=== Network Interface Name Change ===

The new kernel can recognize more hardware features such as virtual function of PCI(e) devices. Since network names are usually derived from PIC(e) addresses and features recognized by the kernel, the network configuration might need to be adapted to match the new interface names.

In such cases, the network connection to a Proxmox Datacenter Manager host might be lost during or after the upgrade process. Hence, it is generally recommended to have either physical access or an independent remote connection to the host (for example, via IPMI or iKVM).

The latest version of Proxmox Mail Gateway 8.2 and 9.0 provide a package called <code>proxmox-network-interface-pinning</code> that you can install.
This package offers a CLI tool that helps you pin all network interfaces to NIC-based names and update the network configuration simultaneously.

== Systemd-boot meta-package changes the bootloader configuration automatically and should be uninstalled ==
With Debian Trixie the <code>systemd-boot</code> package got split up a bit further into <code>systemd-boot-efi</code> (containing the EFI-binary used for booting), <code>systemd-boot-tools</code> (containing <code>bootctl</code>) and the <code>systemd-boot</code> meta-package (containing hooks which run upon upgrades of itself and other packages and install systemd-boot as bootloader).

As Proxmox Systems usually use <code>systemd-boot</code> for booting only in some configurations (ZFS on root and UEFI booted without secure boot), which are managed by <code>proxmox-boot-tool</code>, the meta-package <code>systemd-boot</code> should be removed.

The package was automatically shipped for systems installed from the PMG 8.0 to PMG 8.2 ISOs, as it contained <code>bootctl</code> in bookworm.
If the <code>pmg8to9</code> checklist script suggests it, the <code>systemd-boot</code> meta-package is safe to remove unless you manually installed it and are using <code>systemd-boot</code> as a bootloader. Should <code>systemd-boot-efi</code> and <code>systemd-boot-tools</code> be required, <code>pmg8to9</code> will warn you accordingly.

The <code>pmg8to9</code> checklist script will change its output depending on the state of the upgrade, and should be [[#Continuously_use_the_pmg8to9_checklist_script|run continuously before and after the upgrade]]. It will print which packages should be removed or added at the appropriate time. The only situation where you should keep the meta-package <code>systemd-boot</code> installed is if you manually setup <code>systemd-boot</code> for your system.

See also [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1110177 the filed bug for systemd-boot].

= External links =

[https://www.debian.org/releases/trixie/release-notes/ Release Notes for Debian 13.0 (trixie)]

[[Category: Upgrade]]

Upgrade from 8 to 9

2025-09-25T08:12:14Z

Stoiko Ivanov: update needed pmg-api 8 version (for pmg8to9)/* Preconditions */

<div class="sticky-box warn-box">Note: Proxmox Mail Gateway 9.0 is currently in BETA! Please report any problems in the [https://bugzilla.proxmox.com/ bug tracker] or the [https://forum.proxmox.com/ community forum]</div>
= Introduction =
Proxmox Mail Gateway 9.x is based on the new major version of Debian (Trixie). 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 Trixie.

In general, there are two ways to upgrade a Proxmox Mail Gateway 8.x system to Proxmox Mail Gateway 9.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 Trixie]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian On top of Debian Trixie]
** 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 these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** If you use SSH, you should use a terminal multiplexer (for example, <code>tmux</code> or <code>screen</code>) to ensure the upgrade can continue even if the SSH connection gets interrupted.
** '''Important''': Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgraded to the latest version of Proxmox Mail Gateway 8., see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bookworm repos setup) to upgrade to latest 8.2
** Verify version:
*: You can check the web-interface (reload) at the top, or use <code>pmgversion</code>. Both must show a version with 8.2.5 (or newer), for example something like <code>pmg-api/8.2.5/...</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>.

* Ensure that you have at least 10 GB free disk space on the root mount point:
df -h /
* Check [[#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 8 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.

=== Continuously use the '''pmg8to9''' checklist script ===

A small checklist program named '''<code>pmg8to9</code>''' is included in the latest Proxmox Mail Gateway 8.2 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pmg8to9

This script only '''checks''' and reports things. By default, no changes to the system are made and thus, none of the issues will be automatically fixed.
You should keep in mind that Proxmox Mail Gateway can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

It is recommended to re-run the script after each attempt to fix an issue. This ensures that the actions taken actually fixed the respective warning.

=== 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 ===
First, make sure that the system is using the latest Proxmox Mail Gateway packages:

apt update
apt dist-upgrade
pmgversion -v

The last command should report a version of at least <code>8.2.3</code> or newer.

==== Ensure Repository Archive Keyring is Installed ====

To ensure your system trusts the new APT archive keyring for our Debian Trixie-based releases, install the <code>proxmox-archive-keyring</code> package before switching the repositories to Trixie.

apt install proxmox-archive-keyring

==== Update Debian Base Repositories to Trixie ====
Update all repository entries to Trixie:

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

Ensure that there are no remaining Debian Bookworm specific repositories left. Check all files in the </code>/etc/apt/sources.list.d/</code> folder (like <code>pmg-enterprise.list</code>) and also the top-level <code>/etc/apt/sources.list</code> file. If you are already using sources in the new deb822 format, you will also need to check <code>.sources</code> files in the same location.

{{note|Instead of removing older repositories, you can also disable them. In <code>.list</code> files simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: false</code> to any stanza you want to disable.|reminder}}

See the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories] section in the reference docs for the correct Proxmox Mail Gateway / Debian Trixie repositories.

==== Add the Proxmox Mail Gateway 9 Package Repository ====



During the BETA phase only the <code>pmg-test</code> repository is available, see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories]. You should be able to add it with this command:

cat > /etc/apt/sources.list.d/proxmox-beta.sources << EOF
Types: deb
URIs: http://download.proxmox.com/debian/pmg
Suites: trixie
Components: pmg-test
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

Make sure that <code>apt</code> picks it up correctly with <code>apt update</code> followed by <code>apt policy</code>. Then remove the previous Proxmox Mail Gateway 8 repositories from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pmg-install-repo.list</code> or any other <code>.list</code> file you may have added it to. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.
Instead of removing older repositories, you can also disable them. In <code>.list</code> simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: false</code> to any stanza you want to disable.


Make sure to check that all the <code>.list</code> files you added in <code>/etc/apt/sources.list.d/</code> got switched over to Trixie correctly.

=== 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 ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth.
A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the upgrade can be finished in less than 5 minutes.

{{Note|While the packages are being upgraded certain operations and requests to the API might fail (for example, logging in as a system user in the <code>pam</code> realm)|reminder}}

apt update
apt dist-upgrade

While running the <code>apt dist-upgrade</code> command, you may be asked to approve changes to configuration files and some service restarts among other prompts. This includes:

* The output of <code>apt-listchanges</code>: You can simply exit it by pressing <kbd>q</kbd>.
* Selecting your default keyboard settings: Simply use the arrow keys to navigate to the one applicable in your case and hit enter.
* Questions about service restarts (like <code>Restart services during package upgrades without asking?</code>): Use the default if unsure, as the reboot after the upgrade will restart all services cleanly anyway.
* Questions about (default) configuration changes: It's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup. Common configuration files with changes, and the recommended choices are:
** <code>/etc/issue</code> -> Proxmox Mail Gateway will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.
** <code>/etc/ssh/sshd_config</code> -> If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.
** <code>/etc/clamav/clamd.conf</code> and <code>/etc/clamav/freshclam.conf</code> -> Those two configuration files are managed by Proxmox Mail Gateway directly, at will be re-generate on any relevant change and on boot.
*: Using the default "No" (keep your currently-installed version) is safe here.
** <code>/etc/default/grub</code> -> Here you may want to take special care, as this is normally only asked for if you changed it manually, e.g., for adding some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)
** <code>/etc/postfix/master.cf.proto</code>, <code>/etc/postfix/main.cf.proto</code> -> These files are not used by Proxmox Mail Gateway - they are the templates for setting up multi-instance postfix instances, which was never used by Proxmox Mail Gateway. See the [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=838528 bugreport at bugs.debian.org] for more context.
*: We recommend to select "Yes" (install the new version), in order to not get asked again for a future upgrade.
** <code>/etc/crontab</code> and other <code>cron</code> related files on installations on containers on Proxmox VE: The crontab gets randomized by Proxmox VE to prevent all jobs running at the same time in all containers.
*: Using the default "No" (keep your currently-installed version) is preferred here.
** <code>postgresql</code> may print warnings regarding about <code>collation version mismatch</code> - These are transitory and will disappear once the cluster has been upgraded to the new version.

'''''Important''''': If configuration templates are used in <code>/etc/pmg/templates</code>, you will see a prompt about the changes in the new version that are not yet incorporated. Review the changes carefully and ensure that only the changes you want are shown in the diff.

It is not yet necessary to reboot your Proxmox Mail Gateway host at this point. Before doing so, first upgrade PostgreSQL database.

=== Upgrade the PostgreSQL database ===

* Upgrade the PostgreSQL main cluster from 15 to 17, using <code>pg_upgradecluster</code>
** This step will need some '''time''' and enough '''free disk space''' 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 17 15 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 ===

Reboot the host with e command below. Then check the journal to ensure that everything is running correctly again.

reboot

Reconnect to the node after it successfully rebooted.

== After the Proxmox Mail Gateway upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Unmasking & Starting Cluster Services ===

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

=== Remove old PostreSQL Version ===

You can remove the old PostgreSQL version and its data now, if all is working as expected:

apt purge postgresql-15 postgresql-client-15

=== Optional: Modernize apt Repository Sources ===

You can migrate existing repository sources to the recommended deb822 style format, by running:

apt modernize-sources

By answering the following prompt with "n" you can check the changes the command would make before applying them. To apply them simply run the command again and respond to the prompt with "Y".

The command will also keep the old <code>.list</code> files around by appending <code>.bak</code> to them. So you will have the new <code>.sources</code> files and the old repository configurations in the <code>.list.bak</code> files. You can remove the leftover backup files once you verified that everything works smoothly with the new format.

{{note|ensure that all external and third-party repositories (e.g. the one provided by [https://pmg.proxmox.com/wiki/index.php/Install_Avast avast] have provided the keys in the correct places).
|reminder}}

= 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/trixie/release-notes/upgrading.en.html upgrade specific issues for Trixie].

Please also check the known issue list for the Proxmox Mail Gateway 9.X minor releases as this gets updated with future minor releases:
* https://pmg.proxmox.com/wiki/Roadmap#9.0-known-issues

== Breaking Changes ==

* [https://www.debian.org/releases/trixie/release-notes/issues.en.html#timezones-split-off-into-tzdata-legacy-package Legacy Timezones were split off] This should not be an issue as Proxmox Mail Gateway never offered the deprecated timezones for selection.
but if you've manually configured one and <code>postgresql</code> does not start, install the <code>tzdata-legacy</code> package.
* The external <code>avast</code> Virus Scanner [https://pmg.proxmox.com/wiki/index.php/Install_Avast with integration in Promxox Mail Gateway] has not yet released a version for Debian Trixie. If you are using it consider delaying the upgrade until it becomes available

=== Upgrade wants to remove package 'proxmox-mail-gateway' ===

If you have installed Proxmox Mail Gateway on top of a plain Debian Trixie (without using the Proxmox Mail Gateway ISO), you may have installed the package 'linux-image-amd64', which conflicts with current 9.x setups. To solve this, you have to remove this package with
apt remove linux-image-amd64
before the dist-upgrade.

== Network ==

=== Network Interface Name Change ===

The new kernel can recognize more hardware features such as virtual function of PCI(e) devices. Since network names are usually derived from PIC(e) addresses and features recognized by the kernel, the network configuration might need to be adapted to match the new interface names.

In such cases, the network connection to a Proxmox Datacenter Manager host might be lost during or after the upgrade process. Hence, it is generally recommended to have either physical access or an independent remote connection to the host (for example, via IPMI or iKVM).

The latest version of Proxmox Mail Gateway 8.2 and 9.0 provide a package called <code>proxmox-network-interface-pinning</code> that you can install.
This package offers a CLI tool that helps you pin all network interfaces to NIC-based names and update the network configuration simultaneously.

== Systemd-boot meta-package changes the bootloader configuration automatically and should be uninstalled ==
With Debian Trixie the <code>systemd-boot</code> package got split up a bit further into <code>systemd-boot-efi</code> (containing the EFI-binary used for booting), <code>systemd-boot-tools</code> (containing <code>bootctl</code>) and the <code>systemd-boot</code> meta-package (containing hooks which run upon upgrades of itself and other packages and install systemd-boot as bootloader).

As Proxmox Systems usually use <code>systemd-boot</code> for booting only in some configurations (ZFS on root and UEFI booted without secure boot), which are managed by <code>proxmox-boot-tool</code>, the meta-package <code>systemd-boot</code> should be removed.

The package was automatically shipped for systems installed from the PMG 8.0 to PMG 8.2 ISOs, as it contained <code>bootctl</code> in bookworm.
If the <code>pmg8to9</code> checklist script suggests it, the <code>systemd-boot</code> meta-package is safe to remove unless you manually installed it and are using <code>systemd-boot</code> as a bootloader. Should <code>systemd-boot-efi</code> and <code>systemd-boot-tools</code> be required, <code>pmg8to9</code> will warn you accordingly.

The <code>pmg8to9</code> checklist script will change its output depending on the state of the upgrade, and should be [[#Continuously_use_the_pmg8to9_checklist_script|run continuously before and after the upgrade]]. It will print which packages should be removed or added at the appropriate time. The only situation where you should keep the meta-package <code>systemd-boot</code> installed is if you manually setup <code>systemd-boot</code> for your system.

See also [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1110177 the filed bug for systemd-boot].

= External links =

[https://www.debian.org/releases/trixie/release-notes/ Release Notes for Debian 13.0 (trixie)]

[[Category: Upgrade]]

Roadmap

2025-09-24T13:44:21Z

Stoiko Ivanov: /* Proxmox Mail Gateway 8.2 */

<div class="toclimit-3">__TOC__</div>

=Roadmap=
*<s>SpamAssassin 4</s> done
*Continuous security and bug fix updates
=Release History=
See also [https://forum.proxmox.com/forums/announcements.7/ Announcement forum]

== Proxmox Mail Gateway 9.0 (beta) ==
'''Released 24. September 2025'''

{{Note|This is a test version that is not yet intended for production use. The release notes will be continuously updated during the beta phase.}}

* Based on Debian Trixie (13.1)
* SpamAssassin 4.0.2 (with updated rulesets)
* ClamAV 1.4.3
* PostgreSQL 17
* Latest 6.14.11-2 Kernel as new stable default
* ZFS 2.3.4

=== Highlights ===

* New Quarantine UI on mobile browsers based on the modern Rust-based Yew framework.
* Single-Sign-On (SSO) with OpenID Connect, and multiple authentication realms for PMG, which were introduced with PMG 8.2 got significantly improved based on the feedback from our customers and community.
* Synchronize the configuration templates of the core service <code>postfix</code> with the latest recommendations from upstream.
* Adapt the Content-Type filters to the renaming of relevant MIME-types for Microsoft executable formats.

=== Changelog Overview ===

<div id="9.0-rule-system-enhancements"></div>
==== Enhancements in the Rule System ====

==== Enhancements in the Web Interface (GUI) ====
* New Quarantine UI on mobile browers based on the Rust based Yew framework, in place of the one based on framework7.
* The non-mobile Quarantine UI offers a button to switch to the mobile version and recommends switching on displays which are too narrow for comfortable work with it.
* An XSS vulnerability for the HTTP proxy setting was fixed. See the corresponding Proxmox Security Advisory [https://forum.proxmox.com/threads/proxmox-mail-gateway-security-advisories.149333/post-798035 PSA-2025-00015-1] for further information.
* It is now possible to define an authentication realm as default instead of the hard-coded internal <code>pmg</code> realm.
* OpenID Connect realms can now be configured in the GUI, including the <code>username-claim</code>, and the default role to be assigned to auto-created users.
* All labels and widgets containing the terms "blacklist" and "whitelist" were renamed to "blocklist" and "welcomelist," respectively ([https://bugzilla.proxmox.com/show_bug.cgi?id=3755 issue 3755]).
* Improve the configuration and display of DNSBL sites in the Mail Proxy (<code>postscreen_dnsbl_sites</code>)([https://bugzilla.proxmox.com/show_bug.cgi?id=3284 issue 3284]).
* Make the SpamInfo text selectable in the Spam Quarantine interface.
* Improved handling of translations:
** Add support for plural forms and ngettext usage.
** Translations can now contain comments that are extracted from the source code and provide useful context for translators.
* Updated translations, among others:
** Czech (new!)
** Arabic
** Bulgarian
** French
** German
** Italian
** Japanese
** Korean
** Polish
** Russian
** Simplified Chinese
** Spanish
** Swedish
** Traditional Chinese
** Ukrainian

==== Enhancements in the Mail Gateway API Backend ====

* Improvements of OpenID Connect realms, which were introduced in Proxmox Mail Gateway 8.2:
** Fix an error when logging in the first time to a secondary node as a user in an OIDC realm with enabled auto-creation.
** The validation for OIDC <code>client-id</code> and <code>client-key</code> was aligned with the [https://www.rfc-editor.org/rfc/rfc6749#appendix-A relevant RFC].
** The <code>pmg</code> realm is not hardcoded as the default realm anymore, allowing to select a different default realm.
* The <code>pmgqm</code> utility used for sending spam reports to users now supports timespans between 1 and 24 hours in addition to <code>today</code>,<code>yesterday</code> and <code>week</code>([https://bugzilla.proxmox.com/show_bug.cgi?id=2452 issue 2452]).
* Fix an issue where a disallowed value for the Destination TLS policy was accepted by the backend.
* Leading and trailing whitespace in the <code>__MSGID__</code> macro in the rule system (containing the <code>Message-ID</code> header) is now trimmed.
* The TLS-inbound domains are now added to the Proxmox Mail Gateway system report used in Enterprise support.
* Mails generated by Proxmox Mail Gateway now have a <code>Date</code> header allowing them to have a valid DKIM signature.
* The Date header for autogenerated mails is set with a fixed locale to have it compliant with [https://www.rfc-editor.org/rfc/rfc5322 RFC5322].
* An issue of <code>pmgtunnel</code> exiting with errors due to not correctly adapting to changes in the network information parsing code was repaired by fixing its handling of child processes.
* With the upgrade to Debian Trixie, the <code>application/x-ms-dos-executable</code> MIME-Type was renamed to <code>application/vnd.microsoft.portable-executable</code> and <code>application/x-msdownload</code>. As <code>exe</code> files are filtered out in the default ruleset and are usually considered special when handling mails, the existing rules are automatically adapted.
* The <code>postfix</code> MTA package used by PMG was significantly reworked and improved upstream. PMG was adapted to the changes:
** <code>postfix</code> is now explicitly configured to run without <code>chroot</code> confinement ([https://bugzilla.proxmox.com/show_bug.cgi?id=5323 issue 5323]).
*: The processes were running without <code>chroot</code> since version 5.0, the change now is only making this explicit in the configuration files.
*: The change is in accordance with [https://salsa.debian.org/postfix-team/postfix-dev/-/blob/debian/master/debian/README.Debian?ref_type=heads#L44 Debian's recommendation] and in line with [https://www.postfix.org/COMPATIBILITY_README.html#chroot upstream].
** The <code>postfix@-</code> default instance was dropped in favor of directly using <code>postfix</code>
** Deprecations in the shipped postfix configuration templates were fixed, and the [https://www.postfix.org/COMPATIBILITY_README.html compatibility level] was raised to 3.11.
* The Debian repository sources shipped for the <code>pmg-enterprise</code> repository were adapted to the preferred Deb822 format.
* A change in the upstream <code>clamav-freshclam</code> package caused the daemon not to be enabled automatically since PMG 8.1. Now the <code>pmg-api</code> package enables the service in its <code>postinst</code> maintainer script.
* The <code>pmgproxy</code> and <code>pmgdaemon</code> HTTP API servers were adapted to the paths used by the new Yew-based mobile quarantine UI.
* The locale files served by the HTTP API servers now return their modification times to facilitate caching.
* Spamreports send to users and the system status report sent to administrators now have a <code>text/plain</code> version in addition to <code>text/html</code>([https://bugzilla.proxmox.com/show_bug.cgi?id=4023 issue 4023]) ([https://bugzilla.proxmox.com/show_bug.cgi?id=1621 issue 1621]).
* Adding a custom ACME provider via the <code>pmgconfig</code> command line utility was fixed for Proxmox Mail Gateway ([https://bugzilla.proxmox.com/show_bug.cgi?id=6748 issue 6748]).
* The <code>fetchmail</code> package used for downloading mails via POP/IMAP to be processed by Proxmox Mail Gateway now ships a systemd-unit file instead of a legacy sysv-init script. This is a change to Debian upstream's version.
* Fix a spurious warning by the <code>pmgproxy</code> API server daemon, when sending a <code>Cookie</code> header without a valid authentication ticket.
* Fix a spurious warning during early boot due to <code>/run/pmg-smtp-filter.cfg</code> not being in place yet.
* Ensure the <code>pmgspamreport.timer</code> and <code>pmgreport.timer</code> units are run after their prerequisites have started on reboot
* Allow all <code>admin</code> users to see the list of known MIME-Types, when adding ContentType filter objects ([https://bugzilla.proxmox.com/show_bug.cgi?id=5438 issue 5438]).

==== Installation ISO ====

* Install the microcode package matching the current platform.
*: This ensures that new Proxmox Mail Gateway installations get available fixes for CPU security issues and other CPU bugs.
*: This also means that installations now have the <code>non-free-firmware</code> repository enabled.
*: To get microcode updates that were released after the ISO was built, hosts have to be updated regularly. Microcode updates need a reboot to go into effect.
* Ignore network interfaces without a valid MAC address instead of aborting the installation.
* Check that the configured LVM swapsize is not greater than half the disk size ([https://bugzilla.proxmox.com/show_bug.cgi?id=5887 issue 5887]).
* Handle the case where the DHCP lease includes the search domain in the Host Name option.
* Improve error reporting for disk and RAID checks.
* Improvements to the text-based installer and <code>proxmox-auto-install-assistant</code>:
** Improve error reporting when encountering an invalid CIDR.
** Add plausibility checks for subnet masks and IPv4 address
* Improvements to the automated installation:
** Handle the case where the answer file provides an empty search domain.
** Check the number of disks for RAID configurations already when parsing the answer file to catch invalid configurations earlier.
** Warn if the answer file contains deprecated <code>snake_case</code> keys.
** Check for duplicate disks in the answer file.
* Improve robustness of installing on Btrfs.
* Align the plausibility checks performed by the GUI and TUI installers in case of an installation on Btrfs and a single disk.
* Improve the visibility of CLI errors by printing an additional newline.
* Provide <code>--verify-root-password</code> as option for <code>proxmox-auto-install-assistant</code>, to catch mistakes before installation.
* Set the <code>postfix</code> compatibility level to <code>3.6</code> for all products
* The timezone is now set earlier before configuring <code>postfix</code> to ensure it's set correctly if <code>postfix</code> runs in <code>chroot</code>.
*: Note that this affects all products **apart from Proxmox Mail Gateway**, which runs <code>postfix</code> without <code>chroot</code>
* Do not create the deprecated <code>/etc/timezone</code> in alignment with [https://metadata.ftp-master.debian.org/changelogs//main/t/tzdata/tzdata_2025b-4_changelog Debian upstream].
* Ensure that <code>clamav-freshclam</code> is enabled after installation - see the [https://salsa.debian.org/clamav-team/clamav/-/merge_requests/7 patch submitted upstream for more information].

==== Notable changes ====

<div id="9.0-known-issues"></div>

=== Known Issues & Breaking Changes ===

==== The Test Repository Is Now Named pmg-test ====

For consistency with existing repositories, the <code>pmgtest</code> repository is now spelled <code>pmg-test</code>.

==== Breaking Changes in the Proxmox Mail Gateway API ====

* The "Google Safe Browsing" option for <code>ClamAV</code>, which is deprecated since PMG 7.0, in <code>pmg.conf</code> was dropped.
* The superfluous fields <code>network_address</code> and <code>prefix_size</code> returned by the <code>/config/mynetworks</code> API call were dropped, as <code>cidr</code> contains the same information.
* The <code>ReportSpam</code>, <code>Attach</code>, <code>Counter</code> actions, which were not exposed since at least PMG 5.0, and deprecated in PMG 7.2, were dropped from the database handling code.
* Changing the password of a user via <code>PUT /access/users/{userid}</code> has been dropped in favor of the <code>/access/password</code> API call. The GUI is using <code>/access/password</code> since at least 2017.
* Adding and removing entries in the block- and welcomelists of users are now done by the master node in a cluster ([https://bugzilla.proxmox.com/show_bug.cgi?id=4392 issue 4392]).
* The API has renamed all black-/whitelist API calls to block-/welcomelist respectively ([https://bugzilla.proxmox.com/show_bug.cgi?id=3755 issue 3755]).
*: The old API calls are still present for backward compatibility but will be dropped with the next major release.
*: As these calls were also used in the templates for the spamreport e-mails sent to users, which are often modified by administrators, we recommend adapting your overridden configuration templates.
* The <code>pmail_raw</code> variable available to the template for the spam reports sent to users has been renamed to <code>pmail_plain</code> to match the other variables formatted for plain-text reports.
*: This variable was never used by a templated shipped by Promxox Mail Gateway, thus it is very unlikely to have been used in a modification.

==== Potential changes in network interface names ====

Proxmox Mail Gateway 9 can now transparently handle many network interface name changes.

These changes may occur when upgrading from Proxmox Mail Gateway 8.x to Proxmox Mail Gateway 9.0 due to new naming scheme policies or the added support for new NIC features. For example, this may happen when upgrading from Kernel 6.8 to Kernel 6.14.
If the previous primary name remains available as an alternative name, manual intervention may not be necessary since Proxmox Mail Gateway 9.0 allows the use of alternative names in network configurations and firewall rules.

However, in some cases, the previous primary name might not be available as an alternative name after the upgrade. In such cases, manual reconfiguration after the upgrade is currently still necessary.

Before upgrading, you can use the <code>pve-network-interface-pinning</code> CLI tool to pin network interfaces to custom names.
For details, see the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_overriding_network_device_names Overriding Network Device Names] section in the reference documentation.

==== AppArmor 4 ====

Proxmox Mail Gateway 9 ships with AppArmor version 4.1.
Since this version is relatively new, you might see regressions in packages that are not part of the core Proxmox Mail Gateway distribution, for example, <code>clamav</code> or the CUPS printing daemon.

Most issues with older profiles can be resolved by configuring AppArmor to use the 3.0 ABI by adding the <code>abi <abi/3.0>,</code> rule to the relevant profile.
For more details, see the [https://gitlab.com/apparmor/apparmor/-/wikis/apparmorpolicyfeaturesABI AppArmor Wiki].

==== systemd logs "System is tainted: unmerged-bin" after boot ====

It is recommended to ignore this message. See the [https://www.debian.org/releases/trixie/release-notes/issues.en.html#systemd-message-system-is-tainted-unmerged-bin Debian Trixie release notes] for more details.

== Proxmox Mail Gateway 8.2 ==
'''Released 27. February 2025'''

* Based on Debian Bookworm (12.9)
* SpamAssassin 4.0.1 (with updated rulesets)
* ClamAV 1.0.7
* PostgreSQL 15.11
* Latest 6.8 Kernel as new stable default
* Newer 6.11 Kernel as opt-in
* ZFS 2.2.7

=== Highlights ===

* Support for multiple authentication realms, known from Proxmox VE and Proxmox Backup Server.
* Single-Sign-On (SSO) with the new OpenID Connect access realm type as first new realm.
*: External authorization servers can now be integrated for management access with Proxmox Mail Gateway, either using existing public services or your own identity and access management solution, for example, Keycloak, Zitadel or LemonLDAP::NG.
* Support for automated and unattended installation of Proxmox Mail Gateway.
*: Proxmox VE now ships a tool that prepares a Proxmox Mail Gateway ISO for automated installation.
*: The prepared ISO retrieves all required settings for automated installation from an answer file.
*: The answer file can be provided directly in the ISO, on an additional disk such as a USB flash drive, or over the network.
* Rule System: New option for the Content-Type What Objects, to ignore externally provided type information from the filename and header, and rely solely on file signature based detection.
* Rule System: New option for Match Field What Object, to restrict matching on the top header section, instead of also matching headers in attached emails.
* Mails generated by the Proxmox Mail Gateway processing stack can now be signed with DKIM.
* The Proxmox team has been tracking security-relevant issues in our software explicitly and publishes them in the [https://forum.proxmox.com/threads/149333/ Community Forum] since January 2024.
* Seamless upgrade from Proxmox Mail Gateway 7.3, see [https://pmg.proxmox.com/wiki/index.php/Upgrade_from_7_to_8 Upgrade from 7 to 8].

=== Changelog Overview ===

<div id="8.2-rule-system-enhancements"></div>
==== Enhancements in the Rule System ====
* Add an option to the Match Field What Object to only consider the headers of the top mail-part, instead of also comparing the headers of all attachments (including emails forwarded as attachment [https://bugzilla.proxmox.com/show_bug.cgi?id=2709 issue 2709]).
* Optionally restrict Content-Type What Object to only match based on the signature detected in the content of the file, disregarding the <code>Content-Type:</code> and the recommended filename header information ([https://bugzilla.proxmox.com/show_bug.cgi?id=2691 issue 2691] [https://bugzilla.proxmox.com/show_bug.cgi?id=5618 issue 5618]).

==== Enhancements in the Web Interface (GUI) ====
* The end-user quarantine interface now has a short help page explaining its purpose and the available keyboard shortcuts ([https://bugzilla.proxmox.com/show_bug.cgi?id=4311 issue 4311]).
* The listing of Who, What and When Objects can now optionally also display the description set for each object group, without explicitly selecting it.
* Fix an XSS issue in the Mail Queue view.
*: See [https://forum.proxmox.com/threads/149333/post-730687 PSA-2024-00015-1] for details.
* Fix the display message when removing a rule object, to not include the html-escaped icon.
* Fix a typo in the suggested default text when creating new notification objects.
* Remove whitespace before or after the subscription key when adding a new one, as they usually are copy-pasted.
* Fix the public-key DNS record displaying for DKIM selectors larger than 2048 bit.
* Clarify the label for DKIM domain selection.
* Enable autocompletion hints for the username, password, and TFA input fields to improve compatibility with password managers ([https://bugzilla.proxmox.com/show_bug.cgi?id=5251 issue 5251]).
* Show only installed services in the node's system panel by default, but optionally allow to show all services ([https://bugzilla.proxmox.com/show_bug.cgi?id=5611 issue 5611]).
* Fix an issue where clicking on an external link to the GUI would display a login screen, even if the current session was still valid.
* Fix an issue where the date picker would choose the wrong date after changing to a different month.
* Fix an issue where edit windows would not be correctly masked while loading.
* Display the end-of-life message as a notice up until three weeks before the end-of-life date, and display it as a warning from that point on.
* Move the "Reset" button for edit windows to an icon-only button in the title bar ([https://bugzilla.proxmox.com/show_bug.cgi?id=5277 issue 5277]).
*: This reduces the risk of misclicking and accidentally resetting form data.
* Improved translations, among others:
** Bulgarian (NEW!)
** French
** German
** Italian
** Japanese
** Korean
** Russian
** Simplified Chinese
** Spanish
** Traditional Chinese
** Ukrainian

==== Enhancements in the Mail Gateway API Backend ====
* You can now configure the <code>From</code> header information used for mails from the system itself:
** When sending admin reports
** Notifications from a notify action
** Backup jobs
** Bounces for messages refused for part of the recipients if before queue filtering is used and NDR on block is enabled.
*: For spam reports and quarantine links this could already be set in the Spam Quarantine options.
*: The emails still use an empty envelope from address, or for some cases <code>postmaster</code>
*: If this is set to contain an email address with a domain name, and DKIM signing based on header is enabled, the mails are now signed with DKIM ([https://bugzilla.proxmox.com/show_bug.cgi?id=4658 issue 4658]).
* Fix enabling custom SpamAssassin scores on systems where <code>/var/cache</code> is on a different filesystem from <code>/etc</code>.
*: Any pending changes will be preserved across the upgrade.
* Fix a post-authentication privileged file read vulnerability in the Proxmox Mail Gateway API.
*: See [https://forum.proxmox.com/threads/proxmox-mail-gateway-security-advisories.149333/post-705346 PSA-2024-00009-1] for details.
* Make the static email containing the quarantine access link into a template, helping deployments with predominantly non-English speaking users ([https://bugzilla.proxmox.com/show_bug.cgi?id=4211 issue 4211]).
* Support having a <code>text/plain</code> alternative part for report emails generated by PMG, like the daily admin report and the spam quarantine report send to users.
* Fix the default examples for the Who Objects to use a domain (<code>fromthisdomain.example</code>) reserved for documentation and examples ([https://bugzilla.proxmox.com/show_bug.cgi?id=5972 issue 5972]).
* Include the failure to DKIM sign a mail in the Tracking Center output, by adding the internal queue-id to the log message.
* Prevent a mail from being delivered multiple times when a user clicks on the deliver-button in their spam report multiple times ([https://bugzilla.proxmox.com/show_bug.cgi?id=6126 issue 6126]).
* Include the receiver email address when logging release or deletion from the quarantine.
* Fix the custom check script interface to also allow negative spam-scores as result.
* Fix an issue where comments set for LDAP profiles did not preserve percent encodings.
* Clarify that links are not displayed as links, but as plain-text when enabling the <code>allowhrefs</code> option.
* Use a lower level perl routine for setting file-contents to reduce write amplification.
* Use double-hyphen as argument prefix instead of the outdated single-hyphen in CLI commands documentation.
* Fix an issue where the documentation for CLI aliases did not mention the complete aliased command.
* Reload all Proxmox Mail Gateway services when the <code>proxmox-spamassassin</code> package is updated to a new version.

==== Access Control ====
* Realm System ported from Proxmox VE.
*: Enables you to configure multiple external authentication realms for users in the administration backend.
* Single-Sign-On (SSO) with the new OpenID Connect access realm type as first new realm.
*: External authorization servers can now be integrated for management access with Proxmox Mail Gateway, either using existing public services or your own identity and access management solution, for example, Keycloak, Zitadel or LemonLDAP::NG.
*: With the ability to auto-create users upon first logging it.
*: Roles for auto-created users can be queried from a configurable role-claim on your OpenID Connect service, or use a fixed role for all auto-created user of a realm.
*: Initial login for an auto-created user in a cluster needs to be done on the primary/master node.

==== Notable bugfixes and general improvements ====

* Since the release of Proxmox Mail Gateway 8.1 the Proxmox team has begun [https://forum.proxmox.com/forums/security-advisories.26/ tracking explicit security issues publicly in our forum]. The thread lists all security issues since January 2024.
*: Following the posts there is highly recommended.
* Fix an RCE vulnerability in the shim bootloader used for Secure Boot support.
*: See [https://forum.proxmox.com/threads/proxmox-virtual-environment-security-advisories.149331/post-678937 PSA-2024-00007-1] for details.
* Fix unexpected behavior in handling single-part attachments in the rule system.
*: See [https://forum.proxmox.com/threads/proxmox-mail-gateway-security-advisories.149333/post-728656 PSA-2024-00012-1] for details.
* Fix the <code>pmg7to8</code> tool to identify the newer released <code>proxmox-kernel</code> series (6.5, 6.8, 6.11) as expected kernel versions.
* Add a section to the <code>pmg7to8</code> tool for checking potential issues in the currently configured ruleset.
* Increase the minimum password length to 8, following NIST recommendation and the change in the installer
* Include information about the routing table in the <code>pmg-system-report</code> tool used for Enterprise Support information collection.
* Add anchors to subsections of the documentation to provide links to the specific point where an option is documented.
* Document the steps needed to activate a custom SpamAssassin configuration ([https://bugzilla.proxmox.com/show_bug.cgi?id=3979 issue 3979]).

==== Installation ISO ====
* Support for automated and unattended installation of Proxmox Mail Gateway, as already released for Proxmox VE 8.2 and Proxmox Backup Server 3.2.
*: Introduce the <code>proxmox-auto-install-assistant</code> tool that prepares an ISO for automated installation.
*: The automated installation ISO reads all required settings from an answer file in TOML format.
*: One option to provide the answer file is to directly add it to the ISO. Alternatively, the installer can retrieve it from a specifically-labeled partition or via HTTPS from a specific URL.
*: If the answer file is retrieved via HTTPS, URL and fingerprint can be directly added to the ISO, or obtained via DHCP or DNS.
*: See the [https://pve.proxmox.com/wiki/Automated_Installation wiki page on Automated Installation] for more details.
* Ship the recent version 7.20 of memtestx86+, adding support for current CPU Generations (Intel's Arrow Lake and Ryzen 9000 series) as well as preliminary NUMA support.
* Fix an issue where setting ZFS compression to <code>off</code> did not have any effect, due to a change in upstream defaults.
* Improve the layout of widgets in the GTK-based installer for consistent margins and alignment.
* Add a post-installation notification mechanism for automated installations ([https://bugzilla.proxmox.com/show_bug.cgi?id=5536 issue 5536]).
*: This mechanism can be configured with the new <code>post-installation-webhook</code> section in the answer file.
* Add support for running a custom script on first boot after automated installation ([https://bugzilla.proxmox.com/show_bug.cgi?id=5579 issue 5579]).
*: The script can be provided in the ISO or fetched from an URL.
* Allow users to set hashed passwords in the <code>proxmox-auto-installer</code> answer file.
* Allow users to customize the label of the partition from which the automated installer fetches the answer file.
* Add ability to detect and rename an existing ZFS pool named <code>rpool</code> during the installation.
* Improve the email address validation to include a broader set of email address formats.
*: This implements the email validation check specified in the [https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address HTML specification].
* The text-based installer now fails if no supported NIC was found, similar to graphical installer.
* Improve UI consistency by adding the missing background layer for the initial setup error screen in the text-based installer.
* Improve usability for small screens by adding a tabbed view for the advanced options at the disk selection step in the text-based installer.
*: This change only affects screens with a screen width of less than or equal to 80 columns.
* Fix an issue with ISOs generated with the <code>proxmox-auto-install-assistant</code> which caused the user to end up in the GRUB shell when booting from a block device (e.g. an USB flash drive) in UEFI mode.
* Fix a bug which caused some kernel parameters related to the automated installer to be removed incorrectly.
* Fix a bug which caused the installer to not detect Secure Boot in some cases.
* Ask the user for patience while making the system bootable if multiple disks are configured, as this may take longer than expected.
* Preserve the <code>nomodeset</code> kernel command-line parameter.
*: A missing <code>nomodeset</code> parameter has caused display rendering issues when booting the finished Proxmox Mail Gateway installation on some systems ([https://bugzilla.proxmox.com/show_bug.cgi?id=4230#c38 see this comment for more information]).
* Improve user-visible error and log messages in the installer.
* Improve documentation for the <code>proxmox-auto-install-assistant</code>.
* Improve error reporting by printing the full error message when the installation fails in <code>proxmox-auto-installer</code>.
* Improve error reporting by printing the full error message when mounting and unmounting the installation file system fails in <code>proxmox-chroot</code>.
* Improve debugging and testing by enumerating the installation environment anew (e.g. when running the command <code>dump-env</code>).
* Send the correct content-type charset <code>utf-8</code> when fetching answer files from an HTTP server during automated installation.
* Switch the text-based installer rendering backend from termion to crossterm.
* Raise minimum root password length from 5 to 8 characters for all installers.
*: This change is done in accordance with current [https://pages.nist.gov/800-63-4/sp800-63b.html#passwordver NIST recommendations].
* Print more user-visible information about the reasons the auto installation failed.
* Allow RAID levels to be set case-insensitively in the answer file for the auto-installer.
* Prevent the auto-installer from printing progress messages while there has been no progress.
* Disallow configuring BTRFS as root filesystem for Proxmox products that do not currently support it.
* Correctly acknowledge the user's preference whether to reboot on error during auto installation ([https://bugzilla.proxmox.com/show_bug.cgi?id=5984 issue 5984]).
* Allow binary executables (in addition to shell scripts) to be used as the first-boot executable for the auto-installer.
* Allow properties in the answer file of the auto-installer to be either in <code>snake_case</code> or <code>kebab-case</code>.
*: The <code>kebab-case</code> variant is preferred to be more consistent with other Proxmox configuration file formats.
*: The <code>snake_case</code> variant will be gradually deprecated and removed in future major version releases.
* Validate the locale and first-boot-hook settings while preparing the auto-installer ISO instead of failing the installation due to wrong settings.
* Prevent printing non-critical kernel logging messages, which drew over the TUI installer's interface.
* Keep network configuration detected via DHCP in the GUI Installer, even when not clicking <code>Next</code> first ([https://bugzilla.proxmox.com/show_bug.cgi?id=2502 issue 2502]).

<div id="8.2-known-issues"></div>
=== Known Issues & Breaking Changes ===

==== Kernel 6.8 ====

The Proxmox Mail Gateway 8.2 releases will install and use the 6.8 Linux kernel by default. A major kernel version change can have a few hardware-specific side effects. The kernel version 6.8 has been the default kernel for Proxmox Mail Gateway installations since April 2024, so most existing installations should already be using it.

Most issues with new kernel versions do not affect virtual machines and container guests, so virtualized Promox Mail Gateway installations are not affected.

===== Kernel: Change in Network Interface Names =====

Upgrading kernels always carries the risk of changes in network interface names, which can lead to invalid network configurations after a reboot.
In this case, you must either update the network configuration to reflect the name changes, or pin the network interface to its name beforehand.

See [https://pve.proxmox.com/pve-docs/pve-admin-guide.html#network_override_device_names the Proxmox VE reference documentation] on how to pin the interface names based on MAC Addresses.

Currently, the following models are known to be affected at higher rates:
* Models using <code>i40e</code>. Their names can get an additional port suffix like <code>p0</code> added.

== Proxmox Mail Gateway 8.1 ==
'''Released 29. February 2024'''

* Based on Debian Bookworm (12.5)
* SpamAssassin 4.0.0 (with updated rulesets)
* ClamAV 1.0.3
* PostgreSQL 15.6
* Latest 6.5 Kernel as new stable default
* ZFS 2.2.2

=== Highlights ===

* Extend the rule system to allow selection of the <strong>match-if mode</strong> for entries in What/Who/When Objects, and multiple Objects in Rules, providing flexible control over whether all, any, none, or some but not all must match.
*: See the [[#8.1-rule-system-enhancements|enhancements in the rule system section]] for more details and examples.
* Optional DKIM signing based on the <code>From</code> header (also known as <code>RFC5322.From</code>), instead of the Envelope sender (also known as <code>RFC5321.From</code>) ([https://bugzilla.proxmox.com/show_bug.cgi?id=2971 issue 2971]).

* Secure Boot support.
*: Proxmox Mail Gateway now includes a signed shim bootloader trusted by most hardware's UEFI implementations. All necessary components of the boot chain are available in variants signed by Proxmox.
*: The Proxmox Mail Gateway installer can now be run in environments where Secure Boot is required and enabled, and the resulting installation can boot in such environments.
*: Existing Proxmox Mail Gateway installations can be switched over to Secure Boot without reinstallation by executing some manual steps, see the [https://pve.proxmox.com/pve-docs/chapter-sysadmin.html#sysboot_secure_boot documentation] for details.
*: How to use custom secure boot keys has been documented in the [https://pve.proxmox.com/wiki/Secure_Boot_Setup Secure Boot Setup] page in the Proxmox VE wiki. For using DKMS modules with secure boot see the [https://pve.proxmox.com/pve-docs/chapter-sysadmin.html#sysboot_secure_boot reference documentation].

* Seamless upgrade from Proxmox Mail Gateway 7.3, see [https://pmg.proxmox.com/wiki/index.php/Upgrade_from_7_to_8 Upgrade from 7 to 8]

=== Changelog Overview ===

<div id="8.1-rule-system-enhancements"></div>
==== Enhancements in the Rule System ====
* Make the rule system more flexible by introducing a match-if-mode for objects and groups. The match-if-mode of an object (or group) determines whether any, all, not all or none of its children must match for the whole object (or group) to match. This allows to implement complex rules, for example:
** Exclude certain recipients from a rule, while still considering all later rules for them.
** Treat emails differently if they contain particular attachments and are detected as spam or contain a virus.
** Match attachments with a filename ending in <code>.pdf</code>, but being detected as executable by the content-type filter.
** Matching a mail sent from one address and containing a phrase in the subject.
* Disclaimers can now be added on top of the message, instead of only at the bottom ([https://bugzilla.proxmox.com/show_bug.cgi?id=2606 issue 2606]).
* The separator <code>--</code> for disclaimers can now be optionally omitted ([https://bugzilla.proxmox.com/show_bug.cgi?id=2430 issue 2430]).
* Adapt the number of parallel worker processes for the SMTP filter to increased memory requirements and availability.
* Make the timeout for processing a mail consistent between before- and after-queue filtering, and make it configurable.
* Prevent duplicate mail delivery when filtering runs into a timeout.
* Fix the synchronization of the user wants- and blocklists if the last address is removed for a user ([https://bugzilla.proxmox.com/show_bug.cgi?id=4392 issue 4392]).
* Further improve input validation for regular expressions in the rule system ([https://bugzilla.proxmox.com/show_bug.cgi?id=4811 issue 4811]).
* Fix an error in the collection of virus occurrence statistics.
* The spam report e-mails now correctly handle addresses with characters that need to be escaped for the API and GUI.
* Display the descriptions for rules from the advanced KAM ruleset in the spam info grid in the quarantine view.
* Improve the output of <code>pmgdb dump</code> used for gathering information about the ruleset:
** Add information about the type of What Objects
** Add optional <code>--rules</code> parameter to restrict output to rules that are active or inactive
** Visually emphasize whether a rule is active
** Remove unnecessary filler words from output

==== Enhancements in the Web Interface (GUI) ====

* Make it easier to manage large deployments by adding a filter- and search-box for ([https://bugzilla.proxmox.com/show_bug.cgi?id=4510 issue 4510]):
*: Relay Domains
*: Transport
*: Networks
*: Objects in the rule system
* Add icons to the backup destination panel for improved UX.
* Fix an issue where the OK button would stay disabled when editing an ACME DNS challenge plugin ([https://bugzilla.proxmox.com/show_bug.cgi?id=4531 issue 4531]).
* Fix TLS 1.3-only configuration for the API proxy server ([https://bugzilla.proxmox.com/show_bug.cgi?id=4859 issue 4859]).
* Fix spelling errors in the GUI and improve gettext instances so that they can be better translated.
* Improved translations, among others:
** Croatian (NEW!)
** Georgian (NEW!)
** Arabic
** Catalan
** German
** Italian
** Polish
** Simplified Chinese
** Spanish
** Traditional Chinese
** Ukrainian
** The language code for Korean was corrected from <code>kr</code> to <code>ko</code> in alignment with ISO 639-1, while maintaining a symbolic link for backward compatibility for now.
** Several remaining occurrences of the <code>GiB</code> unit in the GUI can now be translated ([https://bugzilla.proxmox.com/show_bug.cgi?id=4551 issue 4551]).

==== Access Control ====

* Allow usernames shorter than 4 characters, in accordance with Proxmox VE and Proxmox Backup Server ([https://bugzilla.proxmox.com/show_bug.cgi?id=4818 issue 4818])

==== Notable bug fixes and general improvements ====

* Harden the Postfix configuration for the external port to address the [https://www.postfix.org/smtp-smuggling.html SMTP Smuggling] security issue, by implementing all recommendations from upstream.
* Switch the default time-stamp format expected by the Tracking Center to the RFC3339 based information in the logs in Proxmox Mail Gateway 8.0 and newer. While this was initially meant as a small clean-up a few issues around the switch between DST and regular time were fixed with the changes.
* Secure Boot support.
*: Proxmox Mail Gateway now ships a shim bootloader signed by a CA trusted by most hardware's UEFI implementation. In addition, it ships variants of the GRUB bootloader, MOK utilities and kernel images signed by Proxmox and trusted by the shim bootloader.
*: New installation will support Secure Boot out of the box if it is enabled.
*: Existing installations can be adapted to Secure Boot by installing optional packages, and possibly reformatting and re-initializing the ESP(s), without the need for a complete reinstallation. See [https://pve.proxmox.com/wiki/Secure_Boot_Setup the wiki article for more details].
* Fix cluster setups recreated after restoring a backup with statistics ([https://bugzilla.proxmox.com/show_bug.cgi?id=5189 issue 5189]).
* The kernel shipped by Proxmox is shared for all products. This is now reflected in the renaming from <code>pve-kernel</code> and <code>pve-headers</code> to <code>proxmox-kernel</code> and <code>proxmox-headers</code> respectively in all relevant packages.
* The new <code>proxmox-default-kernel</code> and <code>proxmox-default-headers</code> meta-packages will depend on the currently recommended kernel-series.
* Many edge-cases encountered during the upgrade from Proxmox Mail Gateway 7.3 to 8 by our user-base are now detected and warned about in the improved <code>pmg7to8</code> checks:
** Notify when a template was copied to <code>/etc/pmg/templates</code> without any modifications, to prevent missing important changes to config files.
** Warn if [https://github.com/dell/dkms DKMS] modules are detected, as many of them do not upgrade smoothly to the newer kernel versions in Mail Gateway 8.
** Warn if version 7 of the Mail Gateway system does not have the correct meta-package of <code>grub</code> installed. The correct meta-package is required to actually upgrade the installed bootloader to the newest version.
* Support for adding custom ACME enabled CA's which require authentication through '''E'''xternal '''A'''ccount '''B'''inding (EAB) on the command line ([https://bugzilla.proxmox.com/show_bug.cgi?id=4497 issue 4497]).
* Fix non-interactive use of the <code>pmgsh</code> utility ([https://bugzilla.proxmox.com/show_bug.cgi?id=4815 issue 4815]).
* Improve the parsing of config and system files, used in many places of the code. This fixes an issue with displaying the network interfaces without a correct hostname entry in <code>/etc/hosts</code> and aims to prevent similar issues in the future.
* Prevent cluster synchronization from failing due to a change in fingerprint parsing in OpenSSL.
* Add support for having a Proxmox Backup Server remote on an alternate port ([https://bugzilla.proxmox.com/show_bug.cgi?id=4944 issue 4944]).
* Reduce log severity for periodic informational messages from <code>error</code> to <code>info</code>.
* Changelogs for new package versions shown in the UI are now all gathered with <code>apt changelog</code>, as this is now supported by the Proxmox repositories.
* Add information about the configured domains for DKIM signing to the report generated for support cases.
* The documentation on firmware updates provided by the operating system has been extended and revised, helping administrators to identify if their setup is optimal.

==== Installation ISO ====

* The ISO is able to run on Secure Boot enabled machines.
* The text-based UI got significant improvement based on the feedback received from the first release in Proxmox Mail Gateway 8.0.
* The current link-state of each network interface is now displayed in the network configuration view, helping in identifying the correct NIC for the management interface ([https://bugzilla.proxmox.com/show_bug.cgi?id=4869 issue 4869]).
* If provided by the DHCP server, the hostname field is already filled out with the information from the lease.
* The correct meta-package of <code>grub</code> is now installed based on the boot mode (<code>grub-pc</code> or <code>grub-efi-amd64</code>). This ensures that the bootloader on disk gets updated when there is an upgrade for the <code>grub</code> package.
* The text-based UI is now also available over a serial console, for headless systems with a serial port.
* The root dataset on ZFS installations now uses <code>acltype=posixacl</code> in line with [https://openzfs.github.io/openzfs-docs/Getting%20Started/Debian/Debian%20Bookworm%20Root%20on%20ZFS.html upstream's recommendation].
* Kernel parameters passed on the command line during install are now also set in the target system ([https://bugzilla.proxmox.com/show_bug.cgi?id=4747 issue 4747]).
* Fix the warning that is shown in case the address family (IPv4, IPv6) of the host IP and DNS server do not match.
* The text-based UI now sets the correct disk-size for the selected disk, instead of limiting the installation to the size of the first disk in the list ([https://bugzilla.proxmox.com/show_bug.cgi?id=4856 issue 4856]).
* For better UX, the text-based UI now also displays a count-down before automatically rebooting.
* The screensaver in the graphical installer is now disabled.
* The graphical installer now displays the units used for disk-based options.
* The kernel command-line parameter <code>vga788</code> is now set for both the graphical debug and all text-based UI installation options. This improves compatibility of the installer with certain hardware combinations.
* Remove the checksum-options of <code>off</code> and <code>fletcher2</code> for ZFS, for being dangerous and deprecated respectively.
* Improve the layout in the graphical installer to ensure correct margins and alignment of widgets.
* Set a timeout for country detection, preventing the installer from hanging at that step ([https://bugzilla.proxmox.com/show_bug.cgi?id=4872 issue 4872]).
* General improvements for running external commands in the installer backend in order to prevent lockups.
* Improve validation of hostname length and allowed characters set in the installer ([https://bugzilla.proxmox.com/show_bug.cgi?id=5230 issue 5230]).

<div id="8.1-known-issues"></div>
=== Known Issues & Breaking Changes ===
==== Kernel ====
* Some SAS2008 controllers need a workaround to get detected since kernel 6.2, see the [https://forum.proxmox.com/threads/no-sas2008-after-upgrade.129499/page-4#post-607858 forum thread] for details.

* The TPM (Trusted Platform Module) hardware random number generator (RNG) is now disabled on all AMD systems equipped with a firmware-based TPM (fTPM) device. This change was implemented due to such RNGs causing stutters in many systems. Affected systems should switch the RNG source from <code>/dev/hwrng</code> to an alternative, like <code>/dev/urandom</code>.
: Reference: [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=554b841d470338a3b1d6335b14ee1cd0c8f5d754 kernel commit "tpm: Disable RNG for all AMD fTPMs"]

* Some Dell models, which appear to include all those using a BCM5720 network card, have a compatibility issue with the <code>tg3</code> driver in the kernel based on version 6.5.11.
*: From our current understanding 14th Generation Dell Servers (T140, R240, R640,...) are affected, while others (e.g., R630, R620, R610,...) do not seem to be affected. We are currently investigating this issue. In the meantime, we recommend pinning the kernel to version 6.2 on affected hosts.
*: Some users report that disabling the <code>X2APIC</code> option in the BIOS resolved this issue as a workaround.

== Proxmox Mail Gateway 8.0 ==
'''Released 29. June 2023'''

* Based on Debian Bookworm (12.0)
* Latest 6.2 Kernel as stable default
* ZFS 2.1.12
* SpamAssassin 4.0.0 (with updated rulesets)
* ClamAV 1.0.1
* PostgreSQL 15.3

=== Highlights ===

* New major release based on the great Debian Bookworm.

* Seamless upgrade from Proxmox Mail Gateway 7.3, see [[Upgrade from 7 to 8]]
*: New <code>pmg7to8</code> pre-flight checking script analyzing the system for common misconfigurations and missed steps during the upgrade

* Add new text-based UI mode for the installation ISO, written in Rust using the [https://github.com/gyscos/cursive Cursive] TUI (Text User Interface) library:
*: You can use the new TUI mode to work around issues with launching the GTK based graphical installer, sometimes observed on both very new and rather old hardware.
*: The new text mode executes the same code for the actual installation as the existing graphical mode.

=== Changelog Overview ===

==== Enhancements in the Rule System ====

* When adding a "Match Field" ''What'' object, check that the provided regular expression is a valid regular expression.

* Disable SpamAssassin's naive-Bayesian-style classifier and the auto-whitelisting plugin by default.
*: Both features lead to worse detection rates in the Spam Filter in most setups.
*: Bayes needs manual training and thorough consideration, as well as continuous maintenance.
*: Existing setups are kept without change on upgrade.
*: For new setups the old behavior can be enabled through the GUI.


==== Enhancements in the Web Interface (GUI) ====
* Improved Dark color theme:
*: The Dark color theme, introduced in Proxmox Mail Gateway 7.3, received a lot of positive feedback from our community, which resulted in further improvements.
* Improved translations, among others:
** Ukrainian (NEW)

** Japanese

** Simplified Chinese

** Traditional Chinese

** The size units (Bytes, KB, MiB,...) are now passed through the translation framework as well, allowing localized variants (e.g., for French).

** The language selection is now localized and displayed in the currently selected language

* Disable advanced statistic filters by default, as their behavior may not be immediately clear without consulting the documentation first.

* HTML-encode rule names before rendering as additional hardening against XSS.

* The tracking center can now parse the new syslog format for dates that was introduced in Debian Bookworm.
*: The logging format of <code>rsyslog</code> was changed to include Timezone information (RFC3339) in the logs, making the Tracking Center more robust across DST changes and year changes.


==== Access control ====
* Add TFA/TOTP lockout to protect against an attacker who has obtained the user password and attempts to guess the second factor:
*: If TFA fails too many times in a row, this user account is locked out of TFA for an hour. If TOTP fails too many times in a row, TOTP is disabled for the user account. Using a recovery key will unlock a user account. 

==== Installation ISO ====

* Add new text-based UI mode for the installation ISO, written in Rust using the [https://github.com/gyscos/cursive Cursive] TUI (Text User Interface) library:
*: You can use the new TUI mode to work around issues with launching the GTK based graphical installer, sometimes observed on both very new and rather old hardware.
*: The new text mode executes the same code for the actual installation as the existing graphical mode.
* The version of BusyBox shipped with the ISO was updated to version 1.36.1.
* Detection of unreasonable system time.
: If the system time is older than the time the installer was created, the system notifies the user with a warning.

* <code>ethtool</code> is now shipped with the ISO and installed on all systems.
* <code>systemd-boot</code> is provided by its own package instead of <code>systemd</code> in Debian Bookworm and is installed with the new ISO.
* The installation ISO now ships the dependencies for extracting text from attachments using SpamAssassin 4, eliminating the need to install the packages manually.

==== Notable bugfixes and general improvements ====

* Add a <code>pmg7to8</code> CLI tool to assist in upgrading from Proxmox Mail Gateway 7.3 to 8.

* Fix an issue where an invalid regular expression in a "Match Field" ''What'' object would cause <code>pmg-smtp-filter</code> to exit and restart, possibly leading to wrongly denied mails. Instead, <code>pmg-smtp-filter</code> now logs a warning if it encounters an invalid regular expression.

* During package installation or upgrade, ignore certain transient or obvious errors to avoid leaving the package in a broken state.

* Fix an issue where the Proxmox Mail Gateway system report would wrongly indicate a DNS misconfiguration.

* When authenticating via PAM, pass the <code>PAM_RHOST</code> item. With this, it is possible to manually configure PAM such that certain users (for example root@pam) can only log in from certain hosts.


<div id="8.0-known-issues"></div>
=== Known Issues & Breaking Changes ===

* The advanced statistics filter is now disabled by default.
*: To avoid changing the behavior of a Proxmox Mail Gateway 7.3 instance on upgrade, the upgrade process will set the <code>advfilter</code> option to <code>1</code> if no explicit value is set.

* SpamAssassin's naive-Bayesian-style classifier and the auto-whitelisting plugin are now disabled by default.
*:To avoid changing the behavior of a Proxmox Mail Gateway 7.3 instance on upgrade, the upgrade process will set each of the <code>use_awl</code>/<code>use_bayes</code> options to <code>1</code> if no explicit value is set.

== Proxmox Mail Gateway 7.3 ==
'''Released 28. March 2023'''

* Based on Debian Bullseye (11.6)
* Latest 5.15 Kernel as stable default
* Newer 6.2 kernel as opt-in
* ZFS 2.1.9
* SpamAssassin 4.0.0 (new major version)
* PostgreSQL 13.10

=== Highlights ===

* Proxmox Mail Gateway now provides a dark theme for the administrative and quarantine web interfaces.
* SpamAssassin 4.0.0 was integrated, along with many of its new capabilities, like (optionally) scanning document contents (docx, pdf, images,...), or resolving URLs from url-shorteners.

=== Changelog Overview ===

==== Enhancements in the Rule System ====
* New major release SpamAssassin 4.0.0, with many new features:
** Detection of spam inside of attachments. This is implemented for the file types <code>.pdf</code>, <code>.odt</code>, <code>.docx</code>, <code>.doc</code>, <code>.rtf</code>, as well as images (through OCR).
*:: Attachment scanning can be enabled using the Web UI (<code>Spam Detector</code> -> <code>Options</code>), which sets the <code>extract_text</code> option in the <code>spam</code> section of <code>/etc/pmg/pmg.conf</code>.
*:: The dependencies required for attachment scanning are marked as optional, but recommended dependency for the <code>pmg-api</code> package.
*:: This means that on systems that did not change the apt preference the new dependencies should be pulled in automatically on upgrade, otherwise you might need to manually install them.
*: Note that attachment scanning, and OCR in particular, increases CPU time spent per mail. Depending on email volume and available CPU power, you may see a significant increase in load.
** Follow and analyze URL-shortener links.
** Improved support for using information from DMARC-policies.
** Improved handling of internationalized (IDN) domain names.
* Adaptation of the SpamAssassin integration for version 4.0.0:
: The SpamAssassin configuration files shipped with the <code>pmg-api</code> package were adapted to the new features.
: <code>extract_text</code> was added as new option for the spam detector to disable content scanning, while most other new options are triggered with the <code>use_rbl</code> option.
: On deployments with modified templates, the upgrade process will ask how changes should be merged. This provides an opportunity to re-evaluate which modifications are still needed.
* Support enforcing TLS-only connections for mails from certain domains:
: It is now possible to enforce TLS encryption for inbound mail, complementing the already-present TLS policy functionality for outbound mail.
* Improved handling of SMTPUTF8:
: Based on the user feedback on UTF-8 support for the rule system introduced in Proxmox Mail Gateway 7.2, it is now possible to disable SMTPUTF8 through the API and GUI.
: The detection for SMTPUTF8 was aligned with the implementation in <code>postfix</code>.
* The What objects "Match Archive Filename" now also use the optional filename from the GZIP header for matching.
* Support trusted network entries with host bits set in the CIDR:
: Quite a few deployments did use a CIDR with host-bits set, for example 192.0.2.5/24 instead of 192.0.2.0/24. This is now translated internally and handled correctly.
* Ordering of multiple rules with the same priority is now stable, despite not being a recommended setup.

==== Enhancements in the Web Interface (GUI) ====

* Add a fully-integrated "Proxmox Dark" color theme variant of the long-time Crisp light theme.
: By default, the <code>prefers-color-scheme</code> media query from the Browser/OS will be used to decide the default color scheme.
: Users can override the theme via a newly added <code>Color Theme</code> menu in the user menu.
* Add "Proxmox Dark" color theme to the Proxmox Mail Gateway reference documentation.
: The <code>prefers-color-scheme</code> media query from the Browser/OS will be used to decide if the light or dark color scheme should be used.
: The new dark theme is also available in the [https://pmg.proxmox.com/pmg-docs/api-viewer/index.html#/nodes/{node}/version Proxmox Mail Gateway API Viewer].
* Task logs can now be downloaded directly as text files for further inspection.
* The language chooser now displays, for each available language, both its native name as well as its name translated to the currently active language.
* HTML-encode API results before rendering as additional hardening against XSS.
* Automatically redirect HTTP requests to HTTPS for convenience.
: This avoids "Connection reset" browser errors that can be confusing, especially after setting up a Proxmox Mail Gateway host the first time.
* Invalid entries in advanced fields now cause the advanced panel to unfold, providing direct feedback.
* Improved translations, among others:
** Arabic
** French
** German
** Italian
** Japanese
** Russian
** Slovenian
** Simplified Chinese
** Traditional Chinese

==== Notable General Improvements and Bug Fixes ====
* The documentation has now a chapter describing the statistics part of the GUI and API.
* Mail delivery from quarantine uses new code for sending locally generated mail, with the following improvements:
** support for IPv6-only deployments and delivery status notifications.
** Correct decoding of addresses containing UTF-8.
* The cleanup before restoring the configuration from a backup was improved, preventing issues when restoring without rebooting the system.
* Logging of errors when sending locally generated mail was improved.
* Errors in files related to TLS-policy are now also reported in the syslog.
* The output of <code>pmgdb dump</code> is now able to handle UTF-8 characters in rule names, object names, and comments.

==== Installation ISO ====

* the version of BusyBox shipped with the ISO was updated to version 1.36.0.
* The EFI System Partition (ESP) defaults to 1 GiB of size if the root disk partition (<code>hdsize</code>) is bigger than 100 GB.
* UTC can now be selected as timezone during installation.

<div id="7.3-known-issues"></div>

=== Known Issues & Breaking Changes ===

* The ISO does not ship the optional dependencies for extracting text from attachments - If you installed from the ISO and want to use the feature, you can simply install them manually
apt install antiword docx2txt odt2txt poppler-utils tesseract-ocr unrtf

== Proxmox Mail Gateway 7.2 ==
'''Released 30. November 2022'''

* Based on Debian Bullseye (11.5)
* Latest 5.15 Kernel as stable default (5.15.74)
* Newer 5.19 kernel as opt-in
* ZFS 2.1.6
* SpamAssassin 3.4.6 (with updated rule-set)
* PostgreSQL 13.8

'''Changelog Overview'''

* Enhancements in the Rule system:
** Improved handling of international emails
*** Support for UTF-8 characters in the rule system (e.g. matching non-ASCII subjects).
*** Better handling of [https://www.rfc-editor.org/rfc/rfc6531 SMTPUTF8 emails] (the smtp-dialogue already contains non-ASCII data, the headers contain UTF-8 data without MIME encoding).
** Proper encoding for template-variable information in the Notifications and Modify Field actions.
** MatchField now matches all occurrences of a header - not only the first one - especially relevant for <code>Received</code> headers.
** Deprecated the <code>Attach</code>, <code>Counter</code> and <code>ReportSpam</code> Actions.
*: While they were present in the code of Proxmox Mail Gateway, they were never exposed in the GUI or API.
*: All three have now been deprecated and will be removed with version 8.0.

* Improved Quarantine UX:
** Quarantine interface for Administrators: many of the recent features for end-users in the Spam Quarantine have been ported to the administrator view:
*** Allow selection of multiple mails.
*** Context menu in the mail-listing.
*** Display the Receiver information in the Attachment and Virus quarantines and the Mail Info widget.
** Augmented the information visualization in the Spam information grid.
*** The weight (number of points) and the type of impact (positive or negative) of SpamAssassin rules is now shown with colors and font-weights to make them easier to grasp.
*** The rule IDs and scores are using a monospaced font for better comparison of values.
** Colorized <code>Deliver</code> and <code>Delete</code> actions improves intuitive handling of the common actions.
** Display of attachments in the Spam and Virus quarantines (for a more complete overview of the mail).
** Attachment and Virus quarantines can now optionally be filtered by Receiver - especially helpful in larger deployments.
** Display of descriptions for locally defined SpamAssassin rules.
** Fix displaying the quarantine interface on narrow screens: Part of the action buttons were cut off and not reachable through scrolling.

* Enhancements in the web interface (GUI):
** The Postfix queue interface now displays the mail's headers in a decoded way - so that you see it as in your mail user agent.
** The Statistic time selector now does not show non-existent day/month combinations (e.g. the 31. Day of February).
** Better spacing of the Field labels in the rule object edit windows.
** Improved translations, among others:
*** Dutch
*** German
*** Italian
*** Polish
*** Traditional Chinese
*** Turkish

* Support Proxmox Offline Mirroring & Subscription Handling
** Proxmox Offline Mirror: The tool supports subscriptions and repository mirrors for air-gapped systems. The newly added [https://pom.proxmox.com proxmox-offline-mirror] utility can now be used to keep Proxmox Mail Gateway hosts, without access to the public internet up-to-date and running with a valid subscription.

* Notable General Improvements and Bugfixes:
** Add IP networks uniquely to template variables (<code>postfix.mynetworks</code>)
*: If you had multiple entries in your transport directory, all pointing to the same host, they were added multiple times to the variable used in the configuration system.
** Support for Proxmox Backup Server Namespaces.
** Spam report emails now correctly display the <code>From</code> header, even if it contains a comma (e.g. <code>"Lastname, Firstname" <firstname.lastname@domain.example></code>).
** The left-over config file <code>/etc/apt/apt.conf.d/75pmgconf</code> was removed, enabling the automatic removal of obsolete kernel packages, which can take up significant amounts of space.
** SpamAssassin updates now handle updates to multiple channels correctly on the first run.
** Improved parsing of email attributes from LDAP profiles.
** Changing the directory to '/' before running <code>psql</code> as <code>postgres</code>user - preventing the printing of harmless but confusing warnings with various Proxmox Mail Gateway CLI utilities.
** Support disabling TLS 1.2 and configuring TLS 1.3 ciphers for <code>pmgproxy</code> - following the change for <code>pveproxy</code> in Proxmox VE.
'''Upgrade from 6.4'''

See [[Upgrade from 6.x to 7.0]]
== Proxmox Mail Gateway 7.1 ==
'''Released 30. November 2021'''
* Based on Debian Bullseye (11.1)
* Kernel 5.13
* ZFS 2.1
* SpamAssassin 3.4.6 (with updated rule-set)
* PostgreSQL 13.5

'''Changelog Overview'''

* Enhancements in the web interface (GUI)
** Improved configuration editing of LDAP backends: Changes can now be applied without having to specify a password.
** The APT repository configuration, rather than being restricted to 'root', is now visible and editable by all users with 'Administrator' privileges.
** Improved translations, among others:
*** Arabic
*** Basque
*** Brazilian Portuguese
*** French
*** German
*** Simplified Chinese
*** Traditional Chinese
*** Turkish

* Two-Factor Authentication
** Two-factor authentication (TFA) for the web interface. Shares the TFA implementation from Proxmox Backup Server, written in rust.
** Support for multiple types of second factors:
*** WebAuthn, which supports a wide range of security devices, like hardware keys or trusted platform modules.
*** Time-based One-Time Password (TOTP), a short code derived from a shared secret and the current time, it changes every 30 seconds.
*** Single use Recovery Keys.

* Backend and API
** Improved support for setups using DHCP for their network configuration:
*: While email still requires working DNS records, you can now manage and configure the IP of your Proxmox Mail Gateway in your DHCP configuration.
** When adding a new entry to a Who object, a duplicate check is performed before saving.
** Better handling of trailing dot in domain-names:
*: Proxmox Mail Gateway uses the first search domain from <code>/etc/resolv.conf</code> as domain name - it can now handle entries with a trailing dot.
** Delivery status notification (DSN, RFC 3461) support for outbound email with enabled before-queue filtering.
'''Upgrade from 6.4'''

See [[Upgrade from 6.x to 7.0]]

== Proxmox Mail Gateway 7.0 ==
'''Released 15. July 2021'''
* Based on Debian Bullseye (11)
* SpamAssassin 3.4.6 (with updated rule-set)
* Kernel 5.11
* PostgreSQL 13

'''Changelog Overview'''

* Enhancements in the web interface (GUI)
** Make dashboard status panel more detailed, showing, among other things, uptime, kernel version, CPU info and a high level repository status overview.
** New APT repository management panel in the <code>Administration</code> tab shows an in-depth status and a list of all configured repositories.
**: Basic repository management, for example, activating or deactivating a repository, is also supported.
** Updated ExtJS JavaScript framework to latest GPL release 7.0
** Added advanced task-log filtering
** Improved translations, including:
*** Arabic
*** French
*** German
*** Japanese
*** Polish
*** Turkish

* ACME/Let's Encrypt
** Support the use of wildcard domains with the DNS plugins
** API: nodeconfig: validate ACME config before writing

* API
** pmgproxy: allow setting LISTEN_IP parameter
** The "Authentication mode" setting of <code>LDAP</code> for the quarantine interface no longer contains the ticket-link in the report-mails - thus, quarantine users need to provide their LDAP credentials to access the quarantine.

* Installer:
** Rework the installer environment to use <code>switch_root</code> instead of <code>chroot</code>, when transitioning from initrd to the actual installer.
**: This improves module and firmware loading, and slightly reduces memory usage during installation.
** Automatically detect HiDPI screens, and increase console font and GUI scaling accordingly. This improves UX for workstations with Proxmox VE (for example, for passthrough).
** Improve ISO detection:
*** Support ISOs backed by devices using USB Attached SCSI (UAS), which modern USB3 flash drives often do.
*** Linearly increase the delay of subsequent scans for a device with an ISO image, bringing the total check time from 20s to 45s. This allows for the detection of very slow devices, while continuing faster in general.
** Use <code>zstd</code> compression for the initrd image and the squashfs images.
** Update to busybox 1.33.1 as the core-utils provider.

* libarchive-perl
** The perl-bindings to <code>libarchive</code> have been updated to match <code>libarchive</code> version 3.4.3 (shipped in Debian Bullseye) - the library interface was kept backwards-compatible

* libxdgmime-perl
** The perl-bindings to [https://gitlab.freedesktop.org/xdg/xdgmime xdgmime] have been updated to match current upstream - the library interface was kept backwards-compatible

<div id="7.0-breaking-changes"></div>
'''Breaking Changes'''
* New default bind address for pmgproxy, unifying the default behavior with Proxmox VE and Proxmox Backup Server
** 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. Instead of:
*: <code>192.0.2.1- root@pam [01/06/2021:01:19:03 +0200] "GET /api2/json/config/ruledb/digest HTTP/1.1" 200 51</code>
*: the line now looks like:
*: <code>::ffff:192.0.2.1- root@pam [01/06/2021:01:19:03 +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>

* ClamAV has [https://blog.clamav.net/2021/04/are-you-still-attempting-to-download.html deprecated the SafeBrowsing feature]:
** These options have been removed from the shipped <code>freshclam.conf.in</code> template.
** The <code>safebrowsing</code> config key in <code>/etc/pmg/pmg.conf</code> is currently ignored and will be dropped at some point in the future.

* Changes to the database layout:
** The <code>host</code> column of the <code>cgreylist</code> table, which has not been used since Proxmox Mailgateway 6.2, has been dropped from the schema and will be dropped from existing databases during the upgrade.

* API deprecations, moves and removals
** The <code>upgrade</code> parameter of the <code>/nodes/{node}/termproxy</code> API method has been replaced by providing <code>upgrade</code> as <code>cmd</code> parameter.
** The <code>domain</code> parameter of the <code>/config/tlspolicy</code> API method has been replaced by the <code>destination</code> parameter.
** The <code>/quarantine/whitelist/{address}</code> and <code>/quarantine/blacklist/{address}</code> API methods, that take the address as part of the path, have been deprecated in favor of explicitly providing the parameter in the request to <code>/quarantine/whitelist</code> and <code>/quarantine/blacklist</code> respectively.
** The API methods for detailed statistics per e-mail address, which take the address as part of the path (<code>/statistics/contact/{contact}</code>, <code>/statistics/sender/{sender}</code> and <code>/statistics/receiver/{receiver}</code> have been deprecated in favor of <code>/statistics/detail</code>, which takes the address as an explicit parameter.

<div id="7.0-known-issues"></div>
'''Known Issues'''
* '''Network''': Due to the updated systemd version, and for most upgrades, the newer kernel version (5.4 to 5.11), some network interfaces might change upon reboot:
** Some may change their name. For example, due to newly supported functions, a change from <code>enp33s0f0</code> to <code>enp33s0f0np0</code> could occur.
**: We observed such changes with high-speed Mellanox models.
** [https://sources.debian.org/src/bridge-utils/1.7-1/debian/NEWS/#L3-L23 Bridge MAC address selection has changed in Debian Bullseye] - it is now generated based on the interface name and the <code>machine-id (5)</code> of the system.
**: Note that by default, Proxmox Mail Gateway does not use a Linux Bridge for networking, so most setups are unaffected.
* '''Machine-id''': Systems installed using the Proxmox Mail Gateway 5.0 to 5.4 ISO may have a non-unique machine-id. These systems will have their machine-id re-generated automatically on upgrade, to avoid a potentially duplicated bridge MAC and other issues.
: If you do the upgrade remotely, make sure you have a backup method of connecting to the host (for example, IPMI/iKVM, tiny-pilot, another network accessible by a cluster node, or physical access), in case the network used for SSH access becomes unreachable, due to the network failing to come up after a reboot.

'''Upgrade from 6.4'''

See [[Upgrade from 6.x to 7.0]]

==Proxmox Mail Gateway 6.4==
'''Released 30. March 2021'''
* Based on Debian Buster (10.9)
* SpamAssassin 3.4.5 (with update ruleset)
* Kernel 5.4.106
* ACME integration
** Proxmox Mail Gateway now offers full integration of the ACME protocol via the GUI, enabling administrators to create valid and trusted certificates for their domains with the Let's Encrypt certificate authority, in the same way as with Proxmox VE.
** Full support for the <code>http-01</code> and <code>dns-01</code> challenges, with all plugins from [https://github.com/acmesh-official/acme.sh acme.sh].
** Easily configurable from the GUI.
* General Certificate Management via the GUI
** It is now possible to upload custom certificates from the web interface, or set up a cluster-wide ACME account to automatically get and renew certificates from an ACME provider.
* Support for external SpamAssassin update channels (regular automated updates).
** By providing a short configuration file containing a SpamAssassin rule channel's URL and GPG key, Proxmox Mail Gateway will now fetch verified updates from that channel, along with the updates from updates.spamassassin.org.
** The KAM ruleset channel is now available, and a suitable configuration file is shipped with <code>proxmox-spamassassin</code>.
* Improved Quarantine Management
** The admin view of the Spam Quarantine can now display quarantined mail of all users at once.
** All Quarantine views (admin and user) allow you to filter for subject or sender.
** The spam quarantine can now process huge amounts of mails at once (> 3200).
* TLS-logging improvements to the Tracking Center
** The Tracking Center now shows when an outbound connection is established over TLS.
* Enhancements to the Integration of Proxmox Backup Server
** It is now possible to get notified about the result of a scheduled backup to a configured Proxmox Backup Server Remote.
** Inclusion of the (potentially large) statistics database is now configurable per Remote.
* Notable Bugfixes:
** Support for '/' in the local part of an e-mail address (quarantine and statistics view).

==Proxmox Mail Gateway 6.3==
'''Released 19. November 2020'''

* Based on Debian Buster (10.6)
* Updated SpamAssassin rules
* Kernel 5.4.73
* Proxmox Backup Server Integration<br/>Proxmox Mail Gateway is fully supported by the new Proxmox Backup Server 1.0, released on November 11, 2020:
** Backing up to multiple remote backup servers: You can define multiple remote instances of Proxmox Backup Server to store backups on. In case of a large-scale disaster, they can be quickly restored.
** Scheduled Backups: You can schedule regular backups via the GUI, which will then be automatically triggered by a systemd-timer unit. This removes the need for manual backup creation and individual, scripted solutions.
* Quarantine Link via login-page<br />Users can request mails containing a link to their quarantineview, if enabled by the Admin. This enables users to edit their individual blocklists, even if no mails are in their quarantine. Until now this was only possible for sites using LDAP.
* Improvements to the Tracking Center<br />To further improve user experience in the tracking center, pmg-log-tracker handles certain cases better:
** The case sensitivity has been removed from the search box.
** In case the pmg-smtp-filter fails to process emails due to misconfiguration, they are now marked as rejected.
* Notable Bugfixes:
** DKIM signing now uses the longest matching domain for the 'd=' tag.
** Mails held in the Attachment Quarantine are assigned a new Message-ID - fixing interoperability with certain downstream servers (for example, MS Exchange), which silently discard messages with duplicate Message-IDs.

==Proxmox Mail Gateway 6.2==
'''Released 28. April 2020'''

* Based on Debian Buster (10.3)
** Proxmox Mail Gateway is based on the latest stable release of Debian 10.3 (Buster).
* SpamAssassin 3.4.4
** Proxmox ships the latest upstream release of Apache SpamAssassin with a updated and enhance ruleset (KAM rules added)
* Kernel 5.4
** Proxmox Mail Gateway shares the kernel with Proxmox VE and is based on the 5.4 series from Ubuntu 20.04
* pmg-log-tracker in Rust
** <code>pmg-log-tracker</code> has been extended and reimplemented in the Rust programming language. <code>pmg-log-tracker</code> is the binary at the core of the Message Tracking Center, providing live searchable and grouped logs in the GUI.
** The new <code>pmg-log-tracker</code> has support for parsing and grouping logs in before-queue filtering mode.
** The refresh of the code base of <code>pmg-log-tracker</code> provides an optimized performance and more stability.

* Support for before-queue filtering in the GUI
** With the added support for displaying before-queue filtering logs in the GUI and fixing some minor glitches in that area, the before-queue filtering can now be comfortably enabled in the GUI.

* Improved IPv6 support
** The Mail Proxy's SPF checker also verifies SPF records for those remote mail servers connecting via IPv6.
** Greylisting support for IPv6 addresses (with variable netmask, defaulting to '/64') - needs to be explicitly enabled.
** Who-objects containing IPv6 literal address work now.

* Customizable netmask length for greylist matching
** Instead of fixing a greylist network to a '/24' the administrator can now configure which hosts should be considered as belonging to the same network by setting a larger (or smaller) prefix.
** This can help with receiving mail from some cloud-providers, who send out one mail from different ip addresses within a large network, which usually leads to a rather long delay and sometimes even to a legitimate mail being rejected.
** Due to the changed database layout partial upgrades of clusters will prevent nodes running the older version from syncing the greylist database until they are upgraded.

* Better UX for the User Spam Quarantine interface
** If selected in the Quarantine view, the From header and the Subject are now displayed on top of the mail body.
** It is now possible to delete mail addresses containing certain special characters (for example '/') from a users' black- or whitelist.
** Users can set their preferred language directly in the quarantine interface instead of having to log out to change the setting.
** Fixed a bug in the selection of multiple e-mails.

* Handling of changes to overridden templates with <code>ucf</code>
** Starting with this release all service configuration templates, copied and modified in <code>/etc/pmg/templates</code> get registered with <code>ucf</code>. Should a overridden template change with a new package version the administrator is asked and can accept or reject the changes.
** All users who have templates in <code>/etc/pmg/templates</code> will be asked about the current changes for the initial registration.

* New What Object: 'Match Archive Filename'
** In addition to match files in archives (zip, tar.gz, rar,...) based on the file's content-type, it is also possible to look for particular filename patterns inside of archives.
** This completes the feature matrix of matching files based on content-type or filename, as plain attachments, or inside archives.

* Support for downstream LMTP servers
** In certain setups there is no advantage in having a dedicated SMTP server for receiving e-mails from Proxmox Mail Gateway, since all used functionality is provided by a MTA, which speaks IMAP and LMTP (e.g., Dovecot).
** It is now possible to configure Proxmox Mail Gateway to send e-mails directly to a LMTP relay, both as default transport and only as transport for certain domains.

* Improvements to recently added features
** Before-queue filtering and DKIM signing, both implemented with Proxmox Mail Gateway 6.1, have a better user experience and are considered stable now.
** Some remaining glitches and bugs fixed for both.
** DKIM selector handling can handle the existence of multiple selectors and in the GUI, users can comfortably switch between the active selector.

* TLS policy selection for internal downstream servers
** It is now possible to specify a desired level of encryption and authentication for the opportunistic TLS-encryption (STARTTLS) for downstream servers entered in your transports.
** This can help to ensure that your internal communication is not sent in the clear over the network. It can also be used to work around broken TLS implementations in legacy downstream servers.

* Improvements to general usability
** The unbounded growth of the Quarantine disk usage for non-master nodes in clustered setups is fixed.
** It's now possible to switch to incremental updates of the AV signatures for ClamAV via GUI, alleviating the problem that both methods fail in certain cases for some users.
==Proxmox Mail Gateway 6.1==
'''Released 27. November 2019'''

* Based on Debian Buster (10.2)
** Proxmox Mail Gateway is based on the latest stable release of Debian 10.2 (Buster).
* Updated SpamAssassin rules
* Kernel 5.3
** Proxmox Mail Gateway shares the kernel with Proxmox VE and is based on the 5.3 series from Ubuntu 19.10

* DKIM-Signing
** Support for adding DomainKeys Identified Mail (DKIM) Signatures (RFC 6376) to outbound emails
** Configuration via GUI
** Signing happens after processing the email with the rule system, thus ensuring that it leaves the Proxmox Mail Gateway with a valid signature
** Flexible control of which domains should get signed with sensible defaults (the relay domains)
** Inside a cluster, one common selector minimizes the overhead for adding required DNS entries

* Attachment Quarantine
** The <code>Remove Attachments</code> action can now optionally deliver the complete email to the Attachment Quarantine
** The Attachment Quarantine offers a comfortable GUI for selectively downloading parts of the email for further analysis, or delivering the mail to the original recipient
** Accessible only by the administrators, it offers safety from accidentally open malicious executables, doc-files, and other attachments infected with malware

* Adjustable SpamAssassin Rule Scores via GUI
** Adapt the scores of individual SpamAssassin rules directly in the GUI
** Enables you to adapt the scoring to your environment, thus achieving better ham/spam detection rates
** Mostly for adding a bit of weight to rules, which are good indicators for Spam in your environment
** Selectively disable Rules, which cause false positives for your environment

* Improved handling of Configuration and Rule changes in clustered environments
** The Filtering Engine gets notified about a range of configuration changes which require a reload
** The notification is propagated during the cluster sync
** This reduces the situations where you had to manually restart <code>pmg-smtp-filter</code>

* Experimental Support for Before Queue filtering
** Proxmox Mail Gateway can now optionally reject an email during the SMTP dialogue, instead of accepting it and silently discarding unwanted email
** This is a requirement in certain situations
** By answering with a permanent failure code (<code>554</code>), there is no need to generate a Non-Delivery Report, which could cause your system to get blacklisted, due to Backscatter
** Currently incompatible with the Tracking Center, thus needs to be explicitly enabled in <code>/etc/pmg/pmg.conf</code>

* Improvements to general usability
** Clarification of ambiguously used terms in the GUI and documentation
** More detailed documentation of the Service Configuration Templates
** Downloading of emails larger than 2 MB as <nowiki>eml</nowiki> from the Spam Quarantine now works
** API-Viewer now usable from inside every running PMG installation at https://pmg.local:8006/api-viewer/index.html or just online via https://pmg.proxmox.com/pmg-docs/api-viewer/index.html

==Proxmox Mail Gateway 6.0==
'''Released 27. August 2019'''

*Proxmox Mail Gateway is based on the latest stable release of Debian 10.0 (Buster)
*This major version update provides an easy to follow step-by-step upgrade path - https://pmg.proxmox.com/wiki/index.php/Upgrade_from_5.x_to_6.0
*Rule name logging - each final action now logs the name of the rule which triggered it to the system log
*The system logs get displayed faster in the GUI because they now use the Proxmox `mini-journalreader` instead of `journalctl`
*ClamAV 0.101.4 (fix for https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=934359)
*Postgres 11 (new major version backing the rule system)
*OpenSSL 1.1.1c with support for TLS 1.3
*Updated shipped SpamAssassin Ruleset
*Countless bugfixes and improvements in the GUI labels

==Proxmox Mail Gateway 5.2==
'''Released 20. March 2019'''

*Mobile Quarantine Interface
**based on the small and modern framework7
**Deliver/Delete/Whitelist/Blacklist mails in your Quarantine from your mobile device
*Improvements in the LDAP integration
**allow the use of FQDNs instead of IPs in the WebUI
**add support for certificate verification (and enable it for new deployments)
**add support for LDAP+starttls
*PMG-Appliance template
**Install PMG as a (unprivileged) Linux Container (e.g. in PVE)
**Introduces the new 'proxmox-mailgateway-container' metapackage, which does not depend on a kernel, and results in a vastly reduced size (and fewer updates)
*Improvements in Logging
**pmg-smtp-filter now logs each SA-Rules score in addition to the rule names - simplifying the analysis of the spam filter's performance without the need to access the mail's source
*Improvements in the WebUI's TLS configuration
*pmgproxy can now be configured via '/etc/default/pmgproxy' to disable/enable certain ciphers, compression, cipher selection preference.
*new command: `pmg-system-report`
**Provides a overview of key characteristics of PMG's setup and performance
**Improves the initial diagnosis for our Enterprise support
*.eml download from the (non-mobile) Quarantine Interface
**Lets you download the complete source of a quarantined message in .eml format for further analysis
*Add support for custom checks
**Enable users to integrate their own custom check logic by providing a defined interface, which can optionally be enabled, and runs a custom check before the mail gets handed to the virus scanner and rule system.
*Improvements of Blacklist/Whitelist handling in the Quarantine Interface
**multiselect for removing multiple entries at once
*proxmox-spamassassin
**Update the shipped rulesets
*PMG-Cluster: full IPv6 support
*ISO works on Citrix XenServer
*Documentation available via https://pmg.proxmox.com/pmg-docs
*Bugfixes

==Proxmox Mail Gateway 5.1==
'''Released 05. October 2018'''

*Allow to configure TLS policy via GUI
*New 'helpdesk' role
*Support SMTPUTF8 protocol feature
*GUI improvements
*Update Debian Stretch 9.5
*Update kernel to 4.15
*Bugfixes

==Proxmox Mail Gateway 5.0==
'''Released 23. January 2018'''

*Fully licensed under the open source license AGPL
*Based on Debian Stretch 9.3 with a 4.13.13 kernel
*ISO installer supports all ZFS raid levels
*ExtJS based user interface
*New API
*Integrated documentation
*Subscription-based enterprise support options (similar to the Proxmox VE support subscription model)
*Bug fixes

== Old Releases ==
*Proxmox Mail Gateway 4.1
*Proxmox Mail Gateway 4.0
*Proxmox Mail Gateway 3.1
*Proxmox Mail Gateway 3.0
*Proxmox Mail Gateway 2.6
*Proxmox Mail Gateway 2.5
*Proxmox Mail Gateway 2.4
*Proxmox Mail Gateway 2.3
*Proxmox Mail Gateway 2.2
*Proxmox Mail Gateway 2.1
*Proxmox Mail Gateway 2.0
*Proxmox Mail Gateway 1.7
*Proxmox Mail Gateway 1.6
*Proxmox Mail Gateway 1.5
*Proxmox Mail Gateway 1.4
*Proxmox Mail Gateway 1.3
*Proxmox Mail Gateway 1.2
*Proxmox Mail Gateway 1.1
*Proxmox Mail Gateway 1.0 (April 2005)

Upgrade from 8 to 9

2025-09-24T12:47:38Z

Stoiko Ivanov:

= Introduction =
Proxmox Mail Gateway 9.x is based on the new major version of Debian (Trixie). 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 Trixie.

In general, there are two ways to upgrade a Proxmox Mail Gateway 8.x system to Proxmox Mail Gateway 9.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 Trixie]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian On top of Debian Trixie]
** 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 these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** If you use SSH, you should use a terminal multiplexer (for example, <code>tmux</code> or <code>screen</code>) to ensure the upgrade can continue even if the SSH connection gets interrupted.
** '''Important''': Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgraded to the latest version of Proxmox Mail Gateway 8., see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bookworm repos setup) to upgrade to latest 8.2
** Verify version:
*: You can check the web-interface (reload) at the top, or use <code>pmgversion</code>. Both must show a version with 8.2.3 (or newer), for example something like <code>pmg-api/8.2.3/...</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>.

* Ensure that you have at least 10 GB free disk space on the root mount point:
df -h /
* Check [[#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 8 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.

=== Continuously use the '''pmg8to9''' checklist script ===

A small checklist program named '''<code>pmg8to9</code>''' is included in the latest Proxmox Mail Gateway 8.2 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pmg8to9

This script only '''checks''' and reports things. By default, no changes to the system are made and thus, none of the issues will be automatically fixed.
You should keep in mind that Proxmox Mail Gateway can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

It is recommended to re-run the script after each attempt to fix an issue. This ensures that the actions taken actually fixed the respective warning.

=== 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 ===
First, make sure that the system is using the latest Proxmox Mail Gateway packages:

apt update
apt dist-upgrade
pmgversion -v

The last command should report a version of at least <code>8.2.3</code> or newer.

==== Ensure Repository Archive Keyring is Installed ====

To ensure your system trusts the new APT archive keyring for our Debian Trixie-based releases, install the <code>proxmox-archive-keyring</code> package before switching the repositories to Trixie.

apt install proxmox-archive-keyring

==== Update Debian Base Repositories to Trixie ====
Update all repository entries to Trixie:

sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

Ensure that there are no remaining Debian Bookworm specific repositories left. Check all files in the </code>/etc/apt/sources.list.d/</code> folder (like <code>pmg-enterprise.list</code>) and also the top-level <code>/etc/apt/sources.list</code> file. If you are already using sources in the new deb822 format, you will also need to check <code>.sources</code> files in the same location.

{{note|Instead of removing older repositories, you can also disable them. In <code>.list</code> files simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: false</code> to any stanza you want to disable.|reminder}}

See the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories] section in the reference docs for the correct Proxmox Mail Gateway / Debian Trixie repositories.

==== Add the Proxmox Mail Gateway 9 Package Repository ====



During the BETA phase only the <code>pmg-test</code> repository is available, see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories]. You should be able to add it with this command:

cat > /etc/apt/sources.list.d/proxmox-beta.sources << EOF
Types: deb
URIs: http://download.proxmox.com/debian/pmg
Suites: trixie
Components: pmg-test
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

Make sure that <code>apt</code> picks it up correctly with <code>apt update</code> followed by <code>apt policy</code>. Then remove the previous Proxmox Mail Gateway 8 repositories from either the <code>/etc/apt/sources.list</code>, <code>/etc/apt/sources-list.d/pmg-install-repo.list</code> or any other <code>.list</code> file you may have added it to. Run <code>apt update</code> and <code>apt policy</code> again to be certain that the old repo has been removed.
Instead of removing older repositories, you can also disable them. In <code>.list</code> simply comment them out by adding a <code>#</code> to the beginning of the line. In <code>.sources</code> files, you can add the line <code>Enabled: false</code> to any stanza you want to disable.


Make sure to check that all the <code>.list</code> files you added in <code>/etc/apt/sources.list.d/</code> got switched over to Trixie correctly.

=== 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 ===

Note that the time required for finishing this step heavily depends on the system's performance, especially the root filesystem's IOPS and bandwidth.
A slow spinner can take up to 60 minutes or more, while for a high-performance server with SSD storage, the upgrade can be finished in less than 5 minutes.

{{Note|While the packages are being upgraded certain operations and requests to the API might fail (for example, logging in as a system user in the <code>pam</code> realm)|reminder}}

apt update
apt dist-upgrade

While running the <code>apt dist-upgrade</code> command, you may be asked to approve changes to configuration files and some service restarts among other prompts. This includes:

* The output of <code>apt-listchanges</code>: You can simply exit it by pressing <kbd>q</kbd>.
* Selecting your default keyboard settings: Simply use the arrow keys to navigate to the one applicable in your case and hit enter.
* Questions about service restarts (like <code>Restart services during package upgrades without asking?</code>): Use the default if unsure, as the reboot after the upgrade will restart all services cleanly anyway.
* Questions about (default) configuration changes: It's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup. Common configuration files with changes, and the recommended choices are:
** <code>/etc/issue</code> -> Proxmox Mail Gateway will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.
** <code>/etc/ssh/sshd_config</code> -> If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.
** <code>/etc/clamav/clamd.conf</code> and <code>/etc/clamav/freshclam.conf</code> -> Those two configuration files are managed by Proxmox Mail Gateway directly, at will be re-generate on any relevant change and on boot.
*: Using the default "No" (keep your currently-installed version) is safe here.
** <code>/etc/default/grub</code> -> Here you may want to take special care, as this is normally only asked for if you changed it manually, e.g., for adding some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)
** <code>/etc/postfix/master.cf.proto</code>, <code>/etc/postfix/main.cf.proto</code> -> These files are not used by Proxmox Mail Gateway - they are the templates for setting up multi-instance postfix instances, which was never used by Proxmox Mail Gateway. See the [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=838528 bugreport at bugs.debian.org] for more context.
*: We recommend to select "Yes" (install the new version), in order to not get asked again for a future upgrade.
** <code>/etc/crontab</code> and other <code>cron</code> related files on installations on containers on Proxmox VE: The crontab gets randomized by Proxmox VE to prevent all jobs running at the same time in all containers.
*: Using the default "No" (keep your currently-installed version) is preferred here.
** <code>postgresql</code> may print warnings regarding about <code>collation version mismatch</code> - These are transitory and will disappear once the cluster has been upgraded to the new version.

'''''Important''''': If configuration templates are used in <code>/etc/pmg/templates</code>, you will see a prompt about the changes in the new version that are not yet incorporated. Review the changes carefully and ensure that only the changes you want are shown in the diff.

It is not yet necessary to reboot your Proxmox Mail Gateway host at this point. Before doing so, first upgrade PostgreSQL database.

=== Upgrade the PostgreSQL database ===

* Upgrade the PostgreSQL main cluster from 15 to 17, using <code>pg_upgradecluster</code>
** This step will need some '''time''' and enough '''free disk space''' 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 17 15 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 ===

Reboot the host with e command below. Then check the journal to ensure that everything is running correctly again.

reboot

Reconnect to the node after it successfully rebooted.

== After the Proxmox Mail Gateway upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Unmasking & Starting Cluster Services ===

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

=== Remove old PostreSQL Version ===

You can remove the old PostgreSQL version and its data now, if all is working as expected:

apt purge postgresql-15 postgresql-client-15

=== Optional: Modernize apt Repository Sources ===

You can migrate existing repository sources to the recommended deb822 style format, by running:

apt modernize-sources

By answering the following prompt with "n" you can check the changes the command would make before applying them. To apply them simply run the command again and respond to the prompt with "Y".

The command will also keep the old <code>.list</code> files around by appending <code>.bak</code> to them. So you will have the new <code>.sources</code> files and the old repository configurations in the <code>.list.bak</code> files. You can remove the leftover backup files once you verified that everything works smoothly with the new format.

{{note|ensure that all external and third-party repositories (e.g. the one provided by [https://pmg.proxmox.com/wiki/index.php/Install_Avast avast] have provided the keys in the correct places).
|reminder}}

= 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/trixie/release-notes/upgrading.en.html upgrade specific issues for Trixie].

Please also check the known issue list for the Proxmox Mail Gateway 9.X minor releases as this gets updated with future minor releases:
* https://pmg.proxmox.com/wiki/Roadmap#9.0-known-issues

== Breaking Changes ==

* [https://www.debian.org/releases/trixie/release-notes/issues.en.html#timezones-split-off-into-tzdata-legacy-package Legacy Timezones were split off] This should not be an issue as Proxmox Mail Gateway never offered the deprecated timezones for selection.
but if you've manually configured one and <code>postgresql</code> does not start, install the <code>tzdata-legacy</code> package.
* The external <code>avast</code> Virus Scanner [https://pmg.proxmox.com/wiki/index.php/Install_Avast with integration in Promxox Mail Gateway] has not yet released a version for Debian Trixie. If you are using it consider delaying the upgrade until it becomes available

=== Upgrade wants to remove package 'proxmox-mail-gateway' ===

If you have installed Proxmox Mail Gateway on top of a plain Debian Trixie (without using the Proxmox Mail Gateway ISO), you may have installed the package 'linux-image-amd64', which conflicts with current 9.x setups. To solve this, you have to remove this package with
apt remove linux-image-amd64
before the dist-upgrade.

== Network ==

=== Network Interface Name Change ===

The new kernel can recognize more hardware features such as virtual function of PCI(e) devices. Since network names are usually derived from PIC(e) addresses and features recognized by the kernel, the network configuration might need to be adapted to match the new interface names.

In such cases, the network connection to a Proxmox Datacenter Manager host might be lost during or after the upgrade process. Hence, it is generally recommended to have either physical access or an independent remote connection to the host (for example, via IPMI or iKVM).

The latest version of Proxmox Mail Gateway 8.2 and 9.0 provide a package called <code>proxmox-network-interface-pinning</code> that you can install.
This package offers a CLI tool that helps you pin all network interfaces to NIC-based names and update the network configuration simultaneously.

== Systemd-boot meta-package changes the bootloader configuration automatically and should be uninstalled ==
With Debian Trixie the <code>systemd-boot</code> package got split up a bit further into <code>systemd-boot-efi</code> (containing the EFI-binary used for booting), <code>systemd-boot-tools</code> (containing <code>bootctl</code>) and the <code>systemd-boot</code> meta-package (containing hooks which run upon upgrades of itself and other packages and install systemd-boot as bootloader).

As Proxmox Systems usually use <code>systemd-boot</code> for booting only in some configurations (ZFS on root and UEFI booted without secure boot), which are managed by <code>proxmox-boot-tool</code>, the meta-package <code>systemd-boot</code> should be removed.

The package was automatically shipped for systems installed from the PMG 8.0 to PMG 8.2 ISOs, as it contained <code>bootctl</code> in bookworm.
If the <code>pmg8to9</code> checklist script suggests it, the <code>systemd-boot</code> meta-package is safe to remove unless you manually installed it and are using <code>systemd-boot</code> as a bootloader. Should <code>systemd-boot-efi</code> and <code>systemd-boot-tools</code> be required, <code>pmg8to9</code> will warn you accordingly.

The <code>pmg8to9</code> checklist script will change its output depending on the state of the upgrade, and should be [[#Continuously_use_the_pmg8to9_checklist_script|run continuously before and after the upgrade]]. It will print which packages should be removed or added at the appropriate time. The only situation where you should keep the meta-package <code>systemd-boot</code> installed is if you manually setup <code>systemd-boot</code> for your system.

See also [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1110177 the filed bug for systemd-boot].

= External links =

[https://www.debian.org/releases/trixie/release-notes/ Release Notes for Debian 13.0 (trixie)]

[[Category: Upgrade]]

Quarantine Web Interface Via Nginx Proxy

2024-08-27T10:02:34Z

Stoiko Ivanov: fix #5664

== Introduction ==

Proxmox Mail Gateway can be configured to quarantine mail, instead of delivering potentially dangerous content to users directly.
If a mail is detected as spam users themselves can decide whether they want to keep or delete it in the user quarantine interface.
(for dangerous content, as mail containing viruses, or potentially dangerous attachments, the administrator needs to decide whether
to pass the mail on or delete it).

In certain environments it is desired to provide the user quarantine interface at a specific host and port,
e.g. in order to only allow access to the interface from outside on port 443, or to provide a different and
trusted certificate to your users.

The following Howto describes a small nginx configuration, which only exposes the paths necessary for user quarantine interface access,
while preventing access to other parts of the API.

Keep in mind that this provides mostly cosmetic protection, since all paths in the Proxmox Mail Gateway API, apart from the login path
are only available to authenticated users anyways. The unprotected login path needs to be forwarded for the quarantine access as well.

For creating a general reverse proxy for the complete web interface refer to the [https://pve.proxmox.com/wiki/Web_Interface_Via_Nginx_Proxy Howto in the Proxmox VE wiki].

== Installing nginx ==

The Howto creates a configuration suitable for nginx. You can install nginx on your Proxmox Mail Gateway using <nowiki>apt</nowiki>
apt install nginx

== Creating a site to proxy requests for quarantine ==

The following configuration is a minimal working nginx-site to proxy all requests necessary for accessing the quarantine interface for users.
You should adapt it to your site's requirements. This includes:
* changing the path to the used certificates
* setting the proper <code>server_name</code>
* adapting the ssl-configuration parameters to current best practices
* if the proxy server is running directly on PMG:
** you probably want to disable the <code>default</code> site configuration <code>/etc/nginx/sites-enabled/default</code>.
** if you're using the integrated ACME implementation with the standalone plugin you need to remove the server on port 80 below, since the ACME implementation needs to bind to it during certificate renewal
* if the proxy server is running on another host adapting the url for the <code>proxy_pass</code> directives
* You will also need to adapt the settings in the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmgconfig_spamdetector_quarantine Spam Detector Quarantine Options in the PMG GUI] to reflect the hostname and port of the proxy.

To get the site running write the config to <code>/etc/nginx/sites-available/pmg-quarantine.conf</code> and symlink it to <code>/etc/nginx/sites-enabled</code>:
ln -rs /etc/nginx/sites-available/pmg-quarantine.conf /etc/nginx/sites-enabled/

<nowiki>
server {
listen 80 default_server;
rewrite ^(.*) https://$host$1 permanent;
}

server {
listen 443 ssl;
server_name _;
ssl_certificate /etc/pmg/pmg-api.pem;
ssl_certificate_key /etc/pmg/pmg-api.pem;
proxy_redirect off;

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header PVEClientIP $remote_addr;
proxy_buffering off;
client_max_body_size 0;
proxy_connect_timeout 3600s;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
send_timeout 3600s;

# proxy requests for static components
location ~ /proxmoxlib.js$|/favicon.ico$|/pve2/|/fontawesome/|/framework7/|/pwt/ {
proxy_pass https://localhost:8006;
}
location /quarantine {
proxy_pass https://localhost:8006;
}

location /api2 {
location ~ /api2/(extjs|json|htmlmail)/(access/ticket$|version$) {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/nodes/.+/subscription$ {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/quarantine {
proxy_pass https://localhost:8006;
}
return 403;
}

location / {
return 403;
}
}
</nowiki>

Quarantine Web Interface Via Nginx Proxy

2024-07-11T07:34:38Z

Stoiko Ivanov: note that the default site usually should be disabled /* Creating a site to proxy requests for quarantine */

== Introduction ==

Proxmox Mail Gateway can be configured to quarantine mail, instead of delivering potentially dangerous content to users directly.
If a mail is detected as spam users themselves can decide whether they want to keep or delete it in the user quarantine interface.
(for dangerous content, as mail containing viruses, or potentially dangerous attachments, the administrator needs to decide whether
to pass the mail on or delete it).

In certain environments it is desired to provide the user quarantine interface at a specific host and port,
e.g. in order to only allow access to the interface from outside on port 443, or to provide a different and
trusted certificate to your users.

The following Howto describes a small nginx configuration, which only exposes the paths necessary for user quarantine interface access,
while preventing access to other parts of the API.

Keep in mind that this provides mostly cosmetic protection, since all paths in the Proxmox Mail Gateway API, apart from the login path
are only available to authenticated users anyways. The unprotected login path needs to be forwarded for the quarantine access as well.

For creating a general reverse proxy for the complete web interface refer to the [https://pve.proxmox.com/wiki/Web_Interface_Via_Nginx_Proxy Howto in the Proxmox VE wiki].

== Installing nginx ==

The Howto creates a configuration suitable for nginx. You can install nginx on your Proxmox Mail Gateway using <nowiki>apt</nowiki>
apt install nginx

== Creating a site to proxy requests for quarantine ==

The following configuration is a minimal working nginx-site to proxy all requests necessary for accessing the quarantine interface for users.
You should adapt it to your site's requirements. This includes:
* changing the path to the used certificates
* setting the proper <code>server_name</code>
* adapting the ssl-configuration parameters to current best practices
* if the proxy server is running directly on PMG:
** you probably want to disable the <code>default</code> site configuration <code>/etc/nginx/sites-enabled/default</code>.
** if you're using the integrated ACME implementation with the standalone plugin you need to remove the server on port 80 below, since the ACME implementation needs to bind to it during certificate renewal
* if the proxy server is running on another host adapting the url for the <code>proxy_pass</code> directives
* You will also need to adapt the settings in the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmgconfig_spamdetector_quarantine Spam Detector Quarantine Options in the PMG GUI] to reflect the hostname and port of the proxy.

To get the site running write the config to <code>/etc/nginx/sites-available/pmg-quarantine.conf</code> and symlink it to <code>/etc/nginx/sites-enabled</code>:
ln -rs /etc/nginx/sites-available/pmg-quarantine.conf /etc/nginx/sites-enabled/

<nowiki>
server {
listen 80 default_server;
rewrite ^(.*) https://$host$1 permanent;
}

server {
listen 443;
server_name _;
ssl on;
ssl_certificate /etc/pmg/pmg-api.pem;
ssl_certificate_key /etc/pmg/pmg-api.pem;
proxy_redirect off;

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header PVEClientIP $remote_addr;
proxy_buffering off;
client_max_body_size 0;
proxy_connect_timeout 3600s;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
send_timeout 3600s;

# proxy requests for static components
location ~ /proxmoxlib.js$|/favicon.ico$|/pve2/|/fontawesome/|/framework7/|/pwt/ {
proxy_pass https://localhost:8006;
}
location /quarantine {
proxy_pass https://localhost:8006;
}

location /api2 {
location ~ /api2/(extjs|json|htmlmail)/(access/ticket$|version$) {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/nodes/.+/subscription$ {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/quarantine {
proxy_pass https://localhost:8006;
}
return 403;
}

location / {
return 403;
}
}
</nowiki>

Quarantine Web Interface Via Nginx Proxy

2024-07-10T13:03:00Z

Stoiko Ivanov: point to the necessary spam-detector quarantine settings in the GUI /* Creating a site to proxy requests for quarantine */

== Introduction ==

Proxmox Mail Gateway can be configured to quarantine mail, instead of delivering potentially dangerous content to users directly.
If a mail is detected as spam users themselves can decide whether they want to keep or delete it in the user quarantine interface.
(for dangerous content, as mail containing viruses, or potentially dangerous attachments, the administrator needs to decide whether
to pass the mail on or delete it).

In certain environments it is desired to provide the user quarantine interface at a specific host and port,
e.g. in order to only allow access to the interface from outside on port 443, or to provide a different and
trusted certificate to your users.

The following Howto describes a small nginx configuration, which only exposes the paths necessary for user quarantine interface access,
while preventing access to other parts of the API.

Keep in mind that this provides mostly cosmetic protection, since all paths in the Proxmox Mail Gateway API, apart from the login path
are only available to authenticated users anyways. The unprotected login path needs to be forwarded for the quarantine access as well.

For creating a general reverse proxy for the complete web interface refer to the [https://pve.proxmox.com/wiki/Web_Interface_Via_Nginx_Proxy Howto in the Proxmox VE wiki].

== Installing nginx ==

The Howto creates a configuration suitable for nginx. You can install nginx on your Proxmox Mail Gateway using <nowiki>apt</nowiki>
apt install nginx

== Creating a site to proxy requests for quarantine ==

The following configuration is a minimal working nginx-site to proxy all requests necessary for accessing the quarantine interface for users.
You should adapt it to your site's requirements. This includes:
* changing the path to the used certificates
* setting the proper <nowiki>server_name</nowiki>
* adapting the ssl-configuration parameters to current best practices
* if the proxy server is running on another host adapting the url for the <nowiki>proxy_pass</nowiki> directives
* You will also need to adapt the settings in the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmgconfig_spamdetector_quarantine Spam Detector Quarantine Options in the PMG GUI] to reflect the hostname and port of the proxy.

To get the site running write the config to <nowiki>/etc/nginx/sites-available/pmg-quarantine.conf</nowiki> and symlink it to <nowiki>/etc/nginx/sites-enabled</nowiki>:
ln -rs /etc/nginx/sites-available/pmg-quarantine.conf /etc/nginx/sites-enabled/

<nowiki>
server {
listen 80 default_server;
rewrite ^(.*) https://$host$1 permanent;
}

server {
listen 443;
server_name _;
ssl on;
ssl_certificate /etc/pmg/pmg-api.pem;
ssl_certificate_key /etc/pmg/pmg-api.pem;
proxy_redirect off;

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header PVEClientIP $remote_addr;
proxy_buffering off;
client_max_body_size 0;
proxy_connect_timeout 3600s;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
send_timeout 3600s;

# proxy requests for static components
location ~ /proxmoxlib.js$|/favicon.ico$|/pve2/|/fontawesome/|/framework7/|/pwt/ {
proxy_pass https://localhost:8006;
}
location /quarantine {
proxy_pass https://localhost:8006;
}

location /api2 {
location ~ /api2/(extjs|json|htmlmail)/(access/ticket$|version$) {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/nodes/.+/subscription$ {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/quarantine {
proxy_pass https://localhost:8006;
}
return 403;
}

location / {
return 403;
}
}
</nowiki>

'''NOTE: if you're using the integrated ACME implementation with the standalone plugin you need to remove the server on port 80 above, since the ACME implementation needs to bind to it during certificate renewal'''

Upgrade from 7 to 8

2024-02-26T12:13:23Z

Stoiko Ivanov: fix link to potential issues, provision for linking to all minor-releases known issues

= Introduction =
Proxmox Mail Gateway 8.x is based on the new major version of Debian (Bookworm). 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 Bookworm.

In general, there are two ways to upgrade a Proxmox Mail Gateway 7.x system to Proxmox Mail Gateway 8.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 Bookworm]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian On top of Debian Bookworm]
** 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.

* Perform these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** 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.
** '''Important''': Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgraded to the latest version of Proxmox Mail Gateway 7., see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bullseye repos setup) to upgrade to latest 7.3
** Verify version:
*: You can check the web-interface (reload) at the top, or use <code>pmgversion</code>. Both must show a version with 7.3-6 (or newer), for example something like <code>pmg-api/7.3-6/...</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 5 GB free disk space on root mount point.
* Check [[#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 7 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.

=== Continuously use the '''pmg7to8''' checklist script ===

A small checklist program named '''<code>pmg7to8</code>''' is included in the latest Proxmox Mail Gateway 7.3 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pmg7to8

This script only '''checks''' and reports things. By default, no changes to the system are made and thus, none of the issues will be automatically fixed.
You should keep in mind that Proxmox Mail Gateway can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

It is recommended to re-run the script after each attempt to fix an issue. This ensures that the actions taken actually fixed the respective warning.

=== 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 Bookworm - see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories]
Update all Debian repository entries to Bookworm.

sed -i 's/bullseye/bookworm/g' /etc/apt/sources.list

Update the enterprise repository to Bookworm:

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

For the no-subscription repository, see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories].
Rather than commenting out/removing the PMG 7.x repositories, as was previously mentioned, you could also run the following command to update to the Proxmox Mail Gateway 8 repositories:
sed -i -e 's/bullseye/bookworm/g' /etc/apt/sources.list.d/pmg-install-repo.list

Make sure to also update any extra files that you added to <code>/etc/apt/sources.list.d/</code> to Bookworm 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)
:<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

During the above step, you will be asked to approve changes to configuration files, where the default config has been updated by their respective package.

It's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup.

Common configuration files with changes, and the recommended choices are:
* <code>/etc/issue</code> -> Proxmox Mail Gateway will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/clamav/clamd.conf </code> and <code>/etc/clamav/freshclam.conf</code> -> Those two configuration files are managed by Proxmox Mail Gateway directly, at will be re-generate on any relevant change and on boot.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/ssh/sshd_config</code> -> If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.

* <code>/etc/default/grub</code> -> Here you may want to take special care, as this is normally only asked for if you changed it manually, e.g., for adding some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)

It is not necessary to reboot the Proxmox Mail Gateway host yet after the dist-upgrade finished.

=== Adapt modified configuration templates to new shipped versions ===

If configuration templates are used in <code>/etc/pmg/templates</code>, you will see a prompt about the changes in the new version that are not yet incorporated. Review the changes carefully and ensure that only the changes you want are shown in the diff.

=== Disable ClamAV On-Access Scanner Service ===

The new ClamAV on-access scanning service is not useful for Proxmox Mail Gateway setups and is disabled for new installations as it not only slows down the entire system, but also affects the spam and virus detection mechanisms managed by Proxmox Mail Gateway.

During upgrades, the service may get enabled and will then be marked as failed.
It is recommended to disable this service:
systemctl disable clamav-clamonacc.service

=== 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 15 main</pre>
* Upgrade the PostgreSQL main cluster from 13 to 15, using <code>pg_upgradecluster</code>
** This step will need some '''time''' and enough '''free disk space''' 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 15 13 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-13 postgresql-client-13</pre>

== After the Proxmox Mail Gateway upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Unmasking & Starting Cluster Services ===

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.
Thus, ensure to read the [https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html upgrade specific issues for Bookworm].

Please also check the known issue list for the Proxmox Mail Gateway 8.X minor releases:
* https://pmg.proxmox.com/wiki/Roadmap#8.0-known-issues

== Breaking Changes ==

* Changed defaults for Bayes and AWL
** Since the two options cause worse results when enabled in most average installations their defaults changed in 8.0, and they are now disabled
*: If your installation explicitly disabled, or enabled the feature nothing will change
*: In case your installation never set the setting the old default will now be written to <code>/etc/pmg/pmg.conf</code> to keep your system consistent.

* The ClamAV antivirus daemon <code>clamav-daemon</code> now uses socket-activation
*: To disable the service you need to disable <code>clamav-daemon.service</code> and <code>clamav-daemon.socket</code>

* Postgresql config change
*: the <code>stats_temp_directory</code> server variable is no longer supported
*: the postgresql.conf template shipped with Proxmox Mail Gateway accounts for the change
*: if you have modified the template (or copied it without modification) in /etc/pmg/templates/ - make sure to remove the line and/or remove the complete template override (if you don't have any modifications)

=== Upgrade wants to remove package 'proxmox-mail-gateway' ===

If you have installed Proxmox Mail Gateway on top of a plain Debian Bookworm (without using the Proxmox Mail Gateway ISO), you may have installed the package 'linux-image-amd64', which conflicts with current 8.x setups. To solve this, you have to remove this package with
apt remove linux-image-amd64
before the dist-upgrade.

== Network ==

=== Network Interface Name Change ===

Due to the new kernel recognizing more features of some hardware, like for example virtual functions, and since interface naming often derives from the PCI(e) address, some NICs may change their name, in which case the network configuration needs to be adapted.

This can also happen in virtualized environments (and has been reported with Xen for this upgrade)

In general, it's recommended to either have an independent remote connection to the Proxmox Mail Gateways's host console, for example, through the hypervisor in case of a VM or container setup, IPMI or iKVM, or physical access for managing the server even
when its own network doesn't come up after a major upgrade or network change.

=== Network Fails on Boot Due to NTPsec Hook ===

Some users reported that after the upgrade their network failed to come up cleanly on boot, but worked if triggered manually (e.g., using <code>ifreload -a</code>), when ntpsec was installed.

We're still investigating for a definitive root cause, but it seems that an udev hook which the <code>/etc/network/if-up.d/ntpsec-ntpdate</code> might hang on some hardware, albeit due to changes not directly related to ntpsec.

The simplest solution might be switching to that via <code>apt install chrony</code>.

== Systemd-boot (for ZFS on root and UEFI systems only) ==

Systems booting via UEFI from a ZFS on root setup should install the <code>systemd-boot</code> package after the upgrade. You will get a Warning from the <code>pve7to8</code> script after the upgrade if your system is affected - in all other cases you can safely ignore this point.

The <code>systemd-boot</code> was split out from the <code>systemd</code> package for Debian Bookworm based releases. It won't get installed automatically upon upgrade from Proxmox Mail Gateway 7.3 as it can cause trouble on systems not booting from UEFI with ZFS on root setup by the Proxmox Mail Gateway installer.

Systems which have ZFS on root and boot in UEFI mode will need to manually install it if they need to initialize a new ESP (see the output of <code>proxmox-boot-tool status</code>).

Note that the system remains bootable even without the package installed.

It is not recommended installing <code>systemd-boot</code> on systems which don't need it, as it would replace <code>grub</code> as bootloader in its <code>postinst</code> script.

= External links =

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

[[Category: Upgrade]]

Upgrade from 7 to 8

2023-08-16T08:08:26Z

Stoiko Ivanov: /* Update the configured APT repositories */

= Introduction =
Proxmox Mail Gateway 8.x is based on the new major version of Debian (Bookworm). 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 Bookworm.

In general, there are two ways to upgrade a Proxmox Mail Gateway 7.x system to Proxmox Mail Gateway 8.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 Bookworm]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian On top of Debian Bookworm]
** 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.

* Perform these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** 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.
** '''Important''': Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgraded to the latest version of Proxmox Mail Gateway 7., see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bullseye repos setup) to upgrade to latest 7.3
** Verify version:
*: You can check the web-interface (reload) at the top, or use <code>pmgversion</code>. Both must show a version with 7.3-6 (or newer), for example something like <code>pmg-api/7.3-6/...</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 5 GB free disk space on root mount point.
* Check [[Upgrade_from_7.x_to_8.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 7 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.

=== Continuously use the '''pmg7to8''' checklist script ===

A small checklist program named '''<code>pmg7to8</code>''' is included in the latest Proxmox Mail Gateway 7.3 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pmg7to8

This script only '''checks''' and reports things. By default, no changes to the system are made and thus, none of the issues will be automatically fixed.
You should keep in mind that Proxmox Mail Gateway can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

It is recommended to re-run the script after each attempt to fix an issue. This ensures that the actions taken actually fixed the respective warning.

=== 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 Bookworm - see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories]
Update all Debian repository entries to Bookworm.

sed -i 's/bullseye/bookworm/g' /etc/apt/sources.list

Update the enterprise repository to Bookworm:

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

For the no-subscription repository, see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories].
Rather than commenting out/removing the PMG 7.x repositories, as was previously mentioned, you could also run the following command to update to the Proxmox Mail Gateway 8 repositories:
sed -i -e 's/bullseye/bookworm/g' /etc/apt/sources.list.d/pmg-install-repo.list

Make sure to also update any extra files that you added to <code>/etc/apt/sources.list.d/</code> to Bookworm 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)
:<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

During the above step, you will be asked to approve changes to configuration files, where the default config has been updated by their respective package.

It's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup.

Common configuration files with changes, and the recommended choices are:
* <code>/etc/issue</code> -> Proxmox Mail Gateway will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/clamav/clamd.conf </code> and <code>/etc/clamav/freshclam.conf</code> -> Those two configuration files are managed by Proxmox Mail Gateway directly, at will be re-generate on any relevant change and on boot.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/ssh/sshd_config</code> -> If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.

* <code>/etc/default/grub</code> -> Here you may want to take special care, as this is normally only asked for if you changed it manually, e.g., for adding some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)

It is not necessary to reboot the Proxmox Mail Gateway host yet after the dist-upgrade finished.

=== Adapt modified configuration templates to new shipped versions ===

If configuration templates are used in <code>/etc/pmg/templates</code>, you will see a prompt about the changes in the new version that are not yet incorporated. Review the changes carefully and ensure that only the changes you want are shown in the diff.

=== Disable ClamAV On-Access Scanner Service ===

The new ClamAV on-access scanning service is not useful for Proxmox Mail Gateway setups and is disabled for new installations as it not only slows down the entire system, but also affects the spam and virus detection mechanisms managed by Proxmox Mail Gateway.

During upgrades, the service may get enabled and will then be marked as failed.
It is recommended to disable this service:
systemctl disable clamav-clamonacc.service

=== 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 15 main</pre>
* Upgrade the PostgreSQL main cluster from 13 to 15, using <code>pg_upgradecluster</code>
** This step will need some '''time''' and enough '''free disk space''' 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 15 13 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-13 postgresql-client-13</pre>

== After the Proxmox Mail Gateway upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Unmasking & Starting Cluster Services ===

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.
Thus, ensure to read the [https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html upgrade specific issues for Bookworm].

Please also check the known issue list from the Proxmox Mail Gateway 8.0 changelog: https://pmg.proxmox.com/wiki/Roadmap#8.0-known-issues

== Breaking Changes ==

* Changed defaults for Bayes and AWL
** Since the two options cause worse results when enabled in most average installations their defaults changed in 8.0, and they are now disabled
*: If your installation explicitly disabled, or enabled the feature nothing will change
*: In case your installation never set the setting the old default will now be written to <code>/etc/pmg/pmg.conf</code> to keep your system consistent.

* The ClamAV antivirus daemon <code>clamav-daemon</code> now uses socket-activation
*: To disable the service you need to disable <code>clamav-daemon.service</code> and <code>clamav-daemon.socket</code>

* Postgresql config change
*: the <code>stats_temp_directory</code> server variable is no longer supported
*: the postgresql.conf template shipped with Proxmox Mail Gateway accounts for the change
*: if you have modified the template (or copied it without modification) in /etc/pmg/templates/ - make sure to remove the line and/or remove the complete template override (if you don't have any modifications)

=== Upgrade wants to remove package 'proxmox-mail-gateway' ===

If you have installed Proxmox Mail Gateway on top of a plain Debian Bookworm (without using the Proxmox Mail Gateway ISO), you may have installed the package 'linux-image-amd64', which conflicts with current 8.x setups. To solve this, you have to remove this package with
apt remove linux-image-amd64
before the dist-upgrade.

== Network ==

=== Network Interface Name Change ===

Due to the new kernel recognizing more features of some hardware, like for example virtual functions, and since interface naming often derives from the PCI(e) address, some NICs may change their name, in which case the network configuration needs to be adapted.

This can also happen in virtualized environments (and has been reported with Xen for this upgrade)

In general, it's recommended to either have an independent remote connection to the Proxmox Mail Gateways's host console, for example, through the hypervisor in case of a VM or container setup, IPMI or iKVM, or physical access for managing the server even
when its own network doesn't come up after a major upgrade or network change.

=== Network Fails on Boot Due to NTPsec Hook ===

Some users reported that after the upgrade their network failed to come up cleanly on boot, but worked if triggered manually (e.g., using <code>ifreload -a</code>), when ntpsec was installed.

We're still investigating for a definitive root cause, but it seems that an udev hook which the <code>/etc/network/if-up.d/ntpsec-ntpdate</code> might hang on some hardware, albeit due to changes not directly related to ntpsec.

The simplest solution might be switching to that via <code>apt install chrony</code>.

== Systemd-boot (for ZFS on root and UEFI systems only) ==

Systems booting via UEFI from a ZFS on root setup should install the <code>systemd-boot</code> package after the upgrade. You will get a Warning from the <code>pve7to8</code> script after the upgrade if your system is affected - in all other cases you can safely ignore this point.

The <code>systemd-boot</code> was split out from the <code>systemd</code> package for Debian Bookworm based releases. It won't get installed automatically upon upgrade from Proxmox Mail Gateway 7.3 as it can cause trouble on systems not booting from UEFI with ZFS on root setup by the Proxmox Mail Gateway installer.

Systems which have ZFS on root and boot in UEFI mode will need to manually install it if they need to initialize a new ESP (see the output of <code>proxmox-boot-tool status</code>).

Note that the system remains bootable even without the package installed.

It is not recommended installing <code>systemd-boot</code> on systems which don't need it, as it would replace <code>grub</code> as bootloader in its <code>postinst</code> script.

= External links =

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

[[Category: Upgrade]]

Install Avast

2023-07-13T09:38:39Z

Stoiko Ivanov: add instruction to disable upstream reporting

== Introduction ==

Proxmox Mail Gateway ships and uses the open source [https://www.clamav.net/ ClamAV] antivirus engine in its default installation.

Certain environments have the need for a better virus detection rate than the one achieved by ClamAV.

For these setups Proxmox Mail Gateway offers an integration with the [https://www.avast.com/en-us/business/products/antivirus-for-linux Avast Antivirus for Linux].
This HOWTO follows the technical documentation from Avast - https://repo.avcdn.net/linux-av/doc/avast-techdoc.pdf

Avast Antivirus for Linux is commercial software and you will need to purchase a license in order to use it.

The following facts are why it can be integrated with Proxmox Mail Gateway as an alternative to ClamAV:

* The licensing is based on the number of installations instead of other licensing schemes such as the number of processed mails or mailboxes.
* The software runs daemonized and thus reads and caches the AV definitions once upon startup instead of each time a file is scanned

The following HOWTO provides the necessary steps to install and configure Avast within a Proxmox Mail Gateway installation.

== Installing Avast Antivirus for Linux ==

Proxmox Mail Gateway is based on Debian GNU/Linux - thus you need to follow the installation instruction for Debian systems.

To configure the Avast repository and install the software:

# Create the appropriate [https://manpages.debian.org/apt/sources.list.5.en.html sources.list] entry:
#:<code>echo "deb https://repo.avcdn.net/linux-av/deb debian-bookworm release" > /etc/apt/sources.list.d/avast.list</code>
# Verify the signing key for the repository from Avast:
#* Get the key
#*:<code>wget https://repo.avcdn.net/linux-av/doc/avast-gpg-key.asc</code>
#*Read the checksum
#*:<code>sha512sum avast-gpg-key.asc</code>
#* The result should be
#*:<code>7fca6e2a8984931d46a8ff13cd086a934ca126068c074c86a13a30aa2f909663b9e5ae8529a02632c7735d2823bfc71b0e0987a63f8c4dd11130b2529e956f22 avast-gpg-key.asc</code>
#* Add the GPG key
#*:<code>cp avast-gpg-key.asc /etc/apt/trusted.gpg.d/</code>
# Update the apt package information and install the software
#:<code>apt update</code>
#:<code>apt install avast</code>

== Registering license ==

Follow the [https://repo.avcdn.net/linux-av/doc/avast-techdoc.pdf instructions provided by Avast] to activate your purchased license.
Currently (13.07.2023) you'll get an activation code with your purchase and need to obtain the license file with the <code>avastlic</code> utility:
avastlic -f /etc/avast/license.avastlic -c <YOUR-ACTIVATION-CODE>

The utility is in a debian package of its own (so you can also run it on a separate machine):
apt install avast-license

After enabling your license you need to restart the <code>avast.service</code>
systemctl restart avast.service

== Integration with Proxmox Mail Gateway ==

Enabling the Avast scanner in Proxmox Mail Gateway is achieved by editing the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_configuration_file Promox Mail Gateway's configuration file]
<code>/etc/pmg/pmg.conf</code> and adding the line <code>avast 1</code> to the <code>admin</code> section:

section: admin
avast 1
email admin@pmg.example

Finally you need to restart the <code>pmg-smtp-filter</code> service, or reboot your Promox Mail Gateway:
systemctl restart pmg-smtp-filter

== Disable sending statistics and files to the Avast Virus Lab ==

By default <code>avast</code> sends files it considers suspicious and statistics to the Avast's virus lab.
To disable this you need to edit the avast configuration <code>/etc/avast/avast.conf</code>:

# Avast configuration file
#
# Below are all available configuration options and their default values. Only
# the options in the OPTIONS section can be changed at runtime.

# RUN_DIR = "/run/avast"
# TEMP_DIR = "/tmp"
# DATA_DIR = "/var/lib/avast"
# SOCKET = "/run/avast/scan.sock"
# LICENSE = "/etc/avast/license.avastlic"
# WHITELIST = "/etc/avast/whitelist"
SUBMIT = "/bin/true"

[OPTIONS]
# CREDENTIALS = 0
STATISTICS = 0
HEURISTICS = 0
# STREAMING_UPDATES = 1
# REPUTATION_QUERIES = 1

[PACKER_BOMB]
# MAX_FILE_SIZE_TO_EXTRACT_MB = 1000
# MAX_COMPRESSION_RATIO = 100

Should you need further help, consider getting a [https://www.proxmox.com/en/proxmox-mail-gateway/pricing enterprise support subscription]

Install Avast

2023-07-13T09:11:35Z

Stoiko Ivanov: updated to bookworm repository and new changes in avast

== Introduction ==

Proxmox Mail Gateway ships and uses the open source [https://www.clamav.net/ ClamAV] antivirus engine in its default installation.

Certain environments have the need for a better virus detection rate than the one achieved by ClamAV.

For these setups Proxmox Mail Gateway offers an integration with the [https://www.avast.com/en-us/business/products/antivirus-for-linux Avast Antivirus for Linux].
This HOWTO follows the technical documentation from Avast - https://repo.avcdn.net/linux-av/doc/avast-techdoc.pdf

Avast Antivirus for Linux is commercial software and you will need to purchase a license in order to use it.

The following facts are why it can be integrated with Proxmox Mail Gateway as an alternative to ClamAV:

* The licensing is based on the number of installations instead of other licensing schemes such as the number of processed mails or mailboxes.
* The software runs daemonized and thus reads and caches the AV definitions once upon startup instead of each time a file is scanned

The following HOWTO provides the necessary steps to install and configure Avast within a Proxmox Mail Gateway installation.

== Installing Avast Antivirus for Linux ==

Proxmox Mail Gateway is based on Debian GNU/Linux - thus you need to follow the installation instruction for Debian systems.

To configure the Avast repository and install the software:

# Create the appropriate [https://manpages.debian.org/apt/sources.list.5.en.html sources.list] entry:
#:<code>echo "deb https://repo.avcdn.net/linux-av/deb debian-bookworm release" > /etc/apt/sources.list.d/avast.list</code>
# Verify the signing key for the repository from Avast:
#* Get the key
#*:<code>wget https://repo.avcdn.net/linux-av/doc/avast-gpg-key.asc</code>
#*Read the checksum
#*:<code>sha512sum avast-gpg-key.asc</code>
#* The result should be
#*:<code>7fca6e2a8984931d46a8ff13cd086a934ca126068c074c86a13a30aa2f909663b9e5ae8529a02632c7735d2823bfc71b0e0987a63f8c4dd11130b2529e956f22 avast-gpg-key.asc</code>
#* Add the GPG key
#*:<code>cp avast-gpg-key.asc /etc/apt/trusted.gpg.d/</code>
# Update the apt package information and install the software
#:<code>apt update</code>
#:<code>apt install avast</code>

== Registering license ==

Follow the [https://repo.avcdn.net/linux-av/doc/avast-techdoc.pdf instructions provided by Avast] to activate your purchased license.
Currently (13.07.2023) you'll get an activation code with your purchase and need to obtain the license file with the <code>avastlic</code> utility:
avastlic -f /etc/avast/license.avastlic -c <YOUR-ACTIVATION-CODE>

The utility is in a debian package of its own (so you can also run it on a separate machine):
apt install avast-license

After enabling your license you need to restart the <code>avast.service</code>
systemctl restart avast.service

== Integration with Proxmox Mail Gateway ==

Enabling the Avast scanner in Proxmox Mail Gateway is achieved by editing the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_configuration_file Promox Mail Gateway's configuration file]
<code>/etc/pmg/pmg.conf</code> and adding the line <code>avast 1</code> to the <code>admin</code> section:

section: admin
avast 1
email admin@pmg.example

Finally you need to restart the <code>pmg-smtp-filter</code> service, or reboot your Promox Mail Gateway:
systemctl restart pmg-smtp-filter

Should you need further help, consider getting a [https://www.proxmox.com/en/proxmox-mail-gateway/pricing enterprise support subscription]

Upgrade from 7 to 8

2023-07-05T08:25:47Z

Stoiko Ivanov: /* Network Interface Name Change */

= Introduction =
Proxmox Mail Gateway 8.x is based on the new major version of Debian (Bookworm). 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 Bookworm.

In general, there are two ways to upgrade a Proxmox Mail Gateway 7.x system to Proxmox Mail Gateway 8.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 Bookworm]
** [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_install_on_debian On top of Debian Bookworm]
** 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.

* Perform these actions via SSH, a physical console or a remote management console like iKVM or IPMI.
** 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.
** '''Important''': Do not carry out the upgrade via the web UI console directly, as this will get interrupted during the upgrade.

* Upgraded to the latest version of Proxmox Mail Gateway 7., see the [[Roadmap#Release History|roadmap]] for potential important changes in the stable release.
*: Use <code>apt update</code> and <code>apt dist-upgrade</code> (still with Debian Bullseye repos setup) to upgrade to latest 7.3
** Verify version:
*: You can check the web-interface (reload) at the top, or use <code>pmgversion</code>. Both must show a version with 7.3-6 (or newer), for example something like <code>pmg-api/7.3-6/...</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 5 GB free disk space on root mount point.
* Check [[Upgrade_from_7.x_to_8.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 7 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.

=== Continuously use the '''pmg7to8''' checklist script ===

A small checklist program named '''<code>pmg7to8</code>''' is included in the latest Proxmox Mail Gateway 7.3 packages. The program will provide hints and warnings about potential issues before, during and after the upgrade process. You can call it by executing:

pmg7to8

This script only '''checks''' and reports things. By default, no changes to the system are made and thus, none of the issues will be automatically fixed.
You should keep in mind that Proxmox Mail Gateway can be heavily customized, so the script may not recognize all the possible problems with a particular setup!

It is recommended to re-run the script after each attempt to fix an issue. This ensures that the actions taken actually fixed the respective warning.

=== 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 Bookworm - see [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_package_repositories Package Repositories]
Update all Debian repository entries to Bookworm.

sed -i 's/bullseye/bookworm/g' /etc/apt/sources.list

Update the enterprise repository to Bookworm:

echo "deb https://enterprise.proxmox.com/debian/pmg bookworm 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 Bookworm 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)
:<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

During the above step, you will be asked to approve changes to configuration files, where the default config has been updated by their respective package.

It's suggested to check the difference for each file in question and choose the answer accordingly to what's most appropriate for your setup.

Common configuration files with changes, and the recommended choices are:
* <code>/etc/issue</code> -> Proxmox Mail Gateway will auto-generate this file on boot, and it has only cosmetic effects on the login console.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/clamav/clamd.conf </code> and <code>/etc/clamav/freshclam.conf</code> -> Those two configuration files are managed by Proxmox Mail Gateway directly, at will be re-generate on any relevant change and on boot.
*: Using the default "No" (keep your currently-installed version) is safe here.

* <code>/etc/ssh/sshd_config</code> -> If you have not changed this file manually, the only differences should be a replacement of <code>ChallengeResponseAuthentication no</code> with <code>KbdInteractiveAuthentication no</code> and some irrelevant changes in comments (lines starting with <code>#</code>).
*: If this is the case, both options are safe, though we would recommend installing the package maintainer's version in order to move away from the deprecated <code>ChallengeResponseAuthentication</code> option. If there are other changes, we suggest to inspect them closely and decide accordingly.

* <code>/etc/default/grub</code> -> Here you may want to take special care, as this is normally only asked for if you changed it manually, e.g., for adding some kernel command line option.
*: It's recommended to check the difference for any relevant change, note that changes in comments (lines starting with <code>#</code>) are not relevant.
*: If unsure, we suggested to selected "No" (keep your currently-installed version)

It is not necessary to reboot the Proxmox Mail Gateway host yet after the dist-upgrade finished.

=== Adapt modified configuration templates to new shipped versions ===

If configuration templates are used in <code>/etc/pmg/templates</code>, you will see a prompt about the changes in the new version that are not yet incorporated. Review the changes carefully and ensure that only the changes you want are shown in the diff.

=== Disable ClamAV On-Access Scanner Service ===

The new ClamAV on-access scanning service is not useful for Proxmox Mail Gateway setups and is disabled for new installations as it not only slows down the entire system, but also affects the spam and virus detection mechanisms managed by Proxmox Mail Gateway.

During upgrades, the service may get enabled and will then be marked as failed.
It is recommended to disable this service:
systemctl disable clamav-clamonacc.service

=== 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 15 main</pre>
* Upgrade the PostgreSQL main cluster from 13 to 15, using <code>pg_upgradecluster</code>
** This step will need some '''time''' and enough '''free disk space''' 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 15 13 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-13 postgresql-client-13</pre>

== After the Proxmox Mail Gateway upgrade ==

Empty the browser cache and/or force-reload (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd>, or for MacOS <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>R</kbd>) the Web UI.

=== Unmasking & Starting Cluster Services ===

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.
Thus, ensure to read the [https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html upgrade specific issues for Bookworm].

Please also check the known issue list from the Proxmox Mail Gateway 8.0 changelog: https://pmg.proxmox.com/wiki/Roadmap#8.0-known-issues

== Breaking Changes ==

* Changed defaults for Bayes and AWL
** Since the two options cause worse results when enabled in most average installations their defaults changed in 8.0, and they are now disabled
*: If your installation explicitly disabled, or enabled the feature nothing will change
*: In case your installation never set the setting the old default will now be written to <code>/etc/pmg/pmg.conf</code> to keep your system consistent.

* The ClamAV antivirus daemon <code>clamav-daemon</code> now uses socket-activation
*: To disable the service you need to disable <code>clamav-daemon.service</code> and <code>clamav-daemon.socket</code>

* Postgresql config change
*: the <code>stats_temp_directory</code> server variable is no longer supported
*: the postgresql.conf template shipped with Proxmox Mail Gateway accounts for the change
*: if you have modified the template (or copied it without modification) in /etc/pmg/templates/ - make sure to remove the line and/or remove the complete template override (if you don't have any modifications)

=== Upgrade wants to remove package 'proxmox-mail-gateway' ===

If you have installed Proxmox Mail Gateway on top of a plain Debian Bookworm (without using the Proxmox Mail Gateway ISO), you may have installed the package 'linux-image-amd64', which conflicts with current 8.x setups. To solve this, you have to remove this package with
apt remove linux-image-amd64
before the dist-upgrade.

== Network ==

=== Network Interface Name Change ===

Due to the new kernel recognizing more features of some hardware, like for example virtual functions, and since interface naming often derives from the PCI(e) address, some NICs may change their name, in which case the network configuration needs to be adapted.

This can also happen in virtualized environments (and has been reported with Xen for this upgrade)

In general, it's recommended to either have an independent remote connection to the Proxmox Mail Gateways's host console, for example, through the hypervisor in case of a VM or container setup, IPMI or iKVM, or physical access for managing the server even
when its own network doesn't come up after a major upgrade or network change.

=== Network Fails on Boot Due to NTPsec Hook ===

Some users reported that after the upgrade their network failed to come up cleanly on boot, but worked if triggered manually (e.g., using <code>ifreload -a</code>), when ntpsec was installed.

We're still investigating for a definitive root cause, but it seems that an udev hook which the <code>/etc/network/if-up.d/ntpsec-ntpdate</code> might hang on some hardware, albeit due to changes not directly related to ntpsec.

The simplest solution might be switching to that via <code>apt install chrony</code>.

== Systemd-boot (for ZFS on root and UEFI systems only) ==

Systems booting via UEFI from a ZFS on root setup should install the <code>systemd-boot</code> package after the upgrade. You will get a Warning from the <code>pve7to8</code> script after the upgrade if your system is affected - in all other cases you can safely ignore this point.

The <code>systemd-boot</code> was split out from the <code>systemd</code> package for Debian Bookworm based releases. It won't get installed automatically upon upgrade from Proxmox Mail Gateway 7.3 as it can cause trouble on systems not booting from UEFI with ZFS on root setup by the Proxmox Mail Gateway installer.

Systems which have ZFS on root and boot in UEFI mode will need to manually install it if they need to initialize a new ESP (see the output of <code>proxmox-boot-tool status</code>).

Note that the system remains bootable even without the package installed.

It is not recommended installing <code>systemd-boot</code> on systems which don't need it, as it would replace <code>grub</code> as bootloader in its <code>postinst</code> script.

= External links =

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

[[Category: Upgrade]]

DNS server on Proxmox Mail Gateway

2023-01-05T09:25:50Z

Stoiko Ivanov: /* Installing and using unbound */

== Introduction ==

One of the most effective means to detecting spam currently is the use of [https://cwiki.apache.org/confluence/display/SPAMASSASSIN/DnsBlocklists DnsBlocklists].
These lists are used to query the IP of the connecting SMTP server, or IPs and hostnames occurring in the mail body.

Some of the DNS Blocklists used by SpamAssassin (and thus also Proxmox Mail Gateway) allow only a certain number of requests per DNS server and don't respond once your DNS server has reached it's quota.
This is reflected in the mail logs and SpamAssassin hits of a mail. If you see 'URIBL_BLOCKED', 'RCVD_IN_DNSWL_BLOCKED' or 'SURBL_BLOCKED' in your mail logs or the mail headers, this is an indication that your system has reached the quota.

If you're using a shared DNS server (e.g. your ISPs, or a publicly available one like 9.9.9.9, 1.1.1.1, 8.8.8.8) it is quite likely that the Mail Gateway's requests will be blocked.

Installing a dedicated DNS server on the Proxmox Mail Gateway can help in such situations.

Keep in mind that the DNS Blocklists can only count the requests per public IP, i.e. if you have both your internal DNS and Proxmox Mail Gateway natted to the same public IP setting up a recursive DNS server will not help.

If you keep reaching the limit despite having a dedicated recursive server for your Proxmox Mail Gateway you should consider getting a dedicated feed, which is provided by most DNS Blocklist providers for a fee. This also helps keeping this important infrastructure up and running.

We will use the [https://nlnetlabs.nl/projects/unbound/about/ Unbound] recursive DNS server.

== Installing and using unbound ==

Simply run
apt install unbound dnsutils

to install the <code>unbound</code> server - the <code>dnsutils</code> package contains <code>dig</code>, which can be used for testing.

Check that unbound is indeed listening on port 53:
# ss -tulnp | grep :53
udp UNCONN 0 0 127.0.0.1:53 0.0.0.0:* users:(("unbound",pid=137,fd=5))
udp UNCONN 0 0 [::1]:53 [::]:* users:(("unbound",pid=137,fd=3))
tcp LISTEN 0 128 127.0.0.1:53 0.0.0.0:* users:(("unbound",pid=137,fd=6))
tcp LISTEN 0 128 [::1]:53 [::]:* users:(("unbound",pid=137,fd=4))

You can verify that DNS resolution works by using the <code>dig</code> utility
# dig a proxmox.com @127.0.0.1 +short
79.133.36.244

Afterwards you need to configure your Proxmox Mail Gateway installation to use the local dns-server listening on <code>127.0.0.1</code> (or optionally <code>::1</code>) as resolver.
In the following article we assume that your domain is <code>yourdomain.example</code> - you need to adapt the posted configuration.
On a standard installation this is done by simply placing:
nameserver 127.0.0.1
search yourdomain.example

in <code>/etc/resolv.conf</code>. You can use the GUI for setting the dns-resolver as well under Configuration -> Network/Time -> DNS - Just add <code>127.0.0.1</code> as <code>DNS Server 1</code>.

When Proxmox Mail Gateway is running as a Container on Proxmox VE, then you need to edit the container's DNS Settings to use <code>127.0.0.1</code> as DNS Server (and adapt your search domain to <code>yourdomain.example</code>)

If you have installed the resolvconf package you should not need to change everything, since the unbound package in Debian brings integration with <code>resolvconf</code>

Should your system use <code>systemd-resolved</code> make sure that
resolvectl status

indicates that <code>127.0.0.1</code> is listed as <code>Current DNS Server</code>

Alternatively you can simply disable and stop the service
systemctl disable systemd-resolved
systemctl stop systemd-resolved

After installing you can either reboot you Proxmox Mail Gateway, or restart the services relevant for mail-processing:
systemctl restart pmg-smtp-filter pmgpolicy postfix

== Forwarding requests for your internal zone to your internal DNS ==

In some environments the internally used DNS has all knowledge about your domain, and should be consulted for it, instead of unbound getting the publicly available data via DNS delegation from the root-servers.

You can configure unbound to ask your internal DNS-server (for this example the internal DNS-server has the IP 192.0.2.53) for your internal domains (yourdomain.example and yourseconddomain.example).
Create a dedicated config-snippet <code>/etc/unbound/unbound.conf.d/local-stub.conf</code>:

stub-zone:
name: "yourdomain.example"
stub-addr: 192.0.2.53

stub-zone:
name: "yourseconddomain.example"
stub-addr: 192.0.2.53

Afterwards restart unbound and verify that DNS-requests for yourdomain.example are delegated to 192.0.2.53 (by checking the DNS logs there):
systemctl restart unbound
dig test.yourdomain.example @127.0.0.1

== Optional: Using the local unbound only for DNS Blocklist requests ==

Should your environment require you to use an internal DNS server for all requests, because you have a very modified setup or are employing some other blocking for regulatory reasons you can also try to forward all other requests to your internal DNS Server and only ask the DNS Blocklist zones recursively.

This setup is '''not recommended for general use''', since it increases the complexity which makes debugging harder.

In the example we will use recursive queries for the following domains and forward all other requests to 192.0.2.53:
* mailspike.net
* dnsbl.sorbs.net
* rhsbl.sorbs.net
* bl.spamcop.net
* spamhaus.org
* surbl.org
* uribl.com
* dnswl.org

The list is taken from the [https://cwiki.apache.org/confluence/display/SPAMASSASSIN/DnsBlocklists Spam Assassin Entry on DNS Blocklists].
You should enhance the list by all domains you are using in your setup (especially the one's configured for <code>postscreen</code>)

Since unbound cannot do recursive lookups for specific zones if it is forwarding all other requests we will configure 2 unbound instances:
* one listening on port <code>5003</code> for recursive lookups - the DNSBL instance
* one forwarding requests for the DNSBL domains to port 5003, and all other requests to your internal DNS Server.

For the DNSBL instance - create a config-file which does only include the necessary config-options <code>/etc/unbound/unbound-dnsbl.conf</code>:
#unbound instance listening on port 5003 for DNSBL lookups
include: "/etc/unbound/unbound.conf.d/qname-minimisation.conf"
include: "/etc/unbound/unbound.conf.d/root-auto-trust-anchor-file.conf"

port: 5003
remote-control:
control-port: 8954

Additionally you need to create a systemd-unit (<code>/etc/systemd/system/unbound-rbl.service</code>

[Unit]
Description=Unbound DNS server for DNSBL lookups
Documentation=man:unbound(8)
After=network.target
Before=nss-lookup.target
Wants=nss-lookup.target

[Service]
Type=simple
Restart=on-failure
EnvironmentFile=-/etc/default/unbound
EnvironmentFile=-/etc/default/unbound-rbl
ExecStartPre=-/usr/lib/unbound/package-helper chroot_setup
ExecStartPre=-/usr/lib/unbound/package-helper root_trust_anchor_update
ExecStart=/usr/sbin/unbound -c /etc/unbound/unbound-rbl.conf -d $DAEMON_OPTS
ExecReload=/usr/sbin/unbound-control -c /etc/unbound/unbound-rbl.conf reload

[Install]
WantedBy=multi-user.target

and enable it with
systemctl enable unbound-rbl
systemctl start unbound-rbl

For the instance listening on port 53 you need to create a config-snippet in <code>/etc/unbound/unbound.conf.d/pmg-dnsbl.conf</code>:
server:
do-not-query-localhost: no
# depending on your internal DNS-servers capabilities these options might be necessary
# harden-dnssec-stripped: no
# module-config: "iterator"

forward-zone:
name: "uceprotect.net"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "mailspike.net"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "sorbs.net"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "bl.spamcop.net"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "spamhaus.org"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "surbl.org"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "uribl.com"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "dnswl.org"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "."
forward-addr: 192.0.2.53

Test the setup by doing lookups to:
* a testpoint of a DNSBL and verify that the query does not arrive at your internal server
* a testpoint of an arbitrary address (which should arrive at your internal server):

# dig any test.uribl.com.multi.uribl.com @127.0.0.1 +short # should not show up as query on 192.0.2.53
127.0.0.14
"permanent testpoint"
# dig a proxmox.com @127.0.0.1 +short #should show up as query on 192.0.2.53
79.133.36.244

Developer Documentation

2022-08-04T09:05:43Z

Stoiko Ivanov: update links to https and buster to bullseye

== Introduction ==

Please communicate you plans with us, before starting any development. It is important to have a common view of the problem and corresponding solution, in order to avoid duplicated work and unnecessary efforts.

Our source code repository is read-only. To contribute code, send it as a patch (git diff) to the pmg-devel mailing list. We will review your patch and apply it (and possible corrections/additions) if the review is successful. Note that we will only include code that meets our quality criteria.

== Mailing List ==

This is the primary communication channel for developers to discuss new features and implementation details. If you are a developer and you want to develop additional features, this is the place to start.

PMG Development List: https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel

Archive: https://lists.proxmox.com/pipermail/pmg-devel/

== Access to Code Repository (git) ==

You can find all of our project repositories at the link below.

https://git.proxmox.com

== Build instructions ==

*TODO*

== Development Package Repository ==

Some packages required for development can only be found in the ''devel'' repository.
This is a cross-project repository and may be used for all Proxmox projects.

Add the following to the <code>/etc/apt/sources.list</code> file:

deb http://download.proxmox.com/debian/devel/ bullseye main

== Checking out a git repository ==

To clone a repository, run 'git clone' with the repository name prefixed with the common URL: <nowiki>git://git.proxmox.com/git/</nowiki>

<source lang="bash">
# git clone git://git.proxmox.com/git/proxmox-mailgateway.git
</source>

To update an already cloned project to the current version use:

<source lang="bash">
# git pull
</source>

== Working on the code ==

=== Coding guidelines ===

The codebase is mostly Perl, with JavaScript for the web-interface.

We use the ExtJS framework for the GUI components; its API documentation can be found [https://docs.sencha.com/extjs/7.0.0/index.html here.]

=== Using git ===

If you are not familiar with git, it's worth having a look at this interactive tutorial:
https://try.github.io, and reading the brief introduction chapter from the official git documentation: https://git-scm.com/docs/gittutorial
to gain basic knowledge on it.

First, configure your ''real'' name and email address for git, if not done already:

<source lang="bash">
$ git config --global user.name "John Doe"
$ git config --global user.email john@example.com
</source>

This will be used to sign off commits as your work.

We recommend that you start a feature branch before working on the code locally:

<source lang="bash">
# git checkout -b my_branch master
</source>

After this, you can start working on your improvements. You can compare your changes to the current PMG master branch with:

<source lang="bash">
# git diff master..my_branch
</source>

==== Commits and Commit Messages ====

After making changes, commit them (try to make small, self-contained commits) with a sign-off line included (-s).

* Make sure the line length of the commit's message is '''not longer than 70 characters'''. HTTPS links are an exception and should not be split.
* If it fixes a bug, start with that information, in the form: <code>fix #1234: summary here</code>
* If it implements a feature tracked on Bugzilla, use: <code>close #1234: summary here</code>, albeit <code>fix #1234:</code> is commonly used and also fine.
* Add a tag to the beginning, if an obvious choice exists. For example, if you made a change to the user-configuration API, a possible tag could be <code>api: user-config: summary here</code>
: However, do '''not''' just paste the changed file, including path and file ending as a tag. This has no use and makes it harder to read.

The following command will take all the changes in tracked files and commit them:

<source lang="bash">
# git commit -s -a
</source>

New files won't get added automatically with this command. To stage new or altered files for a commit, use:

<source lang="bash">
# git add newfile1.pm file2.pm
</source>

You can always look at what will be committed with:

<source lang="bash">
# git diff --staged
</source>

== Preparing Patches ==

{{note| We need a valid [[#Software License and Copyright|CLA]] to include your changes|reminder}}

Since we have several projects in our git repository that use the pmg-devel mailing list,
we ask you to clarify which repository your patches are meant for,
by specifying it in the subject prefix, for example, 'pmg-api' or 'pmg-gui'.

Example: Creating the raw patch series for the <tt>pmg-api</tt> package:

<source lang="bash">
# rm -rf my-patches/ # to clean left-overs
# git format-patch -o my-patches/ --subject-prefix="PATCH pmg-api" master..my_branch --cover-letter
</source>

Explain in the cover letter the aim of your patches:

<source lang="bash">
edit my-patches/0000-cover-letter.patch
</source>

Sending patches:

<source lang="bash">
# git send-email --to=pmg-devel@lists.proxmox.com my-patches/00*.patch
# rm -rf my-patches/ # to clean left-overs
</source>

If you wish to write comments for individual patches, you can do that either in
the cover-letter, or in the patch's ''commit summary section'' (between the line
consisting of 3 consecutive dashes ending your commit message and before the
list of files with their change-counts).

Example:

<pre>
From 12345abcde Mon Sep 12 00:00:00 2001
From: Git Committer <some email address>
Date: Fri, 7 Oct 2020 08:30:17 +0200
Subject: [PATCH pmg-api 1/2] Fix #1013: this and that

Here is your commit message.
It explains the bugfix and ends after this line.

Signed-off-by: Firstname Lastname <firstname@lastname.email>
---
***HERE*** you can write your comments.
If this is a new version of an old patch, explain your changes here

src/PMG/Config.pm | 2 +-

diff --git a/src/PMG/Config.pm b/src/PMG/Config.pm
(...)
</pre>

If you want to send several related patches that contain changes to different repositories, you can first iterate over all involved repositories, save the patches into one directory and then do a single git send-email over all generated patches. For example, lets go to a few repos and format the most recent commit as a patch to /tmp/patchq, then send it:

<source lang="bash">
# cd pmg-api; git format-patch -s -o /tmp/patchq -1
# cd ../pmg-gui; git format-patch -s -o /tmp/patchq -1
# git send-email --compose --to=pmg-devel@lists.proxmox.com /tmp/patchq/*
</source>

Using "start-number" and the likes can improve this further, but this is a good start.

=== Versioned Patches ===

If an updated version of your patch series is called for, it should be sent
as a new series, rather than as a reply to the old series.
Always send the entire series, with all patches showing the same version.
Please mark your versions in the subject prefix, with a small 'v', followed by
the version number, like this:

<source lang="bash">
# git format-patch -o my-patches/ --subject-prefix="PATCH v2 pmg-api" master..my_branch
</source>

Please list all the changes to the previous versions in the ''commit summary
section'' as shown in the above example.
For patches with no changes to the previous version, you should mention that there were no
changes in the summary section.

If your series has a cover letter, summarize all changes in it as well.

=== Reviewing patches ===

After reviewing patches which affect a subsystem you maintain, you can notify
committers that you have reviewed the patch and are OK with the changes, with:

<pre>
Acked-by: name / email address
</pre>

=== Convenience Settings ===

For convenience, you can store the pmg-devel email address and the repository's
default subject prefixes in your repository clones' configurations as follows:

<source lang="bash">
$ git config --local sendemail.to pmg-devel@lists.proxmox.com
$ git config --local format.subjectprefix 'PATCH pmg-gui'
$ git config --local format.signoff true
</source>

Now the commands to create and send patches become:

<source lang="bash">
# git format-patch -o my-patches/ master..my_branch
# git send-email --compose my-patches/00*.patch
</source>

== Sending Patches ==

Always use <code>git send-email</code> to send out patches, otherwise the indentation and formatting will get mangled and the patch cannot be applied anymore.

=== Tutorial ===

See https://git-send-email.io/ for an interactive tutorial on setting up <code>git send-email</code>.

=== Using Authenticated SMTP Server ===

<code>git send-email</code> can be instructed to use a specific SMTP server for sending. The following shows an anonymized config section example:

[sendemail]
smtpencryption = tls
smtpserver = webmail.example.com
smtpserverport = 587
smtpuser = j.smith@example.com
smtpsslcertpath =
confirm = always

Add this to your global user <code>~/.gitconfig</code> or to the per project <code>.git/config</code>.
<code>git send-email</code> will then use these settings by default and ask you once for the password when sending.

== Bugtracker (Bugzilla) ==

We use Bugzilla to track bugs and feature requests for our products.

https://bugzilla.proxmox.com

== Software License and Copyright ==

We only include code licensed under GNU Affero General Public License, version 3 https://www.gnu.org/licenses/agpl-3.0.html.

Additionally, we ask contributors to send us a contributor license agreement form by email. This agreement establishes a relationship between us and the contributor, gives details on what it means when the contributor grants permission for their work to be included in a project, and enables us to better maintain these projects.

With the contributor agreement chosen by Proxmox, the [http://www.harmonyagreements.org Harmony CLA], the contributor gives Proxmox a license to use their contributions. The contributor continues to own the copyright in the contribution, with full rights to re-use, re-distribute, and continue modifying the contributed code, allowing them to also share that contribution with other projects.

We've tried to keep the agreement as simple and comprehensible as possible. It comes in two flavors:
* one for [https://www.proxmox.com/downloads/item/proxmox-individual-contributor-license-agreement individual contributors]
* and one for [https://www.proxmox.com/downloads/item/proxmox-entity-contributor-assignment-agreement entities contributors] (companies, foundations, or other organizations).

If you are making a contribution that is not your own work (for example, a patch or library written by someone else), please contact office@proxmox.com for guidance on whether any additional steps are needed.

== See Also ==

* [https://git-scm.com/documentation Git Documentation]

Quarantine Web Interface Via Nginx Proxy

2022-07-14T12:25:15Z

Stoiko Ivanov: /* Creating a site to proxy requests for quarantine */

== Introduction ==

Proxmox Mail Gateway can be configured to quarantine mail, instead of delivering potentially dangerous content to users directly.
If a mail is detected as spam users themselves can decide whether they want to keep or delete it in the user quarantine interface.
(for dangerous content, as mail containing viruses, or potentially dangerous attachments, the administrator needs to decide whether
to pass the mail on or delete it).

In certain environments it is desired to provide the user quarantine interface at a specific host and port,
e.g. in order to only allow access to the interface from outside on port 443, or to provide a different and
trusted certificate to your users.

The following Howto describes a small nginx configuration, which only exposes the paths necessary for user quarantine interface access,
while preventing access to other parts of the API.

Keep in mind that this provides mostly cosmetic protection, since all paths in the Proxmox Mail Gateway API, apart from the login path
are only available to authenticated users anyways. The unprotected login path needs to be forwarded for the quarantine access as well.

For creating a general reverse proxy for the complete web interface refer to the [https://pve.proxmox.com/wiki/Web_Interface_Via_Nginx_Proxy Howto in the Proxmox VE wiki].

== Installing nginx ==

The Howto creates a configuration suitable for nginx. You can install nginx on your Proxmox Mail Gateway using <nowiki>apt</nowiki>
apt install nginx

== Creating a site to proxy requests for quarantine ==

The following configuration is a minimal working nginx-site to proxy all requests necessary for accessing the quarantine interface for users.
You should adapt it to your site's requirements. This includes:
* changing the path to the used certificates
* setting the proper <nowiki>server_name</nowiki>
* adapting the ssl-configuration parameters to current best practices
* if the proxy server is running on another host adapting the url for the <nowiki>proxy_pass</nowiki> directives

To get the site running write the config to <nowiki>/etc/nginx/sites-available/pmg-quarantine.conf</nowiki> and symlink it to <nowiki>/etc/nginx/sites-enabled</nowiki>:
ln -rs /etc/nginx/sites-available/pmg-quarantine.conf /etc/nginx/sites-enabled/

<nowiki>
server {
listen 80 default_server;
rewrite ^(.*) https://$host$1 permanent;
}

server {
listen 443;
server_name _;
ssl on;
ssl_certificate /etc/pmg/pmg-api.pem;
ssl_certificate_key /etc/pmg/pmg-api.pem;
proxy_redirect off;

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header PVEClientIP $remote_addr;
proxy_buffering off;
client_max_body_size 0;
proxy_connect_timeout 3600s;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
send_timeout 3600s;

# proxy requests for static components
location ~ /proxmoxlib.js$|/favicon.ico$|/pve2/|/fontawesome/|/framework7/|/pwt/ {
proxy_pass https://localhost:8006;
}
location /quarantine {
proxy_pass https://localhost:8006;
}

location /api2 {
location ~ /api2/(extjs|json|htmlmail)/(access/ticket$|version$) {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/nodes/.+/subscription$ {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/quarantine {
proxy_pass https://localhost:8006;
}
return 403;
}

location / {
return 403;
}
}
</nowiki>

'''NOTE: if you're using the integrated ACME implementation with the standalone plugin you need to remove the server on port 80 above, since the ACME implementation needs to bind to it during certificate renewal'''

Install Avast

2022-06-27T11:00:21Z

Stoiko Ivanov: update date of last command verification

== Introduction ==

Proxmox Mail Gateway ships and uses the open source [https://www.clamav.net/ ClamAV] antivirus engine in its default installation.

Certain environments have the need for a better virus detection rate than the one achieved by ClamAV.

For these setups Proxmox Mail Gateway offers an integration with the [https://www.avast.com/en-us/business/products/antivirus-for-linux Avast Antivirus for Linux].
This HOWTO follows the technical documentation from Avast - https://repo.avcdn.net/linux-av/doc/avast-techdoc.pdf

Avast Antivirus for Linux is commercial software and you will need to purchase a license in order to use it.

The following facts are why it can be integrated with Proxmox Mail Gateway as an alternative to ClamAV:

* The licensing is based on the number of installations instead of other licensing schemes such as the number of processed mails or mailboxes.
* The software runs daemonized and thus reads and caches the AV definitions once upon startup instead of each time a file is scanned

The following HOWTO provides the necessary steps to install and configure Avast within a Proxmox Mail Gateway installation.

== Installing Avast Antivirus for Linux ==

Proxmox Mail Gateway is based on Debian GNU/Linux - thus you need to follow the installation instruction for Debian systems.

To configure the Avast repository and install the software:

# Create the appropriate [https://manpages.debian.org/apt/sources.list.5.en.html sources.list] entry:
#:<code>echo "deb https://repo.avcdn.net/linux-av/deb debian-bullseye release" > /etc/apt/sources.list.d/avast.list</code>
# Verify the signing key for the repository from Avast:
#* Get the key
#*:<code>wget https://repo.avcdn.net/linux-av/doc/avast-gpg-key.asc</code>
#*Read the checksum
#*:<code>sha512sum avast-gpg-key.asc</code>
#* The result should be
#*:<code>7fca6e2a8984931d46a8ff13cd086a934ca126068c074c86a13a30aa2f909663b9e5ae8529a02632c7735d2823bfc71b0e0987a63f8c4dd11130b2529e956f22 avast-gpg-key.asc</code>
#* Add the GPG key
#*:<code>cp avast-gpg-key.asc /etc/apt/trusted.gpg.d/</code>
# Update the apt package information and install the software
#:<code>apt update</code>
#:<code>apt install avast</code>

== Registering license ==

Follow the [https://repo.avcdn.net/linux-av/doc/avast-techdoc.pdf instructions provided by Avast] to activate your purchased license.
Currently (27.06.2022) you'll get an activation code with your purchase and need to obtain the license file with the <code>avastlic</code> utility:
avastlic -f /etc/avast/license.avastlic -c <YOUR-ACTIVATION-CODE>

After enabling your license you need to restart the <code>avast.service</code>
systemctl restart avast.service

== Integration with Proxmox Mail Gateway ==

Enabling the Avast scanner in Proxmox Mail Gateway is achieved by editing the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_configuration_file Promox Mail Gateway's configuration file]
<code>/etc/pmg/pmg.conf</code> and adding the line <code>avast 1</code> to the <code>admin</code> section:

section: admin
avast 1
email admin@pmg.example

Finally you need to restart the <code>pmg-smtp-filter</code> service, or reboot your Promox Mail Gateway:
systemctl restart pmg-smtp-filter

Should you need further help, consider getting a [https://www.proxmox.com/en/proxmox-mail-gateway/pricing enterprise support subscription]

Upgrade from 6.x to 7.0

2022-05-24T09:15:15Z

Stoiko Ivanov: /* Potential issues */

= 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!'''

* 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.

=== 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]

Install Avast

2022-04-20T11:26:10Z

Stoiko Ivanov:

== Introduction ==

Proxmox Mail Gateway ships and uses the open source [https://www.clamav.net/ ClamAV] antivirus engine in its default installation.

Certain environments have the need for a better virus detection rate than the one achieved by ClamAV.

For these setups Proxmox Mail Gateway offers an integration with the [https://www.avast.com/en-us/business/products/antivirus-for-linux Avast Antivirus for Linux].
This HOWTO follows the technical documentation from Avast - https://repo.avcdn.net/linux-av/doc/avast-techdoc.pdf

Avast Antivirus for Linux is commercial software and you will need to purchase a license in order to use it.

The following facts are why it can be integrated with Proxmox Mail Gateway as an alternative to ClamAV:

* The licensing is based on the number of installations instead of other licensing schemes such as the number of processed mails or mailboxes.
* The software runs daemonized and thus reads and caches the AV definitions once upon startup instead of each time a file is scanned

The following HOWTO provides the necessary steps to install and configure Avast within a Proxmox Mail Gateway installation.

== Installing Avast Antivirus for Linux ==

Proxmox Mail Gateway is based on Debian GNU/Linux - thus you need to follow the installation instruction for Debian systems.

To configure the Avast repository and install the software:

# Create the appropriate [https://manpages.debian.org/apt/sources.list.5.en.html sources.list] entry:
#:<code>echo "deb https://repo.avcdn.net/linux-av/deb debian-bullseye release" > /etc/apt/sources.list.d/avast.list</code>
# Verify the signing key for the repository from Avast:
#* Get the key
#*:<code>wget https://repo.avcdn.net/linux-av/doc/avast-gpg-key.asc</code>
#*Read the checksum
#*:<code>sha512sum avast-gpg-key.asc</code>
#* The result should be
#*:<code>7fca6e2a8984931d46a8ff13cd086a934ca126068c074c86a13a30aa2f909663b9e5ae8529a02632c7735d2823bfc71b0e0987a63f8c4dd11130b2529e956f22 avast-gpg-key.asc</code>
#* Add the GPG key
#*:<code>cp avast-gpg-key.asc /etc/apt/trusted.gpg.d/</code>
# Update the apt package information and install the software
#:<code>apt update</code>
#:<code>apt install avast</code>

== Registering license ==

Follow the [https://repo.avcdn.net/linux-av/doc/avast-techdoc.pdf instructions provided by Avast] to activate your purchased license.
Currently (02.07.2021) you'll get an activation code with your purchase and need to obtain the license file with the <code>avastlic</code> utility:
avastlic -f /etc/avast/license.avastlic -c <YOUR-ACTIVATION-CODE>

After enabling your license you need to restart the <code>avast.service</code>
systemctl restart avast.service

== Integration with Proxmox Mail Gateway ==

Enabling the Avast scanner in Proxmox Mail Gateway is achieved by editing the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_configuration_file Promox Mail Gateway's configuration file]
<code>/etc/pmg/pmg.conf</code> and adding the line <code>avast 1</code> to the <code>admin</code> section:

section: admin
avast 1
email admin@pmg.example

Finally you need to restart the <code>pmg-smtp-filter</code> service, or reboot your Promox Mail Gateway:
systemctl restart pmg-smtp-filter

Should you need further help, consider getting a [https://www.proxmox.com/en/proxmox-mail-gateway/pricing enterprise support subscription]

Install Avast

2022-04-15T14:59:36Z

Stoiko Ivanov: update to bullseye instructions

== Introduction ==

Proxmox Mail Gateway ships and uses the open source [https://www.clamav.net/ ClamAV] antivirus engine in its default installation.

Certain environments have the need for a better virus detection rate than the one achieved by ClamAV.

For these setups Proxmox Mail Gateway offers an integration with the [https://www.avast.com/en-us/business/products/antivirus-for-linux Avast Antivirus for Linux].
This HOWTO follows the technical documentation from Avast - https://repo.avcdn.net/linux-av/doc/avast-techdoc.pdf

Avast Antivirus for Linux is commercial software and you will need to purchase a license in order to use it.

The following facts are why it can be integrated with Proxmox Mail Gateway as an alternative to ClamAV:

* The licensing is based on the number of installations instead of other licensing schemes such as the number of processed mails or mailboxes.
* The software runs daemonized and thus reads and caches the AV definitions once upon startup instead of each time a file is scanned

The following HOWTO provides the necessary steps to install and configure Avast within a Proxmox Mail Gateway installation.

== Installing Avast Antivirus for Linux ==

Proxmox Mail Gateway is based on Debian GNU/Linux - thus you need to follow the installation instruction for Debian systems.

To configure the Avast repository and install the software:

# Create the appropriate [https://manpages.debian.org/apt/sources.list.5.en.html sources.list] entry:
#:<code>echo "deb http://deb.avast.com/lin/repo debian-buster release" > /etc/apt/sources.list.d/avast.list</code>
# Verify the signing key for the repository from Avast:
#* Get the key
#*:<code>wget https://repo.avcdn.net/linux-av/doc/avast-gpg-key.asc</code>
#*Read the checksum
#*:<code>sha512sum avast-gpg-key.asc</code>
#* The result should be
#*:<code>7fca6e2a8984931d46a8ff13cd086a934ca126068c074c86a13a30aa2f909663b9e5ae8529a02632c7735d2823bfc71b0e0987a63f8c4dd11130b2529e956f22 avast-gpg-key.asc</code>
#* Add the GPG key
#*:<code>cp avast-gpg-key.asc /etc/apt/trusted.gpg.d/</code>
# Update the apt package information and install the software
#:<code>apt update</code>
#:<code>apt install avast</code>

== Registering license ==

Follow the [https://repo.avcdn.net/linux-av/doc/avast-techdoc.pdf instructions provided by Avast] to activate your purchased license.
Currently (02.07.2021) you'll get an activation code with your purchase and need to obtain the license file with the <code>avastlic</code> utility:
avastlic -f /etc/avast/license.avastlic -c <YOUR-ACTIVATION-CODE>

After enabling your license you need to restart the <code>avast.service</code>
systemctl restart avast.service

== Integration with Proxmox Mail Gateway ==

Enabling the Avast scanner in Proxmox Mail Gateway is achieved by editing the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_configuration_file Promox Mail Gateway's configuration file]
<code>/etc/pmg/pmg.conf</code> and adding the line <code>avast 1</code> to the <code>admin</code> section:

section: admin
avast 1
email admin@pmg.example

Finally you need to restart the <code>pmg-smtp-filter</code> service, or reboot your Promox Mail Gateway:
systemctl restart pmg-smtp-filter

Should you need further help, consider getting a [https://www.proxmox.com/en/proxmox-mail-gateway/pricing enterprise support subscription]

Install Avast

2021-11-26T08:44:27Z

Stoiko Ivanov: /* Registering license */

== Introduction ==

Proxmox Mail Gateway ships and uses the open source [https://www.clamav.net/ ClamAV] antivirus engine in its default installation.

Certain environments have the need for a better virus detection rate than the one achieved by ClamAV.

For these setups Proxmox Mail Gateway offers an integration with the [https://www.avast.com/en-us/business/products/antivirus-for-linux Avast Antivirus for Linux].

Avast Antivirus for Linux is commercial software and you will need to purchase a license in order to use it.

The following facts are why it can be integrated with Proxmox Mail Gateway as an alternative to ClamAV:

* The licensing is based on the number of installations instead of other licensing schemes such as the number of processed mails or mailboxes.
* The software runs daemonized and thus reads and caches the AV definitions once upon startup instead of each time a file is scanned

The following HOWTO provides the necessary steps to install and configure Avast within a Proxmox Mail Gateway installation.

== Installing Avast Antivirus for Linux ==

Proxmox Mail Gateway is based on Debian GNU/Linux - thus you need to follow the installation instruction for Debian systems.

To configure the Avast repository and install the software:

# Create the appropriate [https://manpages.debian.org/apt/sources.list.5.en.html sources.list] entry:
#:<code>echo "deb http://deb.avast.com/lin/repo debian-buster release" > /etc/apt/sources.list.d/avast.list</code>
# Verify the signing key for the repository from Avast:
#* Get the key
#*:<code>wget https://files.avast.com/files/resellers/linux/avast.gpg</code>
#*Read the checksum
#*:<code>sha512sum avast.gpg</code>
#* The result should be
#*:<code>d9bb45d67664ad86f8d91a8f98657554b0550a8e467a5d6a3132de5d214b072470bf793ced9e3f13f774b5bfd061ce0ce7b192bf450bb68fc988072af17fb229 avast.gpg</code>
#* Add the GPG key
#*:<code>apt-key add avast.gpg</code>
# Update the apt package information and install the software
#:<code>apt update</code>
#:<code>apt install avast</code>

== Registering license ==

Follow the [https://deb.avast.com/lin/doc/techdoc.pdf instructions provided by Avast] to activate your purchased license.
Currently (02.07.2021) you'll get an activation code with your purchase and need to obtain the license file with the <code>avastlic</code> utility:
avastlic -f /etc/avast/license.avastlic -c <YOUR-ACTIVATION-CODE>

After enabling your license you need to restart the <code>avast.service</code>
systemctl restart avast.service

== Integration with Proxmox Mail Gateway ==

Enabling the Avast scanner in Proxmox Mail Gateway is achieved by editing the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_configuration_file Promox Mail Gateway's configuration file]
<code>/etc/pmg/pmg.conf</code> and adding the line <code>avast 1</code> to the <code>admin</code> section:

section: admin
avast 1
email admin@pmg.example

Finally you need to restart the <code>pmg-smtp-filter</code> service, or reboot your Promox Mail Gateway:
systemctl restart pmg-smtp-filter

Should you need further help, consider getting a [https://www.proxmox.com/en/proxmox-mail-gateway/pricing enterprise support subscription]

Install Avast

2021-07-02T07:57:44Z

Stoiko Ivanov: /* Registering license */

== Introduction ==

Proxmox Mail Gateway ships and uses the open source [https://www.clamav.net/ ClamAV] antivirus engine in its default installation.

Certain environments have the need for a better virus detection rate than the one achieved by ClamAV.

For these setups Proxmox Mail Gateway offers an integration with the [https://www.avast.com/en-us/business/products/antivirus-for-linux Avast Antivirus for Linux].

Avast Antivirus for Linux is commercial software and you will need to purchase a license in order to use it.

The following facts are why it can be integrated with Proxmox Mail Gateway as an alternative to ClamAV:

* The licensing is based on the number of installations instead of other licensing schemes such as the number of processed mails or mailboxes.
* The software runs daemonized and thus reads and caches the AV definitions once upon startup instead of each time a file is scanned

The following HOWTO provides the necessary steps to install and configure Avast within a Proxmox Mail Gateway installation.

== Installing Avast Antivirus for Linux ==

Proxmox Mail Gateway is based on Debian GNU/Linux - thus you need to follow the installation instruction for Debian systems.

To configure the Avast repository and install the software:

# Create the appropriate [https://manpages.debian.org/apt/sources.list.5.en.html sources.list] entry:
#:<code>echo "deb http://deb.avast.com/lin/repo debian-buster release" > /etc/apt/sources.list.d/avast.list</code>
# Verify the signing key for the repository from Avast:
#* Get the key
#*:<code>wget https://files.avast.com/files/resellers/linux/avast.gpg</code>
#*Read the checksum
#*:<code>sha512sum avast.gpg</code>
#* The result should be
#*:<code>d9bb45d67664ad86f8d91a8f98657554b0550a8e467a5d6a3132de5d214b072470bf793ced9e3f13f774b5bfd061ce0ce7b192bf450bb68fc988072af17fb229 avast.gpg</code>
#* Add the GPG key
#*:<code>apt-key add avast.gpg</code>
# Update the apt package information and install the software
#:<code>apt update</code>
#:<code>apt install avast</code>

== Registering license ==

Follow the [https://deb.avast.com/lin/doc/techdoc.pdf instructions provided by Avast] to activate your purchased license.
Currently (02.07.2021) you'll get an activation code with your purchase and need to obtain the license file with the <code>avastlic</code> utility:
avastlic -f /etc/avast/license.avast -c <YOUR-ACTIVATION-CODE>

After enabling your license you need to restart the <code>avast.service</code>
systemctl restart avast.service

== Integration with Proxmox Mail Gateway ==

Enabling the Avast scanner in Proxmox Mail Gateway is achieved by editing the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmg_configuration_file Promox Mail Gateway's configuration file]
<code>/etc/pmg/pmg.conf</code> and adding the line <code>avast 1</code> to the <code>admin</code> section:

section: admin
avast 1
email admin@pmg.example

Finally you need to restart the <code>pmg-smtp-filter</code> service, or reboot your Promox Mail Gateway:
systemctl restart pmg-smtp-filter

Should you need further help, consider getting a [https://www.proxmox.com/en/proxmox-mail-gateway/pricing enterprise support subscription]

Upgrade from 5.x to 6.0

2021-05-19T13:10:17Z

Stoiko Ivanov: /* For Clusters */

= 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 ==

* 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 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 <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]

URIBL Datafeed over DNS

2020-09-10T07:29:36Z

Stoiko Ivanov: /* Introduction */

== Introduction ==

Certain DNSBLs are run as a "free for most" model, meaning that most users can use their service without payment.

Usually there is a limit on the number of queries you can run against their service, before you get blocked.

The very effective DNSBL [http://uribl.com uribl] indicates that you have reached the rate-limit by creating SpamAssassin hits on <code>URIBL_BLOCKED</code>, which show up in your mail logs.

Reaching the limit means your Proxmox Mail Gateway will not get correct answers from uribl, which reduces the spamdetection accuracy dramatically.

The first mitigation you should consider is making sure that you have a working and correct DNS setup for your Proxmox Mail Gateway, for example by
installing a [https://pmg.proxmox.com/wiki/index.php/DNS_server_on_Proxmox_Mail_Gateway dedicated recursive DNS server].

Should you still reach the query limit, you should consider subscribing to a dedicated [http://uribl.com/datafeed.shtml datafeed via DNS], which
removes the query limit for you, and is priced based on your number of queries.

Once you have subscribed you will receive an email with detailed instructions, which should give you a good overview of the features offered
by the datafeed service.

This HOWTO provides the necessary steps to integrate your custom DNS datafeed in your Promox Mail Gateway installation, based off the
[http://uribl.com/datafeed_dns.txt configuration howto from uribl.com].

Depending on whether you have a dedicated DNS server used by your Proxmox Mail Gateway or not you can follow two
ways to use your custom datafeed.

== Configuration with a dedicated DNS Server ==
If you have one or two dedicated IP Networks under your control, where your DNS Servers are located, you can simply
[https://admin.uribl.com/?section=lookup;method=dologin login to uribl] and add those 2 networks as registered with your datafeed.

Your DNS requests will come from one of the whitelisted IPs and will not be blocked due to ratelimiting

''' This method is only applicable if you run a recursive DNS server, where you know who is allowed to ask queries there.'''

Do not whitelist shared DNS servers provided by your ISP, or globally (8.8.8.8, 9.9.9.9, 1.1.1.1) - since else all requests
being relayed via those IPs will be billed to your account.

== Configuration by adapting SpamAssassin Configuration ==

If your setup needs to use a shared DNS server and you cannot control who can use it for URIBL queries you will have
to configure SpamAssassin within your Proxmox Mail Gateway to use the custom query host provided with your datafeed.

The correct way to change the [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_custom_spamassassin_configuration SpamAssassin configuration in a Proxmox Mail Gateway installation] is by using the
[https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#pmgconfig_template_engine templating system].

Just add the adapted example configuration provided by uribl to your <code>/etc/mail/spamassassin/custom.cf</code> - this will also ensure that it gets synchronized to all nodes, if you have a clustered setup.

Make sure to replace <code>_CUSTID</code> by your custom datafeed id, which you received in the mail from uribl.com

The following minimal config enables your custom datafeed for the regular DNSBLs (URIBL_BLACK, URIBL_GREY, URIBL_RED):

<nowiki>
urirhssub URIBL_BLOCKED _CUSTID.df.uribl.com. A 1
urirhssub URIBL_BLACK _CUSTID.df.uribl.com. A 2
urirhssub URIBL_GREY _CUSTID.df.uribl.com. A 4
urirhssub URIBL_RED _CUSTID.df.uribl.com. A 8
</nowiki>

As suggested in the uribl guide you can check the workings by running: <code> echo -e "Subject: test\n\nhttp://uribl.asia\n\n" | spamassassin -D 2>&1 | grep URIBL_BLACK</code>
Your custom datafeed id should be present in the output.

Should you need further help, consider getting a [https://www.proxmox.com/en/proxmox-mail-gateway/pricing enterprise support subscription]

DNS server on Proxmox Mail Gateway

2020-08-26T16:20:00Z

Stoiko Ivanov: /* Optional: Using the local unbound only for DNS Blocklist requests */

== Introduction ==

One of the most effective means to detecting spam currently is the use of [https://cwiki.apache.org/confluence/display/SPAMASSASSIN/DnsBlocklists DnsBlocklists].
These lists are used to query the IP of the connecting SMTP server, or IPs and hostnames occurring in the mail body.

Some of the DNS Blocklists used by SpamAssassin (and thus also Proxmox Mail Gateway) allow only a certain number of requests per DNS server and don't respond once your DNS server has reached it's quota.
This is reflected in the mail logs and SpamAssassin hits of a mail. If you see 'URIBL_BLOCKED', 'RCVD_IN_DNSWL_BLOCKED' or 'SURBL_BLOCKED' in your mail logs or the mail headers, this is an indication that your system has reached the quota.

If you're using a shared DNS server (e.g. your ISPs, or a publicly available one like 9.9.9.9, 1.1.1.1, 8.8.8.8) it is quite likely that the Mail Gateway's requests will be blocked.

Installing a dedicated DNS server on the Proxmox Mail Gateway can help in such situations.

Keep in mind that the DNS Blocklists can only count the requests per public IP, i.e. if you have both your internal DNS and Proxmox Mail Gateway natted to the same public IP setting up a recursive DNS server will not help.

If you keep reaching the limit despite having a dedicated recursive server for your Proxmox Mail Gateway you should consider getting a dedicated feed, which is provided by most DNS Blocklist providers for a fee. This also helps keeping this important infrastructure up and running.

We will use the [https://nlnetlabs.nl/projects/unbound/about/ Unbound] recursive DNS server.

== Installing and using unbound ==

Simply run
apt install unbound dnsutils

to install the <code>unbound</code> server - the <code>dnsutils</code> package contains <code>dig</code>, which can be used for testing.

Check that unbound is indeed listening on port 53:
# ss -tulnp | grep :53
udp UNCONN 0 0 127.0.0.1:53 0.0.0.0:* users:(("unbound",pid=137,fd=5))
udp UNCONN 0 0 [::1]:53 [::]:* users:(("unbound",pid=137,fd=3))
tcp LISTEN 0 128 127.0.0.1:53 0.0.0.0:* users:(("unbound",pid=137,fd=6))
tcp LISTEN 0 128 [::1]:53 [::]:* users:(("unbound",pid=137,fd=4))

You can verify that DNS resolution works by using the <code>dig</code> utility
# dig a proxmox.com @127.0.0.1 +short
79.133.36.244

Afterwards you need to configure your Proxmox Mail Gateway installation to use the local dns-server listening on <code>127.0.0.1</code> (or optionally <code>::1</code>) as resolver.
In the following article we assume that your domain is <code>yourdomain.example</code> - you need to adapt the posted configuration.
On a standard installation this is done by simply placing:
nameserver 127.0.0.1
search yourdomain.example

in <code>/etc/resolv.conf</code>.

When Proxmox Mail Gateway is running as a Container on Proxmox VE, then you need to edit the container's DNS Settings to use <code>127.0.0.1</code> as DNS Server (and adapt your search domain to <code>yourdomain.example</code>)

If you have installed the resolvconf package you should not need to change everything, since the unbound package in Debian brings integration with <code>resolvconf</code>

Should your system use <code>systemd-resolved</code> make sure that
resolvectl status

indicates that <code>127.0.0.1</code> is listed as <code>Current DNS Server</code>

Alternatively you can simply disable and stop the service
systemctl disable systemd-resolved
systemctl stop systemd-resolved

After installing you can either reboot you Proxmox Mail Gateway, or restart the services relevant for mail-processing:
systemctl restart pmg-smtp-filter pmgpolicy postfix

== Forwarding requests for your internal zone to your internal DNS ==

In some environments the internally used DNS has all knowledge about your domain, and should be consulted for it, instead of unbound getting the publicly available data via DNS delegation from the root-servers.

You can configure unbound to ask your internal DNS-server (for this example the internal DNS-server has the IP 192.0.2.53) for your internal domains (yourdomain.example and yourseconddomain.example).
Create a dedicated config-snippet <code>/etc/unbound/unbound.conf.d/local-stub.conf</code>:

stub-zone:
name: "yourdomain.example"
stub-addr: 192.0.2.53

stub-zone:
name: "yourseconddomain.example"
stub-addr: 192.0.2.53

Afterwards restart unbound and verify that DNS-requests for yourdomain.example are delegated to 192.0.2.53 (by checking the DNS logs there):
systemctl restart unbound
dig test.yourdomain.example @127.0.0.1

== Optional: Using the local unbound only for DNS Blocklist requests ==

Should your environment require you to use an internal DNS server for all requests, because you have a very modified setup or are employing some other blocking for regulatory reasons you can also try to forward all other requests to your internal DNS Server and only ask the DNS Blocklist zones recursively.

This setup is '''not recommended for general use''', since it increases the complexity which makes debugging harder.

In the example we will use recursive queries for the following domains and forward all other requests to 192.0.2.53:
* mailspike.net
* dnsbl.sorbs.net
* rhsbl.sorbs.net
* bl.spamcop.net
* spamhaus.org
* surbl.org
* uribl.com
* dnswl.org

The list is taken from the [https://cwiki.apache.org/confluence/display/SPAMASSASSIN/DnsBlocklists Spam Assassin Entry on DNS Blocklists].
You should enhance the list by all domains you are using in your setup (especially the one's configured for <code>postscreen</code>)

Since unbound cannot do recursive lookups for specific zones if it is forwarding all other requests we will configure 2 unbound instances:
* one listening on port <code>5003</code> for recursive lookups - the DNSBL instance
* one forwarding requests for the DNSBL domains to port 5003, and all other requests to your internal DNS Server.

For the DNSBL instance - create a config-file which does only include the necessary config-options <code>/etc/unbound/unbound-dnsbl.conf</code>:
#unbound instance listening on port 5003 for DNSBL lookups
include: "/etc/unbound/unbound.conf.d/qname-minimisation.conf"
include: "/etc/unbound/unbound.conf.d/root-auto-trust-anchor-file.conf"

port: 5003
remote-control:
control-port: 8954

Additionally you need to create a systemd-unit (<code>/etc/systemd/system/unbound-rbl.service</code>

[Unit]
Description=Unbound DNS server for DNSBL lookups
Documentation=man:unbound(8)
After=network.target
Before=nss-lookup.target
Wants=nss-lookup.target

[Service]
Type=simple
Restart=on-failure
EnvironmentFile=-/etc/default/unbound
EnvironmentFile=-/etc/default/unbound-rbl
ExecStartPre=-/usr/lib/unbound/package-helper chroot_setup
ExecStartPre=-/usr/lib/unbound/package-helper root_trust_anchor_update
ExecStart=/usr/sbin/unbound -c /etc/unbound/unbound-rbl.conf -d $DAEMON_OPTS
ExecReload=/usr/sbin/unbound-control -c /etc/unbound/unbound-rbl.conf reload

[Install]
WantedBy=multi-user.target

and enable it with
systemctl enable unbound-rbl
systemctl start unbound-rbl

For the instance listening on port 53 you need to create a config-snippet in <code>/etc/unbound/unbound.conf.d/pmg-dnsbl.conf</code>:
server:
do-not-query-localhost: no
# depending on your internal DNS-servers capabilities these options might be necessary
# harden-dnssec-stripped: no
# module-config: "iterator"

forward-zone:
name: "uceprotect.net"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "mailspike.net"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "sorbs.net"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "bl.spamcop.net"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "spamhaus.org"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "surbl.org"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "uribl.com"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "dnswl.org"
forward-addr: 127.0.0.1@5003

forward-zone:
name: "."
forward-addr: 192.0.2.53

Test the setup by doing lookups to:
* a testpoint of a DNSBL and verify that the query does not arrive at your internal server
* a testpoint of an arbitrary address (which should arrive at your internal server):

# dig any test.uribl.com.multi.uribl.com @127.0.0.1 +short # should not show up as query on 192.0.2.53
127.0.0.14
"permanent testpoint"
# dig a proxmox.com @127.0.0.1 +short #should show up as query on 192.0.2.53
79.133.36.244

Upgrade from 5.x to 6.0

2020-08-26T15:29:34Z

Stoiko Ivanov: /* Service Failure Caused By Apparmor Featureset Missmatch */

= 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 ==

* 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 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 <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]

Upgrade from 5.x to 6.0

2020-06-22T13:01:26Z

Stoiko Ivanov: s/VE/Mail Gateway/

= 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 ==

* 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 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 <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:
* 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]

Getting started with Proxmox Mail Gateway

2020-06-03T15:27:54Z

Stoiko Ivanov: change link to videotutorials to point to www.proxmox.com instead of the forum thread

== Introduction ==
Proxmox Mail Gateway provides a comprehensive enterprise email security solution, which can be comfortably configured via the Graphical User Interface.

This article is aimed at providing descriptions and links to best-practices that have emerged in the Proxmox Mail Gateway community.

The goal is to present a small set of adaptations, which dramatically improve the detection accuracy and user experience of your
Proxmox Mail Gateway.

It is not meant to display every single possible potential improvement.

If you run into any issues, please try finding a solution in the [https://pmg.proxmox.com/pmg-docs reference documentation],
which is shipped with every Proxmox Mail Gateway installation and will always provide the most up to date information.

Searching the [https://forum.proxmox.com Community Forum], or posting your question there can also provide helpful pointers from
our involved and knowledgeable community.

== Installation ==

An overview of the Proxmox Mail Gateway installation can be found on [https://www.proxmox.com/en/proxmox-mail-gateway/get-started the Proxmox Mail Gateway homepage]

The [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_installation reference documentation] provides a detailed description of the various install methods.

Additionally you can learn about the installation process from our [https://www.proxmox.com/en/training/video-tutorials/category/proxmox-mailgateway video tutorials]

== Operations/Maintenance ==

=== Changing Hostname or IP ===

see [[Change FQDN]]

=== Configuring Outbound Scanning ===

Proxmox Mail Gateway accepts email from internal servers on the internal port (default: 26).
The distinction on which port email arrives is used for the distinction which rules to apply
to an email, and whether to relay an email to a foreign domain.

You should take care not to accept mail from the public internet on your internal port, but
only from trusted internal systems.

It can be difficult to configure certain mailservers (for example Microsoft Exchange) to relay email through a different port than port 25.
In those situations you can swap the internal and external ports of the Proxmox Mail Gateway to use port 25 as internal port and
configure a port-redirection on your
firewall to redirect traffic from the public internet on port 25 to port 26 on your Proxmox Mail Gateway.

For a rationale behind scanning outbound mail check the [https://forum.proxmox.com/threads/filtering-outgoing-mails.78/ community post from the Proxmox Mail Gateway's beginnings]

== Improving Spam Detection ==

One of the most effective means to combat spam nowadays is the use of [https://en.wikipedia.org/wiki/Domain_Name_System-based_Blackhole_List DNS based Blackhole lists (DNSBL)].

Proxmox Mail Gateway offers two places where it can check information against DNSBLs:
* during the SMTP dialog within the Mail Proxy - here only the connecting IP can be checked against the DNSBLs configured in GUI -> Configuration -> Mail Proxy -> Options -> DNSBL Sites
* by the Spam Detector (SpamAssassin) - here the complete content of the mail (including potentially malicious URLs) is checked against a set of [https://cwiki.apache.org/confluence/display/SPAMASSASSIN/DnsBlocklists predefined lists]

DNSBLs have different acceptable use policies, including offering free service for non-commercial use, a limit on the number of queries, or a required registration. Make sure to check that your use-case is allowed by the providers of the list.
Since the service provided by the DNSBL operators is very valuable for the functioning of the email ecosystem you could consider supporting the providers, if possible.

=== Basic set of DNSBLs for the Mail Proxy ===

The following list offers quite good results in practice:
* zen.spamhaus.org [https://www.spamhaus.org/organization/dnsblusage/ Acceptable Use Policy]
* b.barracudacentral.org [https://www.barracudacentral.org/rbl Acceptable Use Policy]

=== Dedicated DNS Resolver on Proxmox Mail Gateway ===

Since DNSBLs transport information via DNS, having a working DNS Setup is essential to good anti-spam results.

Running a [https://pmg.proxmox.com/wiki/index.php/DNS_server_on_Proxmox_Mail_Gateway dedicated recursive DNS Server] on your Proxmox Mail Gateway can help avoid running into rate limits:

=== URIBL custom datafeed ===
For sites where the email volume is so high that even a dedicated DNS server reaches URIBL's rate limit you can consider purchasing a custom DNS datafeed from URIBL:

see [[URIBL Datafeed over DNS]]

== Improving Antivirus Accuracy ==

=== Second virus scanner ===

Installing a second Antivirus engine can help improving the Antivirus detection rate:

see [[Install Avast]]

== Let's Encrypt- a free, automated and open certificate authority ==
To configure a globally trusted certificate using Let's Encrypt follow the
[https://forum.proxmox.com/threads/how-to-lets-encrypt-and-pmg.41493/ thread in our forum]

== End user quarantine access ==

=== Quarantine Web Interface via 443 ===
By redirecting your Quarantine links to a Proxy on port 443 you can restrict access to the admin interface to certain IPs and present your users with a globally trusted certificate:

see [[Quarantine Web Interface Via Nginx Proxy]]

== Load Balancing ==

Load balancing SMTP is most easily achieved using DNS.

Since Proxmox Mail Gateway is a proxy which does not store mail permanently you can simply configure multiple MX records with the same priority for your domains,
or multiple A records for the DNS name, which you use as MX record.

See the ''HA Cluster'' tab on the [https://www.proxmox.com/en/proxmox-mail-gateway/features Proxmox Mail Gateway feature page] and the [https://forum.proxmox.com/threads/redundant-servers-and-load-balancing-using-mx-records.73/ thread in our community forum].

Getting started with Proxmox Mail Gateway

2020-06-03T12:04:41Z

Stoiko Ivanov: change quarantine proxy link to internal

== Introduction ==
Proxmox Mail Gateway provides a comprehensive enterprise email security solution, which can be comfortably configured via the Graphical User Interface.

This article is aimed at providing descriptions and links to best-practices that have emerged in the Proxmox Mail Gateway community.

The goal is to present a small set of adaptations, which dramatically improve the detection accuracy and user experience of your
Proxmox Mail Gateway.

It is not meant to display every single possible potential improvement.

If you run into any issues, please try finding a solution in the [https://pmg.proxmox.com/pmg-docs reference documentation],
which is shipped with every Proxmox Mail Gateway installation and will always provide the most up to date information.

Searching the [https://forum.proxmox.com Community Forum], or posting your question there can also provide helpful pointers from
our involved and knowledgeable community.

== Installation ==

An overview of the Proxmox Mail Gateway installation can be found on [https://www.proxmox.com/en/proxmox-mail-gateway/get-started the Proxmox Mail Gateway homepage]

The [https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_installation reference documentation] provides a detailed description of the various install methods.

Additionally you can learn about the installation process from our [https://forum.proxmox.com/threads/installation-tutorials.40827/ video tutorials]

== Operations/Maintenance ==

=== Changing Hostname or IP ===

see [[Change FQDN]]

=== Configuring Outbound Scanning ===

Proxmox Mail Gateway accepts email from internal servers on the internal port (default: 26).
The distinction on which port email arrives is used for the distinction which rules to apply
to an email, and whether to relay an email to a foreign domain.

You should take care not to accept mail from the public internet on your internal port, but
only from trusted internal systems.

It can be difficult to configure certain mailservers (for example Microsoft Exchange) to relay email through a different port than port 25.
In those situations you can swap the internal and external ports of the Proxmox Mail Gateway to use port 25 as internal port and
configure a port-redirection on your
firewall to redirect traffic from the public internet on port 25 to port 26 on your Proxmox Mail Gateway.

For a rationale behind scanning outbound mail check the [https://forum.proxmox.com/threads/filtering-outgoing-mails.78/ community post from the Proxmox Mail Gateway's beginnings]

== Improving Spam Detection ==

One of the most effective means to combat spam nowadays is the use of [https://en.wikipedia.org/wiki/Domain_Name_System-based_Blackhole_List DNS based Blackhole lists (DNSBL)].

Proxmox Mail Gateway offers two places where it can check information against DNSBLs:
* during the SMTP dialog within the Mail Proxy - here only the connecting IP can be checked against the DNSBLs configured in GUI -> Configuration -> Mail Proxy -> Options -> DNSBL Sites
* by the Spam Detector (SpamAssassin) - here the complete content of the mail (including potentially malicious URLs) is checked against a set of [https://cwiki.apache.org/confluence/display/SPAMASSASSIN/DnsBlocklists predefined lists]

DNSBLs have different acceptable use policies, including offering free service for non-commercial use, a limit on the number of queries, or a required registration. Make sure to check that your use-case is allowed by the providers of the list.
Since the service provided by the DNSBL operators is very valuable for the functioning of the email ecosystem you could consider supporting the providers, if possible.

=== Basic set of DNSBLs for the Mail Proxy ===

The following list offers quite good results in practice:
* zen.spamhaus.org [https://www.spamhaus.org/organization/dnsblusage/ Acceptable Use Policy]
* b.barracudacentral.org [https://www.barracudacentral.org/rbl Acceptable Use Policy]

=== Dedicated DNS Resolver on Proxmox Mail Gateway ===

Since DNSBLs transport information via DNS, having a working DNS Setup is essential to good anti-spam results.

Running a [https://pmg.proxmox.com/wiki/index.php/DNS_server_on_Proxmox_Mail_Gateway dedicated recursive DNS Server] on your Proxmox Mail Gateway can help avoid running into rate limits:

=== URIBL custom datafeed ===
For sites where the email volume is so high that even a dedicated DNS server reaches URIBL's rate limit you can consider purchasing a custom DNS datafeed from URIBL:

see [[URIBL Datafeed over DNS]]

== Improving Antivirus Accuracy ==

=== Second virus scanner ===

Installing a second Antivirus engine can help improving the Antivirus detection rate:

see [[Install Avast]]

== Let's Encrypt- a free, automated and open certificate authority ==
To configure a globally trusted certificate using Let's Encrypt follow the
[https://forum.proxmox.com/threads/how-to-lets-encrypt-and-pmg.41493/ thread in our forum]

== End user quarantine access ==

=== Quarantine Web Interface via 443 ===
By redirecting your Quarantine links to a Proxy on port 443 you can restrict access to the admin interface to certain IPs and present your users with a globally trusted certificate:

see [[Quarantine Web Interface Via Nginx Proxy]]

== Load Balancing ==

Load balancing SMTP is most easily achieved using DNS.

Since Proxmox Mail Gateway is a proxy which does not store mail permanently you can simply configure multiple MX records with the same priority for your domains,
or multiple A records for the DNS name, which you use as MX record.

See the ''HA Cluster'' tab on the [https://www.proxmox.com/en/proxmox-mail-gateway/features Proxmox Mail Gateway feature page] and the [https://forum.proxmox.com/threads/redundant-servers-and-load-balancing-using-mx-records.73/ thread in our community forum].

Quarantine Web Interface Via Nginx Proxy

2020-05-05T10:25:12Z

Stoiko Ivanov: Created page with "== Introduction == Proxmox Mail Gateway can be configured to quarantine mail, instead of delivering potentially dangerous content to users directly. If a mail is detected as..."

== Introduction ==

Proxmox Mail Gateway can be configured to quarantine mail, instead of delivering potentially dangerous content to users directly.
If a mail is detected as spam users themselves can decide whether they want to keep or delete it in the user quarantine interface.
(for dangerous content, as mail containing viruses, or potentially dangerous attachments, the administrator needs to decide whether
to pass the mail on or delete it).

In certain environments it is desired to provide the user quarantine interface at a specific host and port,
e.g. in order to only allow access to the interface from outside on port 443, or to provide a different and
trusted certificate to your users.

The following Howto describes a small nginx configuration, which only exposes the paths necessary for user quarantine interface access,
while preventing access to other parts of the API.

Keep in mind that this provides mostly cosmetic protection, since all paths in the Proxmox Mail Gateway API, apart from the login path
are only available to authenticated users anyways. The unprotected login path needs to be forwarded for the quarantine access as well.

For creating a general reverse proxy for the complete web interface refer to the [https://pve.proxmox.com/wiki/Web_Interface_Via_Nginx_Proxy Howto in the Proxmox VE wiki].

== Installing nginx ==

The Howto creates a configuration suitable for nginx. You can install nginx on your Proxmox Mail Gateway using <nowiki>apt</nowiki>
apt install nginx

== Creating a site to proxy requests for quarantine ==

The following configuration is a minimal working nginx-site to proxy all requests necessary for accessing the quarantine interface for users.
You should adapt it to your site's requirements. This includes:
* changing the path to the used certificates
* setting the proper <nowiki>server_name</nowiki>
* adapting the ssl-configuration parameters to current best practices
* if the proxy server is running on another host adapting the url for the <nowiki>proxy_pass</nowiki> directives

To get the site running write the config to <nowiki>/etc/nginx/sites-available/pmg-quarantine.conf</nowiki> and symlink it to <nowiki>/etc/nginx/sites-enabled</nowiki>:
ln -rs /etc/nginx/sites-available/pmg-quarantine.conf /etc/nginx/sites-enabled/

<nowiki>
server {
listen 80 default_server;
rewrite ^(.*) https://$host$1 permanent;
}

server {
listen 443;
server_name _;
ssl on;
ssl_certificate /etc/pmg/pmg-api.pem;
ssl_certificate_key /etc/pmg/pmg-api.pem;
proxy_redirect off;

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header PVEClientIP $remote_addr;
proxy_buffering off;
client_max_body_size 0;
proxy_connect_timeout 3600s;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
send_timeout 3600s;
# proxy requests for static components
location ~ /proxmoxlib.js$|/favicon.ico$|/pve2/|/fontawesome/|/framework7/|/pwt/css/ {
proxy_pass https://localhost:8006;
}
location /quarantine {
proxy_pass https://localhost:8006;
}

location /api2 {
location ~ /api2/(extjs|json|htmlmail)/(access/ticket$|version$) {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/nodes/.+/subscription$ {
proxy_pass https://localhost:8006;
}
location ~ /api2/(extjs|json|htmlmail)/quarantine {
proxy_pass https://localhost:8006;
}
return 403;
}

location / {
return 403;
}
}
</nowiki>

[[Category:Staging]]

Upgrade from 5.x to 6.0

2019-09-13T18:02:24Z

Stoiko Ivanov: /* Potential issues */

= 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 ==

* 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 [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 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 <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 =

* 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

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

* 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]

Upgrade from 5.x to 6.0

2019-08-27T10:17:07Z

Stoiko Ivanov: /* Potential issues */

= 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 ==

* 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 [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 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 <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 =

* 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

* 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 uninstall <code>apparmor</code> in that situation:
apt remove apparmor

= External links =

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

Upgrade from 5.x to 6.0

2019-08-20T13:43:30Z

Stoiko Ivanov: Created page with "== 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 ext..."

== 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 ===

* 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 ===
* 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 https://enterprise.proxmox.com/debian/pmg buster pmg-enterprise" > /etc/apt/sources.list.d/pmg-enterprise.list

* Stop postfix and all Proxmox Mail Gateway services (emails will be queued by the servers trying to contact the Proxmox Mail Gateway)
This is necessary to prevent changes to the database before the upgrade
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

* 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 service is provided by the nodes not being upgraded.

* Upgrade the system:
apt update
apt dist-upgrade

* 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 MG 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. 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 (<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

* Clamav-freshclam has a bug with it's AppArmor handling, which seems not fixed yet: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=903834

== External links ==

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

[[Category:Staging]]