Audit and Remove Stale Dovecot Instances with doveadm

Use doveadm instance to see which Dovecot instances the host still remembers and to remove an obsolete entry. It earns its keep on a box running more than one Dovecot, and after a service move leaves stale state behind. The read-only audit takes about five minutes.

The route

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

1. Check the command and your access
2. List the remembered instances
3. Choose output for scripts or people
4. Remove only a confirmed stale entry
5. Verify the result
Common traps

The installed package checked for this guide is dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5, providing the Dovecot 2.3 command documented by the local manpage.

Warning

The listing is metadata. It is not, by itself, proof that a process is alive. Removal takes longer only if you need to prove the target is no longer used.

1. Check the command and your access

Run the version check and confirm the subcommand is available. This does not change Dovecot configuration or service state.

doveadm --version
doveadm help instance

On the reference installation, doveadm --version reports Dovecot 2.3.21. The manpage describes two operations: instance list and instance remove. If your distribution reports a different version, read its installed manpage before copying the examples below.

2. List the remembered instances

Start with the default table output. It shows the instance path, its configured or discovered name, when it was last used, and whether Dovecot currently considers it running.

doveadm instance list

A typical record looks like this:

path                         name    last used           running
/run/dovecot                 dovecot 2026-09-23 10:03:43 no

running=no is not an instruction. It describes the record at the time of the query, so do not read it as a request to stop anything.
Listed does not mean current. An instance being listed does not tell you its configuration is still the one you expect.
Verify elsewhere. Confirm service and process state with your normal service-management tools before deleting anything.

Checkpoint

Write down the full path and name you intend to investigate. The removal command accepts either the instance name or its base directory. The path is often safer when names are duplicated across old configurations, because it identifies the instance's base_dir directly.

These are ordinary, read-only checks. Replace the placeholder path with the path from your listing:

INSTANCE_BASE_DIR="/run/dovecot"
sudo systemctl status dovecot
sudo find "$INSTANCE_BASE_DIR" -maxdepth 1 -type f -printf '%f\n' 2>/dev/null

Tip

The sudo prefix is needed only where your account cannot inspect the service or directory. A missing directory alone does not prove the record is stale, because a service may recreate runtime directories during startup.

3. Choose output for scripts or people

The global -f option changes presentation without changing the query:

table for an operator's quick scan.
tab when a simple tab-separated stream is convenient.
flow for one record per line.
pager when each field should be printed on its own line.

doveadm -f table instance list
doveadm -f tab instance list
doveadm -f flow instance list
doveadm -f pager instance list

The flow form is usually easiest to log because a record stays on one line:

path=/run/dovecot name=dovecot last used=2026-09-23 10:03:43 running=no

Tip

In scripts, treat field names and values as data rather than splitting blindly on spaces. The date contains a space, and names or paths differ between installations. The manpage documents these four formatters, not a JSON output mode.

4. Remove only a confirmed stale entry

Removal changes Dovecot's instance list. It does not edit dovecot.conf, stop a service, or uninstall a package. It is still a consequential administrative action, so pause first if the instance may be used by a director, proxy or backend.

Use the exact name from the listing:

sudo doveadm instance remove dovecot

Or use the exact base directory instead:

sudo doveadm instance remove /run/dovecot

Use one form, not both. The command takes name | base_dir.

Warning

Do not substitute a broad parent such as /run, and do not remove a record merely because it is not currently running.

Recovery

The local manpage does not describe an undo command. If you remove the wrong record, start the intended Dovecot instance again so it adds itself back to the list automatically, then verify its name and base directory. Restore any missing instance_name configuration separately if that was the actual mistake.

5. Verify the result

List the instances again and check that the targeted name or path is gone. If you removed an active record, confirm service health and mail flow before treating its reappearance as a fault.

doveadm instance list
doveadm -f flow instance list

Checkpoint

With no matching record, the cleanup is complete. If it comes straight back, inspect the service logs and configuration. Running Dovecot instances add themselves automatically, so a live instance will recreate its entry.

Common traps

Confusing name and path. dovecot is an instance_name; /run/dovecot is a base directory. They are alternative arguments to remove.
Deleting a live backend. A list entry can represent a proxy or backend in a multi-instance setup. Confirm ownership before changing it.
Parsing the table. Aligned columns are for people. Use flow for a stable key-and-value view, and still allow for spaces in values.
Chasing permission errors. Read-only listing may emit errors when the account cannot reach Dovecot's runtime sockets or pid file. Elevate only for the administrative check that needs it, and treat the displayed record as something to verify rather than silently ignoring the error.
Expecting configuration changes. Instance removal does not change dovecot.conf. If the record returns, find and correct the service or instance configuration instead.

Done means

Record noted. You wrote down the exact instance name and base directory.
State checked. You confirmed service state before removing anything.
Formatter chosen. You used a documented formatter suited to the task.
Only stale removed. If removal was needed, it was a confirmed stale record.
Result verified. A second doveadm instance list shows the expected outcome.