doveadm proxy shows exactly who is routed through Dovecot right now, and lets you disconnect them the moment something needs draining. A read-only check takes about ten minutes; a controlled disconnect needs fifteen, and the disconnect itself is immediate for every matching connection, so treat it as service-affecting.
This guide follows the installed dovecot-core package, version 1:2.3.21+dfsg1-2ubuntu6.5, which the local manual identifies as Dovecot v2.3. You need the doveadm binary and access to Dovecot's IPC socket. Run the inspection as an ordinary user first, and reach for extra privilege only when the socket denies access.
Confirm the binary and the configured base directory before looking at sessions. These are read-only commands:
$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5
$ doveconf -h base_dir
/run/dovecotdoveadm proxy uses /run/dovecot/ipc by default. If your base_dir is different, derive the socket path from that setting, or pass the exact absolute path with -a; never guess a socket path borrowed from a different host.
Checkpoint: the socket must exist and be accessible before any of these commands can report proxy state:
$ stat /run/dovecot/ipc
$ test -S /run/dovecot/ipc && echo 'IPC socket found'A socket can exist while its permissions still block access. That is an access problem, not evidence that Dovecot has no proxy connections.
Run the read-only list command:
$ doveadm proxy list
username proto src ip dest ip port
[email protected] imap 192.168.0.100 192.168.0.5 143The columns are the login name, protocol, source address, destination address and destination port. Your rows are host-specific and can change while you read them, so treat the output as a snapshot rather than a lock on a connection.
This command could not reach the local IPC socket in the restricted shell used to prepare this guide, so its diagnostic was:
Error: connect(/run/dovecot/ipc) failed: Permission denied
Error: LIST-FULL failed: ipc connect failedIf you see the same result, check socket ownership and the account used for Dovecot administration, then retry the unchanged read-only command with the required privilege if your policy permits it:
$ sudo doveadm proxy listDo not treat a permission error as an empty list, and do not add sudo to scripts without first deciding how the script authenticates and where its output ends up.
Warning: proxy kick disconnects matching active proxy connections outright. It does not just hide them from the list, and there is no rollback command that reconnects users to their previous sessions. Record the list output, identify the exact login or backend, and check the maintenance impact before running it.
$ sudo doveadm proxy kick [email protected]* and ?:$ sudo doveadm proxy kick '*@example.net'Quote wildcard patterns so the shell does not expand them against local file names. A wildcard can affect many accounts at once, so use one only when that scope is deliberate; start with the exact account name if you are troubleshooting a single session.
Use -h when the target is a backend host rather than a user:
$ sudo doveadm proxy kick -h backend-01.example.net-h takes a host list, and leaving it out takes a user list; do not combine the two casually. Decide whether the incident follows the account or the destination backend, and use the exact host value shown by the proxy list and your Dovecot configuration. If a hostname resolves to more than one address in your environment, confirm the matching behaviour in a maintenance test rather than assuming DNS names and displayed destination addresses line up.
The optional -f passdb_field argument changes which passdb field is used for the kick lookup. That choice depends on your configuration: check the passdb schema and your Dovecot administration documentation before using it, rather than guessing a field name from a username column.
The global -f option selects an output formatter and is separate from the kick command's -f passdb_field option. The supported formatters are table, tab, flow and pager, and the default is table:
$ doveadm proxy list
$ doveadm -f flow proxy listtable is convenient for a person but awkward to parse reliably once column widths or addresses change.flow prints one key=value pair set per line.tab is tab-separated records with a header.pager separates records with a form-feed character.Test whichever formatter you script against on the installed version. -D enables debug messages and -v enables verbosity, including a progress counter; add them only while diagnosing a controlled command, since extra diagnostic output can confuse a simple parser. The global -o setting=value option can override configuration for that one invocation, so treat it as an explicit test, never a permanent change.
After a kick, wait for the affected client or service to notice the disconnect, then list the proxy state again:
$ sudo doveadm proxy list
$ sudo doveadm -f flow proxy listThe targeted connection should no longer appear unless it has already reconnected automatically, so disappearance alone is not proof the account has been blocked. If a backend kick is followed by new rows for the same host, investigate the client's retry behaviour and the proxy configuration.
Recovery: there is no undo operation in doveadm proxy. Recovery means letting the client reconnect, or restoring service through your normal Dovecot and backend procedure. If the kick was too broad, stop issuing further kicks, preserve the before-and-after output, and contact the service owner; do not restart Dovecot just to force a visual change in the list.
doveadm proxy list reached the intended IPC socket, and access errors were distinguished from a genuinely empty result.base_dir were confirmed.