[pmg-devel] [RFC pmg-docs 2/2] add white- and blacklist clarification

[Stoiko Ivanov]

Thanks big-time for this addition to our documentation - much appreciated!

LGTM - a few stylistic suggestions (as in am not sure if it makes sense to
use them - so feel free to disregard them) inline...

On Wed, 27 May 2020 17:42:17 +0200
Mira Limbeck <m.limbeck at proxmox.com> wrote:

> The difference between the 3 whitelists and 2 blacklists is not
> explained anywhere in the docs and leads to confusion all the time.
> To improve this situation add an overview over the different white- and
> blacklists explaining how they work and at which level.
> 
> Signed-off-by: Mira Limbeck <m.limbeck at proxmox.com>
> ---
> The location of this new section is based on the comment from:
> https://pve.proxmox.com/pipermail/pmg-devel/2019-November/000778.html
> 
>  pmgconfig.adoc | 43 +++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 43 insertions(+)
> 
> diff --git a/pmgconfig.adoc b/pmgconfig.adoc
> index 62944c3..919fa8c 100644
> --- a/pmgconfig.adoc
> +++ b/pmgconfig.adoc
> @@ -186,6 +186,49 @@ 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], which is responsible for
> +avoiding greylisting, SPF and DNSBL checks. The rule based whitelist and the
s/avoiding/skipping/ 
also maybe explicitly mention 'during the SMTP dialogue' here - since
SpamAssassin does SPF, an blacklist checks as well (but uses them to score
the mail instead of discarding it)

maybe rephrase 'rule based whitelist' as 'the Whitelist Who Object in the
rule system) (same for rule based blacklist)
> +user whitelist.
> +In addition to the whitelists there are 2 separate blacklists. The rule based
> +one 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.
as above maybe again explicitly write 'during SMTP dialogue'
> +
> +Rule-based White-/Blacklist
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The 
> +ifndef::manvolnum[]
> +xref:chapter_mailfilter[rule-based white- and blacklists]
> +endif::manvolnum[]
> +are predefined rules. They work by checking the attached 'Who' objects
> +containing e.g. 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 and
> +'Block' for the blacklist. In the default setup the blacklist has priority
> +over the whitelist and spam checks.
maybe: s/blacklist/blacklisting rule/ (same for whitelist)
> +
> +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 spam score will be disabled. This can help the mail being accepted, but it
s/the spam score will be disabled/the result of the spam analysis will be
discarded for that recipient/
> +still depends on the other rules what happens next. By default it will be accepted
> +as it is not recognized as spam and quarantined (spam score of 3 or higher).
maybe replace the last sentence by:
In the default ruleset this results in the mail being accepted for this
recpient.
> +
> +For mail addresses on a user's blacklist the spam score will be increased by 100.
> +It still depends on the rule system what happens when a spam score that high is
> +encountered. In the default setup it will be recognized as spam and quarantined
> +(spam score of 3 or higher).
>  
>  [[pmgconfig_systemconfig]]
>  System Configuration