Now that we know the what there is to configure let’s look at the how.
Similar to what was described for Apache, the rspamd main configuration file /etc/rspamd/rspamd.conf doesn’t actually contain much configuration but references other files which in turn may include other files. The following illustration shows how the files relate to each other (click to view full size):
EDIT: I made an updated version for rspamd 1.9.0.
Most of these files give a good hint at what their purpose is:
- Enabling/disabling of modules written in Lua is done in the module-specific configuration file in the modules.d directory via an enabled = true or enabled = false line. These files also hold any module-specific settings. They get included through modules.conf which is otherwise empty.
- Unfortunately there is a number of *.inc files that get included from module-specific configuration files but were placed one level higher in the /etc/rspamd directory. These should have probably been placed in the modules.d directory as well.
- Symbols and their configuration (e.g. scores) are collected in groups for each of which there is configuration file in /etc/spamd/scores.d. These files get included through groups.conf which otherwise only contains maximum scores for the excessqp and excessb64 groups.
- Composition of symbols is configured in composites.conf.
- What actions to trigger at which spaminess level is configured in actions.conf.
- The statistic.conf file is intended to contain the configuration for statistical classifiers. Currently there is only the Bayes classifier. Bayes-specific options can be placed in a file classifier-bayes.conf.
- The logging.inc file is where logging setup is done.
- The options.inc file deserves special mention as this is where several settings are placed such as DNS timeouts but also the enabling/disabling of built-in modules.
- The worker-*.inc files contains the worker-specific configuration such as the socket to bind to or, in case of the controller worker, the passwords required for remote access, e.g. to the Web UI.
- Last not least the common.conf file mostly serves to include other configuration files. The only option placed here is the path to modules written in Lua.
It is important to note that none of the files mentioned above are supposed to be modified directly, at least not at the locations shown above. Instead the rspamd configuration files provide different hooks where you can tweak the configuration:
- You could create a single /etc/rspamd/rspamd.conf.local file, however this is not recommended.
- Instead the idea is to take the filename of the configuration file you wish to modify and create an identically-named copy in either of two directories:
- in local.d if you wish to overwrite single configuration statements. Configuration blocks defined in files in this directory get merged with existing block definitions.
- in overrides.d if you wish to overwrite entire configuration blocks. Any block defined here completely overrides existing block definitions.
Example: Suppose we are basically satisfied with the default logging setup and want to change just a single option. We would then create /etc/rspamd/local.d/logging.inc and place the option in that file. If however we wanted to completely redefine the logging setup, we would instead put our options in the file /etc/rspamd/overrides.d/logging.inc.
This concludes the blog post on rspamd configuration for now. I hope you found it useful. Feel free to send feedback and/or corrections!
Blog post series index:
- Part 1: Introduction
- Part 2: Modules
- Part 3: Scores
- Part 4: Configuration file structure