Run Rspamd 3.8.1 safely in the foreground

You will identify the installed Rspamd binary, inspect its version, and start it in the foreground with an explicit configuration when you need to test or troubleshoot a daemon launch. This guide describes the Rspamd 3.8.1 package installed on this machine. Allow about 15 minutes if the configuration already exists, plus time to investigate any configuration error.

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

1. Confirm the binary and installed version

Start by checking which executable the shell will run. This avoids debugging one installation while the shell finds another. The package version and daemon version should agree, but report both when documenting a host.

$ 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. If command -v prints nothing, stop here and install or repair the package through your normal package-management process. Do not work around a missing binary by guessing a path.

Checkpoint: you know the exact executable and version that will be started.

2. Read the options before changing runtime state

The installed daemon supports the options used in this guide. Ask it for the complete local help text rather than relying on 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 options merely because they appear in help. Use only an option whose effect you have a reason to test.

3. Locate and inspect the configuration

The manpage accepts one or more configuration paths with -c or --config. Use an explicit path for a repeatable test. Replace /etc/rspamd/rspamd.conf with the configuration file used by your deployment; do not create a new file 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 has additional configuration under /etc/rspamd, but this 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 issue 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 because its logs stay in the terminal and the process can be stopped with the normal interrupt key. The command below supplies the configuration explicitly:

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

A successful launch remains attached to the terminal and emits its runtime messages there. It may produce no prompt because the daemon is still running. Press Ctrl-C only when you intend to stop this test process.

Do not run this command against a production instance merely to see whether it starts. It can create a second daemon, compete for listeners or pidfiles, and disrupt mail filtering. First check how your service manager normally starts Rspamd:

$ 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 does not collide with the live instance. Elevated privileges belong at the start of the command 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 created by the daemon. Let the daemon perform its normal shutdown with Ctrl-C, then check that the process has gone:

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

5. Run under the intended account

The -u and -g options select the user and group for Rspamd. They are useful when testing a direct launch that must 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 exact account database fields vary, so the ellipses above are illustrative output, not values to paste. Use the account that actually owns or can read the configuration, certificates, maps and runtime directories required by your installation. A non-root launch can fail because a file or socket is inaccessible; that is a permissions diagnosis, not a reason to add --insecure.

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

6. Choose a pidfile deliberately

Use -p or --pid only when you need to control where the pidfile is written. The destination must be writable by the process that creates it and must not be shared accidentally with another Rspamd instance:

$ 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 an apparently stale file, first verify that no Rspamd process is using 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

The final removal is destructive to that small runtime file, so check the path and process list before running it. Never remove a pidfile simply because it is old.

7. Turn a failure into the next check

A foreground launch gives you the most direct diagnostic. A configuration parse error points at the file or setting that needs attention. A permission error points at ownership, mode bits, a directory, certificate or map. An address-in-use error usually means another process already owns a listener. Check those facts before changing configuration:

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

Use --debug when ordinary foreground output is not enough:

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

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