Skip to main content

Rspamd Configuration Guide

This page links the guides and reference pages for configuring Rspamd. The guides explain what to configure and which file each change goes in; the reference pages describe the options of one area in detail. If Rspamd is not installed yet, start with installation and first setup.

How the Configuration Is Layered​

Rspamd filters spam with its shipped configuration, so you only add the settings you want to change. Don't edit the shipped files: upgrades bring new versions of them. Rspamd reads the configuration in layers, from lowest to highest precedence:

  1. Shipped defaults: rspamd.conf and the files next to it, modules.d/ and scores.d/
  2. local.d/: merged with the defaults, so a file holds only the settings you change
  3. Scores and action thresholds saved from the web interface (/var/lib/rspamd/rspamd_dynamic)
  4. override.d/: each key or block you define replaces the default as a whole

Precedence has examples. Change one thing at a time, check it with rspamadm configtest, and watch the results in the web interface before you make the next change.

Getting Started with Configuration​

New to Rspamd Configuration?​

  1. Configuration Fundamentals - What to configure and how
  2. Tool Selection Guide - Which mechanism to use for a custom check
  3. Common Setups - Which files a minimal, a tuned and a high-volume setup change
  4. Testing Changes - Check the configuration before you restart Rspamd

Specific Configuration Tasks?​

Configuration Areas​

AreaWhat it controlsWhere you change itReference
ActionsWhat Rspamd tells the MTA to do at each scorelocal.d/actions.confActions and scores
ScoresHow much each symbol adds to the message scorelocal.d/groups.conf or local.d/<group>_group.conf, or the web interfaceActions and scores
ModulesWhich checks run and how they are set uplocal.d/<module>.confModules
WorkersThe processes that scan mail, serve the web interface and talk to the MTAlocal.d/worker-<name>.incWorkers
General optionsDNS, timeouts, size limitslocal.d/options.incCommon options
LoggingLog level, destination and formatlocal.d/logging.incLogging
RedisServers for Bayes, greylisting, rate limiting and other modules that keep data in Redislocal.d/redis.confRedis configuration
BayesThe statistical classifierlocal.d/classifier-bayes.confStatistics

Other reference pages:

  • User settings: different scores, thresholds and checks for selected users, domains or IP addresses
  • Composite symbols: new symbols from expressions over other symbols
  • Maps: lists that Rspamd loads from files or URLs and reloads without a restart
  • Selectors: extract data from messages for multimap, ratelimit and other modules
  • Upstreams: server lists and how Rspamd picks a server from them
  • UCL: the syntax of the configuration files
  • Configuration templates: Jinja templates and environment variables in configuration files

Configuration by Scenario​

Different environments have different needs. Find the guide that matches your situation:

By Use Case​

By Integration Type​

  • Postfix Integration - Complete Postfix + Rspamd setup
  • Other MTAs - Exim, Sendmail, Haraka, Stalwart and others
  • Docker - The official image and a Compose file with Redis and a recursive resolver
  • Kubernetes - Deployment example, probes, and what to run separately
  • Alongside SpamAssassin - Run Rspamd next to SpamAssassin and compare results before Rspamd rejects anything

Configuration Best Practices​

File Organization​

/etc/rspamd/
├── local.d/          # Your customizations (recommended)
│   ├── actions.conf      # Spam thresholds
│   ├── groups.conf       # Symbol scores
│   └── worker-*.inc      # Worker settings
├── override.d/       # Replaces defaults key by key (advanced)
└── modules.d/        # Don't edit - defaults only

On FreeBSD the directory is /usr/local/etc/rspamd/. A file in local.d/ contains only the settings you change, without the section name around them: local.d/actions.conf contains reject = 20;, not actions { reject = 20; }. Older guides set scores in local.d/metrics.conf; that file has been deprecated since Rspamd 1.7.

Change Management Process​

  1. Backup current configuration before making changes
  2. Test syntax with rspamadm configtest before restarting
  3. Monitor results in web interface after changes
  4. Document changes for future reference
  5. Have rollback plan for critical changes

Common Mistakes to Avoid​

  • ❌ Editing the shipped files in /etc/rspamd/ instead of adding files to local.d/
  • ❌ Making multiple changes without testing
  • ❌ Setting unrealistic action thresholds
  • ❌ Disabling essential modules without understanding impact
  • ❌ Ignoring log files during troubleshooting

Configuration Tools and Interfaces​

  • Access: http://localhost:11334. The controller listens only on localhost by default, so from another machine use an SSH tunnel
  • Best for: Monitoring, basic adjustments, learning
  • Limitations: It changes only symbol scores, action thresholds and maps; everything else needs the configuration files

Configuration Files (Advanced Users)​

  • Location: /etc/rspamd/local.d/
  • Best for: Complex customizations, automation
  • Requirements: Understanding of Rspamd configuration syntax (UCL)

Command Line Tools​

  • rspamc - Query statistics, test messages
  • rspamadm - Administrative tasks, configuration management
  • rspamadm configtest - Configuration validation

Getting Help with Configuration​

Built-in Help​

# Show the configuration as Rspamd loads it
rspamadm configdump

# Validate configuration files
sudo rspamadm configtest

# Describe a configuration option
rspamadm confighelp options.task_timeout

# List rspamadm commands, or show the options of one command
rspamadm help
rspamadm help configdump

Documentation Resources​

Community Support​

Support also describes commercial support.

Configuration Examples​

Quick Start Configuration​

The shipped configuration filters spam without changes. Its action thresholds are reject = 15, add_header = 6 and greylist = 4, so you don't need local.d/actions.conf to start. Add Redis, which Bayes, greylisting and rate limiting need, and a password for the web interface:

# /etc/rspamd/local.d/redis.conf
servers = "127.0.0.1";
# /etc/rspamd/local.d/worker-controller.inc
password = "$2$...";   # hash printed by rspamadm pw

Tuned Configuration​

Lower action thresholds and a higher score for one symbol. Change values like these only after you have checked the results in the History tab of the web interface:

# /etc/rspamd/local.d/actions.conf
reject = 12;       # default 15
add_header = 5;    # default 6
greylist = 3;      # default 4
# /etc/rspamd/local.d/groups.conf
symbols {
  "FORGED_SENDER" {
    weight = 1.0;    # default 0.3
  }
}

High-Volume Configuration​

More scanner processes and a local recursive resolver:

# /etc/rspamd/local.d/worker-normal.inc
count = 8;   # example value
# /etc/rspamd/local.d/options.inc
dns {
  nameserver = ["127.0.0.1"];   # local recursive resolver
}

Leave max_tasks and the other dns options at their defaults. max_tasks caps how many messages one process handles at the same time; it does not increase throughput. See Normal worker for count and max_tasks, and Performance tuning for the DNS options.

What's Next?​

Choose your path based on your current needs:

Remember: Effective configuration is an iterative process. Start with the basics, monitor results, and refine based on your actual email patterns and business requirements.