mirror of
https://git.proxmox.com/git/pmg-docs
synced 2025-08-02 23:27:48 +00:00

this fixes wording, spelling, grammar, etc. for the chapter 'configuration management' Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
967 lines
30 KiB
Plaintext
967 lines
30 KiB
Plaintext
[[chapter_pmgconfig]]
|
|
ifdef::manvolnum[]
|
|
pmgconfig(1)
|
|
============
|
|
:pmg-toplevel:
|
|
|
|
NAME
|
|
----
|
|
|
|
pmgconfig - Proxmox Mail Gateway Configuration Management Toolkit
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
|
|
include::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/transports`::
|
|
|
|
Message delivery transport setup.
|
|
|
|
`/etc/pmg/user.conf`::
|
|
|
|
GUI user 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.
|
|
|
|
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]]
|
|
White- and Blacklists
|
|
---------------------
|
|
|
|
{pmg} has multiple white- and blacklists. It differentiates between the
|
|
xref:pmgconfig_mailproxy_options[SMTP Whitelist], the rule-based whitelist
|
|
and the user whitelist.
|
|
In addition to the whitelists, there are two separate blacklists: the rule-based
|
|
blacklist and the user blacklist.
|
|
|
|
SMTP Whitelist
|
|
~~~~~~~~~~~~~~
|
|
|
|
The xref:pmgconfig_mailproxy_options[SMTP Whitelist] is responsible for disabling
|
|
greylisting, as well as SPF and DNSBL checks. These are done during the SMTP
|
|
dialogue.
|
|
|
|
Rule-based White-/Blacklist
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The xref:chapter_mailfilter[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.
|
|
|
|
User White-/Blacklist
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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).
|
|
|
|
[[pmgconfig_systemconfig]]
|
|
System Configuration
|
|
--------------------
|
|
|
|
Network and Time
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
ifndef::manvolnum[]
|
|
[thumbnail="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
|
|
----
|
|
|
|
.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 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.
|
|
|
|
|
|
Options
|
|
~~~~~~~
|
|
|
|
ifndef::manvolnum[]
|
|
[thumbnail="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::pmg.admin-conf-opts.adoc[]
|
|
|
|
|
|
include::pmg-ssl-certificate.adoc[]
|
|
|
|
Mail Proxy Configuration
|
|
------------------------
|
|
|
|
[[pmgconfig_mailproxy_relaying]]
|
|
Relaying
|
|
~~~~~~~~
|
|
|
|
ifndef::manvolnum[]
|
|
[thumbnail="pmg-gui-mailproxy-relaying.png", big=1]
|
|
endif::manvolnum[]
|
|
|
|
These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
|
|
using the following configuration keys:
|
|
|
|
include::pmg.mail-relaying-conf-opts.adoc[]
|
|
|
|
[[pmgconfig_mailproxy_relay_domains]]
|
|
Relay Domains
|
|
~~~~~~~~~~~~~
|
|
|
|
ifndef::manvolnum[]
|
|
[thumbnail="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="pmg-gui-mailproxy-ports.png", big=1]
|
|
endif::manvolnum[]
|
|
|
|
These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
|
|
using the following configuration keys:
|
|
|
|
include::pmg.mail-ports-conf-opts.adoc[]
|
|
|
|
|
|
[[pmgconfig_mailproxy_options]]
|
|
Options
|
|
~~~~~~~
|
|
|
|
ifndef::manvolnum[]
|
|
[thumbnail="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::pmg.mail-options-conf-opts.adoc[]
|
|
|
|
|
|
[[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 White-
|
|
and Blacklist' 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="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="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="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.
|
|
|
|
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.
|
|
|
|
Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
|
|
using the following configuration keys:
|
|
|
|
include::pmg.mail-tls-conf-opts.adoc[]
|
|
|
|
|
|
[[pmgconfig_mailproxy_dkim]]
|
|
DKIM Signing
|
|
~~~~~~~~~~~~
|
|
|
|
ifndef::manvolnum[]
|
|
[thumbnail="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.
|
|
|
|
|
|
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.
|
|
|
|
These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
|
|
using the following configuration keys:
|
|
|
|
include::pmg.admin-dkim-conf-opts.adoc[]
|
|
|
|
|
|
Whitelist
|
|
~~~~~~~~~
|
|
|
|
ifndef::manvolnum[]
|
|
[thumbnail="pmg-gui-mailproxy-whitelist.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="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::pmg.spam-conf-opts.adoc[]
|
|
|
|
|
|
[[pmgconfig_spamdetector_quarantine]]
|
|
Quarantine
|
|
~~~~~~~~~~
|
|
|
|
ifndef::manvolnum[]
|
|
[thumbnail="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::pmg.spamquar-conf-opts.adoc[]
|
|
|
|
|
|
[[pmgconfig_spamdetector_customscores]]
|
|
Customization of Rulescores
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
ifndef::manvolnum[]
|
|
[thumbnail="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.
|
|
|
|
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="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::pmg.clamav-conf-opts.adoc[]
|
|
|
|
ifndef::manvolnum[]
|
|
[thumbnail="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="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::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 and name it
|
|
`custom.cf` (in this directory), then add your configuration there. Make sure
|
|
to use the correct {spamassassin} syntax, and test it with:
|
|
|
|
----
|
|
# spamassassin -D --lint
|
|
----
|
|
|
|
If you run a cluster, the `custom.cf` file is synchronized from the
|
|
master node to all cluster members automatically.
|
|
|
|
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`.
|
|
|
|
|
|
User Management
|
|
---------------
|
|
|
|
User management in {pmg} consists of three types of users/accounts:
|
|
|
|
|
|
[[pmgconfig_localuser]]
|
|
Local Users
|
|
~~~~~~~~~~~
|
|
|
|
[thumbnail="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, blacklists and whitelists, 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="pmg-gui-ldap-user-config.png", big=1]
|
|
|
|
You can specify multiple LDAP/Active Directory profiles, so that you can
|
|
create rules matching those users and groups.
|
|
|
|
Creating a profile requires (at least) the following:
|
|
|
|
* profile name
|
|
* protocol (LDAP or LDAPS; LDAPS is recommended)
|
|
* at least one server
|
|
* a username and password (if your server does not support anonymous binds)
|
|
|
|
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 for 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
|
|
like '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.
|
|
|
|
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="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::fetchmail.conf.5-opts.adoc[]
|
|
|
|
|
|
ifdef::manvolnum[]
|
|
include::pmg-copyright.adoc[]
|
|
endif::manvolnum[]
|
|
|