Proxmox Mail Gateway Administration Guide

Proxmox Mail Gateway uses a wide variety of local and network tests to identify spam mail. Here is a short list of used filtering methods:

Proxmox Mail Gateway integrates ClamAV®, which is an open-source (GPL) antivirus engine, designed for detecting Trojans, viruses, malware, and other malicious threats.

It provides a high performance, multi-threaded scanning daemon, command-line utilities for on demand file scanning, and an intelligent tool for automatic signature updates.

The object-oriented rule system enables custom rules for your domains. It’s an easy but very powerful way to define filter rules by user, domains, time frame, content type and resulting action. Proxmox Mail Gateway offers a lot of powerful objects to configure your own custom system.

Every rule has five categories FROM, TO, WHEN, WHAT and ACTION. Each of these categories can contain several objects and a direction (in, out or both).

Options range from simple spam and virus filter setups to sophisticated, highly customized configurations, blocking certain types of emails and generating notifications.

Proxmox Mail Gateway makes email security and filtering simple to manage. The web-based management interface allows you to set up and maintain even a complex mail system with ease.

There is no need to install a separate management tool. Any modern internet browser is sufficient.

Identified spam mails can be stored in the user-accessible Spam Quarantine. Thus, users can view and manage their spam mails by themselves.

The innovative Proxmox Message Tracking Center tracks and summarizes all available logs. With the web-based and user-friendly management interface, IT admins can easily view and control all functions from a single screen.

The Message Tracking Center is fast and powerful. It has been tested on Proxmox Mail Gateway sites which process over a million emails per day. All log files from the last 7 days can be queried, and the results are summarized by an intelligent algorithm.

The logged information includes:

Proxmox Mail Gateway offers the possibility to optionally sign outgoing emails with DKIM.

To provide a 100% secure email system for your business, we developed Proxmox High Availability (HA) Cluster. The Proxmox HA Cluster uses a unique application-level clustering scheme, which provides extremely good performance. It is quick to set-up and the simple, intuitive management interface keeps resource requirements low. After temporary failures, nodes automatically reintegrate without any operator interaction.

It is possible to query user and group data from LDAP servers. This may be used to build special filter rules, or simply to provide authentication services for the Spam Quarantine GUI.

Proxmox Mail Gateway allows you to fetch mail from other IMAP or POP3 servers.

The administration interface uses a role-based access control scheme, using the following roles:

Proxmox Mail Gateway itself is fully open source, so we always encourage our users to discuss and share their knowledge using the Proxmox Community Forum. The forum is moderated by the Proxmox support team, and has a large user base around the world. Needless to say, such a large forum is a great place to get information.

Proxmox Server Solutions GmbH also offers commercial Proxmox Mail Gateway Subscription Service Plans. Users with a Basic subscription or above have access to a dedicated support portal with guaranteed response times, where Proxmox Mail Gateway developers can help them, should an issue appear. Please contact the Proxmox sales team for more information or volume discounts.

We also run a public bug tracker at https://bugzilla.proxmox.com. If you ever detect a bug, you can file a bug entry there. This makes it easy to track the bug’s status and get notified as soon as the bug is fixed.

To use the web interface, you need a modern browser. This includes:

The flash drive needs to have at least 1 GB of storage available.

On a Unix-like operating system, you can use the dd command to copy the ISO image to the USB flash drive. To do this, find the device name of the USB flash drive (see below), then run the dd command.

Open the terminal (query Terminal in Spotlight).

Convert the .iso file to .img using the convert option of hdiutil, for example:

To get the current list of devices, run the command:

Now insert the USB flash drive and run this command again to determine which device node has been assigned to it. (e.g., /dev/diskX).

After a succesful installation and reboot of the system you can use the Proxmox Mail Gateway web interface for further configuration.

For detailed deployment scenarios see chapter Planning for Deployment.

After the installation, you have to route all your incoming and outgoing email traffic to Proxmox Mail Gateway. For incoming traffic, you have to configure your firewall and/or DNS settings. For outgoing traffic you need to change the existing email server configuration.

The installer creates a Volume Group (VG) called pmg, and additional Logical Volumes (LVs) called root and swap. The size of those volumes can be controlled with:

ZFS works best with a lot of memory. If you intend to use ZFS make sure to have enough RAM available for it. A good calculation is 4GB plus 1GB RAM for each TB RAW disk space.

ZFS can use a dedicated drive as write cache, called the ZFS Intent Log (ZIL). Use a fast drive (SSD) for it. It can be added after installation with the following command:

--- # zpool add <pool-name> log </dev/path_to_fast_ssd> ---

Problems may arise on very old or very new hardware due to graphics drivers. If the installation hangs during the boot. In that case, you can try adding the nomodeset parameter. This prevents the Linux kernel from loading any graphics drivers and forces it to continue using the BIOS/UEFI-provided framebuffer.

On the Proxmox Mail Gateway bootloader menu, navigate to Install Proxmox Mail Gateway (Terminal UI) and press e to edit the entry. Using the arrow keys, navigate to the line starting with linux, move the cursor to the end of that line and add the parameter nomodeset, separated by a space from the pre-existing last parameter.

Then press Ctrl-X or F10 to boot the configuration.

Repositories are a collection of software packages. They can be used to install new software, but are also important to get new updates.

APT Repositories are defined in the file /etc/apt/sources.list and in .list files placed in /etc/apt/sources.list.d/.

This is the default, stable and recommended repository, available for all Proxmox Mail Gateway subscription users. It contains the most stable packages, and is suitable for production use. The pmg-enterprise repository is enabled by default:

As soon as updates are available, the root@pam user is notified via email about the newly available packages. From the GUI, the change-log of each package can be viewed (if available), showing all details of the update. Thus, you will never miss important security fixes.

Please note that you need a valid subscription key to access this repository. We offer different support levels, which you can find further details about at https://www.proxmox.com/en/proxmox-mail-gateway/pricing.

As the name suggests, you do not need a subscription key to access this repository. It can be used for testing and non-production use. It’s not recommended to use this on production servers, as these packages are not always heavily tested and validated.

We recommend configuring this repository in /etc/apt/sources.list.

Finally, there is a repository called pmgtest. This contains the latest packages, and is heavily used by developers to test new features. As with before, you can configure this using /etc/apt/sources.list by adding the following line:

We use GnuPG to sign the Release files inside these repositories, and APT uses these signatures to verify that all packages are from a trusted source.

The key used for verification is already installed, if you install from our installation CD. If you install via another means, you can manually download the key by executing the following command as root user:

Verify the checksum afterwards with the sha512sum CLI tool:

or the md5sum CLI tool:

Certain software cannot be made available in the main and contrib areas of the Debian archives, since it does not adhere to the Debian Free Software Guidelines (DFSG). These are distributed in the Debian’s non-free archive area. For Proxmox Mail Gateway two packages from the non-free area are needed in order to support the RAR archive format:

To enable the non-free component, run editor /etc/apt/sources.list and append non-free to the end of each .debian.org repository line.

Following this, you can install the required packages with:

Starting with Debian Bookworm (Proxmox Mail Gateway 8) non-free firmware (as defined by DFSG) has been moved to the newly created Debian repository component non-free-firmware.

Enable this repository if you want to set up Early OS Microcode Updates or need additional Runtime Firmware Files not already included in the pre-installed package pve-firmware.

To be able to install packages from this component, run editor /etc/apt/sources.list, append non-free-firmware to the end of each .debian.org repository line and run apt update.

The SMTP Whitelist is responsible for disabling greylisting, as well as SPF and DNSBL checks. These are done during the SMTP dialogue.

The rule-based white- and blacklists are predefined rules. They work by checking the attached Who objects, containing, for example, a domain or a mail address for a match. If it matches, the assigned action is used, which by default is Accept for the whitelist rule and Block for the blacklist rule. In the default setup, the blacklist rule has priority over the whitelist rule and spam checks.

The user white- and blacklist are user specific. Every user can add mail addresses to their white- and blacklist. When a user adds a mail address to the whitelist, the result of the spam analysis will be discarded for that recipient. This can help in the mail being accepted, but what happens next still depends on the other rules. In the default setup, this results in the mail being accepted for this recipient.

For mail addresses on a user’s blacklist, the spam score will be increased by 100. What happens when a high spam score is encountered still depends on the rule system. In the default setup, it will be recognized as spam and quarantined (spam score of 3 or higher).

As network and time are configured in the installer, these generally do not need to be configured again in the GUI.

The default setup uses a single Ethernet adapter and static IP assignment. The configuration is stored at /etc/network/interfaces, and the actual network setup is done the standard Debian way, using the package ifupdown.

Many tests to detect SPAM mails use DNS queries, so it is important to have a fast and reliable DNS server. We also query some publicly available DNS Blacklists. Most of them apply rate limits for clients, so they simply will not work if you use a public DNS server (because they are usually blocked). We recommend to use your own DNS server, which needs to be configured in recursive mode.

These settings are saved to the admin subsection in /etc/pmg/pmg.conf, using the following configuration keys:

Proxmox Mail Gateway uses two different certificates:

You have the following options for these certificates:

Certificates are managed through the Proxmox Mail Gateway web-interface/API or using the the pmgconfig CLI tool.

If you already have a certificate which you want to use for a Proxmox Mail Gateway host, you can simply upload that certificate over the web interface.

Note that any certificate key files must not be password protected.

Proxmox Mail Gateway includes an implementation of the Automatic Certificate Management Environment (ACME) protocol, allowing Proxmox Mail Gateway admins to use an ACME provider like Let’s Encrypt for easy setup of TLS certificates, which are accepted and trusted by modern operating systems and web browsers out of the box.

Currently, the two ACME endpoints implemented are the Let’s Encrypt (LE) production and staging environments. Our ACME client supports validation of http-01 challenges using a built-in web server and validation of dns-01 challenges using a DNS plugin supporting all the DNS API endpoints acme.sh does.

There is always an implicitly configured standalone plugin for validating http-01 challenges via the built-in web server spawned on port 80.

There are a few prerequisites to use this for certificate management with Let’s Encrypts ACME.

On systems where external access for validation via the http-01 method is not possible or desired, it is possible to use the dns-01 validation method. This validation method requires a DNS server that allows provisioning of TXT records via an API.

If a node has been successfully configured with an ACME-provided certificate (either via pmgconfig or via the web-interface/API), the certificate will be renewed automatically by the pmg-daily.service. Currently, renewal is triggered if the certificate either has already expired or if it will expire in the next 30 days.

Manually Change Certificate over the Command Line

If you change the API certificate of an active cluster node manually, you also need to update the pinned fingerprint inside the cluster configuration.

You can do that by executing the following command on the host where the certificate changed:

Note, this will be done automatically if using the integrated ACME (for example, through Let’s Encrypt) feature.

These settings are saved to the mail subsection in /etc/pmg/pmg.conf. Some of these correspond to postfix options in the main.cf (see the postconf documentation).

They use the following configuration keys:

A list of relayed mail domains, that is, what destination domains this system will relay mail to. The system will reject incoming mails to other domains.

These settings are saved to the mail subsection in /etc/pmg/pmg.conf. Many of these correspond to postfix options in the main.cf (see the postconf documentation).

They use the following configuration keys:

These settings are saved to the mail subsection in /etc/pmg/pmg.conf, using the following configuration keys:

Email scanning can happen at two different stages of mail-processing:

Before-queue filtering has the advantage that the system can reject a mail (by sending a permanent reject code 554), and leave the task of notifying the original sender to the other mail server. This is of particular advantage if the processed mail is a spam message or contains a virus and has a forged sender address. Sending out a notification in this situation leads to so-called backscatter mail, which might cause your server to get listed as spamming on RBLs (Real-time Blackhole List).

After-queue filtering has the advantage of providing faster delivery of mails for the sending servers, since queuing emails is much faster than analyzing them for spam and viruses.

If a mail is addressed to multiple recipients (for example, when multiple addresses are subscribed to the same mailing list), the situation is more complicated; your mail server can only reject or accept the mail for all recipients, after having received the complete message, while your rule setup might accept the mail for part of the recipients and reject it for others. This can be due to a complicated rule setup, or if your users use the User White- and Blacklist feature.

If the resulting action of the rule system is the same for all recipients, Proxmox Mail Gateway responds accordingly, if configured for before-queue filtering (sending 554 for a blocked mail and 250 for an accepted or quarantined mail). If some mailboxes accept the mail and some reject it, the system has to accept the mail.

Whether Proxmox Mail Gateway notifies the sender that delivery failed for some recipients by sending a non-delivery report, depends on the ndr_on_block setting in /etc/pmg/pmg.conf. If enabled, an NDR is sent. Keeping this disabled prevents NDRs being sent to the (possibly forged) sender and thus minimizes the chance of getting your IP listed on an RBL. However in certain environments, it can be unacceptable not to inform the sender about a rejected mail.

The setting has the same effect if after-queue filtering is configured, with the exception that an NDR is always sent out, even if all recipients block the mail, since the mail already got accepted before being analyzed.

The details of integrating the mail proxy with Postfix in both setups are explained in Postfix Before-Queue Content Filter and Postfix After-Queue Content Filter respectively.

Greylisting is a technique for preventing unwanted messages from reaching the resource intensive stages of content analysis (virus detection and spam detection). By initially replying with a temporary failure code (450) to each new email, Proxmox Mail Gateway tells the sending server that it should queue the mail and retry delivery at a later point. Since certain kinds of spam get sent out by software which has no provisioning for queuing, these mails are dropped without reaching Proxmox Mail Gateway or your mailbox.

The downside of greylisting is the delay introduced by the initial deferral of the email, which usually amounts to less than 30 minutes.

In order to prevent unnecessary delays in delivery from known sources, emails coming from a source for a recipient, which have passed greylisting in the past are directly passed on: For each email the triple <sender network, sender email, recipient email> is stored in a list, along with the time when delivery was attempted. If an email fits an already existing triple, the timestamp for that triple is updated, and the email is accepted for further processing.

As long as a sender and recipient communicate frequently, there is no delay introduced by enabling greylisting. A triple is removed after a longer period of time, if no mail fitting that triple has been seen. The timeouts in Proxmox Mail Gateway are:

Mails with an empty envelope sender are always delayed.

Some email service providers send out emails for one domain from multiple servers. To prevent delays due to an email coming in from two separate IPs of the same provider, the triples store a network (cidr) instead of a single IP. For certain large providers, the default network size might be too small. You can configure the netmask applied to an IP for the greylist lookup in /etc/pmg/pmg.conf or in the GUI with the settings greylistmask for IPv4 and greylistmask6 for IPv6 respectively.

You can use Proxmox Mail Gateway to send emails to different internal email servers. For example, you can send emails addressed to domain.com to your first email server and emails addressed to subdomain.domain.com to a second one.

You can add the IP addresses, hostname, transport protocol (smtp/lmtp), transport ports and mail domains (or just single email addresses) of your additional email servers. When transport protocol is set to lmtp, the option Use MX is useless and will automatically be set to No.

You can add additional internal (trusted) IP networks or hosts. All hosts in this list are allowed to relay.

Transport Layer Security (TLS) provides certificate-based authentication and encrypted sessions. An encrypted session protects the information that is transmitted with SMTP mail. When you activate TLS, Proxmox Mail Gateway automatically generates a new self signed certificate for you (/etc/pmg/pmg-tls.pem).

Proxmox Mail Gateway uses opportunistic TLS encryption by default. The SMTP transaction is encrypted if the STARTTLS ESMTP feature is supported by the remote server. Otherwise, messages are sent unencrypted.

You can set a different TLS policy per destination. A destination is either a remote domain or a next-hop destination, as specified in /etc/pmg/transport. This can be used if you need to prevent email delivery without encryption, or to work around a broken STARTTLS ESMTP implementation. See Postfix TLS Readme for details on the supported policies.

Additionally, TLS can also be enforced on incoming connections on the external port for specific sender domains by creating a TLS inbound domains entry. Mails with matching domains must use a encrypted SMTP session, otherwise they are rejected. All domains on this list have and entry of reject_plaintext_session in a check_sender_access table.

Those settings are saved to subsection mail in /etc/pmg/pmg.conf, using the following configuration keys:

DomainKeys Identified Mail (DKIM) Signatures (see RFC 6376) is a method to cryptographically authenticate a mail as originating from a particular domain. Before sending the mail, a hash over certain header fields and the body is computed, signed with a private key and added in the DKIM-Signature header of the mail. The selector (a short identifier chosen by you, used to identify which system and private key were used for signing) is also included in the DKIM-Signature header.

The verification is done by the receiver. The public key is fetched via DNS TXT lookup for yourselector._domainkey.yourdomain.example and used for verifying the hash. You can publish multiple selectors for your domain, each used by a system which sends email from your domain, without the need to share the private key.

Proxmox Mail Gateway verifies DKIM Signatures for inbound mail in the Spam Filter by default.

Additionally, it supports conditionally signing outbound mail, if configured. It uses one private key and selector per Proxmox Mail Gateway deployment (all nodes in a cluster use the same key). The key has a minimal size of 1024 bits and rsa-sha256 is used as the signing algorithm.

The headers included in the signature are taken from the list of Mail::DKIM::Signer. Additionally Content-Type (if present), From, To, CC, Reply-To and Subject get oversigned.

You can either sign all mails received on the internal port using the domain of the envelope sender address or create a list of domains, for which emails should be signed, defaulting to the list of relay domains.

These settings are saved to the admin subsection in /etc/pmg/pmg.conf, using the following configuration keys:

All SMTP checks are disabled for those entries (e.g. Greylisting, SPF, DNSBL, …)

DNSBL checks are done by postscreen, which works on IP addresses and networks. This means it can only make use of the IP Address and IP Network entries.

Proxmox Mail Gateway uses a wide variety of local and network tests to identify spam signatures. This makes it harder for spammers to identify one aspect which they can craft their messages to work around the spam filter.

Every single email will be analyzed and have a spam score assigned. The system attempts to optimize the efficiency of the rules that are run in terms of minimizing the number of false positives and false negatives.

Proxmox Mail Gateway analyses all incoming email messages and decides for each email if it is ham or spam (or virus). Good emails are delivered to the inbox and spam messages are moved into the spam quarantine.

The system can be configured to send daily reports to inform users about personal spam messages received in the last day. The report is only sent if there are new messages in the quarantine.

Some options are only available in the config file /etc/pmg/pmg.conf, and not in the web interface.

While the default scoring of SpamAssassin™'s ruleset provides very good detection rates, sometimes your particular environment can benefit from slightly adjusting the score of a particular rule. Two examples:

The system logs all the rules which a particular mail hits. Analyzing the logs can lead to finding such a pattern in your environment.

You can adjust the score of a rule by creating a new Custom Rule Score entry in the GUI and entering a SpamAssassin™ rule as the name.

All mails are automatically passed to the included virus detector (ClamAV®). The default settings are considered safe, so it is usually not required to change them.

ClamAV® related settings are saved to subsection clamav in /etc/pmg/pmg.conf, using the following configuration keys:

Please note that the virus signature database is automatically updated. You can see the database status in the GUI, and also trigger manual updates from there.

Identified virus mails are automatically moved to the virus quarantine. The administrator can view these mails from the GUI, and choose to deliver them, in case of false positives. Proxmox Mail Gateway does not notify individual users about received virus mails.

Virus quarantine related settings are saved to subsection virusquar in /etc/pmg/pmg.conf, using the following configuration keys:

Local users can manage and audit Proxmox Mail Gateway. They can login on the management web interface.

There are four roles:

In addition, there is always the root user, which is used to perform special system administrator tasks, such as upgrading a host or changing the network configuration.

Local user related settings are saved in /etc/pmg/user.conf.

For details on the fields, see user.conf

With Proxmox Mail Gateway, users can use LDAP and Active directory as authentication methods to access their individual Spam Quarantine. Additionally, if users have extra email aliases defined in the LDAP directory, they will have a single spam quarantine for all of these.

You can specify multiple LDAP/Active Directory profiles, so that you can create rules matching particular users and groups.

Creating a profile requires (at least) the following:

All other fields should work with the defaults for most setups, but can be used to customize the queries.

The settings are saved to /etc/pmg/ldap.conf. Details about the options can be found here: ldap.conf

Fetchmail is a utility for polling and forwarding emails. You can define email accounts, which will then be fetched and forwarded to the email address you defined.

You have to add an entry for each account/target combination you want to fetch and forward. These will then be regularly polled and forwarded, according to your configuration.

The API and web interface offer the following configuration options:

You can set up multiple second factors, in order to avoid a situation in which losing your smartphone or security key locks you out of your account permanently.

The following two-factor authentication methods are available:

Users can choose to enable TOTP or WebAuthn as a second factor on login, via the TFA button in the user list.

Users can always add and use one time Recovery Keys.

There is no server setup required. Simply install a TOTP app on your smartphone (for example, andOTP) and use the Proxmox Backup Server web-interface to add a TOTP factor.

After opening the TOTP window, the user is presented with a dialog to set up TOTP authentication. The Secret field contains the key, which can be randomly generated via the Randomize button. An optional Issuer Name can be added to provide information to the TOTP app about what the key belongs to. Most TOTP apps will show the issuer name together with the corresponding OTP values. The username is also included in the QR code for the TOTP app.

After generating a key, a QR code will be displayed, which can be used with most OTP apps such as FreeOTP. The user then needs to verify the current user password (unless logged in as root), as well as the ability to correctly use the TOTP key, by typing the current OTP value into the Verification Code field and pressing the Apply button.

For WebAuthn to work, you need to have two things:

Once you have fulfilled both of these requirements, you can add a WebAuthn configuration in the Two Factor panel under Datacenter → Permissions → Two Factor.

Recovery key codes do not need any preparation; you can simply create a set of recovery keys in the Two Factor panel under Datacenter → Permissions → Two Factor.

To allow users to use WebAuthn authentication, it is necessaary to use a valid domain with a valid SSL certificate, otherwise some browsers may warn or refuse to authenticate altogether.

You can configure WebAuthn directly in the Two Factor panel, there’s an auto-fill button that will set the correct values for most setups.

Accept mail for Delivery. This is a final action.

Block mail. This is a final action.

Move to quarantine (virus mails are moved to the “virus quarantine”; other mails are moved to “spam quarantine”). This is also a final action.

Send notifications. Please note that object configuration can use macros, so it is easy to include additional information. For example, the default Notify Admin object sends the following information:

Notification can also include a copy of the original mail.

The BCC object simply sends a copy to another target. It is possible to send the original unmodified mail, or the processed result. Please note that this can be quite different, for instance, when a previous rule removed attachments.

This object is able to add or modify mail header attributes. As with Notifications above, you can use macros, making this a very powerful object. For example, the Modify Spam Level actions add detailed information about detected Spam characteristics to the X-SPAM-LEVEL header.

Another prominent example is the Modify Spam Subject action. This simply adds the SPAM: prefix to the original mail subject:

Remove attachments can either remove all attachments, or only those matched by the rule’s What - object. You can also specify the replacement text, if you want.

You can optionally move these mails into the attachment quarantine, where the original mail with all attachments will be stored. The mail with the attachments removed will continue through the rule system.

Add a Disclaimer.

The disclaimer can contain HTML markup. It will be added to the first text/html and text/plain part of an email. A disclaimer only gets added if its text can be encoded in the mail’s character encoding.

By default it will be appended at the end of the selected part of the mail with -- as a separator. The position (start or end of the selected part) and the existence of the separator can be configured with the position and add-separator options respectively.

In its simplest form, a regular expression is just a word or phrase to search for. Mail would match the string "Mail". The search is case sensitive so "MAIL", "Mail", "mail" would not be matched.

Some characters have a special meaning. These characters are called metacharacters. The Period (.) is a commonly used metacharacter. It matches exactly one character, regardless of what the character is. e.mail would match either "e-mail" or "e2mail" but not "e-some-mail" or "email".

The question mark (?) indicates that the character immediately preceding it shows up either zero or one time. e?mail would match either "email" or "mail" but not "e-mail".

Another metacharacter is the asterisk (*). This indicates that the character immediately preceding it may be repeated any number of times, including zero. e*mail would match "email", "mail", and "eeemail".

The plus (+) metacharacter indicates that the character immediately preceding it appears one or more times. So e+mail does not match "mail".

Metacharacters can also be combined. A common combination includes the period and asterisk metacharacters (.*), with the asterisk immediately following the period. This is used to match an arbitrary string of any length, including the null string. For example: .*company.* matches "company@domain.com" or "company@domain.co.uk" or "department.company@domain.com".

The book [Friedl97] provides a more comprehensive introduction.

This page shows statistics about server CPU, memory, disk and network usage. You can select the displayed time span from the upper right.

Administrators can open a terminal window using the Console button. It is also possible to trigger a server Restart or Shutdown.

This panel lists all the major services used for mail processing and cluster synchronization. If necessary, you can start, stop or restart them. The Syslog button shows the system log, filtered for the selected service.

Please note that Proxmox Mail Gateway uses systemd to manage services, so you can also use the standard systemctl command-line tool to manage or view service status, for example:

We release software updates on a regular basis, and it is recommended to always run the latest available version. This page shows the available updates, and administrators can run an upgrade by pressing the Upgrade button.

See section Package Repositories for details about the available package repositories.

The Syslog page gives you a quick real-time log view. You can use the Tracking Center to search the logs.

The Tasks page provides a history of the administration tasks that you carried out on the server, such as upgrading the system. Each task entry provides status information about the task, as well as the output.

This panel lets you inspect the mail quarantine. Emails can be safely previewed and if desired, delivered to the original user.

The email preview on the web interface is very secure, as malicious code (attacking your operating system or email client) is removed by Proxmox Mail Gateway.

Users can access their personalized quarantine via the daily spam report or by navigating to the URL configured for the quarantine (defaults to https://<pmg-host>:8006/quarantine) and logging in with their LDAP credentials (email address and password).

You can additionally enable user self-service for sending an access link from the Quarantine Login page. To enable this on the Quarantine Login page, edit /etc/pmg/pmg.conf. See section Spam Detector Configuration - Quarantine for more details about the available settings.

Allows administrators to inspect quarantined virus mails.

Allows administrators to inspect quarantined mails and download their attachments or deliver/delete them.

This is mostly useful to debug or verify white- and blacklist user settings. The administrator should not change these values because users can manage this themselves.

In the Deferred Mail tab, you can examine each deferred email separately. In addition to providing contact information about the sender and receiver, you can also check the reason for which an email remains queued.

You can view the complete headers and filter by sender or receiver of queued emails.

Here, you can also flush or delete each deferred email independently.

This section is suitable for all devices. Updated microcode, which is usually included in a BIOS/UEFI update, is stored on the motherboard, whereas other firmware is stored on the respective device. This persistent method is especially important for the CPU, as it enables the earliest possible regular loading of the updated microcode at boot time.

Please check with your vendor which update methods are available.

This method stores firmware on the Proxmox Mail Gateway operating system and will pass it to a device if its persisted firmware is less recent. It is supported by devices such as network and graphics cards, but not by those that rely on persisted firmware such as the motherboard and hard disks.

In Proxmox Mail Gateway the package pve-firmware is already installed by default. Therefore, with the normal system updates (APT), included firmware of common hardware is automatically kept up to date.

An additional Debian Firmware Repository exists, but is not configured by default.

If you try to install an additional firmware package but it conflicts, APT will abort the installation. Perhaps the particular firmware can be obtained in another way.

Microcode updates are intended to fix found security vulnerabilities and other serious CPU bugs. While the CPU performance can be affected, a patched microcode is usually still more performant than an unpatched microcode where the kernel itself has to do mitigations. Depending on the CPU type, it is possible that performance results of the flawed factory state can no longer be achieved without knowingly running the CPU in an unsafe state.

To get an overview of present CPU vulnerabilities and their mitigations, run lscpu. Current real-world known vulnerabilities can only show up if the Proxmox Mail Gateway host is up to date, its version not end of life, and has at least been rebooted since the last kernel update.

Besides the recommended microcode update via persistent BIOS/UEFI updates, there is also an independent method via Early OS Microcode Updates. It is convenient to use and also quite helpful when the motherboard vendor no longer provides BIOS/UEFI updates. Regardless of the method in use, a reboot is always needed to apply a microcode update.

The Proxmox Mail Gateway installer creates 3 partitions on all disks selected for installation.

The created partitions are:

Systems using ZFS as root filesystem are booted with a kernel and initrd image stored on the 512 MB EFI System Partition. For legacy BIOS systems, and EFI systems with Secure Boot enabled, GRUB is used, for EFI systems without Secure Boot, systemd-boot is used. Both are installed and configured to point to the ESPs.

GRUB in BIOS mode (--target i386-pc) is installed onto the BIOS Boot Partition of all selected disks on all systems booted with GRUB
[These are all installs with root on ext4 or xfs and installs with root on ZFS on non-EFI systems]
.

proxmox-boot-tool is a utility used to keep the contents of the EFI System Partitions properly configured and synchronized. It copies certain kernel versions to all ESPs and configures the respective bootloader to boot from the vfat formatted ESPs. In the context of ZFS as root filesystem this means that you can use all optional features on your root pool instead of the subset which is also present in the ZFS implementation in GRUB or having to create a separate small boot-pool
[Booting ZFS on root with GRUB https://github.com/zfsonlinux/zfs/wiki/Debian-Stretch-Root-on-ZFS]
.

In setups with redundancy all disks are partitioned with an ESP, by the installer. This ensures the system boots even if the first boot device fails or if the BIOS can only boot from a particular disk.

The ESPs are not kept mounted during regular operation. This helps to prevent filesystem corruption to the vfat formatted ESPs in case of a system crash, and removes the need to manually adapt /etc/fstab in case the primary boot device fails.

proxmox-boot-tool handles the following tasks:

You can view the currently configured ESPs and their state by running:

To format and initialize a partition as synced ESP, e.g., after replacing a failed vdev in an rpool, or when converting an existing system that pre-dates the sync mechanism, proxmox-boot-tool from proxmox-kernel-helper can be used.

For example, to format an empty partition /dev/sda2 as ESP, run the following:

To setup an existing, unmounted ESP located on /dev/sda2 for inclusion in Proxmox Mail Gateway’s kernel update synchronization mechanism, use the following:

or

to force initialization with GRUB instead of systemd-boot, for example for Secure Boot support.

Afterwards /etc/kernel/proxmox-boot-uuids should contain a new line with the UUID of the newly added partition. The init command will also automatically trigger a refresh of all configured ESPs.

To copy and configure all bootable kernels and keep all ESPs listed in /etc/kernel/proxmox-boot-uuids in sync you just need to run:

(The equivalent to running update-grub systems with ext4 or xfs on root).

This is necessary should you make changes to the kernel commandline, or want to sync all kernels and initrds.

The following kernel versions are configured by default:

Should you wish to add a certain kernel and initrd image to the list of bootable kernels use proxmox-boot-tool kernel add.

For example run the following to add the kernel with ABI version 5.0.15-1-pve to the list of kernels to keep installed and synced to all ESPs:

proxmox-boot-tool kernel list will list all kernel versions currently selected for booting:

Run proxmox-boot-tool kernel remove to remove a kernel from the list of manually selected kernels, for example:

The simplest and most reliable way to determine which bootloader is used, is to watch the boot process of the Proxmox Mail Gateway node.

You will either see the blue box of GRUB or the simple black on white systemd-boot.

Determining the bootloader from a running system might not be 100% accurate. The safest way is to run the following command:

If it returns a message that EFI variables are not supported, GRUB is used in BIOS/Legacy mode.

If the output contains a line that looks similar to the following, GRUB is used in UEFI mode.

If the output contains a line similar to the following, systemd-boot is used.

By running:

you can find out if proxmox-boot-tool is configured, which is a good indication of how the system is booted.

GRUB has been the de-facto standard for booting Linux systems for many years and is quite well documented
[GRUB Manual https://www.gnu.org/software/grub/manual/grub/grub.html]
.

systemd-boot is a lightweight EFI bootloader. It reads the kernel and initrd images directly from the EFI Service Partition (ESP) where it is installed. The main advantage of directly loading the kernel from the ESP is that it does not need to reimplement the drivers for accessing the storage. In Proxmox Mail Gateway proxmox-boot-tool is used to keep the configuration on the ESPs synchronized.

You can modify the kernel commandline in the following places, depending on the bootloader used:

The kernel commandline needs to be placed in the variable GRUB_CMDLINE_LINUX_DEFAULT in the file /etc/default/grub. Running update-grub appends its content to all linux entries in /boot/grub/grub.cfg.

The kernel commandline needs to be placed as one line in /etc/kernel/cmdline. To apply your changes, run proxmox-boot-tool refresh, which sets it as the option line for all config files in loader/entries/proxmox-*.conf.

A complete list of kernel parameters can be found at https://www.kernel.org/doc/html/v<YOUR-KERNEL-VERSION>/admin-guide/kernel-parameters.html. replace <YOUR-KERNEL-VERSION> with the major.minor version, for example, for kernels based on version 6.5 the URL would be: https://www.kernel.org/doc/html/v6.5/admin-guide/kernel-parameters.html

You can find your kernel version by checking the web interface (Node → Summary), or by running

Use the first two numbers at the front of the output.

To select a kernel that is not currently the default kernel, you can either:

This should help you work around incompatibilities between a newer kernel version and the hardware.

For example: To permanently select the version 5.15.30-1-pve for booting you would run:

You can also set a kernel version to be booted on the next system boot only. This is for example useful to test if an updated kernel has resolved an issue, which caused you to pin a version in the first place:

To remove any pinned version configuration use the unpin subcommand:

While unpin has a --next-boot option as well, it is used to clear a pinned version set with --next-boot. As that happens already automatically on boot, invonking it manually is of little use.

After setting, or clearing pinned versions you also need to synchronize the content and configuration on the ESPs by running the refresh subcommand.

Since Proxmox Mail Gateway 8.1, Secure Boot is supported out of the box via signed packages and integration in proxmox-boot-tool.

The following packages need to be installed for Secure Boot to be enabled:

Only GRUB as bootloader is supported out of the box, since there are no other pre-signed bootloader packages available. Any new installation of Proxmox Mail Gateway will automatically have all of the above packages included.

More details about how Secure Boot works, and how to customize the setup, are available in our wiki.

A Proxmox Backup Server remote can be configured using the Proxmox Backup Server panel in the Backup/Restore menu of the GUI, or by using the remote subcommand of pmgbackup.

The fingerprint is optional, if the certificate of the Proxmox Backup Server remote is signed by a CA trusted by Proxmox Mail Gateway.

Additionally, you can configure prune-settings for each remote, giving you flexible control over how many backups should be stored on the Proxmox Backup Server over a specific period of time.

If prune settings are configured, the backup-group of Proxmox Mail Gateway is pruned automatically after each successful backup.

The notify and include-statistics settings of a remote define the defaults for notifications and whether to include the statistic database in backups. They are also used for scheduled backups.

The public settings are stored in /etc/pmg/pbs/pbs.conf. Sensitive settings, like passwords are stored in individual files named after the remote inside /etc/pmg/pbs/:

With a configured remote, you can create backups using the GUI or the proxmox-backup backup subcommand of the pmgbackup CLI tool.

For restoring, you can optionally select a particular backup-snapshot to return to the state of configuration and rules at that time.

From the command line, you can get a list of available backup snapshots using the proxmox-backup list subcommand:

You can remove a particular snapshot by using the forget subcommand. This allows the Proxmox Backup Server to remove it during garbage collection.

Many people do not want to install two redundant mail proxies. Instead they use the mail proxy of their ISP as a fallback. This can be done by adding an additional MX record with a lower priority (higher number). Continuing from the example above, this would look like:

In such a setup, your provider must accept mails for your domain and forward them to you. Please note that this is not advisable, because spam detection needs to be done by the backup MX server as well, and external servers provided by ISPs usually don’t do this.

However, you will never lose mails with such a setup, because the sending Mail Transport Agent (MTA) will simply deliver the mail to the backup server (mail.provider.tld), if the primary server (mail.proxmox.com) is not available.

Using your ISP’s mail server is not always a good idea, because many ISPs do not use advanced spam prevention techniques, or do not filter spam at all. It is often better to run a second server yourself to avoid lower spam detection rates.

It’s quite simple to set up a high-performance, load-balanced mail cluster using MX records. You just need to define two MX records with the same priority. The rest of this section will provide a complete example.

First, you need to have at least two working Proxmox Mail Gateway servers (mail1.example.com and mail2.example.com), configured as a cluster (see section Cluster Administration below), with each having its own IP address. Let us assume the following DNS address records:

It is always a good idea to add reverse lookup entries (PTR records) for those hosts, as many email systems nowadays reject mails from hosts without valid PTR records. Then you need to define your MX records:

This is all you need. Following this, you will receive mail on both hosts, load-balanced using round-robin scheduling. If one host fails, the other one is used.

You can create a cluster from any existing Proxmox Mail Gateway host. All data is preserved.

The GUI shows the status of all cluster nodes. You can also view this using the command-line tool:

When you add a new node to a cluster (using join), all data on that node is destroyed. The whole database is initialized with the cluster data from the master.

You need to enter the root password of the master host, when asked for a password. When joining a cluster using the GUI, you also need to enter the fingerprint of the master node. You can get this information by pressing the Add button on the master node.

Also note that joining a cluster can take several minutes, because the new node needs to synchronize all data from the master (although this is done in the background).

Please detach nodes from the cluster network, before removing them from the cluster configuration. Only then you should run the following command on the master node:

Parameter <cid> is the unique cluster node ID, as listed with pmgcm status.

It is highly recommended to use redundant disks on all cluster nodes (RAID). So in almost any circumstance, you just need to replace the damaged hardware or disk. Proxmox Mail Gateway uses an asynchronous clustering algorithm, so you just need to reboot the repaired node, and everything will work again transparently.

The following scenarios only apply when you really lose the contents of the hard disk.

By default, pmgproxy uses the certificate /etc/pmg/pmg-api.pem for HTTPS connections. This certificate is self signed, and therefore not trusted by browsers and operating systems by default. You can simply replace this certificate with your own (include the key inside the .pem file) or obtain one from an ACME enabled CA (configurable in the GUI).

It is possible to configure “apache2”-like access control lists. Values are read from file /etc/default/pmgproxy. For example:

IP addresses can be specified using any syntax understood by Net::IP. The name all is an alias for 0/0 and ::/0 (meaning all IPv4 and IPv6 addresses).

The default policy is allow.

By default the pmgproxy daemon listens on the wildcard address and accepts connections from both IPv4 and IPv6 clients.

By setting LISTEN_IP in /etc/default/pmgproxy, you can control which IP address the pmgproxy daemon binds to. The IP-address needs to be configured on the system.

Setting the sysctl net.ipv6.bindv6only to the non-default 1 will cause the daemons to only accept connections from IPv6 clients, while usually also causing lots of other issues. If you set this configuration, we recommend either removing the sysctl setting, or setting the LISTEN_IP to 0.0.0.0 (which will allow only IPv4 clients).

LISTEN_IP can be used to restrict the socket to an internal interface, thus leaving less exposure to the public internet, for example:

Similarly, you can also set an IPv6 address:

Note that if you want to specify a link-local IPv6 address, you need to provide the interface name itself. For example:

To apply the change you need to either reboot your node or fully restart the pmgproxy service:

You can define the cipher list in /etc/default/pmgproxy, via the CIPHERS (TLS ⇐ 1.2) and CIPHERSUITES (TLS >= 1.3) keys.

For example:

The above is the default. See the ciphers(1) man page from the openssl package for a list of all available options.

The first of these ciphers that is available to both the client and pmgproxy will be used.

Additionally, you can allow the client to choose the cipher from the list above, by disabling the HONOR_CIPHER_ORDER option in /etc/default/pmgproxy:

The insecure SSL versions 2 and 3 are unconditionally disabled for pmgproxy. TLS versions below 1.1 are disabled by default on recent OpenSSL versions, which is honored by pmgproxy (see /etc/ssl/openssl.cnf).

To disable TLS version 1.2, set the following in /etc/default/pmgproxy:

or, respectively, to disable TLS version 1.3:

You can define the used Diffie-Hellman parameters in /etc/default/pmgproxy by setting DHPARAMS to the path of a file containing DH parameters in PEM format, for example:

If this option is not set, the built-in skip2048 parameters will be used.

By default pmgproxy uses gzip HTTP-level compression for compressible content, if the client supports it. This can be disabled in /etc/default/pmgproxy

The file is divided into several section. Each section has the following format:

Blank lines in the file separates sections, and lines starting with a # character are treated as comments and are also ignored.

The file is divided into several section. There is one master and several node sections.

Blank lines in the file separates sections, and lines starting with a # character are treated as comments and are also ignored.

The file has the following format for each user:

The file is divided into a section for each LDAP profile. Each section has the following format:

Blank lines in the file separates sections, and lines starting with a # character are treated as comments and are also ignored.