List and Kick Connections with doveadm proxy

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.

1. Check the installed command and socket

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/dovecot

doveadm 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.

$ 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.

2. List active proxied users

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 143

The 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 failed

If 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 list

Do 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.

3. Choose a precise kick target

• Kick one user. Pass the login name after the command:

$ sudo doveadm proxy kick [email protected]

• Kick a matching set with wildcards. The manual permits * 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.

4. Kick connections for a backend host

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.

5. Use the right output when checking or scripting

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 list

• table 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.

6. Verify the result and recover safely

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 list

The 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.