Disconnect Dovecot Sessions Safely with doveadm kick

You will disconnect selected Dovecot sessions by login name, source IP address, network range, or a combination of user and network. This guide follows the locally installed Dovecot 2.3.21 package on Ubuntu. Allow about 10 minutes for a careful one-off operation, including the preview.

Before you start

You need the dovecot-core package, a shell on the Dovecot server, and administrative access to the Dovecot control socket. The examples use documentation addresses and names. Replace them with real values only after checking the current sessions.

doveadm kick is service-disrupting: matching clients are disconnected and may reconnect immediately. It does not delete mail, disable an account, or block an address. Treat a broad user pattern or network range as an outage-sized action. Run the commands as a user that can access Dovecot's control socket, commonly root or a suitably privileged service administrator.

1. Check the installed command and current sessions

The installed package reports version 2.3.21 on the system used for this guide. Confirm the package version on your host, then list sessions before choosing a mask.

dpkg-query -W -f='${Version}\n' dovecot-core
sudo doveadm who -1

Expected output is a table containing fields such as username, proto, pid and ip. If doveadm who cannot connect to the socket, stop here and fix the service or permissions. Do not guess a socket path while preparing a disconnect.

2. Preview a user's sessions

Use doveadm who with a user mask to see the likely target. In a shell, quote wildcard masks so the shell does not expand them against local filenames.

sudo doveadm who -1 '[email protected]'
sudo doveadm who -1 'jane*'

The first command targets one login name. The second is broader: it can match login names beginning with jane. The who command is only a preview; it does not disconnect anything.

3. Disconnect by login name

When the preview shows the intended accounts, pass the same mask to kick.

sudo doveadm kick '[email protected]'

For a wildcard example, ba? matches login names with three characters beginning with ba, such as bar and baz. The command prints a list headed by kicked connections from the following users: when matching connections are removed. An empty or non-matching result is not evidence that every session is gone, so repeat the preview.

4. Disconnect by address or network

Use an individual address for one observed client, or CIDR notation for a network. IPv4 and IPv6 addresses are accepted by the command documented here.

sudo doveadm who -1 '192.0.2.53'
sudo doveadm kick '192.0.2.53'

sudo doveadm who -1 '192.0.2.0/24'
sudo doveadm kick '192.0.2.0/24'

The network form disconnects all users connected from that range. Check the range carefully: a /24 covers many addresses, not just the address shown in the preview. If your shell or a wrapper treats the slash specially, quote the argument as shown.

5. Narrow the action to a user and network

The safest useful form often combines a login mask with an address range. It disconnects only sessions satisfying both conditions.

sudo doveadm who -1 'foo'
sudo doveadm kick 'foo' '192.0.2.0/24'
sudo doveadm who -1 'foo'

After the kick, sessions for foo from the documentation range should no longer appear, while a session for foo from another address can remain. The command can print the user's name even when several matching connections existed.

6. Handle the force option and alternate socket

Normally, Dovecot avoids a disconnect when multiple users from different networks share one process. The command's -f option enforces the disconnect in the special configuration described by the manpage: for example, an IMAP service with client_limit set to 1+n, service_count set to 0, and several users in one process.

sudo doveadm kick -f 'foo' '192.0.2.0/24'

Use -f only when you understand that shared-process situation. It is not a general repair switch for a failed socket or a permission error.

The default control socket is /run/dovecot/anvil. If the configured base_dir puts it elsewhere, supply an absolute path:

sudo doveadm kick -a '/run/dovecot/anvil' 'foo'

Use the actual path from the running configuration. An alternative socket path does not bypass permissions or make an incompatible Dovecot instance safe to control.

7. Verify and recover

Run the same who query after every kick. If a session is still listed, check that the username and address were copied exactly, that a proxy has not changed the visible address, and that you used the intended Dovecot instance. Add -v for progress output or -D for debug messages when investigating a controlled failure, but avoid leaving debug output in shared logs if it contains operational details.

sudo doveadm who -1 'foo'
sudo doveadm who -1 '192.0.2.0/24'

There is no undo command: a kick only ends the connections. The recovery is for affected users to reconnect, subject to your normal authentication and service policy. If clients reconnect immediately, use the preview to distinguish a successful kick from an ongoing client or network problem.

Done means

• You confirmed the installed Dovecot version and could run doveadm who.
• You previewed the exact user, address or network before disconnecting it.
• You used quoted masks and treated wildcard and CIDR matches as broad actions.
• You verified the post-kick session list and know that recovery means reconnecting, not undoing the command.