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

[Stoiko Ivanov]

Thanks!
LGTM

Reviewed-By: Stoiko Ivanov <s.ivanov at proxmox.com>

On Thu, 28 May 2020 16:26:54 +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 at which level and how they work.
> 
> Signed-off-by: Mira Limbeck <m.limbeck at proxmox.com>
> ---
> v2:
>  - incorporated stoiko's suggestions
>  - fixed the ifndef/ifdef for the manpage
> 
>  pmgconfig.adoc | 47 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 47 insertions(+)
> 
> diff --git a/pmgconfig.adoc b/pmgconfig.adoc
> index 62944c3..9aab393 100644
> --- a/pmgconfig.adoc
> +++ b/pmgconfig.adoc
> @@ -186,6 +186,53 @@ 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 2 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 
> +ifndef::manvolnum[]
> +xref:chapter_mailfilter[rule-based white- and blacklists]
> +endif::manvolnum[]
> +ifdef::manvolnum[]
> +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 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 the mail being accepted, but it still depends on the other rules what
> +happens next. 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.
> +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