Apply suggestions from code review

Co-authored-by: Casper <casperklein@users.noreply.github.com>

.gitattributes

@@ -20,9 +20,8 @@
 
 ## BUILD:
 .dockerignore       text
-Dockerfile          text
+Dockerfile          text eol=lf
 Makefile
-VERSION
 
 ## EXAMPLE (RUNTIME):
 *.env               text
@@ -75,8 +74,8 @@ target/postsrsd/**  text
 #################################################
 
 ## BATS
-*.bash              text
-*.bats              text
+*.bash              text eol=lf
+*.bats              text eol=lf
 
 ## CONFIG (test/config/)
 ### OpenLDAP image

CHANGELOG.md

@@ -13,6 +13,14 @@ All notable changes to this project will be documented in this file. The format
   - Postfix is now configured with `smtputf8_enable = no` in our default `main.cf` config (_instead of during container startup_). ([#3750](https://github.com/docker-mailserver/docker-mailserver/pull/3750))
 - **Rspamd** ([#3726](https://github.com/docker-mailserver/docker-mailserver/pull/3726)):
   - symbol scores for SPF, DKIM & DMARC were updated to more closely align with [RFC7489](https://www.rfc-editor.org/rfc/rfc7489#page-24); please note though that complete alignment is undesirable, because other symbols might be added as well, which changes the overall score calculation again, see [this issue](https://github.com/docker-mailserver/docker-mailserver/issues/3690#issuecomment-1866871996)
+- **Docs:**
+  - Revised the SpamAssassin ENV docs to better communicate configuration and their relation to other ENV settings. ([#3756](https://github.com/docker-mailserver/docker-mailserver/pull/3756))
+
+
+### Fixes
+
+- **Internal:**
+  - `.gitattributes`: Always use LF line endings on checkout for files with shell script content ([#3755](https://github.com/docker-mailserver/docker-mailserver/pull/3755))
 
 ## [v13.2.0](https://github.com/docker-mailserver/docker-mailserver/releases/tag/v13.2.0)
 

Dockerfile

@@ -319,7 +319,7 @@ LABEL org.opencontainers.image.title="docker-mailserver"
 LABEL org.opencontainers.image.vendor="The Docker Mailserver Organization"
 LABEL org.opencontainers.image.authors="The Docker Mailserver Organization on GitHub"
 LABEL org.opencontainers.image.licenses="MIT"
-LABEL org.opencontainers.image.description="A fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.). Only configuration files, no SQL database."
+LABEL org.opencontainers.image.description="A fullstack but simple mail server (SMTP, IMAP, LDAP, Anti-spam, Anti-virus, etc.). Only configuration files, no SQL database."
 LABEL org.opencontainers.image.url="https://github.com/docker-mailserver"
 LABEL org.opencontainers.image.documentation="https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md"
 LABEL org.opencontainers.image.source="https://github.com/docker-mailserver/docker-mailserver"

README.md

@@ -11,7 +11,7 @@
 
 ## :page_with_curl: About
 
-A production-ready fullstack but simple containerized mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.). Only configuration files, no SQL database. Keep it simple and versioned. Easy to deploy and upgrade. Originally created by @tomav, this project is now maintained by volunteers since January 2021.
+A production-ready fullstack but simple containerized mail server (SMTP, IMAP, LDAP, Anti-spam, Anti-virus, etc.). Only configuration files, no SQL database. Keep it simple and versioned. Easy to deploy and upgrade. Originally created by @tomav, this project is now maintained by volunteers since January 2021.
 
 ## :bulb: Documentation
 

docs/content/config/advanced/optional-config.md

@@ -33,7 +33,7 @@ This is a list of all configuration files and directories which are optional or
 - **ldap-aliases.cf:** Configuration for the virtual alias mapping `virtual_alias_maps`. See the [`setup-stack.sh`][github-commit-setup-stack.sh-L411] script.
 - **ldap-domains.cf:** Configuration for the virtual domain mapping `virtual_mailbox_domains`. See the [`setup-stack.sh`][github-commit-setup-stack.sh-L411] script.
 - **whitelist_clients.local:** Whitelisted domains, not considered by postgrey. Enter one host or domain per line.
-- **spamassassin-rules.cf:** Antispam rules for Spamassassin. (Docs: [FAQ - SpamAssassin Rules][docs-faq-spamrules])
+- **spamassassin-rules.cf:** Anti-spam rules for Spamassassin. (Docs: [FAQ - SpamAssassin Rules][docs-faq-spamrules])
 - **fail2ban-fail2ban.cf:** Additional config options for `fail2ban.cf`. (Docs: [Fail2Ban][docs-fail2ban])
 - **fail2ban-jail.cf:** Additional config options for fail2ban's jail behaviour. (Docs: [Fail2Ban][docs-fail2ban])
 - **amavis.cf:** replaces the `/etc/amavis/conf.d/50-user` file

docs/content/config/environment.md

@@ -519,27 +519,14 @@ Changes the interval in which log files are rotated.
 - **0** => SpamAssassin is disabled
 - 1 => SpamAssassin is enabled
 
-!!! info "SpamAssassin analyzes incoming mail and assigns a spam score"
+??? info "SpamAssassin analyzes incoming mail and assigns a spam score"
 
-    Integration with Amavis involves processing mail based on the assigned spam score via [`SA_TAG`, `SA_TAG2` and `SA_KILL`][amavis-docs::spam-score]. These settings have equivalent ENV supported by DMS for easy adjustments.
+    Integration with Amavis involves processing mail based on the assigned spam score via [`SA_TAG`, `SA_TAG2` and `SA_KILL`][amavis-docs::spam-score].
+
+    These settings have equivalent ENV supported by DMS for easy adjustments, as documented below.
 
 [amavis-docs::spam-score]: https://www.ijs.si/software/amavisd/amavisd-new-docs.html#tagkill
 
-##### 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).
-
-The Amavis action configured by this setting:
-
-- Influences the behaviour of the [`SA_KILL`](#sa_kill) setting.
-- Applies to the Amavis config parameters `$final_spam_destiny` and `$final_bad_header_destiny`.
-
-This ENV setting is related to:
-
-- [`MOVE_SPAM_TO_JUNK=1`](#move_spam_to_junk)
-- [`MARK_SPAM_AS_READ=1`](#mark_spam_as_read)
-
 ##### ENABLE_SPAMASSASSIN_KAM
 
 - **0** => KAM disabled
@@ -547,62 +534,135 @@ This ENV setting is related to:
 
 [KAM](https://mcgrail.com/template/projects#KAM1) 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.
 
+##### 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.
+
+!!! note
+
+    The Amavis action configured by this setting:
+
+    - Influences the behaviour of the [`SA_KILL`](#sa_kill) setting.
+    - Applies to the Amavis config parameters `$final_spam_destiny` and `$final_bad_header_destiny`.
+
+!!! note "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)
+
 ##### SA_TAG
 
-- **2.0** => add spam info headers if at, or above this level
+- **2.0** => add 'spam info' headers at, or above this spam score
 
-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 at this spam score, but for purposes like diagnostics it can be useful to identify mail with a spam score at a lower bound than `SA_TAG2`.
+
+??? example "`X-Spam` headers appended to mail"
+
+    Send a simple mail to a local DMS account `hello@example.com`:
+
+    ```bash
+    docker exec dms swaks --server 0.0.0.0 --to hello@example.com --body 'spam'
+    ```
+
+    Inspecting the raw mail you will notice several `X-Spam` headers were added to the mail like this:
+
+    ```
+    X-Spam-Flag: NO
+    X-Spam-Score: 4.162
+    X-Spam-Level: ****
+    X-Spam-Status: No, score=4.162 tagged_above=2 required=4
+            tests=[BODY_SINGLE_WORD=1, DKIM_ADSP_NXDOMAIN=0.8,
+            NO_DNS_FOR_FROM=0.379, NO_RECEIVED=-0.001, NO_RELAYS=-0.001,
+            PYZOR_CHECK=1.985] autolearn=no autolearn_force=no
+    ```
+
+    !!! info "The `X-Spam-Score` is `4.162`"
+    
+        High enough for `SA_TAG` to trigger adding these headers, but not high enough for `SA_TAG2` (_which would set `X-Spam-Flag: YES` instead_).
 
 ##### 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.
 
-!!! tip "Choosing an appropriate value"
+??? tip "Choosing an appropriate `SA_KILL` value"
 
     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_).
 
-!!! info "Trigger action"
+    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"_).
 
-    DMS will configure Amavis with either of these actions based on the DMS [`SPAMASSASSIN_SPAM_TO_INBOX`](#spamassassin_spam_to_inbox) setting:
+[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
 
-    - `D_PASS` (default):
-        - Accept mail and deliver it to the recipient(s), despite a high spam score.
+??? info "Trigger action"
+
+    DMS will configure Amavis with either of these actions based on the DMS [`SPAMASSASSIN_SPAM_TO_INBOX`](#spamassassin_spam_to_inbox) ENV setting:
+
+    - `D_PASS` (**default**):
+        - 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.
 
-!!! note "Quarantine"
+??? note "Quarantined mail"
 
-    When mail has a spam score that reaches the `SA_KILL` threshold, [it will be quarantined][amavis-docs::quarantine] regardless of the `SA_KILL` action to perform.
+    When mail has a spam score that reaches the `SA_KILL` threshold:
+
+    - [It will be quarantined][amavis-docs::quarantine] regardless of the `SA_KILL` action to perform.
+    - With `D_PASS` the delivered mail also appends an `X-Quarantine-ID` mail header. The ID value of this header is part of the quarantined file name.
 
     If emails are quarantined, they are compressed and stored at a location dependent on the [`ONE_DIR`](#one_dir) setting:
 
     - `ONE_DIR=1` (default): `/var/mail-state/lib-amavis/virusmails/`
     - `ONE_DIR=0`: `/var/lib/amavis/virusmails/`
 
+    !!! tip
+
+        Easily list mail stored in quarantine with `find` and the quarantine path:
+
+        ```bash
+        find /var/lib/amavis/virusmails -type f
+        ```
+
 [amavis-docs::actions]: https://www.ijs.si/software/amavisd/amavisd-new-docs.html#actions
 [amavis-docs::quarantine]: https://www.ijs.si/software/amavisd/amavisd-new-docs.html#quarantine
 
 ##### 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_)***`**.
+??? example "Including trailing white-space"
+
+    Add trailing white-space by quote wrapping the value: `SA_SPAM_SUBJECT='[SPAM] '`
+
+??? example "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
 

docs/content/faq.md

@@ -378,18 +378,7 @@ When you run DMS with the ENV variable `ONE_DIR=1` (default), this directory wil
 
 #### How can I manage my custom SpamAssassin rules?
 
-Antispam 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] "
-```
+Anti-spam rules are managed in `docker-data/dms/config/spamassassin-rules.cf`.
 
 #### Why are SpamAssassin `x-headers` not inserted into my `subdomain.example.com` subdomain emails?
 

docs/content/index.md

@@ -14,7 +14,7 @@ This documentation provides you not only with the basic setup and configuration
 
 ## About
 
-`docker-mailserver`, or DMS for short, is a production-ready fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.). It employs only configuration files, no SQL database. The image is focused around the slogan "Keep it simple and versioned".
+`docker-mailserver`, or DMS for short, is a production-ready fullstack but simple mail server (SMTP, IMAP, LDAP, Anti-spam, Anti-virus, etc.). It employs only configuration files, no SQL database. The image is focused around the slogan "Keep it simple and versioned".
 
 ## Contents
 

docs/mkdocs.yml

@@ -1,6 +1,6 @@
 # Site specific:
 site_name: 'Docker Mailserver'
-site_description: 'A fullstack but simple mail-server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.) using Docker.'
+site_description: 'A fullstack but simple mail-server (SMTP, IMAP, LDAP, Anti-spam, Anti-virus, etc.) using Docker.'
 site_author: 'docker-mailserver (Github Organization)'
 copyright: '<p>&copy <a href="https://github.com/docker-mailserver"><em>Docker Mailserver Organization</em></a><br/><span>This project is licensed under the MIT license.</span></p>'
 

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 to 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 -------------------------