mwaeckerlin/rspamd repository overview

⁠Rspamd

Headless, shell-free Rspamd container. Signs outgoing mail with DKIM, verifies incoming DKIM / DMARC / SPF, greylists, runs a Bayes classifier trained by IMAPSieve, hands mail parts to ClamAV, and — via a single DKIM_DMARC mode switch — either logs its verdict, softly enforces standards, or hard-rejects on failure.

Intended primary use inside mwaeckerlin/mailservice (Docker Compose mail stack: postfix, dovecot, postfixadmin, snappymail). Works standalone against any postfix that speaks the milter protocol on port 11332.

⁠Environment variables

⁠Scores and thresholds

The action thresholds are Rspamd's own upstream defaults — the de-facto convention for a mail gateway — and are kept unchanged:

RSPAMD_REJECT_SCORE=15 is deliberately conservative: the tail of false positives sits at scores ~10–14, where legitimate mail with wonky signals lands, so 15 avoids bouncing it («lieber zu hoch als legitime Mail bouncen»). Lowering it catches more spam at the cost of more false-positive rejects; raising it does the opposite. Bayes learning (via IMAPSieve) sharpens the scores over time so the threshold rarely needs tuning.

The verdict headers are authoritative: rspamd's milter_headers module removes any incoming X-Spam-Flag / X-Spam-Status on every scan (and X-Spam-Level from score ≥ 1) before this container's own verdict is stamped, and the SPAM_FLAG rule additionally scores a pre-existing flag as a spam signal — a sender-supplied flag can therefore not route legitimate mail to Junk on a downstream that files by these headers. Pinned by the mailservice e2e suite. The X-Transport-Security header enjoys the same protection (see below).

⁠Limits and delivery

Rspamd never rejects a mail because of its size. The only knob that turns into an SMTP reject is the spam score crossing RSPAMD_REJECT_SCORE (see above). Size only affects how deeply a message is inspected, and always fail-open:

• Rspamd's content rules (Bayes, regexps) inspect the message body up to Rspamd's max_message (upstream default ~50 MB). A larger mail is still delivered; only the tail beyond that size is not fed to the content rules. This never causes a reject.
• Virus scanning is bounded by the sibling clamav container's CLAMD_MAX_FILESIZE / CLAMD_MAX_SCANSIZE / CLAMD_STREAM_MAXLENGTH (defaults 2 GiB / 4 GiB / 4 GiB — clamav's architectural maxima). A mail exceeding those is delivered unscanned (CLAM_VIRUS_FAIL, weight 0), never bounced.

So no message size limit in this stack can bounce a legitimate mail; the accepted size is bounded only by postfix's MESSAGE_SIZE_LIMIT (default 100 GiB, configurable, 0 = unlimited).

⁠DKIM key generation and DNS-record notification

On first start, init calls rspamadm dkim_keygen -s <selector> -b 2048 -d <domain> for every domain in DOMAINS that does not already have a ${selector}-${domain}.key file under /var/lib/rspamd/dkim/, and prints the resulting BIND-formatted DNS TXT record with a banner to stdout — visible via docker compose logs rspamd.

If NOTIFY_EMAIL is set, the same records are additionally delivered by e-mail to that address using minimal in-process SMTP (no shell, no extra binary, no external client). Delivery is best-effort and never blocks start-up: a failing SMTP round-trip only logs a warning; the records still appear on stdout.

⁠DKIM_DMARC — the single mode knob

log mode is meant to be run for a few days after enabling this container in production. Grep delivered mail's Authentication-Results: and X-Spamd-Result: headers for the verdicts you would have rejected; when nothing legitimate is caught, escalate to permissive (or reject, if every legitimate sender you receive from is known to sign).

⁠Volumes to persist

• /var/lib/rspamd/dkim/ — private DKIM keys per domain. Critical: losing this volume invalidates every published DNS TXT record; outgoing mail is still signed but with a new key, so receivers stop verifying until the DNS is rolled forward.
• /var/lib/rspamd/ — compiled Lua cache and misc state. Non- critical; regenerated on start.

Bayes / greylist / ratelimit state lives in Redis — see the sibling mwaeckerlin/redis container and its /data volume.

⁠Postfix integration

In postfix/main.cf (via the RSPAMD env on mwaeckerlin/postfix):

smtpd_milters = inet:rspamd:11332
non_smtpd_milters = inet:rspamd:11332
milter_default_action = accept
milter_protocol = 6

The postfix Dockerfile in mwaeckerlin/postfix adds this automatically when RSPAMD env is set (host or host:port; default port 11332).

⁠Image layout

Three-stage build, following the mwaeckerlin/nginx, mwaeckerlin/ php-fpm, mwaeckerlin/opendkim and mwaeckerlin/opendmarc pattern:

1. init — compiles init.cpp statically with g++ -static -Os -flto. The resulting binary parses env, generates DKIM keys via rspamadm dkim_keygen, optionally notifies via minimal in-process SMTP, stages /etc/rspamd/local.d/*.conf from templates, and execvs the daemon.
2. build — installs rspamd on the Alpine base, then uses tar cph … + ldd to collect only the binaries, shared libraries, Lua modules and configs the runtime needs into /root/.
3. runtime — FROM mwaeckerlin/scratch, COPY --from=build /root/ /. No shell, no package manager, no perl, no busybox. ENTRYPOINT ["/usr/bin/init"].

Debugging on this shell-free image:

docker compose logs rspamd            # every rspamd decision streams here
docker compose exec rspamd rspamc stat
docker compose exec rspamd rspamc symbols < mail.eml

The rspamd web UI is available on port 11334 (http://<host>:11334/) if you expose it — useful for browsing the history of recent decisions per message.