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.
spamdhad already gone back to the packaged daemon unnoticed. On bookworm the unit isspamd.service, so our override forspamassassin.serviceno longer applied.- Rules are read from a directory named after the version. The packaged 4.0.1 never saw what the CPAN
sa-updatewrote, sospamdran 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 --versionWhat 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 spamd3. 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.0Plugins 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::PyzorAttachmentPresent 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 -discoverThen 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 0Leave 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.log7. 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::/648. 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 -8509. 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.org10. 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 spamdCheck the threshold spamd is really applying:
printf 'Subject: t\n\nhi\n' | sudo -u Debian-exim spamc -u Debian-exim -c12. 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.gittools/ 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
doneEvery 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.orgsa-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
- Install the packages (section 1) and AttachmentPresent (section 3).
- Set the
spamdflags (section 2). - Deploy
/etc/spamassassinfrom git. Addzz-<host>.cfif needed. - Link the tools and add the cron lines (section 12).
- Create the Bayes directory, owned by
Debian-exim(see the Bayes article). - Set up Razor2 and Pyzor as
Debian-exim(section 4). - Lint and restart (section 11).
- Run
sa-learn-rejects.shonce by hand. Until it has run, the health check reports that the learn has never completed. - Send a test message. Check that
X-Spam-Checker-Versionshows 4.0.1 and thatspamc -creports the threshold you expect.
- Log in to post comments