Rspamd

Synopsis #

Rspamd filters email using regular expressions, statistical analysis, SPF/DKIM/DMARC checks, and URL reputation. It integrates with mail servers such as OpenSMTPD, Postfix, and Exim.

Follow the mail server’s documented integration procedure. The examples below use OpenBSD’s smtpd(8).

Features #

• Spam classification and scoring
• Built-in support for DKIM, SPF, and DMARC validation
• Statistical filtering with Redis backend
• Milter and proxy protocol support
• Web-based administration and status interface
• Lua scripting engine for custom rules
• Integration with antivirus and antiphishing backends

Installation #

Rspamd is not included in the OpenBSD base system. Install it using pkg_add(1):

doas pkg_add rspamd

The package configures a local Redis backend. Ensure Redis is installed and running for the enabled modules.

To enable and start Rspamd:

doas rcctl enable redis rspamd
doas rcctl start redis rspamd

The main configuration directory is located at:

/etc/rspamd/

The runtime data is located in:

/var/db/rspamd/

Architecture Overview #

Rspamd uses a multi-process architecture composed of the following components:

• controller: handles configuration reload, statistics, and HTTP requests
• normal workers: perform spam checks and filtering
• proxy workers: used when running behind MTAs in milter or proxy mode
• rspamc: the client tool used to submit messages for classification or learning

Configuration Structure #

Rspamd separates its configuration into several files:

After making changes to any configuration files, restart the service:

doas rspamadm configtest && doas rcctl restart rspamd

Enabling the Web Interface #

Keep the controller bound to loopback and use an SSH tunnel for remote administration:

Edit /etc/rspamd/local.d/worker-controller.inc:

bind_socket = "127.0.0.1:11334";
password = "replace-with-rspamadm-pw-output";
enable_password = "replace-with-separate-rspamadm-pw-output";

Generate the password hash using:

doas rspamadm pw

secure_ip grants trusted controller access; it is not a network allowlist. Use binding and PF for network restrictions. Put local changes in local.d rather than editing packaged defaults.

Access the web UI at:

http://localhost:11334/

Integration with smtpd(8) #

Install the OpenSMTPD integration package:

doas pkg_add opensmtpd-filter-rspamd

Follow /usr/local/share/doc/pkg-readmes/opensmtpd-filter-rspamd for the filter command and listener configuration. This integration uses OpenSMTPD’s filter protocol; a generic milter executable is not an OpenSMTPD filter. Preserve the existing TLS, actions, and relay restrictions when adding the filter. Validate both configurations with rspamadm configtest and smtpd -n, then test actual mail scanning and delivery.

Integration with Postfix #

To use Rspamd as a milter with Postfix:

In /etc/rspamd/local.d/worker-proxy.inc:

bind_socket = "127.0.0.1:11332";
milter = yes;

In /etc/postfix/main.cf:

smtpd_milters = inet:127.0.0.1:11332
non_smtpd_milters = inet:127.0.0.1:11332
milter_protocol = 6
milter_mail_macros = i {mail_addr} {client_addr} {client_name} {auth_authen}

Then restart Postfix:

doas postfix reload

Mail Scanning with rspamc #

The rspamc tool can be used to manually scan messages, train the Bayesian classifier, or check scores:

rspamc -h localhost:11333 < message.eml
rspamc learn_spam < spam.eml
rspamc learn_ham < ham.eml

Using Redis for Statistics #

Rspamd uses Redis for statistical storage and rate-limiting. Install and enable Redis:

doas pkg_add redis
doas rcctl enable redis
doas rcctl start redis

In /etc/rspamd/local.d/classifier-bayes.conf:

backend = "redis";
servers = "127.0.0.1";

Restart Rspamd:

doas rspamadm configtest && doas rcctl restart rspamd

DKIM Signing and Verification #

Signing Outgoing Mail #

Generate DKIM keys:

doas install -d -m 750 -o root -g _rspamd /etc/rspamd/dkim
doas sh -c 'umask 077; rspamadm dkim_keygen -d example.org -s mail -k /etc/rspamd/dkim/example.org.mail.key' > example.org.mail.dns.txt

Set permissions:

doas chown _rspamd:_rspamd /etc/rspamd/dkim/example.org.mail.key
doas chmod 0400 /etc/rspamd/dkim/example.org.mail.key

In /etc/rspamd/local.d/dkim_signing.conf:

domain {
  example.org {
    selector = "mail";
    path = "/etc/rspamd/dkim/example.org.mail.key";
  }
}

Publish the DKIM public key in DNS (output by dkim_keygen).

Verifying DKIM #

Rspamd verifies DKIM automatically if the dkim.conf module is enabled. Configuration is usually in /etc/rspamd/modules.d/dkim.conf.

DMARC and SPF #

Ensure the following modules are enabled and configured:

• /etc/rspamd/modules.d/dmarc.conf
• /etc/rspamd/modules.d/spf.conf

Ensure the resolvers in /etc/resolv.conf can answer the DNS queries required by these checks.

Bayes Training #

Rspamd learns spam and ham from messages. Submit them via rspamc:

rspamc learn_spam < spam.eml
rspamc learn_ham < ham.eml

Feed selected, correctly classified messages to these learning commands. Folder-based automation requires a separate, explicitly configured workflow; there is no generic learned module that watches mail folders.

Logging and Monitoring #

Logs are written to:

/var/log/rspamd/rspamd.log

Use rspamc stat to view live statistics:

rspamc stat

Use rspamadm configdump to inspect effective configuration:

doas rspamadm configdump

Security Considerations #

• Run Rspamd as _rspamd with limited privileges
• Use local sockets or restrict TCP listener access
• Protect the controller interface with strong passwords and IP restrictions
• Regularly update configuration files and rulesets
• Validate SPF, DKIM, and DMARC policies for incoming mail

File Locations #