[[chapter_pmgconfig]]
ifdef::manvolnum[]
pmgconfig(1)
============
:pmg-toplevel:

NAME
----

pmgconfig - Proxmox Mail Gateway Configuration Management Toolkit


SYNOPSIS
--------

include::generated/pmgconfig.1-synopsis.adoc[]


DESCRIPTION
-----------
endif::manvolnum[]
ifndef::manvolnum[]
Configuration Management
========================
:pmg-toplevel:
endif::manvolnum[]

{pmg} is usually configured using the web-based Graphical User Interface (GUI),
but it is also possible to directly edit the configuration files, using the
REST API over 'https' or the command-line tool `pmgsh`.

The command-line tool `pmgconfig` is used to simplify some common configuration
tasks, such as generating certificates and rewriting service configuration
files.

NOTE: We use a Postgres database to store mail filter rules and statistical
data. See chapter xref:chapter_pmgdb[Database Management] for more information.


Configuration files overview
----------------------------

`/etc/network/interfaces`::

Network setup. We never modify this file directly. Instead, we write
changes to `/etc/network/interfaces.new`. When you reboot, {pmg} renames
the file to `/etc/network/interfaces`, thus applying the changes.

`/etc/resolv.conf`::

DNS search domain and nameserver setup. {pmg} uses the search domain setting
to create the FQDN and domain name used in the postfix configuration.

`/etc/hostname`::

The system's hostname. {pmg} uses the hostname to create the FQDN used
in the postfix configuration.

`/etc/hosts`::

Static table lookup for hostnames.

`/etc/pmg/pmg.conf`::

Stores common administration options, such as the spam and mail proxy
configuration.

`/etc/pmg/cluster.conf`::

The cluster setup.

`/etc/pmg/domains`::

The list of relay domains.

`/etc/pmg/dkim/domains`::

The list of domains for outbound DKIM signing.

`/etc/pmg/fetchmailrc`::

Fetchmail configuration (POP3 and IMAP setup).

`/etc/pmg/ldap.conf`::

LDAP configuration.

`/etc/pmg/mynetworks`::

List of local (trusted) networks.

`/etc/pmg/subscription`::

Stores your subscription key and status.

`/etc/pmg/tls_policy`::

TLS policy for outbound connections.

`/etc/pmg/tls_inbound_domains`::

Sender domains for which TLS is enforced on inbound connections.

`/etc/pmg/transport`::

Message delivery transport setup.

`/etc/pmg/user.conf`::

GUI user configuration.

`/etc/pmg/realms.conf`::

Login realm configuration.

`/etc/mail/spamassassin/custom.cf`::

Custom {spamassassin} setup.

`/etc/mail/spamassassin/pmg-scores.cf`::

Custom {spamassassin} rule scores.

Keys and Certificates
---------------------

`/etc/pmg/pmg-api.pem`::

Key and certificate (combined) used by the HTTPS server (API).

`/etc/pmg/pmg-authkey.key`::

Private key used to generate authentication tickets.

`/etc/pmg/pmg-authkey.pub`::

Public key used to verify authentication tickets.

`/etc/pmg/pmg-csrf.key`::

Internally used to generate CSRF tokens.

`/etc/pmg/pmg-tls.pem`::

Key and certificate (combined) to encrypt mail traffic (TLS).

`/etc/pmg/dkim/<selector>.private`::

Key for DKIM signing mails with selector '<selector>'.


[[pmgconfig_template_engine]]
Service Configuration Templates
-------------------------------

{pmg} uses various services to implement mail filtering, for example,
the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
engine, and the Apache {spamassassin} project. These services use
separate configuration files, so we need to rewrite those files when the
configuration is changed.

{pmg} also features support for customizing the email-based reports and
notifications it can send to administrators and users. These can be adjusted in
the same way as configuration files. For some reports and notifications, both
HTML and plain-text variants exist, which will be sent together as multi-part
mail. These can be recognized by being suffixed using `.tt`, for the html part
for historic reasons or `.plain.tt`, for the plain-text part respectively, and
should be modified together if available to present a consistent experience to
users. Dropping either part to get a single-part mail can be done by creating
an empty file as override.

We use a template-based approach to generate these files. The {tts} is
a well known, fast and flexible template processing system. You can
find the default templates in `/var/lib/pmg/templates/`. Please do not
modify these directly, otherwise your modifications will be lost on the
next update. Instead, copy the template you wish to change to
`/etc/pmg/templates/`, then apply your changes there.

Templates can access any configuration settings, and you can use the
`pmgconfig dump` command to get a list of all variable names:

----
# pmgconfig dump
...
dns.domain = yourdomain.tld
dns.hostname = pmg
ipconfig.int_ip = 192.168.2.127
pmg.admin.advfilter = 1
...
----

The same tool is used to force the regeneration of all template-based
configuration files. You need to run the following after modifying a template,
or when you directly edit configuration files:

----
# pmgconfig sync --restart 1
----

The above command also restarts services if the underlying configuration
files are changed. Please note that this is automatically done when
you change the configuration using the GUI or API.

NOTE: Modified templates from `/etc/pmg/templates/` are automatically
synced from the master node to all cluster members.

[[pmgconfig_whitelist_overview]]
[[pmgconfig_welcomelist_overview]]
Welcome- and Blocklists
---------------------

{pmg} has multiple welcome- and blocklists. It differentiates between the
xref:pmgconfig_mailproxy_options[SMTP Welcomelist], the rule-based welcomelist
and the user welcomelist.
In addition to the welcomelists, there are two separate blocklists: the rule-based
blocklist and the user blocklist.

SMTP Welcomelist
~~~~~~~~~~~~~~

The xref:pmgconfig_mailproxy_welcomelist[SMTP Welcomelist] is responsible for disabling
greylisting, as well as SPF and DNSBL checks. These are done during the SMTP
dialogue.

Rule-based Welcome-/Blocklist
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The xref:chapter_mailfilter[rule-based welcome- and blocklists] 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 welcomelist rule and 'Block'
for the blocklist rule. In the default setup, the blocklist rule has priority
over the welcomelist rule and spam checks.

User Welcome-/Blocklist
~~~~~~~~~~~~~~~~~~~~~

The user welcome- and blocklist are user specific. Every user can add mail addresses
to their welcome- and blocklist. When a user adds a mail address to the welcomelist,
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 blocklist, 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).

[[pmgconfig_systemconfig]]
System Configuration
--------------------

Network and Time
~~~~~~~~~~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-network-config.png", big=1]
endif::manvolnum[]

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'.

.Example network setup '/etc/network/interfaces'
----
source /etc/network/interfaces.d/*

auto lo
iface lo inet loopback

auto ens18
iface ens18 inet static
	address  192.168.2.127
	netmask  255.255.240.0
	gateway  192.168.2.1
----

Overriding network device names
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When upgrading kernels, adding PCIe devices or updating your BIOS,
automatically generated network interface names can change. To alleviate
this issues, Proxmox Mail Gateway provides a tool for automatically
generating
https://www.freedesktop.org/software/systemd/man/latest/systemd.link.html[systemd
.link] files for overriding the name of network devices. It also
automatically replaces the occurrences of the old interface name in
`/etc/network/interfaces`.

NOTE: Pinning network interfaces in many container environments, including
Proxmox VE is not supported, as the container stack handles network
configuration.

The generated link files are stored in `/usr/local/lib/systemd/network`.
For the interfaces file a new file will be generated in the same place
with a `.new` suffix. This way you can inspect the changes made to the
configuration by using diff (or another diff viewer of your choice):

----
diff -y /etc/network/interfaces /etc/network/interfaces.new
----

If you see any problematic changes or want to revert the changes made by
the pinning tool *before rebooting*, simply delete all `.new` files and
the respective link files from `/usr/local/lib/systemd/network`.

The following command will generate a `.link` file for all physical
network interfaces that do not yet have a `.link` file and update
selected Proxmox VE configuration files (see above). The generated names
will use the default prefix `nic`, so the resulting interface names will
be `nic1`, `nic2`, ...

----
proxmox-network-interface-pinning generate
----

You can override the default prefix with the `--prefix` flag:

----
proxmox-network-interface-pinning generate --prefix myprefix
----

It is also possible to pin only a specific interface:

----
proxmox-network-interface-pinning generate --interface enp1s0
----

When pinning a specific interface, you can specify the exact name that
the interface should be pinned to:

----
proxmox-network-interface-pinning generate --interface enp1s0 --target-name if42
----

In order to apply the changes made by
`proxmox-network-interface-pinning` to the network configuration, the
host needs to be rebooted.

.DNS recommendations

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 Blackholelists. 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.

[[gui_consent_banner]]
.Consent Banner

A custom consent banner that has to be accepted before login can be configured
in __Configuration -> Options -> Consent Text__. If there is no content, the
consent banner will not be displayed. The text will be stored as a base64
string in the `admin` section of `/etc/pmg/pmg.conf`.

Options
~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-system-options.png", big=1]
endif::manvolnum[]


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

include::generated/pmg.admin-conf-opts.adoc[]


include::pmg-ssl-certificate.adoc[]

Mail Proxy Configuration
------------------------

[[pmgconfig_mailproxy_relaying]]
Relaying
~~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-mailproxy-relaying.png", big=1]
endif::manvolnum[]

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
https://www.postfix.org/postconf.5.html[postconf documentation]).

They use the following configuration keys:

include::generated/pmg.mail-relaying-conf-opts.adoc[]

[[pmgconfig_mailproxy_relay_domains]]
Relay Domains
~~~~~~~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-mailproxy-relaydomains.png", big=1]
endif::manvolnum[]

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.


[[pmgconfig_mailproxy_ports]]
Ports
~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-mailproxy-ports.png", big=1]
endif::manvolnum[]

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
https://www.postfix.org/postconf.5.html[postconf documentation]).

They use the following configuration keys:

include::generated/pmg.mail-ports-conf-opts.adoc[]


[[pmgconfig_mailproxy_options]]
Options
~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-mailproxy-options.png", big=1]
endif::manvolnum[]

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

include::generated/pmg.mail-options-conf-opts.adoc[]


[[pmgconfig_mailproxy_log_headers]]
Logging Mail Header Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For auditing and troubleshooting, you can enable the `log-headers` option in the
mail proxy settings. {pmg} then logs the envelope sender and recipient together
with the decoded `From`, `To`, and `Subject` headers of each processed mail to
the mail log, in addition to the queue and rule information that is always
logged.

NOTE: The logged headers can contain personal data, such as mail subjects and
sender or recipient addresses. Make sure that logging this information, and
keeping it in the system logs, is compatible with your data-protection
obligations before you enable this option. It is disabled by default.


[[pmgconfig_mailproxy_before_after_queue]]
Before and After Queue scanning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

* Before-queue filtering: During the SMTP session, after the complete message
  has been received (after the 'DATA' command).

* After-queue filtering: After initially accepting the mail and putting it on
  a queue for further 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 Welcome-
and Blocklist' feature.

If the resulting action of the rule system is the same for all recipients, {pmg}
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 {pmg} 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_beforequeue} and {postfix_afterqueue} respectively.


[[pmgconfig_mailproxy_greylisting]]
Greylisting
~~~~~~~~~~~

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, {pmg} 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 {pmg} 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 {pmg}
are:

* 2 days for the retry of the first delivery

* 36 days for a known triple

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.


[[pmgconfig_mailproxy_transports]]
Transports
~~~~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-mailproxy-transports.png", big=1]
endif::manvolnum[]

You can use {pmg} 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'.


[[pmgconfig_mailproxy_networks]]
Networks
~~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-mailproxy-networks.png", big=1]
endif::manvolnum[]

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

NOTE: Hosts in the same subnet as {pmg} can relay by default and don't need to
be added to this list.


[[pmgconfig_mailproxy_tls]]
TLS
~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-mailproxy-tls.png", big=1]
endif::manvolnum[]

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, {pmg} automatically
generates a new self signed certificate for you (`/etc/pmg/pmg-tls.pem`).

{pmg} 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 an encrypted SMTP session, otherwise they are
rejected. All domains on this list have an entry of
https://www.postfix.org/postconf.5.html#reject_plaintext_session[`reject_plaintext_session`]
in a `check_sender_access` table.

Enable TLS logging::

To get additional information about SMTP TLS activity, you can enable
TLS logging. In this case, information about TLS sessions and used
certificates is logged via syslog.

Add TLS received header::

Set this option to include information about the protocol and cipher
used, as well as the client and issuer CommonName into the "Received:"
message header.

TLS security profile::

The `modern` profile configures stricter inbound SMTP TLS defaults intended for
deployments aligned with current interoperable TLS guidance. It disables TLS protocol
versions below 1.2, uses the server cipher preference and limits TLS 1.2 cipher
suites to forward-secret AEAD suites.

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

include::generated/pmg.mail-tls-conf-opts.adoc[]


[[pmgconfig_mailproxy_dkim]]
DKIM Signing
~~~~~~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-mailproxy-dkim.png", big=1]
endif::manvolnum[]

DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) 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.

{pmg} 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 {pmg} 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.

Mails generated by {pmg} itself, like notifications and reports, usually have
an empty envelope. Thus they will only be signed if you have selected `header`
as the source of the signing domain and have set an RFC5322.From with a domain
that would be signed as a `From:` setting in the
xref:pmgconfig_spamdetector_quarantine[spam quarantine options] for spam reports
and quarantine links, and in the xref:pmgconfig_systemconfig[system options] for
other mails sent by {pmg}.

Enable DKIM Signing::

Controls whether outbound mail should get DKIM signed.

Selector::

The selector used for signing the mail. The private key used for signing is
saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT
record which you need to add to all domains signed by {pmg} by clicking on the
'View DNS Record' Button.

Sign all Outgoing Mail::

Controls whether all outbound mail should get signed or only mails from domains
listed in `/etc/pmg/dkim/domains`, if it exists and `/etc/pmg/domains`
otherwise.

Select Signing Domain::

Determines whether to DKIM sign emails using the domain found in the envelope
from or the from header of the email. The envelope from is also known as
reverse-path and RFC5321.MailFrom (see {rfc_5321} section 3.3).
The from header is also known as RFC5322.From (see {rfc_5322} section 3.6.2).
+
The envelope from of certain emails, bounces for example, can be empty. In these
cases it is desirable to sign them using the domain found in the from header.
+
Additionally, DMARC (see {dmarc_rfc} section 3.1.1) needs the domain found in
the from header in certain situations.

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

include::generated/pmg.admin-dkim-conf-opts.adoc[]

[[pmgconfig_mailproxy_broken_mime]]
Handling of Messages With Broken MIME Structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Messages with broken MIME structure and ambiguous content can be used to bypass
security checks. Therefore, they are rejected by {pmg} before being passed to
the rule system.

As some legitimate messages also have a broken MIME structure, you can
optionally allow broken messages to be accepted by the parser by enabling the
`accept-broken-mime` setting in the `mail` subsection in `/etc/pmg/pmg.conf`.

If enabled, a `X-Proxmox-Broken-Message` header is added to each suspicious
message. This header can be used in the rule system to selectively accept or
block such messages.


[[pmgconfig_mailproxy_whitelist]]
[[pmgconfig_mailproxy_welcomelist]]
Welcomelist
~~~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-mailproxy-welcomelist.png", big=1]
endif::manvolnum[]

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.

NOTE: If you use a backup MX server (for example, your ISP offers this service
for you) you should always add those servers here.

NOTE: To disable DNSBL checks entirely, remove any `DNSBL Sites` entries in
xref:pmgconfig_mailproxy_options[Mail Proxy Options].

[[pmgconfig_spamdetector]]
Spam Detector Configuration
---------------------------

Options
~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-spam-options.png", big=1]
endif::manvolnum[]

{pmg} 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.

include::generated/pmg.spam-conf-opts.adoc[]


[[pmgconfig_spamdetector_quarantine]]
Quarantine
~~~~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-spamquar-options.png", big=1]
endif::manvolnum[]

{pmg} 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.

include::generated/pmg.spamquar-conf-opts.adoc[]


[[pmgconfig_quarantine_listener]]
Dedicated Quarantine Listener
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By default `pmgproxy` serves the management API, the administration
interface and the user quarantine from the same listener on port 8006.
Making the quarantine reachable for users therefore also makes the
management API reachable on the same socket.

The `pmgquarantineproxy` service serves only the quarantine, on its own
port, so port 8006 can stay restricted to the internal network. It rejects
every request outside the quarantine API before authentication happens, so
even a valid quarantine ticket cannot reach node, configuration or access
management endpoints through it.

On this listener the bare host redirects to `/quarantine`, so users who only
remember the hostname still end up in the right place.

It is not enabled after installation. To use it:

* Set `listenport` (default 8007) and, if the public quarantine hostname
  differs from the management hostname, `listencert` in the `spamquar`
  section of `/etc/pmg/pmg.conf`. The certificate file holds both the
  certificate and its key.
* Restrict `pmgproxy` to the internal network with `LISTEN_IP` in
  `/etc/default/pmgproxy`.
* Optionally set `LISTEN_IP`, `ALLOW_FROM`, `DENY_FROM` and the cipher
  options in `/etc/default/pmgquarantineproxy`. These behave exactly as
  they do for `pmgproxy`.
* Enable and start the service:
+
----
systemctl enable --now pmgquarantineproxy
----

Set `port` as well when users reach the quarantine on a different port than
`listenport`, for example behind a reverse proxy or port forwarding. That
value is only used to build the links in the daily spam report. With
protocol `https` and port 443 no port is added to those links.


[[pmgconfig_spamdetector_customscores]]
Customization of Rulescores
~~~~~~~~~~~~~~~~~~~~~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-spam-custom-scores.png", big=1]
endif::manvolnum[]

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:

* Your system receives spam mails which are scored at 4.9 and you have
  a rule which puts all mails above 5 in the quarantine. The one thing the
  spam mails have in common is that they all hit 'URIBL_BLACK'. By increasing
  the score of this rule by 0.2 points the spam mails would all be quarantined
  instead of being sent to your users

* Your system tags many legitimate mails from a partner organization as spam,
  because the organization has a policy that each mail has to start with
  'Dear madam or sir' (generating 1.9 points through the rule
  'DEAR_SOMETHING'). By setting the score of this rule to 0, you can disable
  it completely.

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.

NOTE: In general, it is strongly recommended not to make large changes to the
default scores.


[[pmgconfig_clamav]]
Virus Detector Configuration
----------------------------

[[pmgconfig_clamav_options]]
Options
~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-virus-options.png", big=1]
endif::manvolnum[]

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:

include::generated/pmg.clamav-conf-opts.adoc[]

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-clamav-database.png", big=1]
endif::manvolnum[]

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.


[[pmgconfig_clamav_quarantine]]
Quarantine
~~~~~~~~~~

ifndef::manvolnum[]
[thumbnail="screenshot/pmg-gui-virusquar-options.png", big=1]
endif::manvolnum[]

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. {pmg} 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:

include::generated/pmg.virusquar-conf-opts.adoc[]


Custom SpamAssassin configuration
---------------------------------

This is only for advanced users. {spamassassin}'s rules and their associated
scores get updated regularly and are trained on a huge corpus, which gets
classified by experts. In most cases, adding a rule for matching a particular
keyword is the wrong approach, leading to many false positives. Usually bad
detection rates are better addressed by properly setting up DNS than by adding
a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or
spam-headers - see the {spamassassin_dnsbl}.

To add or change the Proxmox {spamassassin} configuration, log in to the
console via SSH and change to the `/etc/mail/spamassassin/` directory. In this
directory there are several files (`init.pre`, `local.cf`, ...) - do not change
them, as `init.pre`, `v310.pre`, `v320.pre`, `local.cf` will be overwritten by
the xref:pmgconfig_template_engine[template engine], while the others can
get updated by any {spamassassin} package upgrade.

To add your custom configuration, you have to create a new file named
`custom.cf` (in `/etc/mail/spamassassin/`), then add your configuration there.
Make sure to use the correct {spamassassin_rule_syntax} and test it with:

----
# spamassassin -D --lint
----

The change to the configuration will be picked up when `pmg-smtp-filter` gets
restarted. To directly have it enabled you need to restart manually, after
editing the custom configuration:

----
# systemctl restart pmg-smtp-filter.service
----

If you run a cluster, the `custom.cf` file is synchronized from the master node
to all cluster members and the relevant services are restarted automatically on
the cluster members.

To adjust the score assigned to a particular rule, you
can also use the xref:pmgconfig_spamdetector_customscores[Custom Rule Score]
settings in the GUI.


[[pmgconfig_custom_check]]
Custom Check Interface
----------------------

For use-cases which are not handled by the {pmg} Virus Detector and
{spamassassin} configuration, advanced users can create a custom check
executable which, if enabled will be called before the Virus Detector and before
passing an email through the Rule System. The custom check API is kept as
simple as possible, while still providing a great deal of control over the
treatment of an email. Its input is passed via two CLI arguments:

* the 'api-version' (currently `v1`) - for potential future change of the
  invocation

* the 'queue-file-name' - a filename, which contains the complete email as
  rfc822/eml file

The expected output needs to be printed to STDOUT and consists of two lines:

* the 'api-version' (currently 'v1') - see above

* one of the following 3 results:
** 'OK' - email is OK
** 'VIRUS: <virusdescription>' - email is treated as if it contained a virus
    (the virus description is logged and added to the email's headers)
** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
    to the email's spamscore

The check is run with a 5 minute timeout - if this is exceeded, the check
executable is killed and the email is treated as OK.

All output written to STDERR by the check is written with priority 'err' to the
journal/mail.log.

Below is a simple sample script following the API (and yielding a random result)
for reference:

----
#!/bin/sh

echo "called with $*" 1>&2

if [ "$#" -ne 2 ]; then
  echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2
  exit 1
fi

apiver="$1"
shift

if [ "$apiver" != "v1" ]; then
  echo "wrong APIVERSION: $apiver" 1>&2
  exit 2
fi

queue_file="$1"

echo "v1"

choice=$(shuf -i 0-3 -n1)

case "$choice" in
  0)
    echo OK
    ;;
  1)
    echo SCORE: 4
    ;;
  2)
    echo VIRUS: Random Virus
    ;;
  3) #timeout-test
    for i in $(seq 1 7); do
      echo "custom checking mail: $queue_file - minute $i" 1>&2
      sleep 60
    done
    ;;
esac

exit 0
----

The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf`

----
section: admin
    custom_check 1
----

The location of the custom check executable can also be set there with the key
`custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`.

NOTE: The custom check executable runs as the unprivileged
`pmg-smtp-filter` daemon user. It cannot elevate privileges with tools
like `sudo`, as the service runs with the systemd `NoNewPrivileges`
hardening enabled.


User Management
---------------

User management in {pmg} consists of three types of users/accounts:


[[pmgconfig_localuser]]
Local Users
~~~~~~~~~~~

[thumbnail="screenshot/pmg-gui-local-user-config.png", big=1]

Local users can manage and audit {pmg}. They can login on the management web
interface.

There are four roles:

Administrator::

Is allowed to manage settings of {pmg}, excluding some tasks like network
configuration and upgrading.

Quarantine manager::

Is allowed to manage quarantines, blocklists and welcomelists, but not other
settings. Has no right to view any other data.

Auditor::

With this role, the user is only allowed to view data and configuration, but
not to edit it.

Helpdesk::

Combines permissions of the 'Auditor' and the 'Quarantine Manager' role.

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.

NOTE: Only PAM users are able to log in via the web interface and ssh, while the
users created through the web interface are not. Those users are created for
{pmg} administration only.

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

For details on the fields, see xref:pmg_user_configuration_file[user.conf]

[[pmgconfig_ldap]]
LDAP/Active Directory
~~~~~~~~~~~~~~~~~~~~~

[thumbnail="screenshot/pmg-gui-ldap-user-config.png", big=1]

With {pmg}, users can use LDAP and Active directory as authentication methods to
access their individual xref:pmgadministration_spam_quarantine[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.

NOTE: Authentication via LDAP must first be enabled using the `Authentication
mode` (`authmode`) parameter in the
xref:pmgconfig_spamdetector_quarantine[Spam Detector's Quarantine configuration settings].

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:

* `Profile Name`:  The name assigned to the LDAP profile.
* `Protocol`:  LDAP, LDAPS, or LDAP+STARTTLS (LDAP+STARTTLS is recommended).
* `Server`: The domain name/IP address of the LDAP server. A fallback can also
    be configured using the second field.
* `User name`: The Bind DN for authentication on the LDAP server.
    This is required if your server does not support anonymous binds.
* `Password`: Password for the Bind DN user.
* `Base DN`: The directory which users are searched under.

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: xref:pmg_ldap_configuration_file[ldap.conf]

Bind user
^^^^^^^^^

It is highly recommended that the user which you use for connecting to the
LDAP server only has permission to query the server. For LDAP servers
(for example OpenLDAP or FreeIPA), the username has to be of a format like
'uid=username,cn=users,cn=accounts,dc=domain', where the specific fields
depend on your setup. For Active Directory servers, the format should be
'username@domain' or 'domain\username'.

Sync
^^^^

{pmg} synchronizes the relevant user and group information periodically, so that
the information is quickly available, even when the LDAP/AD server is
temporarily inaccessible.

You can actively trigger a synchronization with `pmgconfig`:

----
# pmgconfig ldapsync
----

After a successful sync, the groups and users should be visible on the web
interface. Following this, you can create rules targeting LDAP users and groups.

[[pmgconfig_fetchmail]]
Fetchmail
~~~~~~~~~

[thumbnail="screenshot/pmg-gui-fetchmail-config.png", big=1]

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:

include::generated/fetchmail.conf.5-opts.adoc[]

[[user_tfa_auth]]
Two-Factor Authentication
-------------------------

Users of the admin interface can configure two-factor authentication to
increase protection of their accounts.

NOTE: Joining a cluster with two-factor authentication enabled for the `root`
user is not supported. Remove the second factor when joining the cluster.

Available Second Factors
~~~~~~~~~~~~~~~~~~~~~~~~

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:

* User configured TOTP
  (https://en.wikipedia.org/wiki/Time-based_One-Time_Password[Time-based One-Time Password]).
  A short code derived from a shared secret and the current time, it changes
  every 30 seconds.
* WebAuthn (https://en.wikipedia.org/wiki/WebAuthn[Web Authentication]).
  A general standard for authentication. It is implemented by various security
  devices, like hardware keys or trusted platform modules (TPM) from a computer
  or smart phone.
* Single use Recovery Keys. A list of keys which should either be
  printed out and locked in a secure place or saved digitally in an electronic
  vault. Each key can be used only once. These are perfect for ensuring that
  you are not locked out, even if all of your other second factors are lost or
  corrupt.

Configuration of Two-Factor
~~~~~~~~~~~~~~~~~~~~~~~~~~~

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'.

//[thumbnail="screenshot/gui-datacenter-two-factor.png"]//TODO

[[user_tfa_setup_totp]]
=== TOTP

//[thumbnail="screenshot/pve-gui-tfa-add-totp.png"]//TODO

There is no server setup required. Simply install a TOTP app on your
smartphone (for example, https://github.com/andOTP/andOTP#downloads[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.


[[user_tfa_setup_webauthn]]
=== WebAuthn

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

* A trusted HTTPS certificate (for example, by using
  xref:sysadmin_certs_get_trusted_acme_cert[Let's Encrypt]).
  While it probably works with an untrusted certificate, some browsers may
  warn or refuse WebAuthn operations if it is not trusted.
* Setup the WebAuthn configuration (see *User Management -> Two Factor ->
  WebAuthn* in the {pmg} web interface). This can be
  auto-filled in most setups.

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

[[user_tfa_setup_recovery_keys]]
=== Recovery Keys

//[thumbnail="screenshot/pve-gui-tfa-add-recovery-keys.png"]//TODO

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*.

NOTE: There can only be one set of single-use recovery keys per user at any
time.

WebAuthn Configuration
~~~~~~~~~~~~~~~~~~~~~~

//[thumbnail="screenshot/gui-datacenter-webauthn-edit.png"]//TODO

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

NOTE: Changing the 'WebAuthn' configuration may render all existing 'WebAuthn'
registrations unusable!

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.


[[user_authentication_realms]]
Authentication Realms
---------------------

As {pmg} users are just counterparts for users existing on some external
realm, the realms have to be configured in `/etc/pmg/realms.conf`.
The following realms (authentication methods) are available:

Linux PAM Standard Authentication::

Linux PAM is a framework for system-wide user authentication. These users are
created on the host system with commands such as `adduser`.

{pmg} Authentication Server::

This is a Unix-like password store, which stores hashed passwords directly in
`/etc/pmg/user.conf`. Passwords are hashed using the SHA-256 hashing
algorithm. This is the most convenient realm for small-scale (or even
mid-scale) installations, where users do not need access to anything outside of
{pmg}. In this case, users are fully managed by {pmg} and are able to change
their own passwords via the GUI.

OpenID Connect::

OpenID Connect is implemented as an identity layer on top of the Oauth 2.0
protocol. It allows clients to verify the identity of the user, based on
authentication performed by an external authorization server.

[[user-realms-pam]]
Linux PAM Standard Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As Linux PAM corresponds to host system users, a system user must exist on each
node which the user is allowed to log in on. The user authenticates with their
usual system password. This realm is added by default and can't be removed. In
{pmg} this realm is restricted to the `root` user.


[[user-realms-pmg]]
{pmg} Authentication Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The {pmg} authentication server realm is a simple Unix-like password store.
The realm is created by default.

Unlike the other {pmg} realm types, users are created and authenticated entirely
through {pmg}, rather than authenticating against another system. Hence, you are
required to set a password for this type of user upon creation.


[[user_oidc]]
OpenID Connect
~~~~~~~~~~~~~~

The main OpenID Connect configuration options are:

* `Issuer URL` (`issuer-url`): This is the URL of the authorization server.
{pmg} uses the OpenID Connect Discovery protocol to automatically configure
further details.
+
While it is possible to use unencrypted `http://` URLs, we strongly recommend to
use encrypted `https://` connections.

* `Realm` (`realm`): The realm identifier for {pmg} users

* `Client ID` (`client-id`):  OpenID Client ID.

* `Client Key` (`client-key`): Optional OpenID Client Key.

* `Autocreate Users` (`autocreate`): Automatically create users if they do not
exist. While authentication is done at the OpenID server, all users still need
an entry in the {pmg} user configuration. You can either add them manually, or
use the `autocreate` option to automatically add new users.

* `Autocreate Users with Assigned Role` (`autocreate-role-assignment`): By
default, all autocreated users will be assigned the Audit role. You can either
assign a fixed xref:pmgconfig_localuser[role] to all autocreated users (for
example, `source=fixed,fixed-role=helpdesk`), or set a custom claim that is used
to assign users to different roles (for example,
`source=from-claim,role-claim=custom_role_claim`).

* `Username Claim` (`username-claim`): OpenID claim used to generate the unique
username (`sub` or `preferred_username`).

Username mapping
^^^^^^^^^^^^^^^^

The OpenID Connect specification defines a single unique attribute
('claim' in OpenID terms) named `sub` (Subject). By default, we use the
value of this attribute to generate {pmg} usernames, by simply adding
`@` and the realm name: `${subject}@${realm}`.

Unfortunately, most OpenID servers use random strings for `sub` (Subject), like
`DGH76OKH34BNG3245SB`, so a typical username would look like
`DGH76OKH34BNG3245SB@yourrealm`. While unique, it is difficult for
humans to remember such random strings, making it quite impossible to
associate real users with this.

The `username-claim` setting allows you to use other attributes for
the username mapping. Setting it to `preferred_username` is preferred if the
OpenID Connect server provides that attribute and guarantees its
uniqueness.

As {pmg} currently forbids `@` in usernames the option to use `email` is not
possible.

Examples
^^^^^^^^

Here is an example of creating an OpenID realm using Google. You need to
replace `--client-id` and `--client-key` with the values
from your Google OpenID settings.

----
pmgsh create /access/auth-realm --realm myrealm1 --type oidc --issuer-url  https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim username
----

The above command uses `--username-claim username`, so that the usernames on the
{pmg} side look like `example.user@myrealm1`.

Keycloak (https://www.keycloak.org/) is a popular open source Identity
and Access Management tool, which supports OpenID Connect. In the following
example, you need to replace the `--issuer-url` and `--client-id` with
your information:

----
pmgsh create /access/auth-realm --realm  myrealm2 --type oidc --issuer-url  https://your.server:8080/realms/your-realm --client-id XXX --username-claim username
----

WARNING: You need to ensure that the user is not allowed to edit
the username setting themselves (on the Keycloak server).

ifdef::manvolnum[]
include::pmg-copyright.adoc[]
endif::manvolnum[]
