a well known, fast and flexible template processing system. You can
find the default templates in `/var/lib/pmg/templates/`. Please do not
modify them directly, because your modification would get lost on the
-next update. Instead, copy them to `/etc/pmg/templates/`, then apply
-your changes there.
+next update. Instead, copy the template you wish to change to
+`/etc/pmg/templates/`, then apply your changes there.
Templates can access any configuration setting, and you can use the
`pmgconfig dump` command to get a list of all variable names:
# pmgconfig sync --restart 1
----
-Above commands also restarts services if underlying configuration
+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.
include::pmg.mail-tls-conf-opts.adoc[]
+[[pmgconfig_mailproxy_dkim]]
+DKIM Signing
+~~~~~~~~~~~~
+
+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
~~~~~~~~~
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/spamassasin/`. In this directory there are several
-files (`init.pre`, `local.cf`, ...) – do not change them.
+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. 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
+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
----
# spamassassin -D --lint
master node to all cluster members.
+[[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
---------------