Reload Dovecot Without Dropping Live Sessions

Get one word wrong in a Dovecot config file and a careless reload can boot every logged-in IMAP and POP3 client off the server. This walks through checking the installed Dovecot version, reading the active configuration, test-driving a config file before it goes near production, and reloading without guessing what happens to sessions that are already open. Budget about 10 minutes. The examples match the installed Ubuntu package dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5, whose binary reports Dovecot 2.3.21.

You need a shell account that can read the configuration for the read-only checks in the first three sections. Reloading or stopping the service normally needs root, so keep sudo for those steps only. Swap in a real test configuration path wherever you see /path/to/dovecot.conf: it is a placeholder, not something to paste as is.

1. Check the installed command and package

• Get the version Dovecot reports. dovecot --version and the package version from dpkg-query tell you exactly what you are running, before you compare notes with another machine or a random forum post.
• List the build options. dovecot --build-options shows which SQL drivers, passdb and userdb backends this particular build has. Do not assume every Dovecot install ships the same set.

$ dovecot --version
2.3.21 (47349e2482)
$ dpkg-query -W -f='\${Package} \${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5
$ dovecot --build-options
Build options: ioloop=epoll notify=inotify openssl io_block_size=8192
SQL driver plugins: mysql postgresql sqlite
Passdb: checkpassword ldap pam passwd passwd-file shadow sql
Userdb: checkpassword ldap(plugin) passwd prefetch passwd-file sql

None of this touches Dovecot's state. Build options vary by package, so treat what you just saw as the contract for this host, not a universal truth.

Checkpoint: you have the exact executable and package version pinned down before comparing behaviour with another machine or an upstream document.

2. Find the configuration file and inspect non-default settings

dovecot -n prints every setting that differs from the default, and the first line tells you exactly which file it read. It is equivalent to doveconf -n.

$ dovecot -n
# 2.3.21 (47349e2482): /etc/dovecot/dovecot.conf
# Pigeonhole version 0.5.21 (f6cd4b8e)
# OS: Linux 6.8.0-139-generic x86_64 Ubuntu 24.04.5 LTS
protocols = imap pop3
mail_location = maildir:~/Maildir
ssl = required

• Do not paste the full output into a ticket. Your settings will differ from the example, and the output can include private paths, usernames and hostnames.
• Leave doveconf -P alone in routine diagnostics. It exists specifically to reveal passwords and other sensitive values that -n hides.
• Edit the file that owns the setting. The main file is normally /etc/dovecot/dovecot.conf, and it may include files under /etc/dovecot/conf.d/. A competing duplicate just confuses the next person.

After any edit, run the inspection again and check the value actually changed.

3. Test an alternative configuration without touching the live one

The -c option points Dovecot at a specific config file. Pair it with -n for a read-only parse.

$ sudo dovecot -n -c /path/to/dovecot.conf
# 2.3.21 (47349e2482): /path/to/dovecot.conf
protocols = imap pop3

A successful run prints settings and exits. A syntax or include error prints a diagnostic and a non-zero exit status: fix the reported file and line, then run it again.

Warning: do not start a second Dovecot instance just to test syntax. It needs its own paths and unused listener ports, and it can collide with the production service.

Configuration files can contain secrets or point at secret files. Keep any temporary copy readable only by the administrator doing the work, and remove it through your normal change-control process once you are done. Never repurpose a live private key as a test fixture.

Checkpoint: dovecot -n succeeds against the exact configuration you plan to reload, and its output shows the change you intended.

4. Reload a running service after a reviewed change

Once the check passes, ask the running master process to reload. This is a service operation, so it needs elevated privileges on a normal package install.

$ sudo dovecot reload
$ sudo dovecot -n | sed -n '1,12p'
# 2.3.21 (47349e2482): /etc/dovecot/dovecot.conf
...

The reload command is silent on success. The second command confirms what Dovecot reads after the reload, but it does not prove every existing client has moved onto the new settings, only that new connections will.

Tip: the manual documents a boundary that is easy to miss. With shutdown_clients = no, sessions that were already open can keep running on the old settings after a reload. That is useful for cutting disruption, but it means a change can be live for new connections before it is live for old ones. Check your session policy before calling the job done.

If systemd manages the service, sudo systemctl reload dovecot may be your host's convention, but the interface documented here is Dovecot's own. Follow the service manager's status and logging workflow if it reports a failure.

5. Use signals only when you need their specific effect

Dovecot also answers to two signals: HUP reloads configuration, and USR1 reopens the configured log files, useful after rotating logs without changing anything else.

$ sudo kill -HUP "$(cat /run/dovecot/master.pid)"
$ sudo kill -USR1 "$(cat /run/dovecot/master.pid)"

The PID path depends on your install, so check your package's process and runtime configuration first. Prefer dovecot reload when you have it, since it avoids hard-coding a PID file location. A stale PID or a failed command substitution will happily signal the wrong process, so verify the target before you send anything.

6. Avoid the destructive stop command

Warning: dovecot stop shuts down Dovecot and its child processes, and by default that takes active sessions down with it. It is not a routine way to apply a config edit. Warn connected users, confirm the maintenance window, and make sure your service manager knows how to bring it back up.

$ sudo dovecot stop
$ sudo systemctl status dovecot --no-pager

Recovery: if you stopped the service by mistake, bring it back through the host's service manager rather than launching an unmanaged daemon.

$ sudo systemctl start dovecot
$ sudo systemctl status dovecot --no-pager

No systemd on your host? Use its installed init script or package documentation instead. dovecot stop only stops the running processes; it cannot undo changes already made to a configuration file.

7. Diagnose a failed change

Rerun the non-destructive parse first and capture its exit status, then check the service manager and Dovecot's logs. The traps that catch people out:

• Editing an included file that gets overridden later. Check the whole include chain, not just the file you touched.
• Testing one configuration with -c and reloading another. Make sure the path you validated is the path the live service actually reads.
• Treating a successful parse as proof of anything more. A clean dovecot -n only means the syntax is valid, not that certificates, sockets or authentication backends actually work.

$ sudo dovecot -n >/tmp/dovecot-n.txt
$ echo $?
0
$ sudo systemctl status dovecot --no-pager
$ sudo journalctl -u dovecot -n 50 --no-pager

That temporary file can contain infrastructure details, so read it locally and delete it once you are done. If validation fails, restore the last known-good file from your change record, run dovecot -n again, and reload only once it passes.

Done means

• Version pinned. dovecot --version and the package version are recorded for this host.
• Config file identified. dovecot -n names the active file and shows the settings you expect.
• Alternative config validated. Any file used with -c passed dovecot -n -c ... before deployment.
• Reload confirmed. The service reloaded only after validation, and you know how existing sessions behave.
• Stop avoided. Nobody ran dovecot stop without a maintenance and recovery plan.