SpamAssassin 4.0.x Setup and Hardening on Debian/Ubuntu

Submitted by JB on

SpamAssassin 4.0.x Setup and Hardening on Debian 12

Author: Jeff Brown
Revised: 8 November 2026 (first edition March 2026)
Applies to: Future Foundation mail servers, Debian 12 (bookworm), Exim4 with SA-Exim

This guide replaces the March 2026 edition, which installed SpamAssassin from CPAN and added the KAM rule channel. Neither is used any more. Bayes training has its own article: SpamAssassin: Bayes Training & Weekly cron Learning.


Standing rule: Debian packages only

We use the Debian-packaged SpamAssassin (4.0.1 on bookworm): its daemon, its rules, its sa-learn and its lint. Never install SpamAssassin or its tools from CPAN or into /usr/local. In cron jobs, scripts and by hand, call the tools by full path (/usr/bin/sa-learn, /usr/bin/spamassassin), because /usr/local/bin comes first in root's PATH.

Why the guide changed

The first edition used CPAN because Debian 11 shipped SpamAssassin 3.4.6, and the DMARC, FromNameSpoof and Phishing plugins need 4.x. After the August 2026 upgrade to Debian 12 an audit found:

  • Debian 12 ships 4.0.1, which includes those plugins.
  • spamd had already gone back to the packaged daemon unnoticed. On bookworm the unit is spamd.service, so our override for spamassassin.service no longer applied.
  • Rules are read from a directory named after the version. The packaged 4.0.1 never saw what the CPAN sa-update wrote, so spamd ran for two months on stock rules only, and nobody missed KAM.

We removed the CPAN install and retired KAM.


1. Installation

apt-get update
apt-get install spamassassin spamd sa-compile libmail-dmarc-perl \
  razor pyzor re2c libarchive-zip-perl

/usr/bin/spamassassin --version

What goes where on bookworm:

Daemon spamd.service, /usr/sbin/spamd. Options in /etc/default/spamd
Rule updates spamassassin-maintenance.timer (daily): sa-update, sa-compile, then reloads spamd
Rules /var/lib/spamassassin/4.000001/
Site config /etc/spamassassin/

/etc/cron.daily/spamassassin is a legacy script that does nothing unless CRON=1 is set. Do not add jobs to it.

2. spamd options

Do not override the systemd unit. Set the flags in /etc/default/spamd:

OPTIONS="-x -s /var/log/spamd.log --helper-home-dir --max-children 8 --min-children 2 --min-spare 2 --max-spare 4 --max-conn-per-child 50 --timeout-child 240"
PIDFILE="/run/spamd.pid"
-x no per-user config files
-s /var/log/spamd.log log to a file (add a logrotate entry)
--helper-home-dir use the scanning user's home for .razor and .pyzor
--max-children 8 concurrent scanners, roughly 80-120 MB each
--max-conn-per-child 50 recycle children to contain memory leaks
--timeout-child 240 kill a child after 4 minutes

Then:

systemctl restart spamd

3. Configuration files

local.pre loadplugin lines only
local.cf everything else: scores, networks, Bayes settings, rules
zz-<host>.cf only what differs on one host

local.pre and local.cf are identical on every server and come from git. Do not hand-edit them on a server, and do not use per-server branches. zz-<host>.cf is gitignored, stays on its own server, and loads after local.cf, so its settings win. A typical one holds a single line:

required_score 5.0

Plugins go in local.pre because .pre files are read first. A score for a test whose plugin loads too late can fail silently.

loadplugin Mail::SpamAssassin::Plugin::DMARC
loadplugin Mail::SpamAssassin::Plugin::AttachmentPresent
loadplugin Mail::SpamAssassin::Plugin::FromNameSpoof
loadplugin Mail::SpamAssassin::Plugin::Phishing
loadplugin Mail::SpamAssassin::Plugin::Razor2
loadplugin Mail::SpamAssassin::Plugin::Pyzor

AttachmentPresent is a third-party plugin that Debian does not package. Copy the file from an existing server to /usr/local/share/perl/5.36.0/Mail/SpamAssassin/Plugin/ before deploying local.pre, or lint fails. Do not remove it from local.pre for one host: the file is installed on the host instead.

4. Razor2 and Pyzor

Both keep their state in the home directory of the user spamd scans as. With SA-Exim that is Debian-exim (/var/spool/exim4), not root or debian-spamd.

sudo -u Debian-exim pyzor --homedir /var/spool/exim4/.pyzor ping

cd /tmp
sudo -u Debian-exim razor-admin -home=/var/spool/exim4/.razor -create
sudo -u Debian-exim razor-admin -home=/var/spool/exim4/.razor -discover

Then set debuglevel = 0 in /var/spool/exim4/.razor/razor-agent.conf. Without this home directory Razor rediscovers its servers on every scan: creating it cut our median scan time from 4.5 s to 1.4 s.

DCC is not used. Debian does not package it, and building from source breaks the packages-only rule.

5. Scores

Overrides live in local.cf under "Custom Scores", one per line, with the stock score and the reason in a comment.

  • Override a stock score only on evidence. Count how often the rule hits clean and spam mail in /var/log/spamd.log, then re-score the logged scans.
  • Check that the rule exists under /var/lib/spamassassin/4.000001/updates_spamassassin_org/. A score for a missing rule does nothing and lint does not warn.
  • Do not reward authentication much. Compromised accounts and spammers with their own domains pass SPF, DKIM and DMARC.
  • Score modern phishing patterns up: Spamhaus DBL phish, malware and botnet listings, SURBL PH, IPFS-hosted pages, the recipient's address in a link fragment or the subject.

The tag threshold is required_score, default 6 in local.cf and set per host in zz-<host>.cf. SA-Exim rejects at SMTP time at 12.

6. DNS restrictions

Some lists block queries from certain resolvers and return misleading answers. Suppress only the ones stock rules actually use:

dns_query_restriction deny bl.score.senderscore.com
dns_query_restriction deny sa-accredit.habeas.com
dns_query_restriction deny sa-trusted.bondedsender.org
dns_query_restriction deny isipp.com
score RCVD_IN_VALIDITY_RPBL 0
score RCVD_IN_VALIDITY_CERTIFIED 0
score RCVD_IN_VALIDITY_SAFE 0

Leave URIBL_BLOCKED and the other *_BLOCKED rules at their stock 0.001. They add no real score, but they log when a list refuses our resolver. Check with:

grep -c BLOCKED /var/log/spamd.log

7. Trusted networks

List the relay IPs under your control. The list must match your SPF record. IPv4 and IPv6 go on separate lines:

trusted_networks 192.0.2.0/29 198.51.100.0/29
trusted_networks 2001:db8:1::/64

8. Shortcircuit and priorities

Skip expensive network tests when an early result is already definite. In local.cf:

ifplugin Mail::SpamAssassin::Plugin::Shortcircuit
shortcircuit USER_IN_BLACKLIST on
shortcircuit ALL_TRUSTED on
endif

priority BAYES_99 -850
priority BAYES_999 -850

9. Backscatter (VBounce)

The stock VBounce plugin looks inside a bounce for the original message's Received headers. If none names one of your relays, the original was never yours. Without this setting the rule never fires. List the hostnames that write "by <host>" on your mail, one line per server:

welcomelist_bounce_relays mail.example.org mx.example.org

10. Phishing feeds

Loading the Phishing plugin is not enough: it matches nothing without OpenPhish or PhishTank feed files. They come from their own cron job, not from sa-update, and stay out of git.

find /var/lib/spamassassin /etc/spamassassin -iname "*phish*"

11. Lint and reload

Lint with the packaged binary, as the scanning user, from /:

cd / && sudo -u Debian-exim /usr/bin/spamassassin --lint && echo "Config OK"
systemctl reload spamd

Check the threshold spamd is really applying:

printf 'Subject: t\n\nhi\n' | sudo -u Debian-exim spamc -u Debian-exim -c

12. Git and the tools directory

One master branch serves every server. Server pulls run as an ordinary admin user over ssh, given access with POSIX ACLs on .git and the tracked files only, so gitignored files stay closed:

git@git.example.org:org/spamassassin.git

tools/ holds the helper scripts. SpamAssassin ignores it. Each is symlinked from the repo into /usr/local/tools and /usr/local/bin, so a git pull updates them:

for t in vbounce-weekly-report.sh sa-learn-rejects.sh sa-health-check.sh \
         sa-fp-daily.py sa-bayes-week-report.sh sa-learn-ham.sh; do
    ln -s /etc/spamassassin/tools/$t /usr/local/tools/$t
    ln -s /etc/spamassassin/tools/$t /usr/local/bin/$t
done

Every server runs the same checks, from root's crontab:

# Bayes: learn rejects Bayes wasn't sure of, Sun 03:00
0 3 * * 0 /usr/local/tools/sa-learn-rejects.sh --verbose > /run/sa-learn-rejects.out 2>&1 && s=OK || s=FAILED; /usr/bin/mail -s "sa-learn-rejects $s on $(hostname -f)" admin@example.org < /run/sa-learn-rejects.out
# Keep a year of rejects in cur/
30 4 1 * * find /var/spool/sa-exim/SApermreject/cur -type f -mtime +365 -delete
# Possible false positives, daily; mails only when something is listed
0 7 * * * /usr/local/tools/sa-fp-daily.py ops@example.org
# Health check, weekly; mails only on a problem (SCANS_MIN=20 on quiet hosts)
10 7 * * 2 /usr/local/tools/sa-health-check.sh ops@example.org
# Backscatter flagged by VBounce, Mondays
30 7 * * 1 /usr/local/tools/vbounce-weekly-report.sh ops@example.org
# Monthly Bayes report (--change: the host's first full day on the fixed Bayes)
30 7 1 * * /usr/local/tools/sa-bayes-week-report.sh --change YYYY-MM-DD ops@example.org

sa-fp-daily.py and vbounce-weekly-report.sh hold a list of our domains in OURDOM. Keep it to domains whose public MX really points at us.

13. New server checklist

  1. Install the packages (section 1) and AttachmentPresent (section 3).
  2. Set the spamd flags (section 2).
  3. Deploy /etc/spamassassin from git. Add zz-<host>.cf if needed.
  4. Link the tools and add the cron lines (section 12).
  5. Create the Bayes directory, owned by Debian-exim (see the Bayes article).
  6. Set up Razor2 and Pyzor as Debian-exim (section 4).
  7. Lint and restart (section 11).
  8. Run sa-learn-rejects.sh once by hand. Until it has run, the health check reports that the learn has never completed.
  9. Send a test message. Check that X-Spam-Checker-Version shows 4.0.1 and that spamc -c reports the threshold you expect.
Category