[pmg-devel] [PATCH pmg-docs] Expand the docs for custom SA configuration

[Stoiko Ivanov]

Users regularly ask how to classify mails containing some keywords as spam.
Given that this usually indicates a misconfiguration in their DNS-Setup, and
the changes lead to more false positives than actually catching more spam
we should address this more explictly in the documentation.

Signed-off-by: Stoiko Ivanov <s.ivanov at proxmox.com>
---
 asciidoc/asciidoc-pmg.conf |  1 +
 pmgconfig.adoc             | 24 +++++++++++++++---------
 2 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/asciidoc/asciidoc-pmg.conf b/asciidoc/asciidoc-pmg.conf
index 46838c0..2939e3b 100644
--- a/asciidoc/asciidoc-pmg.conf
+++ b/asciidoc/asciidoc-pmg.conf
@@ -10,6 +10,7 @@ forum=https://forum.proxmox.com/[Proxmox Community Forum]
 manmanual=Proxmox Mail Gateway Documentation
 max-width=55em
 spamassassin=https://spamassassin.apache.org[SpamAssassin(TM)]
+spamassassin_dnsbl=https://cwiki.apache.org/confluence/display/SPAMASSASSIN/DnsBlocklists[SpamAssassin DNSBL documentation]
 postfix=http://www.postfix.org[Postfix]
 postfix_tls_readme=http://www.postfix.org/TLS_README.html[Postfix TLS Readme]
 systemd=https://www.freedesktop.org/wiki/Software/systemd/[systemd]
diff --git a/pmgconfig.adoc b/pmgconfig.adoc
index 2ac8a84..5df47eb 100644
--- a/pmgconfig.adoc
+++ b/pmgconfig.adoc
@@ -529,15 +529,21 @@ include::pmg.virusquar-conf-opts.adoc[]
 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. 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
 
 ----
 # spamassassin -D --lint
-- 
2.20.1