Skip to main content

Getting started with Rspamd

The pages below take you from a new server to Rspamd checking mail for your MTA. If you are new to Rspamd, read them in order. If you are migrating from SpamAssassin, connecting an existing installation to your MTA, or running Rspamd in containers, see Other starting points.

Prerequisites​

  • Debian, Ubuntu or a RHEL-compatible distribution (the EL packages need EPEL), FreeBSD, or any host that runs Docker. Downloads lists the supported releases, packages for other systems and how to build from source.
  • Root or sudo access to install packages and edit the Rspamd configuration in /etc/rspamd (/usr/local/etc/rspamd on FreeBSD).
  • Redis, for Bayes and the other features listed under Is Redis required?. You can install it during setup.
  • A local recursive DNS resolver, for example Unbound. Spamhaus and other DNS blocklists refuse queries that arrive through public resolvers.
  • An MTA to connect Rspamd to.
  • Working knowledge of the Unix command line, DNS, SMTP and message headers.

Reading order​

  1. Understanding Rspamd explains how a message moves through Rspamd: the processing pipeline, symbols, scores and actions, and the worker processes. Read it before you change any configuration.
  2. Installation covers installing Rspamd and Redis from the official packages or running the official Docker image, connecting Rspamd to Redis, setting the web interface password and checking that the workers are listening. Downloads also has the experimental and ASAN packages.
  3. First setup checks the Redis connection and the web interface password, then covers the action thresholds, Postfix integration, an end-to-end test and Bayes training (by hand with rspamc learn_spam and rspamc learn_ham, or with autolearn). For Exim, Sendmail and other MTAs, use the MTA integration tutorial.
  4. Configuration fundamentals covers modules, scores, actions, workers and the local.d/override.d layout, so you know where each change goes.
  5. Tool selection helps you choose between regexp rules, multimap, Lua rules, plugins and composites when you write your own rules.

Other starting points​

Migrating from SpamAssassin​

Read Understanding Rspamd, then follow the SpamAssassin migration guide. The main differences from SpamAssassin:

  • SpamAssassin Bayes databases cannot be imported. Retrain Rspamd from your own ham and spam with rspamc learn_ham and rspamc learn_spam.
  • Rspamd returns an action (such as add header or reject) together with the score. The default thresholds in actions.conf are greylist = 4, add_header = 6 and reject = 15. Tune them against your own mail instead of copying SpamAssassin's required_score.
  • Rspamd has its own modules for SPF, DKIM, DMARC, DNS blocklists, Bayes and fuzzy hashes. Import only custom rules you wrote yourself, using the SpamAssassin module.
  • Rspamd can also sign outbound mail (DKIM signing, ARC) and send DMARC aggregate reports. SpamAssassin only checks DMARC and ARC.
  • Rspamd is event-driven: each worker scans many messages at once and does DNS and Redis lookups without blocking, while each SpamAssassin spamd child process handles one message at a time. The project reports roughly ten times SpamAssassin's throughput with the same rules; see Performance.

The migration guide describes a staged rollout. Run Rspamd next to SpamAssassin without rejecting mail (Testing alongside SpamAssassin shows the action settings) and compare the verdicts. Tune the thresholds, then switch the MTA over. Keep SpamAssassin installed until you no longer need a rollback.

Connecting a mail server​

If Rspamd is already installed and you only need to connect your MTA:

MTAProtocolRspamd worker (default address)Instructions
PostfixMilterProxy (localhost:11332)First setup
SendmailMilterProxy (localhost:11332)MTA integration
Eximspamd_address with variant=rspamd (legacy RSPAMC protocol)Normal (localhost:11333)MTA integration

The MTA integration tutorial also covers Haraka, EmailSuccess, Apache James, Stalwart and LDA mode.

Docker and Kubernetes​

The official image is rspamd/rspamd. See the Docker section of Installation and the image README, which also describes production use with your configuration baked into a derived image. Some things work differently from a package install:

  • Put your configuration in /etc/rspamd/local.d (and override.d if needed): mount a host directory there, or copy the files into a derived image.
  • The image binds every worker to all container interfaces. Publish the ports on 127.0.0.1 only. Set a controller password before you use the web interface: connections through a published port come from outside secure_ip (loopback by default), and the controller refuses the default password q1 from such addresses.
  • Bayes, neural, ratelimit and greylisting data live in Redis, so run Redis too and persist its data. /var/lib/rspamd holds caches, history and counters. It is already a volume in the image; if you bind-mount a host directory there, it must be writable by uid/gid 11333.
  • Use a local recursive DNS resolver. The Compose example runs Rspamd with Redis and Unbound.
  • The image has a HEALTHCHECK on the controller's /ping endpoint, which needs no password; use /ping for liveness probes too. For readiness use /ready on the controller, which needs the controller password unless the probe comes from secure_ip. See Production notes.

For Kubernetes, see Kubernetes in the installation guide and the Tanka example in the same repository.

Common questions​

Is Redis required?​

Rspamd starts without Redis, but install it for any production setup. Set the servers in /etc/rspamd/local.d/redis.conf. In the default configuration, these features keep their data in Redis and do not work without it:

  • the Bayes classifier (per-token spam and ham counters)
  • the neural module
  • ratelimit and greylisting
  • DMARC aggregate reporting
  • your own fuzzy storage worker, if you run one (disabled by default)

The history_redis module also stores the scan history for the web interface's History tab in Redis. Without Redis, the History tab shows the controller's built-in history instead. Fuzzy checks against the public rspamd.com storage need no local Redis.

What works without training?​

Most checks need no training: SPF, DKIM, DMARC and ARC verification, DNS blocklists for IP addresses and URLs, regexp content rules, MIME and URL checks, and fuzzy checks against the public rspamd.com storage. Bayes gives no result until it has learned at least 200 spam and 200 ham messages (the min_learns setting), and the neural module also has to collect training data first. Training Bayes on your own mail usually improves detection noticeably over static rules alone.

Is Lua required?​

No. You configure the built-in modules with UCL files in /etc/rspamd/local.d/, and multimap, regexp rules, selectors and composites cover many custom rules without code. You need Lua only for writing plugins and for rules these tools can't express. Put such rules in /etc/rspamd/rspamd.local.lua or in a *.lua file in /etc/rspamd/lua.local.d/. Tool selection explains which to use.

After getting started​

Configuration guides:

Module reference:

Internals and development:

Operations:

Getting help​

You needGo to
Answers to common questionsFAQ
Help from other usersDiscord, Telegram, GitHub Discussions or the mailing lists
To report a bug or request a featureGitHub Issues
To contribute codePull requests on rspamd/rspamd
Commercial support (consulting, NDA, dedicated access to fuzzy storage or DNS lists)support@rspamd.com, see Support
To report a security vulnerabilityGitHub private vulnerability reporting (preferred), or email vsevolod@rspamd.com with [SECURITY] in the subject
To report a documentation problemdocs.rspamd.com issues, or a pull request through the "Edit this page" link

Do not open public GitHub issues for security problems. SECURITY.md explains what the project treats as a vulnerability.