Run Rspamd 3.8.1 Safely in the Foreground

A mail filter that will not start is a bad time to be guessing at flags, so run Rspamd by hand and watch it fail in plain sight instead. This guide covers the Rspamd 3.8.1 package installed on this machine: confirm the binary, check the config, and launch it in the foreground with --no-fork so the logs land in your terminal. Allow about 15 minutes if the configuration already exists, plus time to chase down any error it throws.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Confirm the binary and installed version
2. Read the options before changing runtime state
3. Locate and inspect the configuration
4. Start a controlled foreground test
5. Run under the intended account
6. Choose a pidfile deliberately
7. Turn a failure into the next check

This is an administration task. Reading the version and help output needs no special access. Starting Rspamd may need elevated privileges if it must read protected configuration, bind a restricted port, create a pidfile in a protected directory, or switch to a service account. A foreground process also occupies your terminal until you stop it.

1. Confirm the binary and installed version

Check which executable the shell will actually run before you debug the wrong installation:

$ command -v rspamd
/usr/bin/rspamd
$ rspamd --version
Rspamd daemon version 3.8.1

The corresponding Ubuntu package on this machine is rspamd 3.8.1-1ubuntu3. Your path and package revision can differ, and the package version and daemon version should agree; report both when documenting a host. If command -v prints nothing, stop here and install or repair the package through your normal package-management process rather than guessing a path.

Checkpoint

You know the exact executable and version that will be started.

2. Read the options before changing runtime state

Ask the installed daemon for its own help text rather than trusting an example copied from another Rspamd release:

$ rspamd --help
Usage:
  rspamd [OPTION...] - run rspamd daemon

Application Options:
  -f, --no-fork           Do not daemonize main process
  -c, --config            Specify config file(s)
  -u, --user              User to run rspamd as
  -g, --group             Group to run rspamd as
  -p, --pid               Path to pidfile
  -d, --debug             Force debug output
  -i, --insecure          Ignore running workers as privileged users (insecure)

Rspamd also reports options for its version, environment variables, Jinja templates and Lua environment. Do not add those merely because help lists them. Use an option only when you have a reason to test its effect.

3. Locate and inspect the configuration

The manpage accepts one or more configuration paths with -c or --config. Use an explicit path so the test is repeatable. Replace /etc/rspamd/rspamd.conf with the file used by your deployment; do not create a new one by copying this placeholder.

$ test -r /etc/rspamd/rspamd.conf && echo 'configuration is readable'
configuration is readable
$ ls -l /etc/rspamd/rspamd.conf

The installed Rspamd package commonly keeps additional configuration under /etc/rspamd, but the manpage does not define a universal directory layout. Confirm the paths on your host and preserve the existing ownership and permissions. If the file is absent or unreadable, fix that packaging or permissions problem before starting the daemon.

Checkpoint

You have an actual readable configuration path, not a guessed filename.

4. Start a controlled foreground test

Use --no-fork for a test: the logs stay in the terminal and you can stop the process with the normal interrupt key. Supply the configuration explicitly:

$ rspamd --no-fork --config /etc/rspamd/rspamd.conf

A successful launch stays attached to the terminal and prints its runtime messages there. It may show no prompt because the daemon is still running; press Ctrl-C only when you mean to stop this test process.

Never run this against a production instance just to see if it starts. It can create a second daemon, fight for listeners or pidfiles, and disrupt mail filtering.
Check how your service manager normally starts Rspamd first. Run systemctl status rspamd --no-pager shown below.

$ systemctl status rspamd --no-pager

If a service is already active, prefer its logs and status commands. If you must run a foreground test, use a maintenance window and a configuration that will not collide with the live instance. Elevated privileges belong at the start of the command, and only when the host's permissions require them:

$ sudo rspamd --no-fork --config /etc/rspamd/rspamd.conf

There is no persistent change to undo when you stop a foreground test, apart from any pidfile or other runtime artefact the daemon created. Let it shut down normally with Ctrl-C, then confirm the process has gone:

$ pgrep -a rspamd || echo 'no rspamd process found'

5. Run under the intended account

-u and -g pick the user and group Rspamd runs as, which matters when a direct launch has to match a service account:

$ getent passwd rspamd
rspamd:x:...:...:...:/var/lib/rspamd:/usr/sbin/nologin
$ getent group rspamd
rspamd:x:...
$ sudo rspamd --no-fork --config /etc/rspamd/rspamd.conf --user rspamd --group rspamd

The account database fields above are illustrative, not values to paste; the ellipses stand in for whatever your host reports. Use the account that actually owns or can read the configuration, certificates, maps and runtime directories your installation needs. A non-root launch can fail because a file or socket is inaccessible, and that is a permissions diagnosis, not a reason to reach for --insecure.

Warning

--insecure tells Rspamd to ignore workers running as privileged users, and the installed manual labels the option insecure by name. Leave it out in normal operation. If a test genuinely needs it, record why, keep the test isolated, and remove the flag from the command afterwards.

6. Choose a pidfile deliberately

Use -p or --pid only when you need to control where the pidfile lands. The destination must be writable by the process creating it and must never collide with another Rspamd instance's pidfile:

$ sudo rspamd --no-fork \
    --config /etc/rspamd/rspamd.conf \
    --user rspamd --group rspamd \
    --pid /run/rspamd-test.pid

Do not point a test at the live daemon's pidfile. If the test exits and leaves what looks like a stale file, verify first that no Rspamd process holds the recorded process ID, then remove only that known test pidfile with elevated privileges if necessary:

$ test -f /run/rspamd-test.pid && cat /run/rspamd-test.pid
$ pgrep -a rspamd
$ sudo rm -- /run/rspamd-test.pid

Destructive action

That removal deletes a small runtime file for good, so check the path and process list before you run it. Never remove a pidfile simply because it looks old.

7. Turn a failure into the next check

A foreground launch gives you the most direct diagnostic you will get. Match the failure to the check:

Configuration parse error: points at the file or setting that needs attention.
Permission error: points at ownership, mode bits, a directory, a certificate or a map.
Address already in use: usually means another process already owns that listener.

Check those facts before touching the configuration again:

$ ps -ef | grep '[r]spamd'
$ ss -ltnp
$ namei -l /etc/rspamd/rspamd.conf

Reach for --debug when ordinary foreground output does not tell you enough:

$ rspamd --no-fork --debug --config /etc/rspamd/rspamd.conf

Warning

Debug output can expose paths, connection details or configuration values in a terminal or captured log. Treat it as sensitive operational data, and never paste it into a public issue without reviewing it first.

Done means

You confirmed the executable and installed Rspamd version.
You verified a real, readable configuration path.
You understand that --no-fork keeps the daemon in the terminal.
You avoided starting a second instance on a live service.
You used the intended user, group and pidfile only when required.
You left --insecure out of normal operation.
You stopped any test process and checked for leftover runtime state.