Reload or Stop Dovecot Safely with doveadm

Reload the wrong way and Dovecot ignores half your config change; stop it and every connected mail client drops without warning. This guide covers the installed doveadm command set, a safe reload after a configuration change, and the difference between the two. The examples target Ubuntu's package, Dovecot 2.3.21, and take about ten minutes once you have shell access.

Before you begin

You need a shell on the Dovecot host, the dovecot-core package, and access to Dovecot's administrative socket. Reloading and stopping the master process normally need root, so use sudo where your system grants it. Do not test the stop command on a production server just to see what it does.

Keep a copy of the configuration change you're about to apply, and know how this host starts Dovecot again. A reload is usually reversible by restoring the previous configuration and reloading it; a stop is a service outage that needs an explicit restart step.

1. Confirm the local command

Check the package version and ask doveadm for its command list, so you're not copying options from a different Dovecot release. This installation reports version 2.3.21:

dpkg-query -W dovecot-core; doveadm help

The first command prints a dovecot-core version starting with 1:2.3.21 here. The second prints the global syntax followed by commands such as reload and stop. A permission error connecting to a Dovecot socket means rerun with sudo, not change the socket's permissions.

2. Validate before you reload

Check the effective configuration before asking the running server to read it. The doveadm manpage names /etc/dovecot/dovecot.conf, conf.d/10-mail.conf and conf.d/90-plugin.conf as key files; on a host with its own packaging or include conventions, follow whatever dovecot.conf actually references.

sudo doveconf -n

Read the output for the setting you changed and for obvious path, permission or syntax mistakes. Save it if you need to report a failure: Dovecot's own documentation recommends attaching doveconf -n to any bug report.

3. Reload the running server

Once the configuration check is clean, reload:

sudo doveadm reload; printf 'reload exit status: %s\n' "$?"

reload tells the Dovecot master to reread its configuration; it does not mean every existing connection instantly adopts every new setting. Check the exit status, then check the Dovecot log or service status with whatever logging and service tools this host uses.

Useful output controls

The global -D option turns on debug messages, -v adds verbosity and a progress counter, and -f picks a formatter for commands that produce records. table gives aligned columns; flow gives key=value pairs:

sudo doveadm -f table who; sudo doveadm -f flow who

Don't parse human-oriented table output in a script when a stable machine-readable form exists for that command. The global -o setting=value option overrides one configuration setting for a single invocation, and can be repeated; treat it as a diagnostic tool, not a way to edit the running config.

4. Stop Dovecot only when you mean an outage

sudo doveadm stop; printf 'stop exit status: %s\n' "$?"

Before running it, know the service-manager command or platform procedure that starts Dovecot on this host: the doveadm manpage does not prescribe one universal start command. After maintenance, start it with that procedure and verify both the service state and a real client connection. If the stop itself fails, check the log and process state before repeating it; hammering the command can hide the original fault.

Common traps

• Copying an option from another release. Run doveadm help on the target host first. This guide is written against Dovecot 2.3.21.
• Confusing reload with restart. Reload asks the master to reread configuration; it is not a full process replacement and not a substitute for a package upgrade.
• Ignoring the privilege boundary. A shell that can run doveadm may still be unable to reach the administrative socket. Keep the socket's ownership as-is and use the intended administrative account.
• Treating a clean exit as proof of health. The exit status covers that one invocation. Check logs, process state and a real mail client afterwards.