From f05af51443742e14f0deaa384c843923bc9ee10a Mon Sep 17 00:00:00 2001 From: polarathene <5098581+polarathene@users.noreply.github.com> Date: Mon, 8 Jan 2024 13:19:14 +1300 Subject: [PATCH] docs: ENV - Additional revisions to SA ENV --- docs/content/config/environment.md | 45 ++++++++++++++++++++++-------- docs/content/faq.md | 11 -------- mailserver.env | 12 ++++---- 3 files changed, 40 insertions(+), 28 deletions(-) diff --git a/docs/content/config/environment.md b/docs/content/config/environment.md index 601a8802..07967a68 100644 --- a/docs/content/config/environment.md +++ b/docs/content/config/environment.md @@ -528,7 +528,7 @@ Changes the interval in which log files are rotated. ##### SPAMASSASSIN_SPAM_TO_INBOX - 0 => (_Amavis action: `D_BOUNCE`_): Spam messages will be bounced (_rejected_) without any notification (_dangerous_). -- **1** => (_Amavis action: `D_PASS`_): Spam messages will be delivered to the inbox and tagged as spam using [`SA_SPAM_SUBJECT`](#sa_spam_subject). +- **1** => (_Amavis action: `D_PASS`_): Spam messages will be delivered to the inbox. The Amavis action configured by this setting: @@ -539,6 +539,7 @@ This ENV setting is related to: - [`MOVE_SPAM_TO_JUNK=1`](#move_spam_to_junk) - [`MARK_SPAM_AS_READ=1`](#mark_spam_as_read) +- [`SA_SPAM_SUBJECT`](#sa_spam_subject) ##### ENABLE_SPAMASSASSIN_KAM @@ -549,19 +550,26 @@ This ENV setting is related to: ##### SA_TAG -- **2.0** => add spam info headers if at, or above this level +- **2.0** => add 'spam info' headers at, or above this level -Mail is not yet considered spam, but for purposes like diagnositcs it can be useful to identify mail from a lower bound spam score. +Mail is not yet considered spam, but for purposes like diagnositcs it can be useful to identify mail with a spam score from a lower bound than `SA_TAG2`. + +This appends the mail header `X-Spam-Level`, with the spam score value assigned. ##### SA_TAG2 - **6.31** => add 'spam detected' headers at, or above this level -Mail that is considered to be spam. With settings like [`MOVE_SPAM_TO_JUNK=1`](#move_spam_to_junk), the mail is delivered but to the recipient(s) junk folder. +When a spam score is high enough, mark mail as spam (_Appends the mail header: `X-Spam-Flag: YES`_). + +!!! info "Interaction with other ENV" + + - [`SA_SPAM_SUBJECT`](#sa_spam_subject) modifies the mail subject to better communicate spam mail to the user. + - [`MOVE_SPAM_TO_JUNK=1`](#move_spam_to_junk): The mail is still delivered, but to the recipient(s) junk folder instead. This feature reduces the usefulness of `SA_SPAM_SUBJECT`. ##### SA_KILL -- **10.0** => triggers action + quarantine +- **10.0** => quarantine + triggers action to handle spam Controls the spam score threshold for triggering an action on mail that has a high spam score. @@ -570,17 +578,23 @@ Controls the spam score threshold for triggering an action on mail that has a hi The value should be high enough to be represent confidence in mail as spam: - Too low: The action taken may prevent legitimate mail (ham) that was incorrectly detected as spam from being delivered successfully. - - Too high: Allows more spam through. + - Too high: Allows more spam to bypass the `SA_KILL` trigger (_how to treat mail with high confidence that it is actually spam_). + + Experiences from DMS users with these settings has been [collected here][gh-issue::sa-tunables-insights], along with [some direct configuration guides][gh-issue::sa-tunables-guides] (_under "Resources for references"_). + +[gh-issue::sa-tunables-insights]: https://github.com/docker-mailserver/docker-mailserver/pull/3058#issuecomment-1420268148 +[gh-issue::sa-tunables-guides]: https://github.com/docker-mailserver/docker-mailserver/pull/3058#issuecomment-1416547911 !!! info "Trigger action" DMS will configure Amavis with either of these actions based on the DMS [`SPAMASSASSIN_SPAM_TO_INBOX`](#spamassassin_spam_to_inbox) setting: - `D_PASS` (default): - - Accept mail and deliver it to the recipient(s), despite a high spam score. + - Accept mail and deliver it to the recipient(s), despite the high spam score. A copy is still stored in quarantine. + - This is a good default to start with until you are more confident in an `SA_KILL` threshold that won't accidentally discard / bounce legitimate mail users are expecting to arrive but is detected as spam. - `D_BOUNCE`: - Additionally sends a bounce notification (DSN). - - The [DSN is suppressed][amavis-docs::actions] (_no bounce sent_) when the spam score exceeds the Amavis `$sa_dsn_cutoff_level` config setting (default: `10`). + - The [DSN is suppressed][amavis-docs::actions] (_no bounce sent_) when the spam score exceeds the Amavis `$sa_dsn_cutoff_level` config setting (default: `10`). With the DMS `SA_KILL` default also being `10`, no DSN will ever be sent. - `D_REJECT` / `D_DISCARD`: - These two aren't configured by DMS, but are valid alternative action values if configuring Amavis directly. @@ -598,11 +612,20 @@ Controls the spam score threshold for triggering an action on mail that has a hi ##### SA_SPAM_SUBJECT -- **`***SPAM(_SCORE_)***`** => add tag to subject if spam detected +Adds a prefix to the subject header when mail is marked as spam (_via [`SA_TAG2`](#sa_tag2)_). -!!! tip +- **`'***SPAM*** '`** => A string value to use as a mail subject prefix. +- `undef` => Opt-out of modifying the subject for mail marked as spam. - Add the SpamAssassin score to the subject line by inserting the keyword `_SCORE_`: **`***SPAM(_SCORE_)***`**. +!!! tip "Including trailing white-space" + + Add trailing white-space by quote wrapping the value: `SA_SPAM_SUBJECT='[SPAM] '` + +!!! tip "Including the associated spam score" + + The [`_SCORE_` tag][sa-docs::score-tag] will be substituted with the SpamAssassin score: `SA_SPAM_SUBJECT=***SPAM(_SCORE_)***`. + +[sa-docs::score-tag]: https://spamassassin.apache.org/full/4.0.x/doc/Mail_SpamAssassin_Conf.html#rewrite_header-subject-from-to-STRING ##### SA_SHORTCIRCUIT_BAYES_SPAM diff --git a/docs/content/faq.md b/docs/content/faq.md index 5fbe1deb..f666b102 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -380,17 +380,6 @@ When you run DMS with the ENV variable `ONE_DIR=1` (default), this directory wil Anti-spam rules are managed in `docker-data/dms/config/spamassassin-rules.cf`. -#### What are acceptable `SA_SPAM_SUBJECT` values? - -For no subject set `SA_SPAM_SUBJECT=undef`. - -For a trailing white-space subject one can define the whole variable with quotes in `compose.yaml`: - -```yaml -environment: - - "SA_SPAM_SUBJECT=[SPAM] " -``` - #### Why are SpamAssassin `x-headers` not inserted into my `subdomain.example.com` subdomain emails? In the default setup, amavis only applies SpamAssassin x-headers into domains matching the template listed in the config file (`05-domain_id` in the amavis defaults). diff --git a/mailserver.env b/mailserver.env index e84157a2..c564bb7c 100644 --- a/mailserver.env +++ b/mailserver.env @@ -368,9 +368,6 @@ DOVECOT_INET_PROTOCOLS=all ENABLE_SPAMASSASSIN=0 -# deliver spam messages in the inbox (eventually tagged using SA_SPAM_SUBJECT) -SPAMASSASSIN_SPAM_TO_INBOX=1 - # KAM is a 3rd party SpamAssassin ruleset, provided by the McGrail Foundation. # If SpamAssassin is enabled, KAM can be used in addition to the default ruleset. # - **0** => KAM disabled @@ -379,23 +376,26 @@ SPAMASSASSIN_SPAM_TO_INBOX=1 # Note: only has an effect if `ENABLE_SPAMASSASSIN=1` ENABLE_SPAMASSASSIN_KAM=0 +# deliver spam messages in the inbox (tagged using SA_SPAM_SUBJECT) +SPAMASSASSIN_SPAM_TO_INBOX=1 + # spam messages will be moved in the Junk folder (SPAMASSASSIN_SPAM_TO_INBOX=1 required) MOVE_SPAM_TO_JUNK=1 # spam messages wil be marked as read MARK_SPAM_AS_READ=0 -# add spam info headers if at, or above that level: +# add 'spam info' headers at, or above this level SA_TAG=2.0 -# add 'spam detected' headers at that level +# add 'spam detected' headers at, or above this level SA_TAG2=6.31 # triggers spam evasive actions SA_KILL=10.0 # add tag to subject if spam detected -SA_SPAM_SUBJECT=***SPAM***** +SA_SPAM_SUBJECT='***SPAM*** ' # ----------------------------------------------- # --- Fetchmail Section -------------------------