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;
}
upstream {
    resolve_min_interval = 60;
}
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 where 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 direct communication between cluster members. Rspamd sends the neighbours list to the web browser, and all subsequent communication occurs directly between the browser and the listed neighbours via HTTP requests.

Rspamd adds the Access-Control-Allow-Origin: * header if at least one server is configured in the neighbours section. Therefore, including at least one valid entry is necessary. The specifics of the neighbours configuration on other servers are not important, as long as there is at least one valid entry.

A minimal configuration with a dummy entry can look like this:

neighbours {
    server1 { host = ""; }
}

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

If you have a reverse proxy with TLS in front of Rspamd, 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"; }
}

By default, the protocol is http and the port is 11334.

Additionally, you can use the same hostname but specify different paths for different servers:

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

Upstreams options

Upstreams logic and settings are described in the dedicated document. Options for upstreams fall under a dedicated subsection called upstream and control their behaviors in Rspamd. Here is a list of available tunables:

• error_time (defaults to 10): timeframe to check errors in seconds
• max_errors (defaults to 4): maximum count of errors during error_time to consider the upstream as down
• revive_time (defaults to 60): time in seconds before attempting to recover an upstream after it has faced max_errors and has been marked as unhealthy
• lazy_resolve_time (defaults to 3600, which is 1 hour): time in seconds to resolve upstream addresses in lazy mode
• resolve_min_interval (defaults to 60): minimum interval in seconds to perform resolving upstream DNS resolution