This document includes some questions and practical examples that are frequently asked by Rspamd users.

## General questions

### Where to get help about Rspamd

The most convenient place for asking questions about Rspamd is the IRC channel #rspamd on http://freenode.net. For more information you can also check the support page

Back to content

### What versions of Rspamd are supported

There are usually two supported branches in Rspamd git repo: the stable (rspamd-<version>) and the development (namely, master) ones. Stable releases are usually cut from the stable branch. Unstable or mainline releases are cut from the master branch. Once the new major release is ready for switching to the stable stage, the support for old stable branch is finished and all users are advised to switch to the new stable branch. Old releases and old stable branches are NOT supported by the project.

Back to content

### Using of the experimental packages

Experimental packages are usually cut from the master branch and there are no exact change logs or release notes. However, all experimental packages include git hash, so you can easily get all changes by using the following command:

git log <old_hash>..<new_hash>


Experimental packages are considered less stable but they are normally built when all internal tests are passed. These packages also include new major and minor features that might be useful for your setup.

Back to content

### How Rspamd packages are built

Rspamd packages are provided for many platforms. The packages are built using the following principles:

1. Enable link time optimizations where possible to improve the overall performance
2. Bundle LuaJIT using 2.1 beta versions from the vendor. This provides up to 30% improvement over the vanilla LuaJIT normally available in your distributive.
3. Enable jemalloc
4. Enable neural networks support (libfann before 1. 7, torch after 1.7)
5. Support Hyperscan

Some of these options are not available on some older platforms (Debian wheezy, Ubuntu Precise or CentOS 6) due to limitations of software provided.

All packages are signed and should also be downloaded using https.

Back to content

### Resolver setup

DNS resolving is a very important part of the spam filtering since a lot of information is obtained from DNS lists, e.g. IP and URL blacklists, whitelists, reputation data and so on and so forth. Hence, Rspamd will be totally broken in case: it might even refuse to start. Furthermore, if you are using your provider’s resolver or some public resolver you might be affected by blocking from the vast majority of DNS lists providers or even corrupted results. It is known that Rspamd is broken when your provider’s DNS returns some IP address to redirect your browser to instead of the real response.

Hence, it is strongly recommended to have your own recursive resolver when using Rspamd (or any other email related technology in fact). Our own recommended choice is to set up Unbound. You can read about it here.

Then you can either set your local resolver globally via /etc/resolv.conf or set it explicitly for Rspamd in local.d/options.inc file:

 # local.d/options.inc
dns {
nameserver = ["127.0.0.1"];
}


Back to content

### How to figure out why Rspamd process crashed

Like other programs written in C language, the best way to debug these problems is to obtain core dump. Unfortunately, there is no universal solution suitable for all platforms, however, for FreeBSD and Linux you could do the following:

First of all, you need to create a special directory for core files that will be writeable by all users on the system:

mkdir /coreland
chmod 1777 /coreland


It is also good idea is to add the following settings to /etc/sysctl.conf and then run sysctl -p to apply them:

Linux sepcific

sysctl kernel.core_pattern=/coreland/%e.core


or (with PID)

sysctl kernel.core_pattern=/coreland/%e-%p.core


sysctl kernel.core_uses_pid=1
sysctl fs.suid_dumpable=2


FreeBSD specific

For FreeBSD you can have either one core for all processes by setting:

sysctl kern.corefile=/coreland/%N.core


or a separate core for each crash (that includes PID of process):

sysctl kern.corefile=/coreland/%N-%P.core


sysctl kern.sugid_coredump=1


#### Setting system limits

In distros with traditional SysV init, you can use the service init file, for example /etc/init.d/rspamd to permit dumping of core files by setting the appropriate resource limit. You will need to add the following line:

ulimit -c unlimited


just after the heading comment. On FreeBSD you can use the file /usr/local/etc/rc.d/rspamd in the same way.

A good way to test the core files setup is sending a SIGILL signal to a process. For example, run pkill --signal 4 rspamd or kill -s 4 <YOUR_PID> and then check the /coreland directory for a core dump.

#### Systemd notes

On a distro with systemd (most mainstream Linux distros), things are a bit different. First, you will need to edit the file /etc/systemd/system.conf and uncomment the DefaultLimitCORE parameter to enable systemd core dumps:

DefaultLimitCORE=infinity


After this, you will need to run systemctl daemon-reload to reread the configuration followed by systemctl daemon-reexec to apply it.

Back to content

### How to limit number of core files

Rspamd can stop dumping cores upon reaching a specific limit. To enable this functionality you can add the following lines to /etc/rspamd/local.d/options.inc:

That will limit the combined size of files in the /coreland/ directory to 1 gigabyte. After reaching this limit, Rspamd will stop dumping core files. (Please note that Rspamd cannot distinguish its own core files from other core files in a system.)

Back to content

### What can I do with core files

In most cases, it is enough to open core file with gdb or another debugger, such as lldb:

gdb which rspamd -c /coreland/rspamd.core
lldb which rspamd -c /coreland/rspamd.core


If a core file has been opened without errors then you can type bt full in the debugger command line to get the full stack trace that caused this particular error.

Back to content

### Why do I have zero score for a spam message

This is a very frequent question that comes from Rspamd users. The typical log sample looks like this one:

2018-08-27 13:23:11 #29623(normal) <xxx>; task; rspamd_task_write_log: id: <xxx@xxx.com>, qid: <xxx>, ip: xx.xx.xx.xx, from: <info@xxx.xxx>, (default: F (soft reject): [0.00/15.00] [DBL_SPAM(6.50){xxx.dbl.spamhaus.org;},URIBL_SBL_CSS(6.50){xxx.xxx;},RBL_SPAMHAUS_CSS(2.00){xx.xx.xx.xx.zen.spamhaus.org : 127.0.0.3;},RECEIVED_SPAMHAUS_CSS(1.00){116.179.76.62.zen.spamhaus.org : 127.0.0.3;},GREYLIST(0.00){greylisted;Mon, 27 Aug 2018 10:28:11 GMT;new record;}), len: xx, time: 978.464ms real, 15.045ms virtual, dns req: 45, digest: <xxx>, rcpts: <x@x.x>, mime_rcpts: <x@x.x.>


Actually, Rspamd treats scores internally and no external services should depend on those scores. Generally, you need to use merely action to decide what to do with this or that message. For example, in the example above, greylisting module decided that we need to greylist a message and build somehow better confidence about this particular message. MTA, in turn, should emit a temporary error in this case. Scores should be used to understand the decision process but they should not be treated to make an action with a message - that’s a rule of thumb.

Back to content

### Why can I have different results for the same message

If your message has gained a reject score, Rspamd will stop further checks to save resources. However, some checks, such as network checks, could still occur as they might be started before reaching this threshold for the message. Therefore, sometimes you might see different (but all greater than or equal to the reject threshold) results for the same message. To avoid this behaviour you can set the HTTP header

Pass: all


when making a request to Rspamd (which is equal to -p flag for rspamc client).

Another possible reason for different results is too low a DNS, or task, timeout setting so asynchronous rules can’t get results before being killed by a timeout. To get help about the relevant options you can type the following commands:

rspamadm confighelp options.dns


and more generally:

rspamadm confighelp -k timeout


Back to content

### How to debug some module in Rspamd

If you are unaware about some functions of Rspamd modules then it is usually useful to enable debugging for this module. To do that, write something like:

Please bear in mind that some modules do not produce any useful debug so far.

Back to content

### How to report bugs found in Rspamd

If your issue is related to crashes, then you need to obtain core file prior to reporting. It is also useful to explain when a crash occurs and, if relevant, provide some minimal test message and/or problematic config.

For issues about the rules, we usually need a message sample that causes a problem. To protect your privacy, you can remove unrelevant headers and content. E.g. you can blind message sender/recipients, subject and/or other fields.

For issues with SPF, we need SMTP From (or Helo) and sender’s IP address.

For issues with statistics, DKIM or ARC we unfotunately need a full message with all headers and content being preserved.

Without message samples, your bug reports will not be considered unless you provide either patch or a bug is tirvial by its nature.

Finally, we always prefer patches/pull requests to plain bug reports.

To report bugs or suggest something about the documentation or the web site, please take a look at this Github repo.

Back to content

### What is the difference between rspamc and rspamadm

rspamadm is an administration tool that works with the local Rspamd daemon via a unix socket and performs management tasks. You can get help for this tool, and its options, by typing:

rspamadm help


rspamc is a client for an Rspamd remote daemon. It can communicate with an Rspamd scanner process or Rspamd controller process using the HTTP (with optional encryption) protocol, getting and displaying the results. It can do tasks such as scanning, learning and getting statistics:

rspamc message.eml # Scan a message
rspamc learn_spam message.eml # Learn message
rspamc -f 1 -w 10 fuzzy_add message.eml # Add message to fuzzy storage


Back to content

### How does Rspamd support different characters sets

By default, Rspamd converts all messages to UTF-8 encoding. This includes text parts (both text/plain and text/html), headers and MIME elements (boundaries, filenames). If there is no information on how to convert something to UTF-8 - for example, when there is no charset attribute in the Content-Type header or if there are some broken UTF-8 characters - then Rspamd treats this text as raw for safety considerations. The difference between raw and UTF-8 text is that for UTF-8 it is possible to use unicode regular expressions by specifying the /U flag. For raw texts, Rspamd uses raw complementary expressions, which may lack some features.

It is always safe to assume that everything will be encoded in UTF-8; even in the case of raw messages, you would just miss some particular features. There is also a module called chartable that checks for different unicode (or ASCII - non ASCII characters in raw mode) symbols and tries to guess if there is an attempt to mix characters sets.

Back to content

### Can I relearn messages for fuzzy storage or for statistics

In case you need to move a hash from one list (e.g. blacklist) to another (e.g. whitelist), you need to call the rspamc fuzzy_del command for the first list (lists are identified by number) followed by rspamc fuzzy_add command:

rspamc -f 1 fuzzy_del message.eml
rspamc -f 2 -w <weight> fuzzy_add message.eml


If you just need to increase a score, then call fuzzy_add with the score change. (It is not possible to decrease a score, however.)

Statistics are treated a bit differently. Rspamd keeps hashes of tokens learned in a special storage called the learn_cache. If Rspamd finds that a particular token combination has been learned already it does the following:

• if the class of tokens is the same (e.g. spam and spam) then Rspamd just refuses to learn these tokens again
• otherwise, Rspamd performs so-called relearning:
• scores in the current class are decreased for this token set
• scores in the opposite class are increased for this token set
• the class of tokens in the learn cache is updated accordingly

All these actions are performed automatically if learn_cache is enabled. (It is highly recommended to enable this setting, as repeated learnings will affect the performance of the statistical module.)

Back to content

### Why do some symbols have different scores for different messages

Rspamd supports so-called dynamic symbols. A metric score is multiplied by some value (that is usually in the range [0..1]) and added to the scan result. For example, the Bayes classifier adds a score based on probability:

• if the probability is close to 50% then the score is very close to 0
• if the probability is higher [50% .. 75%] then the score increases gradually
• when the probability is closer to 90% the symbol’s score is close to 0.95 and on 100% it is exactly 1.0
• this logic is reversed for HAM probability (from 50% to 0% spam probability)

Many Rspamd rules, such as PHISHING and fuzzy checks, use dynamic scoring.

Back to content

### Can I check a message with Rspamd without rspamc

curl --data-binary @- http://localhost:11333/symbols < file.eml


Back to content

### How is Rspamd spelled and capitalized?

Rspamd as a spam-filtering system or as a project is spelled with a capital R followed by a lower-case spamd, but when referring to the process or application it is not capitalized.

Back to content

## Configuration questions

### Rspamd does not work as expected

Please check your configuration using rspamdadm configdump. You can narrow search by specifying the specific module:

rspamadm configdump fuzzy_check


Back to content

### Rspamd still does not work as expected

Have you added an extra section_name {} to local.d/section.conf file? For example, this one will NOT work:

The correct version is the following:

Back to content

### What are Rspamd actions

Unlike SpamAssassin, Rspamd suggests the desired action for a specific message scanned. This could be treated as a recommendation to MTA what it should do with this message. Here is a list of possible choices that are sent by Rspamd:

• discard: drop an email but return success for sender (should be used merely in special cases)
• reject: ultimately reject message
• rewrite subject: rewrite subject to indicate spam
• add header: add specific header to indicate spam
• no action: allow message
• soft reject: temporarily delay message (this is used, for instance, to greylist or ratelimit messages)

This might be a bit confusing but internally Rspamd operates with rules. Each rule can add positive or negative score to the result. Therefore it is required to have some thresholds for actions that are applied to a message. These thresholds are defined in metric.actions section:

As you can see, it is slightly different from the real actions list. The name actions should actually be treated as score thresholds but it has this name historically. As you can see, there is no discard and soft reject actions but there is a very special greylist element that specifies score threshold for greylisting plugin.

Thresholds usually define when this or that action should be applied. However, some modules can directly set a specific action without regard of the score-based thresholds. Hence, you should never ever rely on score when making a decision about what to do with a message scanned by Rspamd. In short, you should always use action and use scoring just to specify generic thresholds and for debugging purposes. There is completely no guarantee that score, action threshold and the real action will match for a message.

Back to content

### What are local and override config files

Historically, Rspamd provided user-editable configuration files. However, as the project developed, it became clear that this idea certain had drawbacks. Rspamd configuration defines the overall filtering quality, performance and other important characteristics. However, it is extremely difficult to maintain merging of local and updated configurations with new releases of Rspamd. Hence, we have decided to add two recommended ways to apply local changes:

1. Override configurations
2. Local configurations

An override configuration (/etc/rspamd/rspamd.conf.override) is used to ultimately redefine the default values in Rspamd. In this file, you can redefine whole sections of the default configuration. For example, if you have a module example defined in the default configuration as follows:

and you wanted to override option2 by adding the following to /etc/rspamd/rspamd.conf.override:

this might work unexpectedly: the new config would have an example section with a single key option2, while option1 would be ignored. The global local file, namely rspamd.conf.local, has the same limitation: you can add your own configuration there but you should NOT redefine anything from the default configuration there or it will just be ignored. The only exception to this rule is the metric section. So you could use something like:

and add this to the rspamd.conf.local (but not override).

Back to content

### What are the local.d and override.d directories

From Rspamd version 1.2 onwards, the default configuration provides two more ways to extend or redefine each configuration file shipped with Rspamd. Each section definition includes two files with different priorities:

• /etc/rspamd/local.d/<conf_file> - included with priority 1 that allows you to redefine and extend the default rules; but dynamic updates or items redefined via the WebUI will have higher priority and can redefine the values included
• /etc/rspamd/override.d/<conf_file> - included with priority 10 that allows you to redefine all other things that could change configuration in Rspamd

Types of settings which can be merged are collections ({}) and lists ([]); other settings would be effectively overridden by either file.

An important difference from the global override and local rules is that these files are included within each section. Here is an example of utilizing local.d for the modules.d/example.conf configuration file:

in local.d/example.conf:

in override.d/example.conf:

and the target configuration (that you could see using rspamadm configdump example):

Here is another example with more complicated structures inside. Here is the original configuration:

and there is some local.d/orig.conf that looks like this:

then we will have the following merged configuration:

If you have the same config but in override.d directory, then it will completely override all rules defined in the original file:

This looks complicated but it allows smoother updates and simplifies automatic management. If you are unsure about your configuration, then take a look at the output of the rspamadm configdump command, which displays the target configuration with many options available, and the rspamadm confighelp command which shows help for many Rspamd options.

Back to content

### What are rspamd.conf.local and rspamd.conf.override

While override.d and local.d replace entries inside block elements, rspamd.conf.local and rspamd.conf.override operate on whole blocks ({}).

What distinguishes these files is the way in which they alter the configuration - rspamd.conf.local adds or merges config elements (and is useful, for example, for setting custom metrics) while rspamd.conf.override adds or replaces config elements (and is useful for redefining settings completely).

Back to content

### What are maps

Maps are files that contain lists of keys or key-value pairs that could be dynamically reloaded by Rspamd when changed. The important difference to configuration elements is that map reloading is done ‘live’ without and expensive restart procedure. Another important thing about maps is that Rspamd can monitor both file and HTTP maps for changes (modification time for files and HTTP If-Modified-Since header for HTTP maps). So far, Rspamd supports HTTP and file maps.

Back to content

### What can be in the maps

Maps can have the following objects:

• spaces and one line comments started by # symbols
• keys
• optional values separated by a space character
• keys with spaces enclosed in double quotes
• keys with slashes (regular expressions) enclosed in slashes

Here are some examples:

key1 # Single key
# Comment ignored

# Empty line ignored
key2 1 # Key and value
"key3 with space"
"key with \" escaped" value with spaces


Regexp maps:

/regexp/i
/regexp/is some other value


IP maps:

192.168.0.1 # Mask is /32
[::1]/64
192.168.0.1/19


Back to content

### How to sign maps

From Rspamd version 1.2 onwards, each map can have a digital signature using the EdDSA algorithm. To sign a map you can use rspamadm signtool and to generate a signing keypair - rspamadm kyypair -s -u:

Then you can use signtool to edit the map file:

rspamadm signtool -e --editor=vim -k <keypair_file> <map_file>


To enforce signing policies you should add a sign+ string to your map definition:

map = "sign+http://example.com/map"


To specify the trusted key you could either put the public key from the keypair in the local.d/options.inc file as following:

trusted_keys = ["<public key string>"];


or add it as a key definition in the map string:

map = "sign+key=<key_string>+http://example.com/map"


Back to content

### What are one-shot rules

In Rspamd, each rule can be triggered multiple times. For example, if a message has 10 URLs and 8 of them are in some URL blacklist (based on their unique tld), then Rspamd would add a URIBL rule 8 times for this message. Sometimes, that’s not a desired behaviour - in that case just add one_shot = true to the symbol’s definition in the metric for that symbol and the symbol won’t be added multiple times.

Back to content

### What is the use of symbol groups

Symbol groups are intended to group similar rules. This is most useful when group names are used in composite expressions such as gr:<group_name>. It is also possible to set a joint limit for the score of a specific group:

In this case, if test1 and test2 both match, their joint score won’t be more than 15.

Back to content

### Why are some symbols missing in the metric configuration

It is now possible to set up rules completely using Lua. This allows setting all necessary attributes without touching the configuration files. However, it is still possible to override the default scores in any configuration file. Here is an example of such a rule:

rspamd_config.LONG_SUBJ = {
if sbj and util.strlen_utf8(sbj) > 200 then
return true
end
return false
end,

score = 3.0,
description = 'Subject is too long'
}


You can use the same approach when writing rules in rspamd.local.lua.

Back to content

### How can I disable some Rspamd rules safely

The best way is to add a condition for the specific symbol. This could be done, for example, in /etc/rspamd/rspamd.local.lua:

rspamd_config:add_condition('SOME_SYMBOL', function(task) return false end)


You can add more complex conditions but this one is the easiest in terms of rules management and upgrades.

Additionally you can dynamically selectively enable/disable symbols with settings module.

To disable an entire module you can set enabled = false in its configuration.

Back to content

### Can I scan outgoing mail with Rspamd

Yes, Rspamd should be safe for outbound scanning by default, see here for detail.

Back to content

### Can I just sign messages using DKIM

Yes, use user settings and enable just DKIM_SIGN symbol (and DKIM_SIGNED in case if dkim_signing module is used), e.g.

In this sample, we disable all checks with the exception of DKIM/ARC check and signing. This will work in case of authenticated user, local network (2 networks in this sample) or by passing a special HTTP header when doing manual check:

rspamc --header="settings-id=dkim" message.eml


Back to content

### Where can I find all configuration options supported by Rspamd

You can use rspamadm confighelp to get a description of options supported by Rspamd. You can either specify a specific option or path: rspamadm confighelp options or search some keyword: rspamadm confighelp -k servers. Please read rspamadm help confighelp for the list of command line options available for this command.

Back to content

### How to read Rspamd logs

Rspamd logs are augmented, meaning that each log line normally includes a tag which can help to figure out log lines that are related to, for example, a specific task:

# fgrep 'b120f6' /var/log/rspamd/rspamd.log

2016-03-18 15:15:01 #29588(normal) <b120f6>; task; accept_socket: accepted connection from 127.0.0.1 port 52870
2016-03-18 15:15:01 #29588(normal) <b120f6>; task; rspamd_message_parse: loaded message; id: <201603181414.u2IEEfKL062480@repo.freebsd.org>; queue-id: <D4CFE300135>
2016-03-18 15:15:01 #29588(normal) <b120f6>; task; rspamd_task_write_log: id: <201603181414.u2IEEfKL062480@repo.freebsd.org>, qid: <D4CFE300135>, ip: 2001:1900:2254:206a::19:2, from: <owner-ports-committers@freebsd.org>, (default: F (no action): [-2.11/15.00] [MIME_GOOD,R_SPF_ALLOW,RCVD_IN_DNSWL_HI,MAILLIST,BAYES_HAM,FANN_SCORE,FORGED_RECIPIENTS_MAILLIST,FORGED_SENDER_MAILLIST]), len: 6849, time: 538.803ms real, 26.851ms virtual, dns req: 22


Normally, you might want to check the final log line, for example, rspamd_task_write_log and subsequently find the tag which is b120f6 in this example. Thereafter, you can check all log messages that are associated with this message.

Back to content

### Can I customize log output for logger

Yes, there is log_format option in logging.inc. Here is a useful configuration snippet that allows you to add more information in comparison to the default Rspamd logger output:

As you can see, you can use both embedded log variables and Lua code to customize log output. More information is available in the logger documentation

It is sometimes useful to get debug information about some particular module in Rspamd. In this case, you can use debug_modules option in the logging configuration:

Back to content

### Which backend should I use for statistics

Currently, we recommend using redis for the statistics and fuzzy storage backend.

You can convert existing statistics in sqlite by using rspamadm statconvert routine:

# rspamadm statconvert -d bayes.spam.sqlite -h 127.0.0.1:6379 -s BAYES_SPAM
# rspamadm statconvert -d bayes.ham.sqlite -h 127.0.0.1:6379 -s BAYES_HAM \
-c learn_cache.sqlite


You should import learn cache just once with either ham or spam statistics.

The only limitation of the redis backend is that it doesn’t support per language statistics. This feature, however, is not needed in the majority of cases. Per user statistics in redis works in a different way than in sqlite. Please read the corresponding documentation for further details.

You can also convert fuzzy storage using rspamadm fuzzyconvert:

# rspamadm fuzzyconvert -d fuzzy.db -h 127.0.0.1:6379 -e 7776000


Finally, you need to change the default sqlite backend to redis and restart rspamd.

local.d/classifier-bayes.conf:

override.d/worker-fuzzy.inc:

Back to content

### What Redis keys are used by Rspamd

The statistics module uses <SYMBOL><username> as keys. Statistical tokens are recorded within a hash table with the corresponding name. The ratelimit module uses a key for each value stored in Redis, see ratelimit module documentation. The DMARC module also uses multiple keys to store cumulative reports: a separate key for each domain.

It is recommended to set a limit for dynamic Rspamd data stored in Redis ratelimits, ip reputation, and DMARC reports. You could use a separate Redis instance for statistical tokens and set different limits or use separate databases (by specifying db when setting up the redis backend).

Back to content

### How to run Rspamd using Unix sockets

From https://github.com/vstakhov/rspamd/issues/1905

Redis

/etc/redis/rspamd.conf (changes only)

bind 127.0.0.1
port 0
unixsocket /var/run/redis/rspamd.sock
unixsocketperm 770
pidfile /var/run/redis/rspamd.pid
logfile /var/log/redis/rspamd.log
dir /var/lib/redis/rspamd/


You should create the directory /var/lib/redis/rspamd and make it writable for user redis.

If you need to launch a separate Redis instance for Rspamd, follow these instructions.

/etc/rspamd/local.d/redis.conf

servers = "/var/run/redis/rspamd.sock";


/etc/rspamd/local.d/classifier-bayes.conf

backend = "redis";
autolearn = true;


Don’t forget to add the user _rspamd to the group redis (run usermod -a -G redis _rspamd)

You can check the connection with this:

myserver:~ # redis-cli -s /run/redis/rspamd.sock
redis /run/redis/rspamd.sock> ping
PONG
redis /run/redis/rspamd.sock> monitor
OK
1509722016.014458 [0 unix:/var/run/redis/rspamd.sock] "SMEMBERS" "BAYES_HAM_keys"
1509722018.522879 [0 unix:/var/run/redis/rspamd.sock] "SMEMBERS" "BAYES_SPAM_keys"
1509722018.523305 [0 unix:/var/run/redis/rspamd.sock] "HLEN" "BAYES_SPAM"
1509722018.523334 [0 unix:/var/run/redis/rspamd.sock] "HGET" "BAYES_SPAM" "learns"
1509722024.892442 [0 unix:/var/run/redis/rspamd.sock] "SMEMBERS" "BAYES_SPAM_keys"
1509722024.892870 [0 unix:/var/run/redis/rspamd.sock] "HLEN" "BAYES_SPAM"
1509722024.892899 [0 unix:/var/run/redis/rspamd.sock] "HGET" "BAYES_SPAM" "learns"
...


Nginx

/etc/tmpfiles.d/rspamd.conf (create this file if needed and run systemd-tmpfiles --create)

d  /var/run/rspamd  0755  _rspamd  _rspamd  -


/etc/rspamd/local.d/worker-controller.inc

bind_socket = "/run/rspamd/worker-controller.socket mode=0660 owner=_rspamd group=www";
password = "$2$paparrytknfm8...";
enable_password = "$2$paparrytknfm8...";


nginx.conf

location /rspamd/ {
auth_basic "Restricted Area";
auth_basic_user_file /srv/www/.mydomain.tld.htpasswd;
map $status$loggable {
~^[23]  0;
default 1;
}
access_log /var/log/nginx/rspamd.access.log combined if=$loggable; error_log /var/log/nginx/rspamd.error.log warn; proxy_pass http://unix:/run/rspamd/worker-controller.socket:/; proxy_set_header Host$host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }  Back to content ## Plugin questions ### How to whitelist messages or skip spam checks for certain users You have multiple options here. First of all, if you need to define a whitelist based on SPF, DKIM or DMARC policies, then you should look at the whitelist module. Otherwise, there is a multimap module that implements different types of checks to add symbols according to list matches or to set pre-actions which allow you to reject or permit certain messages. Another option is to disable spam filtering for some senders or recipients based on user settings. You can specify want_spam = yes and Rspamd will skip messages that satisfy a particular rule’s conditions. Back to content ### How to blacklist messages based on extension In this example, we want to blacklist the following extensions using the multimap module: exe arj scr lnk  Then define the following multimap rule in local.d/multimap.conf: Back to content ### What are filters, pre-filters and post-filters Rspamd executes different types of filters depending on the time of execution. • pre-filters are executed before everything else and they can set a pre-result that ultimately classifies a message. Filters and post-filters are not executed in this case. • filters are generic Rspamd rules. • post-filters are guaranteed to be executed after all filters are finished and allow the execution of actions that depends on the results of scan • idempotent post-filters are executed after all and they MUST NOT change metric result anyhow, e.g. these filters could be used for history The overall execution order in Rspamd is the following: 1. pre-filters 2. filters 3. classifiers 4. composite symbols 5. post-filters 6. autolearn rules 7. composites second pass (from 1.7) 8. idempotent rules (from 1.7) Back to content ### What is the meaning of the URIBL_BLOCKED symbol This symbol means that you have exceeded the amount of DNS queries allowed for non-commercial usage by SURBL services. If you use some a public DNS server, e.g. goolgle public DNS, then try switching to your local DNS resolver (or set one up, for example, unbound). Otherwise, you should consider buying a commercial subscription or you won’t be able to use the service. The URIBL_BLOCKED symbol has a weight of 0 and is used just to inform you about this problem. Back to content ### How can I use commercial feeds for SURBL/RBL others The most starightforward way is to use your own local resolver with forward zones that point to dedicated rbldnsd instance or instances that serve static zones provided by different vendors (e.g. Spamhaus or SURBL). Here is a sample configuration snippet for Unbound caching resolver: forward-zone: name: "sbl.spamhaus.org." forward-addr: x.x.x.x # Your rbldnsd instance IP forward-addr: y.y.y.y # Secondary server if needed forward-first: yes  You can also change suffixes in Rspamd config to use your custom (e.g. premium zones). You should use local.d/rbl.conf or local.d/surbl.conf. Back to content ### What are monitored checks Rspamd periodically checks various DNS lists to avoid possible issues with DNS, for instance if your nameserver returns some weird redirect instead of NXDOMAIN error, or lists themselves, for example, if they start to blacklist the whole Internet as it happened in the past with some particular lists. Hence, Rspamd queries the following addresses: • 1.0.0.127.rbl.tld - this MUST return NXDOMAIN for all RBLs • facebook.com.uribl.tld - it is highly unlikely that any sane URIBL would ever block Facebook, hence, this query is used to check URL black lists sanity If monitored checks fail, Rspamd will disable a failed resource and continue retrying these checks after some amount of time (around 1 minute). If checks are successfull then a resource will be enabled back. Back to content ### Why do I have monitored errors in my log files Some users complain about log lines like the following ones: <xxx>; monitored; rspamd_monitored_dns_cb: DNS reply returned 'no error' for multi.uribl.com while 'no records with this name' was expected  This errors usually means that you are blocked on uribl.com which, in turn, can mean that you are using some public DNS resolver (e.g. Google DNS). If you do not use public resolver but if you have a significant mail flow then you might be out of free band for URIBL so you could consider a commercial subscription option. However, even in this case you should use a dedicated resolvers and not some public ones. You can read more about DNS setup here. The second possible reason of this error is RBL/URLBL malfunction which means that it returns positive results for queries that shouldn’t be banned (e.g. facebook.com or 127.0.0.1). This means a serious malfunction in the DNS list. The third reason could be in your DNS server: sometimes DNS servers provides fake replies for queries that are not found. For example, they could lead you to some search page or to some informational page. Rspamd cannot work normally in such a situation and will disable DNSBL lookups. Please consider using of your own forwarding DNS server in this case. Back to content ### What is the meaning of the message like inv_chi_square: exp overflow This message usually means that some statistics class is overflowed with tokens and another one is underflowed. You should consider to learn more messages from both Spam and Ham classes for Bayes classifier. Back to content ### How can I learn messages You should use rspamc learn_spam and rspamc learn_ham commands to learn Spam and Ham classes accordingly. Youd should always learn both classes with almost equal amount of messages to increase performance of the statistical engine. Learning requires enable level for the controller and you need to specify enable_password or use secure_ip setting to allow learning and other modifications from certain IP addresses. Back to content ### How to learn Rspamd automatically Please check the following document for more details. Back to content ### What is faster between custom Lua rules and regular expressions Switching from C to Lua might be expensive. Hence, you should use regular expressions for simple checks where possible. If Rspamd is compiled with Hyperscan the cost of adding another regular expression is usually very cheap. In this case, you should avoid constructions that are not supported by Hyperscan: backtracking, lookbehind and some others. On the other hand, Lua provides some unique functions that are not available by using of regular expressions. In this case, you should use Lua. Back to content ## WebUI questions ### What are enable_password and password for the WebUI Rspamd can limit the functions available through the WebUI in three ways: 1. Allow read-only commands when password is specified 2. Allow all commands when enable_password is specified 3. Allow all commands when client IP address matches the secure_ip list in the controller configuration When password is specified but enable_password is missing then password is used for both read and write commands. Back to content ### How to store passwords securely Rspamd can encrypt passwords and store them using PBKDF2 or Catena. Catena is used by default since 1.4 as it provides better resistance to brute-force attacks requiring additional memory for computation (memory hard function). To use this feature you can use the rspamadm pw command as follows: rspamadm pw Enter passphrase:$1$jhicbyeuiktgikkks7in6mecr5bycmok$boniuegw5zfc77pfbqf14bjdxmzd3yajnngwdekzwhjk1daqjixb


Then you can use the resulting string (in the format $<algorithm_id>$<salt>$<encrypted_data>) as password or enable_password. Please note that this command will generate different encrypted strings even for the same passwords. That is the intended behaviour. Back to content ### How to use the WebUI behind a proxy server Here is an example for nginx: Corresponding Apache configuration: When a connection comes from an IP listed in secure_ip or from a unix socket then Rspamd checks for two headers: X-Forwarded-For and, if that is not found- X-Real-IP. If one of those headers is found then Rspamd treats a connection as if it comes from the IP specified in that header. For example, X-Real-IP: 8.8.8.8 will trigger checks against secure_ip for 8.8.8.8. Back to content ### Where does the WebUI store settings The WebUI sends AJAX requests for Rspamd and Rspamd can store data in a dynamic_conf file. By default, it is defined in options.inc as following: dynamic_conf = "$DBDIR/rspamd_dynamic";


Rspamd loads symbols and actions settings from this file with priority 5 which allows you to redefine those settings in an override configuration.

Back to content

### Why can’t I edit some maps with the WebUI

The map file might have insufficient permissions, or not exist. The WebUI also ignores all HTTP maps. Editing of signed maps is not yet supported.

Back to content

### How to setup cluster in WebUI

You need to add neighbours list to the global options configuration.

Please see the Rspamd options settings for details.

Back to content

### Why does the User column show ‘undefined’?

The User column shows the authenticated username of the message sender- you would have to be scanning authenticated outbound mail to see something here.

Back to content

## Lua questions

### What is the difference between plugins and rules

Rules are intended to do simple checks and return either true when rule matches or false when rule does not match. Rules normally cannot execute any asynchronous requests or insert multiple symbols. In theory, you can do this but registering plugins by rspamd_config:register_symbol functions is the recommended way to perform such a task. Plugins are expected to insert results by themselves using the task:insert_result method.

Back to content

### What is table form of a function call

The difference between table and sequential forms is simple:

Historically, all Lua methods used the sequential call type. This has changed somewhat, however, and has the following advantages:

• you don’t need to remember the exact order of arguments
• you can see not only a value but a name = value pair which helps in debugging
• it is easier to extend methods with new features and to keep backward compatibility
• it is much easier to allow optional arguments

However, there is a drawback: table calls are slightly more expensive in terms of computational resources. The difference is negligible in the majority of cases so Rspamd now supports the table form for most functions which accept more than two or three arguments. You can check in the documentation which forms are allowed for a particular function.

Back to content

### How to use rspamd modules

Use a require statement:

Rspamd also ships some additional lua modules which you can use in your rules:

Back to content

### How to write to Rspamd log

Rspamd logger provides many convenient methods to log data from lua rules and plugins. You should consider using one of the modern methods (with x suffix) that allow use of %s and %1 .. %N notation. The %s format is used to print the next argument, and %<number> is used to process the particular argument (starting from 1):

It is also possible to use other objects, such as Rspamd task or Rspamd config to augment logger output with a task or config logging tag.

Moreover, there is an rspamd_logger.slog function which allows replacement of the Lua standard function string.format when you need to print complex objects, such as tables.

Back to content

### Should I use local for my variables

Yes: always use local variables unless it is unavoidable. Too many global variables can cause significant performance degradation for Lua scripts.

Back to content

### How can I create regexps in Lua

Regexp objects are special in case of Rspamd. Unlike other objects, they do not have garbage collection method and should be explicitly destroyed. For example, if you have this code:

rspamd_config.RULE = function(task)
local re = rspamd_regexp.create('/re/') -- Memory leak here!
...
end


Then re object will not be destroyed and you will have a memory leak. To resolve this situation, you should always use the global regexps cache which exists during Rspamd process lifetime:

rspamd_config.RULE = function(task)
local re = rspamd_regexp.create_cached('/re/') -- Regexp will be reused from the cache if possible
...
end


The only situation when you might have a problem with this approach is when you need to create regular expressions dependent on some external data:

local function blah(task)
-- Return something that depends on task properties
end

local re = rspamd_regexp.create_cached(blah(task)) -- Too many regexps could be created
...
end


If you cannot avoid this bad pattern (and it is bad since regexp creation is an expensive procedure), then you can explicitly destroy regexp object:

local function blah(task)
-- Return something that depends on task properties
end

local re = rspamd_regexp.create(blah(task)) -- This is expensive procedure!
...
re:destroy() -- frees memory
end


However, you should consider using regexp maps with multimap module when you need something like this.

Back to content

## Integration questions

### How to distinguish inbound and outbound traffic for Rspamd instance

From version 1.7.0 onwards, proxy worker can pass a special header called settings-id when doing checks (both proxy and self-scan modes). This header allows Rspamd to apply specific settings for a message. You can set custom scores for a message or disable some rules or even a group of rules when scanning. For example, if we want to disable some rules for outbound scanning we could create an entry in the settings module:

Then, we can apply this setting ID on the outbound MTA using the proxy configuration:

Another possibility is to apply settings based merely on the sender being authenticated or having an IP address in a particular range, refer to the documentation for detail.

Back to content

### How can I restore the old Rmilter SPF behaviour

Previously, Rmilter could reject mail which fail SPF verification for certain domains. So far, this behaviour could be implemented using Rspamd.

One can create rules in rspamd to force rejection on whatever symbols (+ other conditions) they want (DMARC module, among others has built-in support for such; multimap being the most generally useful)

For example, add to /etc/rspamd/rspamd.local.lua:

local myfunc = function(task)