Rspamd (DKIM) - How to setup dynamic path to support all domains/selectors?

[audioscavenger]

I can swear this worked yesterday and today it won't at all, nothing is signed anymore:

# The path location is searched for a DKIM key with these variables:
# - $domain is sourced from the MIME mail message From header
# - $selector is configured for mail (as a default fallback)
path = "/tmp/docker-mailserver/rspamd/dkim/rsa-2048-$selector-$domain.private.txt";

# DKIM-selector: this is critical and must match a TXT entry called selector._domainkey in ALL of your domains
# To allow regular key rotation without loss of service:
# 1. generate new keys
# 2. create new TXT entries with public dns values of the keys
# 3. modify the selector name below:
selector = "dkim";

What happened is that yesterday at some point i forgot to comment the 1. 2. 3. lines, and restarted the container. Dkim signing stopped working after that, and even after I fixed the file.

Now to get DKIM-signature again I have to add each domain manually inside a domain {} and cannot use $ variables at all.
Why is so?

Now I would have to also edit this file each time I add a new domain. Why can't rspamd 3.12.1 use variables for the key path ? even $domain does not work. The help page at https://docs.rspamd.com/modules/dkim_signing/ clearly indicates that $domain in the private key file name should work

[polarathene]

TL;DR: Add try_fallback = true; to your config.

• This is something we could PR for the upcoming DMS v16 release, I don't think there's any reason not to enable it.
• Also appears to be the default in /etc/rspamd/modules.d/dkim_signing.conf. DMS could minimize the config generated for this module (I am not the maintainer of Rspamd support in DMS, so I wasn't aware of this default configs file until now).

---

Upstream docs explain what you need

While DMS does provide the mail server image with services bundled and integrated with some conveniences like our setup CLI commands and supported ENV config features, users are generally expected to become more familiar with upstream services config/docs when they need to customize further.

That keeps maintenance/support simpler for us, since we can only spare to volunteer time unlike some others that have devs with financial support to work on the project 😅 When possible though, I try to push helpful information for common tasks onto our docs to save users that hassle.

Looking at the official Rspamd docs: https://docs.rspamd.com/modules/dkim_signing

The default global configuration (fallback mode) searches for keys at the defined path.

This path is constructed using the eSLD normalized domain name of the header from and the default selector defined with selector (dkim).
For example, the search path for [email protected] would be /var/lib/rspamd/dkim/example.com.dkim.key.

If a key is found, the message will be signed.

Which tells us that path and selector settings are specifically for the global config (fallback), as opposed to the more explicit domain mapping to DKIM keys/selectors that DMS is configuring currently. There's also this later example section which clearly indicates the use of try_fallback = true; in the config.

I have a tracking issue where I'd like to refactor Rspamd DKIM support in DMS to switch over to using the global path and selector fallbacks, where $domain is taken from the sender address (and the selector if needed could be mapped by $domain via a selector_map setting).

At that linked tracking issue I do reference the Rspamd DKIM signing config docs, specifically calling out use_domain + use_esld with $domain considerations and I have pointed out the need for try_fallback = true to be set. I've just not had time to tackle that yet (and subsequently improve documentation, although the plan is for this to be fairly implicit config for a DMS user to not worry about).

So at a minimum, you want these settings (I've added some contextual comments if helpful):

# documentation: https://rspamd.com/doc/modules/dkim_signing.html

enabled = true;

# Authentication over port 587/465 when submitting mail will sign with DKIM:
sign_authenticated = true;

# This can be a fixed value for a domain to always use, or various supported sources to acquire the domain
# NOTE: `header` will extract from the MIME `FROM` header of mail received, aka the sender address
use_domain = "header";

# Strips subdomain(s) from `$domain` if present in sender domain (`marketing.example.com` => `example.com`)
# eSLD to normalize to must exist in the PSL checked (https://publicsuffix.org/list/public_suffix_list.dat)
# Additional Refs (NOTE: `.test` is a private TLD, thus not present in the PSL):
# - https://en.wikipedia.org/wiki/Public_Suffix_List
# - https://en.wikipedia.org/wiki/Second-level_domain
# - https://github.com/rspamd/rspamd/blob/3.13.0/src/lua/lua_url.c#L664-L670
use_esld = true;

# Global DKIM keys config (requires `try_fallback = true`):
# - `path` defines the location of your DKIM keys, with optional dynamic `$selector` + `$domain` variables.
# - `$domain` is determined from `use_domain` + `use_esld` settings.
# - `$selector` defaults to the `selector` setting, unless another setting like `selector_map` overrides that.
path = "/tmp/docker-mailserver/rspamd/dkim/rsa-2048-$selector-$domain.private.txt";
selector = "dkim";
try_fallback = true;

I'm not too familiar with Rspamd config, but it looks like /etc/rspamd/modules.d/dkim_signing.conf provides the base config for the module.

• Many of the desired defaults are already set there (including `selector = "dkim";). Although it doesn't hurt to be explicit about config you want to rely on being predictable.
• In the files comments it instructs that specifying any of path = ...;, domain { ... }, or use_redis = true; will implicitly trigger enabled = true;.

So technically you could get away with only setting path! 😎

---

Adapting the reproduction compose.yaml I shared with you earlier here, we can verify DKIM is signing as desired like so:

name: example

services:
  dms:
    image: ghcr.io/docker-mailserver/docker-mailserver:${DMS_RELEASE:-15.1.0}
    hostname: mail.example.test
    environment:
      ENABLE_RSPAMD: 1
      ENABLE_OPENDKIM: 0
      # NOTE: These ENV below are just to simplify the reproduction and aren't relevant to reproduction:
      ENABLE_AMAVIS: 0
      ENABLE_UPDATE_CHECK: 0
    configs:
      - source: dms-accounts
        target: /tmp/docker-mailserver/postfix-accounts.cf
      - source: rspamd-dkim
        target: /tmp/docker-mailserver/rspamd/override.d/dkim_signing.conf

# The Docker Compose `configs` feature inlines file content into `compose.yaml` (convenient for reproductions)
# NOTE: `$` will be inferred as an ENV on the host to replace with a value if found,
#       `$$` is required as an escape to opt-out of that feature when an actual `$` is expected in the file content.
configs:
  dms-accounts:
    content: |
      [email protected]|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.

  rspamd-dkim:
    content: |
      # Setting `path` will implicitly set `enabled = true;`:
      path = "/tmp/docker-mailserver/rspamd/dkim/rsa-2048-$$selector-$$domain.private.txt";

      # These are both implicit defaults configured by upstream at `/etc/rspamd/modules.d/dkim_signing.conf`
      try_fallback = true; 
      selector = "dkim";

      # For reproduction verification (also implicit by upstream default)
      # Used to ensure DKIM signing is used when sending mail internally:
      sign_local = true;

Test that it's all working:

# Start DMS:
$ docker compose up -d --force-recreate

# Wait about 20 sec (`grep rspamd <<< "$(ps -auxf)"` should then show rspamd child processes, signaling service is ready)

# Create DKIM keys (config already provided in advance via `configs.rspamd-dkim`):
$ docker compose exec dms setup config dkim selector dkim

# Send mail to self:
$ docker compose exec dms swaks --silent \
  --server localhost --port 587 \
  --auth PLAIN --auth-user [email protected] --auth-password secret \
  --from [email protected] --to [email protected]

# Verify mail was receive with DKIM signature using expected selector:
$ docker compose exec dms grep -R dkim /var/mail/example.test/john.doe/new/

/var/mail/example.test/john.doe/new/1758603138.M252519P1420.mail.example.test,S=1322,W=1352:    s=dkim; t=1758603138;

[polarathene]

I can swear this worked yesterday and today it won't at all, nothing is signed anymore

What happened is that yesterday at some point i forgot to comment the 1. 2. 3. lines, and restarted the container. Dkim signing stopped working after that, and even after I fixed the file.

When you are getting started with your DMS configuration, please remember that DMS is unlike your typical container with a single service per image.

Not only are we running multiple services, but we're abstracting configuration through separate volume for configs and ENV support that setup scripts will process (and some monitored for changes while the container runs). This adds complexity and is somewhat fragile in how some changes are applied. As such most of that will only be run during the first run of the container, and to reapply new changes cleanly you'll need to at least create a new container instance, not just restart the container.

This is why it's important to keep our troubleshooting docs page in mind, especially that early tip that requests you use docker compose up -d --force-recreate.

Some users get a bit eager and mount configs directly into /etc/ dirs to be used directly. That can be required sometimes but depending on where you're mounting, DMS may assume ownership of internal config and there could be a conflict there. Likewise our support is assuming there is no other config there that would break functionality in our own configs, but this can happen with config directories like /etc/dovecot/conf.d/, often due to users adding configs without understanding them that well which causes bugs from misconfiguration / typos.

DMS maintainers have limited support in those scenarios, but we do try to make DMS flexible to users that need to add their own customizations in (which for some services we support in the DMS config volume: /tmp/docker-mailserver/).

---

So try to keep that in mind:

• Read upstream docs when you're doing changes that DMS doesn't provide convenient support for. It's easy to miss things and get frustrated (I know that all too well 😂 ), hopefully highlights the efforts that DMS goes through to simplify what we can for users (I know it could be better, but time is limited).
• Restart DMS properly when you make config changes. When you run into specific issues like you've had here, I find it easier to break it down into a small reproduction compose.yaml like I've shown above, isolating the issue and that's how I reproduced your problem and likewise got frustrated until looking over the Rspamd docs again more thoroughly to understand what was going wrong.

---

One other thing is our check-for-changes.sh script that runs in the background. Whenever you make changes to /tmp/docker-mailserver/rspamd content for example, it can be detected and trigger a copy of that config to internal Rspamd config dir which is actually used, and rspamd is restarted.

I have encountered a crash loop at one point with rspamd, while others were just slightly stalled during restart. I also noticed the child processes for Rspamd were a bit slow to start on my VPS test environment (20 sec after rspamd was restarted), so there's a possibility of that affecting you during config changes.

DMS definitely is a bit rough around the edges at times, but once you've got it configured how you like it, it should be a good experience going forward 👍

[audioscavenger]

YEP try_fallback = true; did it, you fixed it!!! thanks so much