# 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,spf,surbl,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";
"User-Agent",
"X-Mailer",
"Content-Type",
"X-MimeOLE",
];

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


## Global options

• filters: comma separated string that defines enabled internal Rspamd filters; for a list of the internal filters please check the modules page
• 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)
• 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.
• 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
• 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
• history_file: this file is automatically created and refreshed on shutdown to preserve the rolling history of operations displayed by the WebUI across restarts
• temp_dir: a directory for temporary files (can also be set via the environment variable TMPDIR).
• 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
• pid_file: file used to store PID of the Rspamd main process (not used with syst.html)
• 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
• control_socket: path/bind for the control socket
• classify_headers: list of headers that are processed by statistics
• history_rows: number of rows in the recent history table
• explicit_modules: always load modules from the list even if they have no configuration section in the file
• disable_hyperscan: disable Hyperscan optimizations (if enabled at compile time)
• cores_dir: directory where Rspamd should drop core files
• max_cores_size: maximum total size of core files that are placed in cores_dir
• max_cores_count: maximum number of files in cores_dir
• 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)
• neighbours: list of servers in Rspamd cluster
• disable_monitoring: if this flag is set to true then RBL monitoring is disabled completely

## DNS options

These options are in a separate subsection named dns and specify the behaviour of Rspamd name resolution. Here is a list of available tunables:

• nameserver: list (or array) of DNS servers to be used (if this option is skipped, then /etc/resolv.conf is parsed instead). It is also possible to specify weights of DNS servers to balance the payload, e.g.
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. Please 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 and changing configuration of all cluster members at once.

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 just sends the neighbours list to the web-browser. Everything else happens on the browser side. The web-browser makes HTTP requests directly to the neighbours on the list.

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 = ""; }
}


But if you are plannig to access WebUI on this host as well you should configure something sensible.

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.