Rspamd options settings

Introduction

The options section defines basic Rspamd behaviour. Options are global for all types of workers. Some default options are shown in the following example snippet:

filters = "chartable,dkim,regexp,fuzzy_check";
raw_mode = false;
one_shot = false;
cache_file = "$DBDIR/symbols.cache";
map_watch_interval = 5min;
map_file_watch_multiplier = 0.1;
dynamic_conf = "$DBDIR/rspamd_dynamic";
history_file = "$DBDIR/rspamd.history";
check_all_filters = false;
dns {
    timeout = 1s;
    sockets = 16;
    retransmits = 5;
}
tempdir = "/tmp";
url_tld = "${PLUGINSDIR}/effective_tld_names.dat";
classify_headers = [
	"User-Agent",
	"X-Mailer",
	"Content-Type",
	"X-MimeOLE",
];

control_socket = "$DBDIR/rspamd.sock mode=0600";

Global options

Option Description
allow_raw_input allow non MIME input for rspamd
cache_file used to store information about rules and their statistics; this file is automatically generated if Rspamd detects that a symbol’s list has been changed.
cache_reload how often cache reload should be performed (default: 30.0)
check_all_filters turns off optimizations when a message gains an overall score more than the reject score for the default metric; this optimization can also be turned off for each request individually
check_attachements treat text attachments as normal text parts
check_timeout maximum time for checking a message (alias for task_timeout)
classify_headers list of headers that are processed by statistics
compat_messages use pre 1.4 style of messages in the protocol
control_socket path/bind for the control socket
cores_dir directory where Rspamd should drop core files
disable_hyperscan disable Hyperscan optimizations (if enabled at compile time)
disable_monitoring if this flag is set to true then RBL monitoring is disabled completely
disable_pcre_jit disable PCRE JIT
dns_max_requests maximum DNS requests per task (default: 64)
dns_nameserver legacy option for DNS servers used
dns_retransmits legacy option for DNS retransmits count (default: 5)
dns_sockets legacy option for DNS sockets per server count
dns_timeout legacy option for DNS request timeout (default: 1.0)
dynamic_conf path to the dynamic configuration
enable_experimental enable experimental plugins
enable_shutdown_workaround enable workaround for legacy clients
enable_test_patterns enable test GTUBE like patterns (not for production!)
events_backend events backend to use: kqueue, epoll, select, poll or auto (default: auto)
explicit_modules always load modules from the list even if they have no configuration section in the file
filters comma separated string that defines enabled internal (not Lua) Rspamd filters; for a list of the internal filters please check the modules page
fips_mode enable FIPS 140-2 mode in OpenSSL
full_gc_iters task scanned before memory gc is performed (default: 0 - disabled)
heartbeat_interval time between workers heartbeats (default: 10.0)
heartbeats_loss_max maximum count of heartbeats to be lost before trying to terminate a worker (default: 0 - disabled)
history_file this file is automatically created and refreshed on shutdown to preserve the rolling history of operations displayed by the WebUI across restarts
history_rows number of rows in the recent history table (default: 200)
hs_cache_dir path directory where rspamd would save hyperscan cache
ignore_received ignore data from the first received header
images_cache size of DCT data cache for images (256 elements by default)
local_addrs or local_networks map or list of IP networks used as local, so certain checks are skipped for them (e.g. SPF checks)
lua_gc_pause lua garbage-collector pause (default: 200)
lua_gc_step lua garbage-collector step (default: 200)
map_file_watch_multiplier multiplier for map watch interval when map is file
map_watch_interval interval between map scanning; the actual check interval is jittered to avoid simultaneous checking, so the real interval is from this value up to 2x this value
maps_cache_dir directory to save maps cached data (default: $DBDIR)
max_blas_threads maximum number of Blas threads for learning neural networks (default: 1)
max_cores_count maximum number of files in cores_dir
max_cores_size maximum total size of core files that are placed in cores_dir
max_lua_urls maximum count of URLs to pass to Lua to avoid DoS (default: 1024)
max_message maximum size of the message to be scanned (50Mb by default)
max_opts_len maximum size of all options for a single symbol (default: 4096)
max_pic maximum size of the picture to be normalized (1Mb by default)
max_recipients maximum count of recipients to process to avoid DoS (default: 1024)
max_sessions_cache maximum number of sessions in cache before warning (default: 100)
max_shots maximum number of hits per a single symbol (default: 100)
max_urls maximum count of URLs to process to avoid DoS (default: 10240)
max_word_len maximum length of the word to be considered in statistics/fuzzy
min_word_len minimum size in letters (valid for utf-8 as well) for a sequence of characters to be treated as a word; normally Rspamd skips sequences if they are shorter or equal to three symbols
monitoring_watch_interval monitoring watch interval for the periodic checks of RBL and some other resources, 60 seconds by default
neighbours list of servers in Rspamd cluster
one_shot if this flag is set to true then multiple rule triggers do not increase the total score of messages (however, this option can also be individually configured in the metric section for each symbol)
pid_file file used to store PID of the Rspamd main process (not used with syst.html)
public_groups_only output merely public groups everywhere
raw_mode don’t try to convert all messages to utf8
rrd path to RRD file
sessions_cache enable sessions cache to debug dangling sessions
soft_reject_on_timeout emit soft reject if task timeout takes place
ssl_ca_path path to ssl CA file
ssl_ciphers list of ssl ciphers (e.g. HIGH:!aNULL:!kRSA:!PSK:!SRP:!MD5:!RC4)
stats_file path to stats file
task_timeout maximum time for checking a message
temp_dir a directory for temporary files (can also be set via the environment variable TMPDIR).
tld path to the TLD file for urls detector
trusted_keys list of trusted public keys used for signatures in base32 encoding
url_tld path to file with top level domain suffixes used by Rspamd to find URLs in messages; by default this file is shipped with Rspamd and should not be touched manually
vectorized_hyperscan use hyperscan in vectorized mode (experimental)
words_decay start skipping words at this amount
zstd_input_dictionary dictionary for zstd inbound protocol compression
zstd_output_dictionary dictionary for outbound zstd compression

DNS options

These options fall under a dedicated subsection called dns and control the name resolution behavior of Rspamd. Here is a list of available tunables:

  • nameserver: A list (or array) of DNS servers to be used. If this option is omitted, Rspamd will parse the /etc/resolv.conf file. Additionally, you can specify weights for DNS servers to balance the load. For example:
options {
	dns {
		# 9/10 on 127.0.0.1 and 1/10 to 8.8.8.8
		nameserver = ["127.0.0.1:53:10", "10.0.1.1:53:1"];
	}
}

You can also specify another configuration of DNS servers selection strategy using upstream syntax, e.g.:

options {
	dns {
		nameserver = "master-slave:127.0.0.1:53:10,8.8.8.8:53:1";
	}
}

In this case, 8.8.8.8 public resolver will be used as a backup when local resolver is down. It’s important to note that by default, Rspamd uses round-robin strategy which is also used when resolvers are read from /etc/resolv.conf.

  • timeout: timeout for each DNS request
  • retransmits: how many times each request is retransmitted before it is treated as failed (the overall timeout for each request is thus timeout * retransmits)
  • sockets: how many sockets are opened to a remote DNS resolver; can be tuned if you have tens of thousands of requests per second).

Neighbours list

The WebUI supports displaying and aggregating statistics from a cluster of Rspamd servers, as well as changing the configuration of all cluster members simultaneously.

On the Rspamd server at which you want to point your web-browser add a neighbours list to the local.d/options.inc:

neighbours {
    server1 { host = "host1.example.com"; }
    server2 { host = "host2.example.com"; }
    server3 { host = "10.10.10.10:11334"; }
}

There is no communication between the cluster members. Rspamd simply sends the neighbours list to the web browser, and all subsequent communication happens directly between the browser and the neighbours on the list via HTTP requests.

For some reason (ask @cebka on IRC about that) you should have such a list in the configuration of every other neighbour. Actually, it does not matter what is configured in the neighbours section on other servers of the cluster. There should be at least one host entry.

A dummy entry like this is enough:

neighbours {
    server1 {host = ""; }
}

However, if you plan to access the WebUI on this particular host, it is advisable to configure something more appropriate and relevant for that entry.

If you have a reverse proxy with TLS in front of Rspamd, you need to explicitly specify the protocol and port in the host directive:

neighbours {
    server1 { host = "https://host1.example.com:443"; }
    server2 { host = "https://host2.example.com:443"; }
}

Otherwise it defaults to http and 11334 respectively.

Also you can use the same host name but set different paths:

neighbours {
    server1 {
        host = "https://host.example.com:443";
        path = "/rspamd1";
    }
    server2 {
        host = "https://host.example.com:443";
        path = "/rspamd2";
    }
}

Upstream options

See this document for details.