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

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