An alternative introduction to rspamd configuration - a detailed information about Rspamd configuration files and their purposes from the sysadmin point of view: concentrating on two main questions “What is there to configure?” and “How do I configure things?”.
Own mail server based on Dovecot, Postfix, MySQL, Rspamd and Debian 9 Stretch - a good example of all-in-one tutorial about how to setup your own mail server. Please bear in mind that the advice of adding level = error to /etc/rspamd/local.d/logging.inc is not correct. You should use the default info in the most of the cases or silent if you merely want important information to be logged.
First of all, you need a working MTA that can send and receive email for your domain using SMTP protocol. In this guide, we describe the setup of the Postfix MTA. However, Rspamd can work with other MTA software - you can find details in the integration document. Exim MTA has a very limited support of Rspamd so it is not recommended to run Exim in conjunction with Rspamd.
It is strongly recommended to setup TLS for your mail system. We suggest to use certificates issued by Let’s Encrypt as they are free to use and are convenient to manage. You can read more about this topic in one of the guides available on the Internet, for instance, this one.
In this guide, we assume that all services have the same certificate which might not be desired if you want greater levels of security.
Postfix setup
We assume that you are installing Postfix with your OS’s package manager (e.g. apt install postfix). Here is the desired configuration for Postfix:
For IMAP we recommend to install Dovecot. For Debian based systems you can use the following packages:
apt install dovecot-imapd dovecot-sieve
Configuration of Dovecot (especially its authentication mechanisms) is a bit out of the scope for this guide but you can find many good guides at the Dovecot main site. By default, Dovecot uses Unix users in system and place mail into the standard mailbox /var/mail/username.
However, you should set up Postfix authentication. This lives in /etc/dovecot/conf.d/10-master.conf: make sure that you have uncommented the following lines in this file:
whitelisting of reply messages (storing reply message IDs to avoid certain checks for replies to our own sent messages)
Installation of Redis is quite straightforward: install it using the preferred way for your OS (e.g. from packages), start redis-server with the default settings (it should listen on the local interface using port 6379) and you are done.
We strongly recommend using a separate Redis instance for each module that stores non-volatile data, in particular for the statistical module (BAYES classifier) and fuzzy storage. A multi-instance Redis configuration simplifies some administration tasks (e.g. backup/restore) and makes possible to set memory limits and eviction policies, establish data replication between Rspamd installations. A detailed explanation of multi-instance Redis configuration can be found in the Redis replication tutorial.
You might also want to limit the memory used by Redis at some sane value:
maxmemory 500mb
and for non-volatile data Redis instances you might want to set volatile-ttl eviction policy:
maxmemory-policy volatile-ttl
Eviction of volatile data keys can cause undesirable effects.
Please bear in mind that Redis could listen for connections from all network interfaces. This is potentially dangerous and in most cases should be limited to the loopback interfaces, with the following configuration directive:
bind 127.0.0.1 ::1
For saving data to disk, it is also useful to setup overcommit memory behavior which might be useful for loaded systems. It could be done in Linux by using the following command:
echo 1 > /proc/sys/vm/overcommit_memory
Rspamd installation
The download process is described in the downloads page where you can find how to get Rspamd, how to install it in your system, and, alternatively, how to build Rspamd from the sources.
Running Rspamd
Platforms with systemd (Arch, CentOS 7, Debian, Fedora, Ubuntu)
Packaging should start rspamd and configure it to run on startup on installation.
You can verify it’s running as follows:
systemctl status rspamd
Configuring Rspamd
Though Rspamd’s default config aims to be useful for most purposes you may wish to make some adjustments to suit your environment/tastes.
Using of configwizard
From version 1.7, there is a configuration wizard available as rspamadm subcommand. This wizard can help you to configure the most commonly used features in Rspamd, for instance:
Redis server
Controller password
DKIM signing for outbound
To run the wizard, use the following command:
rspamadm configwizard
This tool will guide you interactively throughout the configuration process using CLI interface.
Manual configuration
First of all, please read the basic configuration principles here.
It is recommended to use the special include files that are referenced in the stock configuration. Conventionally every configuration file in /etc/rspamd/ will include two such includes:
# /etc/rspamd/modules.d/imaginary_module.conf
imaginary_module {
# there would probably be some settings in this area
.include(try=true,priority=1,duplicate=merge) "$CONFDIR/local.d/imaginary_module.conf"
.include(try=true,priority=10) "$CONFDIR/override.d/imaginary_module.conf"
}
Settings in local.d will be merged with stock configuration (where possible: ie. the setting is a list [] or collection {}) where-as settings in override.d will always replace the stock configuration. Unlike rspamd.conf.local and rspamd.conf.override, these include directives are effective inside a given block of configuration ({}). Similarly to rspamd.conf.override settings in override.d have higher priority than settings generated by the web interface, unlike local.d and rspamd.conf.local.
Overriding symbols scores and actions thresholds
You can read more about actions, scores and these configuration parameters in this explanation.
Since Rspamd 1.7, you can edit local.d/actions.conf for thresholds setup:
# local.d/actions.conf
reject = 150; # Reject when reaching this score
add_header = 6; # Add header when reaching this score
greylist = 4; # Apply greylisting when reaching this score (will emit `soft reject action`)
For symbols scores, you should redefine scores defined in scores.d/ directory where they are placed by a symbol’s group:
fuzzy_group.conf - fuzzy hashes scores
headers_group.conf - various headers checks
hfilter_group.conf - host filter symbols
mime_types_group.conf - mime types rules
mua_group.conf - MUA related rules
neural_group.conf - neural network produced scores
You can also change the weight of rules using the WebUI. To get the current information about symbols and scores, you can use rspamc counters command.
If you want to add your own rule or just change the score without taking extra care about groups, you can still use file local.d/groups.conf in the following way:
# /etc/rspamd/local.d/groups.conf
# Just scores for Rspamd defined symbols
symbols = {
"R_DKIM_ALLOW" = {
score = -0.1;
}
"BAYES_SPAM" = {
score = 5.0;
}
}
# Custom user defined symbols and groups
group "mygroup" {
symbols = {
"FOO" {
score = 20.0;
}
}
}
One more note about scores
There are two components of the final score in Rspamd:
score = runtime_score * static_score
Runtime score is a concept used to express confidence. For example, you
have IP reputation and it changes in range [-1;1] smoothly. Then you
tell that the static score for IP reputation is 3.0. Hence,
You should notice that individual files are included within sections:
module { .include "..."; }
Hence, you don’t need to repeat module { ... } inside the included file! Rspamd will issue an error in this case: nested section: module { module { ... } }, it is likely a configuration error.
In addition to equivalents to files in /etc/rspamd/modules.d the following includes are referenced in the stock configuration (both of local.d/override.d):
classifier-bayes.conf: included inside classifier "bayes" {} block
logging.inc: included inside logging { }
options.inc: included inside options { }
worker-normal.inc: included inside normal worker {} block
worker-controller.inc: included inside controller worker {} block
worker-proxy.inc: included inside rspamd_proxy worker {} block
Setting listening interface
Rspamd’s normal worker will, by default, listen on all interfaces on port 11333. From Rspamd 1.7.4, it has changed to localhost by default.
If you’re running Rspamd on the same machine as your mailer (or whatever will be querying it) you might want to set this to ‘localhost’ instead. This option should be defined in /etc/rspamd/local.d/worker-normal.inc:
If you plan to leave this as is you may wish to use a firewall to restrict access to your machine. Please review the worker documentation for more information about bind_socket and related settings.
Rspamd controller worker listens on the port 11334 by default, and the proxy worker uses port 11332 accordingly.
Because Rspamd skips some checks for local networks, you may want to tune global local_addrs map.
Rspamd requires a password when queried from non-trusted IPs, except for scanning messages which are unrestricted (the default config trusts the loopback interface). This is configured in the file /etc/rspamd/local.d/worker-controller.inc.
You should store an encrypted password for better security. To generate such a password just type
$ rspamadm pw
Enter passphrase:
$2$g95ywihfinjqx4r69u6mgfs9cqbfq1ay$1h4bm5uod9njfu3hdbwd3w5xf5d9u8gb7i9xnimm5u8ddq3c5byy
The config to be modified is shown below (replace ‘q1’ with your chosen password):
Optionally you may set enable_password - if set, data-changing operations (such as Bayes training or fuzzy storage) will require this password. For example:
From version 1.7, the setting of passwords is also suggested by rspamadm configwizard.
Important information: the default passwords (namely, q1 and q2) are BANNED, so you cannot use them in your installation. Please set the appropriate passwords before using the controller. This is done to prevent an occasional data leak caused by misconfiguration.
Setting up the WebUI
WebUI is managed by a controller worker but you might want to proxy its requests using Nginx, for example, to add TLS support. Here is a minimal setup required for nginx to do that:
Alternatively, you could set up HTTP authentication in Nginx itself.
Using of Milter protocol (for Rspamd >= 1.6)
From Rspamd 1.6, rspamd proxy worker supports the milter protocol which is supported by some of the popular MTA, such as Postfix or Sendmail. The introducing of this feature also finally obsoletes the rmilter project in honor of the new integration method. Milter support is presented in rspamd_proxyonly, however, there are two possibilities to use milter protocol:
Proxy mode (for large instances) with a dedicated scan layer
Self-scan mode (for small instances)
Here, we describe the simplest self-scan option:
In this mode, rspamd_proxy scans messages itself and talks to MTA directly using the Milter protocol. The advantage of this approach is its simplicity. Here is a sample configuration for this mode:
# local.d/worker-proxy.inc
milter = yes; # Enable milter mode
timeout = 120s; # Needed for Milter usually
upstream "local" {
default = yes; # Self-scan upstreams are always default
self_scan = yes; # Enable self-scan
}
count = 4; # Spawn more processes in self-scan mode
max_retries = 5; # How many times master is queried in case of failure
discard_on_reject = false; # Discard message instead of rejection
quarantine_on_reject = false; # Tell MTA to quarantine rejected messages
spam_header = "X-Spam"; # Use the specific spam header
reject_message = "Spam message rejected"; # Use custom rejection message
For more advanced proxy usage, please see the corresponding documentation.
Setup Redis statistics
From version 1.1, it is also possible to specify Redis as a backend for statistics and caching of learned messages. Redis is recommended for clustered configurations as it allows simultaneous learning and checking and, besides, is very fast. To set up Redis, you could specify redis backend for a classifier (cache is set to the same servers accordingly).
Another feature of Rspamd is dynamic map support. Maps are lists of values, for example, domain names or IP/networks listed in an external file or by HTTP that are periodically monitored by Rspamd and reloaded in case of updates. This technique is useful for writing your own rules, whitelisting or blacklisting some networks and so on. The important difference with maps is that Rspamd restart is not required when those lists are changed. Maps are defined as URI strings:
http://example.com/file.map - HTTP map (server should respect If-Modified-Since header to avoid unnecessary updates)
file:///path/to/map - file map
/path/to/map - alternative syntax for file map
All maps behaves in the same way so you can have some choices about how to define a map:
Plain path to file or http (like map = "http://example.com/file.txt" or map = "/tmp/mymap")
Composite path like map = ["http://example.com/file.txt", "/tmp/mymap"]. Maps data is concatenated from the sources.
An embedded map like map = ["foo bar"]; or map = ["foo 1", "bar b", "baz bababa"] or map = ["192.168.1.1/24", "10.0.0.0/8"]
A fully decomposed object with lots of options
For the second option it is also possible to have a composite path with a fallback:
In the example above fallback+file://${CONFDIR}/2tld.inc will be used when the first composite backend is somehow unreachable (e.g. when the first load of Rspamd or all elements are invalid).
Bear in mind that (1) and (3) can only be distinguished by making an array-like map = ["192.168.1.1/24"]
Historically just for the radix map (IP network ones) you could also use map = "192.168.1.1/24" but it is not recommended.
Within maps, you can use whitespace or comments. For example, here is an example of IP/network map:
# Example map
127.0.0.1 # localhost
10.0.0.0/8
fe80::/64
There is a special module called multimap that allows you to define your maps without writing Lua rules. You can check the module’s documentation and create your configuration in local.d/multimap.conf.
Configuring RBLs
Though Rspamd is free to use for any purpose many of the RBLs used in the default configuration aren’t & care should be taken to see that your use cases are not infringing. Notes about specific RBLs follow below (please follow the links for details):
Abusix Mail Intelligence - Free for home/non-commercial use up to 100k queries per day (requires registration), commercial use requires a subscription
DNSWL - Commercial use forbidden (see link for definition); Limit of 100k queries per day
Mailspike - Limit of 100k messages or queries per day
Rspamd URIBL - Commercial use forbidden (see link for definition); Limit of 250k queries per day
SORBS - Limit of 100k users or more than 5 messages per second sustained
SpamEatingMonkey - Limit of 100k queries per day or more than 5 queries per second for more than a few minutes
Spamhaus - Commercial use forbidden (see link for definition); Limit of 300k queries or 100k SMTP connections per day
SURBL - Commercial use forbidden (see link for definition); Limit of 1k users or 250k queries per day
UCEProtect - If you’re sending 100k queries or more per day you should use the (free) Rsync service.
URIBL - Requires a commercial subscription if ‘excessive queries’ are sent (numbers unclear).
Refer to the RBL module documentation for information about disabling RBLs/SURBLs.
Using Rspamd
Using rspamc console routine
rspamc implements a feature-complete client for Rspamd. For detailed documentation refer to man rspamc.
Rspamadm is a new utility that is intended to manage rspamd directly. It comes with embedded help that can be displayed by typing:
% rspamadm help
Rspamadm 2.6
Usage: rspamadm [global_options] command [command_options]
Available commands:
configdump Perform configuration file dump
configgraph Produces graph of Rspamd includes
confighelp Shows help for configuration options
configtest Perform configuration file test
configwizard Perform guided configuration for Rspamd daemon
control Manage rspamd main control interface
cookie Produces cookies or message ids
corpustest Create logs files from email corpus
dkim_keygen Create dkim key pairs
dnstool DNS tools provided by Rspamd
fuzzyconvert Convert fuzzy hashes from sqlite3 to redis
grep Search for patterns in rspamd logs
keypair Manages keypairs for Rspamd
lua Run LUA interpreter
mime Mime manipulations provided by Rspamd
pw Manage rspamd passwords
signtool Sign and verify files tool
statconvert Convert statistics from sqlite3 to redis
template Apply jinja templates for strings/files
vault Perform Hashicorp Vault management
For example, it is possible to get help for a specific configuration option by typing something like
rspamadm confighelp -k fuzzy
See here for more information about rspamadm utilities.
Using mail system utilities
It is also useful to have a simple Sieve script to place all messages marked as spam in the Junk folder. Here is an example of such a script (~/.dovecot.sieve):
You can also setup rspamc to learn via passing messages to a certain email address. I recommend using /etc/aliases for these purposes and mail-redirect command (e.g. provided by Mail Redirect addon for Thunderbird MUA). The desired aliases could be the following:
You’d need some less predictable aliases to avoid sending messages to such addresses by some adversary or just by a mistake to prevent statistics pollution.
There is also an add-on for Thunderbird MUA written by Alexander Moisseev to visualise Rspamd stats. You can download the latest version from its homepage or a version reviewed by moz://a from Tunderbird Add-ons page. You’d need to add extended spam headers (X-Spamd-Result) with Rspamd proxy worker and/or (from add-on’s version 0.8.0) X-Spam-Score and X-Spam-Report headers with Exim to make the whole setup work.
To enable extended spam headers in Milter headers module add the following line to local.d/milter_headers.conf:
extended_spam_headers = true;
To enable headers in Exim refer to the “Integration with Exim MTA” section of the MTA integration document.
Here is a screenshot of this addon in use:
Using the WebUI
Rspamd has a built-in WebUI which supports setting metric actions and scores; Bayes training and scanning messages - for more information see the WebUI documentation.
Using Rspamd in large email systems
Rspamd has been designed to be used in large scale email systems. It supports various features to simplify processing emails for thousands or millions of users. However, the default settings are quite conservative to provide a suitable experience for small grade systems.
First of all, you are strongly advised to get the official Rspamd packages from rspamd.com site if you use Debian derived Linux. They are heavily optimized in terms of performance and features. For users of other platforms, it is advised to ask Rspamd support (mailto://support@rspamd.com) about your specific demands. Maybe there are optimized packages for your specific platform that is not automatically built yet.
Secondly, you need to setup Redis. Normally, you need two types of Redis instances:
Master-slave replicated instances for persistent data: statistics, fuzzy hashes, neural networks. These instances are mostly read-only so you can split your load over read-only slaves.
Non-replicated but (probably) sharded instances for volatile data: greylisting, replies, IP reputation, and other temporary stuff. These instances are not required to be persistent and they could be scaled by sharding that is automatically performed by Rspamd if you specify multiple servers. These instances have mixed read-write payload.
You might also want to enable the following modules:
IP score: IP reputation module, requires volatile Redis instance (or shared volatile Redis instance). In some cases, it can provide your results common to the expensive IP DNS blacklists. However, it also depends on the quality of your rules and your scale.
Neural networks: this module provides significant improvement for your filtering quality but it requires CPU resources (SandyBridge or newer Intel CPUs are strongly adviced) and somehow good rules set. It also requires some setup and a persistent Redis instance. From version 2.0 Rspamd uses libkann for neural networks which demonstrates better performance and preciseness than the pre 1.7 implementations based on libfann. Here is a minimal setup for neural networks module:
# local.d/neural.conf
servers = "redis:6384";
timeout = 25s; # Sometimes ANNs are very large
train {
max_trains = 1k; # Number ham/spam samples needed to start train
max_usages = 20; # Number of learn iterations while ANN data is valid
spam_score = 8; # Score to learn spam
ham_score = -2; # Score to learn ham
learning_rate = 0.01; # Rate of learning
max_iterations = 100; # Maximum iterations of learning (better preciseness but also lower speed of learning)
}
ann_expire = 2d; # For how long ANN should be preserved in Redis
Ratelimit: this module is very useful to limit spam waves as it allows to temporary delay senders that have either bad reputation or send messages too aggressively without somehow a good reputation. Requires a volatile Redis instance.
Replies: whitelists replies to your user’s mail. It is very useful to provide users instant communication with known recipients. Requires a volatile Redis instance.
URL redirector: resolves URL redirects on some common redirectors and URLs shorteners, e.g. t.co or goo.gl. Requires a volatile Redis instance.
Clickhouse: saves analytical data to the Clickhouse server. Clickhouse server can be used thereafter to create new filtering rules or maintaining blacklists. You can treat it as an advanced Syslog with indexes and complex analytics queries. There are also graphical interfaces available for Clickhouse, e.g. Redash
