Default variable details
Some of the debops.rspamd
default variables have more extensive
configuration than simple strings or lists, here you can find documentation and
examples for them.
rspamd__configuration
The rspamd__*_configuration
variables define the contents of the
/etc/rspamd/local.d
and /etc/rspamd/override.d
configuration
directories. The variables are merged in the order defined by the
rspamd__combined_local_configuration
and
rspamd__combined_override_configuration
variables, which allows
modification of the default configuration through the Ansible inventory.
Note that files which are not configured via the rspamd__*_configuration
variables will be deleted from the /etc/rspamd/local.d
and
/etc/rspamd/override.d
directories, to ensure that the Rspamd
configuration is predictable.
See the Rspamd
configuration documentation and, in particular, the
modules documentation for details on the possible configuration files
and the relevant parameters for each file.
Examples
See the rspamd__default_local_configuration
and
rspamd__default_override_configuration
variables for examples of
existing configuration.
Configure another RBL (Runtime Black List) check:
rspamd__local_configuration:
- file: 'rbl.conf'
comment: |
RBL configuration
https://rspamd.com/doc/modules/rbl.html
options:
- name: 'rules'
options:
- name: 'SIMPLE_RBL'
options:
- name: 'rbl'
value: 'rbl.example.net'
- name: 'checks'
value: [ 'from' ]
This will result in /etc/rspamd/local.d/rbl.conf
being created with
the following content:
...
rules {
SIMPLE_RBL {
rbl = "rbl.example.net";
checks = ["from"];
}
}
Syntax
The variables contain a list of YAML dictionaries, each dictionary can have the following parameters:
file
Required. Name of the file to create in the
/etc/rspamd/local.d
or/etc/rspamd/override.d
directory. This parameter is used as an "anchor", configuration entries with the samefile
are combined together and affect each other in order of appearance.comment
Optional. This parameter can be used to provide a short description which will be included in the generated configuration file.
state
Optional. If not specified or
present
, the configuration file will be generated. Ifabsent
orinit
, the configuration file will not be generated and if any old configuration file with the same name exists on the target host, it will be removed. Ifignore
, the configuration file will not be generated and old configuration files, if any, will not be removed.weight
Optional. A positive or negative number which can be used to affect the order of files to be generated. Positive numbers add more "weight" to the section making it appear "lower" in the list; negative numbers subtract the "weight" and therefore move the file up in the list.
options
Required. A list of rspamd configuration options for a given file. The
options
parameters from configuration entries with the samefile
parameter are merged together in order of appearance and can affect each other.Note that the
options
parameters can be used recursively to generate configuration blocks of arbitrary depth (as illustrated in the example above).The options can be specified in a simple form as key/value pairs, where the key is the option name and value is the option value. Alternatively, if the
name
andvalue
parameters are used, the entries can use an extended format with specific parameters:name
Required. The name of a given rspamd configuration option for a given
file
. Options with the samefile
andname
will be merged in order of appearance.value
Either
value
oroptions
is required. This defines the value of a given configuration option. It can be either a string, a boolean, a number, or a YAML list.options
Either
value
oroptions
is required. This parameters takes a list of configuration sub-options, thus allowingoptions
to be used recursively to generate configuration blocks of arbitrary depth (as illustrated in the example above).raw
Optional. String or YAML text block which will be included in the configuration file "as is". If this parameter is specified, the
name
andvalue
parameters are ignored - you need to specify the entire line(s) with configuration option names as well.state
Optional. If not defined or
present
, a given configuration option or section will be included in the generated configuration file. Ifabsent
,ignore
orinit
, a given configuration option or section will not be included in the generated file. Ifcomment
, the option will be included but commented out and inactive.comment
Optional. String or YAML text block that contains comments about a given configuration option.
DKIM
DomainKeys Identified Mail (DKIM) is an email authentication method designed to sign outgoing messages using keys which are published in the DNS zone of the sending domain. This allows the recipient to check that a received email was indeed sent from the given domain.
rspamd includes support for both checking DKIM signatures and for generating DKIM signatures for outgoing email messages. In order to do the signing, suitable keys have to be generated and published in the right DNS zone(s). In addition, the keys used for signing the emails should be replaced on a regular basis (as explained e.g. in this document), a process which is often referred to as key rollover.
Unfortunately, the step of publishing/removing DNS records cannot be fully automated as there is no universal means for doing so, neither in the generic case, nor in DebOps. The support for DKIM signing therefore defaults to being disabled in the debops.rspamd role, but the recommendation is to go through the steps of manually enabling and configuring it.
In order to simplify this task, the debops.rspamd role includes two
tools, rspamd-dkim-keygen
and rspamd-dkim-update
which,
after some initial configuration, can automate the key rollover process.
To enable DKIM signing, first check that rspamd__dkim_domains
lists
all the domains that will be used to send email and then override the
rspamd__dkim_enabled
parameter:
rspamd__dkim_enabled: True
rspamd__dkim_domains: [ "example.com", "example.net" ]
rspamd-dkim-keygen
The rspamd-dkim-keygen
script takes care of generating keys for the
domains listed in rspamd__dkim_domains
and will be executed on a
monthly basis via a cron job. The configuration for
rspamd-dkim-keygen
is stored in /etc/rspamd/dkim-keygen.json
,
which is controlled via the rspamd__dkim_keygen_*_configuration
variables.
These variables are merged in the order defined by the
rspamd__dkim_keygen_combined_configuration
variable, which allows
modification of the default configuration through the Ansible inventory in a
manner similar to the rspamd__configuration and with a simplified
version of the Syntax, since options
are
not supported.
In the default configuration, RSA
and ed25519
keys will be generated in
/var/lib/rspamd/dkim/
. Three time periods are defined by the
future_period
, active_period
and expired_period
(in months). These
are the stages of the key rollover that keys go through. Keys are generated
future_period
number of months before they are made active (in order to
allow for the keys to be published in the DNS). Then they are in active use
(i.e. used to sign outgoing emails) during the active_period
. Finally, keys
enter the expired_period
where they are no longer used to sign emails (but
the records are still published in the DNS to make sure that in-flight emails
are still valid). Finally, upon expiry of the expired_period
, when no
emails should be in-flight any more, the keys can be archived (to
/var/lib/rspamd/dkim-archive/
and removed from the DNS.
The one exception is when rspamd-dkim-keygen is first executed (usually the first time the debops.rspamd role is run for a given host), in which case the initial keys will immediately go live.
Whenever rspamd-dkim-keygen detects that a new key should be published in the DNS, or that a stale key needs to be removed, it will call out to the complimentary tool rspamd-dkim-update.
rspamd-dkim-update
The rspamd-dkim-update
script takes care of publishing/removing DNS
resource records for DKIM keys generated/expired by the rspamd-dkim-keygen
script.
The most important variable for rspamd-dkim-update
is the
rspamd__dkim_update_method
, which defaults to sending emails to
the administrator for manual handling of DNS updates.
In the alternative, the process can be automated using the nsupdate
tool. This requires configuration changes to the DNS server (e.g.
bind), either to trust the IP address of the rspamd host
(not recommended), or to generate suitable keys (for example, TSIG keys)
and to configure these keys to have the appropriate permissions to add/remove
DNS resource records (for example, using bind's fine-grained
update-policy options). Alternatively, the server can be configured to allow
a given Kerberos principal to perform updates (in which case a keytab
needs to be generated instead of a TSIG
key file and the references to the
key file below should then be read as referring to the keytab
file).
The key file needs to be stored on the rspamd host, by default at
/etc/rspamd/dkim_dns_key
(preferably with 0640
permissions and
root:_rspamd
ownership). This can be automated by transferring the key
file to the Ansible controller and putting it in the appropriate override
directory (e.g. project-dir/ansible/overrides/files/etc/rspamd/dkim_dns_key
as
explained below in the Overriding rspamd-dkim-keygen/update section).
Once the keyfile has been prepared, check the values of nsupdate_*
in the
configuration for rspamd-dkim-update
, stored in
/etc/rspamd/dkim-update.json
, which is controlled via the
rspamd__dkim_update_*_configuration
variables. These variables are merged
in the order defined by the
rspamd__dkim_update_combined_configuration
variable, which allows
modification of the default configuration through the Ansible inventory in a
manner similar to the rspamd__configuration and with a simplified
version of the Syntax, since options
are
not supported.
Overriding rspamd-dkim-keygen/update
The reason why there are two separate scripts for key generation and DNS
updates is that it allows the administrator to override the default scripts by
providing their alternative script in the files_path
override directory
defined in the .debops.cfg
file (see Configuration).
For example, if .debops.cfg
reads:
...
[override_paths]
files_path = ansible/overrides/files
...
Then the custom script(s) should be placed in
project-dir/ansible/overrides/files/usr/local/sbin/rspamd-dkim-update
and/or
project-dir/ansible/overrides/files/usr/local/sbin/rspamd-dkim-keygen
.