Validate Rspamd Configuration Safely with rspamadm

Before you reload Rspamd and hope for the best, rspamadm can tell you whether the configuration is even valid. This guide covers discovering the commands available on this host, testing a configuration, inspecting the processed result, and avoiding the permission and secret-handling mistakes that trip people up. Allow about 15 minutes for a first check. The examples use Rspamd 3.8.1, installed here from the Ubuntu rspamd package.

1. Confirm the installed tool

Run the version check as your normal account. No service interruption or elevated privilege needed:

$ command -v rspamadm
/usr/bin/rspamadm
$ rspamadm --version
Rspamadm 3.8.1

The version output matters when comparing a result across hosts, since command options and configuration behaviour differ between Rspamd releases. Record it with any incident or change review. The local manual calls the program an administration utility for configuration tests, password encryption, database work and configuration signing.

2. Discover commands and command-specific options

Do not guess a subcommand from a blog post or a different Rspamd release. List what this installation actually provides:

$ rspamadm --list-commands
Available commands:
  configdump         Perform configuration file dump
  configtest         Perform configuration file test
  pw                 Manage rspamd passwords
  keypair            Manages keypairs for Rspamd
  ...

The full list runs longer and depends on the build. Ask for help before you paste an option into a script:

$ rspamadm help configtest
Usage: rspamadm configtest [-q -c <config_name>]
$ rspamadm configdump --help
Usage: rspamadm configdump [-c <config_name> [-j --compact -m] [<path1> [<path2> ...]]]

The manual documents two useful help forms: rspamadm help COMMAND and rspamadm COMMAND --help. Keep the help output alongside the version when troubleshooting; it heads off an easy mistake, copying an option that belongs to another release or another subcommand entirely.

3. Test the configuration without changing it

Find the configuration file your service uses, then test that exact path. A typical packaged install uses /etc/rspamd/rspamd.conf:

$ rspamadm configtest -c /etc/rspamd/rspamd.conf
syntax OK

Successful output and exit status 0 mean the syntax was accepted, nothing more. Check the status explicitly when scripting it:

$ rspamadm configtest -c /etc/rspamd/rspamd.conf && echo 'configuration test passed'
syntax OK
configuration test passed

Use -q when a script needs less output. The manual also documents a strict test form with -s; check rspamadm configtest --help on your installed release before relying on it in automation.

4. Interpret permission errors instead of masking them

Rspamd may need to read or write runtime data while loading its configuration. On this host, an unprivileged test prints permission errors for files and Hyperscan caches under /var/lib/rspamd, then still reports syntax OK. That is not a clean operational test: the syntax is valid, but the process could not inspect every runtime resource it needs.

Capture the full result and status first:

$ rspamadm configtest -c /etc/rspamd/rspamd.conf > /tmp/rspamd-configtest.log 2>&1
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ rg -n 'Permission denied|syntax (OK|BAD)' /tmp/rspamd-configtest.log

Do not treat syntax OK as proof the service account can actually load this deployment. Run the check under the same account and environment as the daemon, or use the service's normal diagnostic procedure. Administrator approval for an elevated read-only validation can be appropriate, but sudo changes the environment and permissions, so it is not automatically equivalent to the daemon's own run.

5. Inspect the processed configuration

Once the syntax check actually means something, ask configdump to show the configuration after includes and variables have been resolved:

$ rspamadm configdump -c /etc/rspamd/rspamd.conf > /tmp/rspamd-configdump.txt
$ test -s /tmp/rspamd-configdump.txt && echo 'dump written'
dump written

Use -j for machine-readable output. You can also restrict the dump to a path accepted by the installed command:

$ rspamadm configdump -c /etc/rspamd/rspamd.conf -j > /tmp/rspamd-config.json
$ head -c 1 /tmp/rspamd-config.json
{

6. Keep password and key operations deliberate

The pw command can encrypt passwords, check encrypted passwords and list the available PBKDF algorithms. Listing algorithms is harmless:

$ rspamadm pw --list
pbkdf2: PBKDF2-blake2b - standard CPU intensive "slow" KDF using blake2b hash function
catena: Catena-Butterfly - modern CPU and memory intensive KDF

Password encryption and keypair generate security-sensitive output. Never put a real password in shell history, a process list or an article example. Read the command help first and use your organisation's secret-storage process: a generated keypair or encrypted password is not an undoable test, and replacing a live value can break controller access.

The same boundary applies to commands that merge databases, convert statistics or sign files. Validate paths and take a backup before any state-changing operation. The examples in this guide deliberately stop at inspection.