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).
Custom {spamassassin} setup.
+`/etc/mail/spamassassin/pmg-scores.cf`::
+
+Custom {spamassassin} rule scores.
Keys and Certificates
---------------------
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
-------------------------------
~~~~~~~~~~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-network-config.png[]
+[thumbnail="pmg-gui-network-config.png", big=1]
endif::manvolnum[]
Normally the network and time is already configured when you visit the
~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-system-options.png[]
+[thumbnail="pmg-gui-system-options.png", big=1]
endif::manvolnum[]
~~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-mailproxy-relaying.png[]
+[thumbnail="pmg-gui-mailproxy-relaying.png", big=1]
endif::manvolnum[]
Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
~~~~~~~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-mailproxy-relaydomains.png[]
+[thumbnail="pmg-gui-mailproxy-relaydomains.png", big=1]
endif::manvolnum[]
List of relayed mail domains, i.e. what destination domains this
~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-mailproxy-ports.png[]
+[thumbnail="pmg-gui-mailproxy-ports.png", big=1]
endif::manvolnum[]
Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-mailproxy-options.png[]
+[thumbnail="pmg-gui-mailproxy-options.png", big=1]
endif::manvolnum[]
Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
include::pmg.mail-options-conf-opts.adoc[]
+[[pmgconfig_mailproxy_before_after_queue]]
+Before and After Queue scanning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Scanning email can happen at two different stages of mail-processing:
+
+* During the SMTP Session after the complete message has been received (after
+ the 'DATA' command), known as 'before queue filtering'.
+
+* After intially accepting the mail and putting it on a queue for further
+ processing, known as 'after queue filtering'.
+
+The former 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 mailserver. 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 so-called
+'backscatter' mail, which might cause your server to get listed as spamming on
+RBLs.
+
+The latter has the advantage of providing faster delivery of mails for the
+sending servers, since queueing mails is much faster than analyzing it for
+spam and viruses.
+
+If a mail is addressed to multiple recipients (e.g. when multiple addresses are
+subscribed to the same mailinglist) the situation is more complicated: Your
+mailserver 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 it disabled prevents
+NDRs being sent to the (possibly forged) sender and thus minimizes the chance
+of getting your IP listed on a 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.
+
+NOTE: Since before queue filtering is currently incompatible with the
+'Tracking Center' you need to enable it by manually
+editing '/etc/pmg/pmg.conf'.
+
+
[[pmgconfig_mailproxy_transports]]
Transports
~~~~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-mailproxy-transports.png[]
+[thumbnail="pmg-gui-mailproxy-transports.png", big=1]
endif::manvolnum[]
You can use {pmg} to send e-mails to different internal
~~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-mailproxy-networks.png[]
+[thumbnail="pmg-gui-mailproxy-networks.png", big=1]
endif::manvolnum[]
You can add additional internal (trusted) IP networks or hosts.
~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-mailproxy-tls.png[]
+[thumbnail="pmg-gui-mailproxy-tls.png", big=1]
endif::manvolnum[]
Transport Layer Security (TLS) provides certificate-based
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 use by a system which sends e-mail 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 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 e-mails
+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.
+
+Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
+using the following configuration keys:
+
+include::pmg.admin-dkim-conf-opts.adoc[]
+
+
Whitelist
~~~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-mailproxy-whitelist.png[]
+[thumbnail="pmg-gui-mailproxy-whitelist.png", big=1]
endif::manvolnum[]
All SMTP checks are disabled for those entries (e. g. Greylisting,
~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-spam-options.png[]
+[thumbnail="pmg-gui-spam-options.png", big=1]
endif::manvolnum[]
{pmg} uses a wide variety of local and network tests to identify spam
~~~~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-spamquar-options.png[]
+[thumbnail="pmg-gui-spamquar-options.png", big=1]
endif::manvolnum[]
Proxmox analyses all incoming e-mail messages and decides for each
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 rules which 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 to not make large changes to the
+default scores.
+
+
[[pmgconfig_clamav]]
Virus Detector Configuration
----------------------------
~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-virus-options.png[]
+[thumbnail="pmg-gui-virus-options.png", big=1]
endif::manvolnum[]
All mails are automatically passed to the included virus detector
include::pmg.clamav-conf-opts.adoc[]
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-clamav-database.png[]
+[thumbnail="pmg-gui-clamav-database.png", big=1]
endif::manvolnum[]
Please note that the virus signature database it automatically
~~~~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-virusquar-options.png[]
+[thumbnail="pmg-gui-virusquar-options.png", big=1]
endif::manvolnum[]
Indentified virus mails are automatically moved to the virus
Custom SpamAssassin configuration
---------------------------------
-This is only for advanced users. To add or change the Proxmox
-{spamassassin} configuration please login to the console via SSH. Go
-to directory `/etc/mail/spamassassin/`. In this directory there are several
-files (`init.pre`, `local.cf`, ...) – do not change them.
-
-To add your special configuration, you have to create a new file and
-name it `custom.cf` (in this directory), then add your
-configuration there. Be aware to use the {spamassassin}
-syntax, and test with
+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 please login to the
+console via SSH. 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 special 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 with
----
# spamassassin -D --lint
----
If you run a cluster, the `custom.cf` file is synchronized from the
-master node to all cluster members.
+master node to all cluster members automatically.
+
+Should you only wish 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 e-mail 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 e-mail. 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 e-mail as
+ rfc822/eml file
+
+The expected output need to be printed on STDOUT and consists of two lines:
+
+* the 'api-version' (currently 'v1') - see above
+
+* one of the following 3 results:
+** 'OK' - e-mail is ok
+** 'VIRUS: <virusdescription>' - e-mail is treated as if it contained a virus
+ (the virusdescription is logged and added to the e-mail's headers)
+** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
+ to the e-mail's spamscore
+
+The check is run with a 5 minute timeout - if it is exceeded the check
+executable is killed and the e-mail is treated as OK.
+
+All output written to STDERR by the check is written with priority 'err' to the
+journal/mail.log.
+
+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
Local Users
~~~~~~~~~~~
-image::images/screenshot/pmg-gui-local-user-config.png[]
+[thumbnail="pmg-gui-local-user-config.png", big=1]
Local users are used to manage and audit {pmg}. Those users can login on the
management web interface.
LDAP/Active Directory
~~~~~~~~~~~~~~~~~~~~~
-image::images/screenshot/pmg-gui-ldap-user-config.png[]
+[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.
Fetchmail
~~~~~~~~~
-image::images/screenshot/pmg-gui-fetchmail-config.png[]
+[thumbnail="pmg-gui-fetchmail-config.png", big=1]
Fetchmail is utility for polling and forwarding e-mails. You can define
e-mail accounts, which will then be fetched and forwarded to the e-mail
projects / pmg-docs.git / blobdiff