Inspect Dovecot Login Penalties with doveadm penalty

You will use doveadm penalty to see the penalties currently held by Dovecot's anvil service, then narrow the report to one address or CIDR network. The command reads service state only. It does not clear penalties, disconnect users or change Dovecot configuration. Allow about ten minutes if Dovecot is already running and you have an account allowed to access its administrative socket.

This guide describes the installed dovecot-core package, version 1:2.3.21+dfsg1-2ubuntu6.5, whose command reports itself as Dovecot v2.3. The local manual page is the authority for the examples here. Newer Dovecot documentation uses the same core syntax but can add global options, so check man doveadm-penalty on the host you are administering.

1. Check the anvil socket before running the report

doveadm penalty normally connects to the Unix socket /run/dovecot/anvil. The socket location follows Dovecot's base_dir setting, so a deliberately customised installation may use another path. Check the service and socket without changing anything:

$ systemctl is-active dovecot
active
$ ls -l /run/dovecot/anvil
srw-rw---- 1 root dovecot 0 Sep 23 10:20 /run/dovecot/anvil

The exact owner, group and timestamp will differ. If the service is inactive, starting it is an operational decision outside this read-only check. If the socket exists but your account cannot open it, use an approved administrative account or ask the Dovecot operator to grant the required access. Do not loosen socket permissions just to make a diagnostic command work.

2. Show all current penalties

Run the command as an ordinary user first. It may need elevated privileges on a default installation, but sudo is not automatically required:

$ doveadm penalty
IP               penalty last_penalty        last_update
192.0.2.222            3 2010-06-15 15:19:27 15:19:27
192.0.2.53             3 2010-06-15 15:19:34 15:19:34

The header identifies four fields. IP is the address being tracked. penalty is the current penalty value. last_penalty records the latest penalty time, while last_update records the most recent update time. The dates above are the manual's sample data, not a promise about your server's clock or entries.

Your output may contain no rows when there are no current penalties. Treat the header and exit status as the useful result; do not interpret the example addresses as real clients.

3. Filter the report to an address or network

Pass an address as the final argument when you are investigating one client:

$ doveadm penalty 192.0.2.53
IP               penalty last_penalty        last_update
192.0.2.53             3 2010-06-15 15:19:34 15:19:34

You can also supply a network in CIDR notation. This is useful when a mail gateway, NAT device or test subnet is the common source:

$ doveadm penalty 192.0.2.0/24
IP               penalty last_penalty        last_update
192.0.2.53             3 2010-06-15 15:19:34 15:19:34
192.0.2.222            3 2010-06-15 15:19:27 15:19:27

Replace the documentation-only 192.0.2.0/24 value with a network you are authorised to inspect. The argument filters the report; it does not add a penalty and does not alter the network configuration.

4. Use an alternative anvil socket when required

Use -a when the anvil socket is not at the default location. The argument can be an absolute local Unix socket path:

$ sudo doveadm penalty -a /srv/dovecot/run/anvil 192.0.2.0/24

It can also be a remote endpoint in the form hostname:port:

$ doveadm penalty -a doveadm-admin.example.net:12345 192.0.2.0/24

Only use a remote endpoint when that listener is deliberately configured, authenticated and protected by the host's network controls. The command's -a option selects a socket; it does not turn an untrusted network into a safe administrative channel. Avoid putting credentials in shell history or pasting sensitive hostnames into shared tickets.

The local path in the first example is a placeholder. Verify it against the relevant base_dir and service configuration before running it. The sudo prefix is an example of elevated execution, not a requirement to use root for every installation.

5. Diagnose the common access failures

If the command reports a connection or permission error, capture the exact status immediately:

$ doveadm penalty
$ status=$?
$ printf 'doveadm penalty exit status: %s\n' "$status"
doveadm penalty exit status: 0

A non-zero status means the report was not obtained successfully. Check that the socket path is correct, Dovecot is running, and the invoking account can access the socket. If you use sudo, run the complete command with it rather than running only the status check as root:

$ sudo doveadm penalty 192.0.2.53
IP               penalty last_penalty        last_update
192.0.2.53             3 2010-06-15 15:19:34 15:19:34

Do not treat an empty report as proof that Dovecot has never penalised anyone. Penalty state changes over time, and a filter can legitimately match no rows. For a repeatable incident record, save the output with a timestamp in a protected location, then review and remove that copy according to your normal retention policy. The command itself makes no persistent change and has no undo operation.