Check and Recalculate Mail Quotas with doveadm

A user is locked out of sending mail, yet doveadm quota get shows plenty of room, because Dovecot's own accounting has drifted from reality. This guide covers reading one user's quota and repairing stale figures with quota recalc. The local system runs Dovecot 2.3.21+dfsg1-2ubuntu6.5 from the dovecot-core package, and the syntax here is the installed Dovecot v2.3 interface.

Allow about ten minutes for a single user, longer if a recalculation has to scan a large mailbox. You need shell access to the Dovecot host and a username that exists in its user database. Reading usage is normally harmless; recalculation is an administrative repair operation and can create noticeable mailbox I/O.

1. Confirm the installation and quota plugin

Start with read-only checks as the account that will run the command:

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5

The quota get and quota recalc subcommands only work when the global mail_plugins setting includes the quota plugin. Check the effective configuration before troubleshooting the command itself:

$ doveconf -n | grep -E '^(mail_plugins|plugin \{)' -A 12

Look for quota in the effective mail_plugins value and for the quota settings in the plugin section. Do not add configuration just to make this test pass; confirm the host's existing quota design is the one you actually intend to inspect.

2. Read one user's current usage

Replace [email protected] with the exact login or userdb value used by this Dovecot installation:

$ doveadm quota get -u '[email protected]'
Quota name                        Type    Value  Limit  %
user                              STORAGE 90099 102400 87
user                              MESSAGE 20548  30000 68

The default formatter is a table, and storage values are reported in kilobytes. In the example, the user has used 90,099 KB of a 102,400 KB storage limit and 20,548 messages of a 30,000-message limit. A dash or other host-specific value can appear when a limit is not configured, so do not assume every quota has both limits.

$ doveadm quota get -u '[email protected]'
$ status=$?
$ printf 'quota get exit status: %s\n' "$status"
quota get exit status: 0

Status 0 means the command completed; it does not mean the figures are sensible, nor does it prove the user is below every configured limit. Read the rows and compare them with the expected quota policy.

3. Choose a clearer output formatter when needed

Use a global -f option before quota when another program will consume the result. The installed manpage documents flow, pager, tab and table:

$ doveadm -f flow quota get -u '[email protected]'
quota_name=user type=STORAGE value=90099 limit=102400 percent=87
quota_name=user type=MESSAGE value=20548 limit=30000 percent=68

Use the exact keys and spacing your host emits rather than parsing the visual table. For a human report, the default table is usually easiest to read; pager separates records with a form-feed character, while tab produces a header and tab-separated rows.

4. Recalculate one user's quota

Recalculation changes Dovecot's stored accounting for the selected user. Warn anyone operating the mail service and choose a maintenance window if the mailbox is large before running it. Do not start with -A on a busy production system: it targets every user returned by the user database and can cause substantial I/O.

$ sudo doveadm quota recalc -u '[email protected]'
$ status=$?
$ printf 'quota recalc exit status: %s\n' "$status"
quota recalc exit status: 0

Use elevated privileges only if your host's Dovecot administration model requires them; if the command can already connect and operate under the service's approved administrative account, do not add sudo just because the command repairs something. It does not delete messages, change quota limits or rewrite the quota configuration, but it can read a large amount of mailbox data.

5. Verify the repaired figures

Read the same user's quota again and compare it with the pre-recalculation capture:

$ doveadm quota get -u '[email protected]'
Quota name                        Type    Value  Limit  %
user                              STORAGE 90112 102400 88
user                              MESSAGE 20548  30000 68

A changed value is not automatically an error: recalculation may expose messages or sizes that were not included in the previous accounting. If the result is still implausible, inspect the effective quota configuration, mailbox location and the relevant quota backend before repeating the operation. For a longer job, add -v for a progress counter, and add -D only when you need debug messages for an incident report.

6. Operate on a controlled set of users

The -u option accepts a user or mask, including * and ? wildcards. Quote a mask so the shell does not expand it:

$ sudo doveadm quota get -u '*@example.org'

For an explicit list, put one username per line in a file and use -F:

$ install -m 0600 /dev/null /tmp/quota-users.txt
$ editor /tmp/quota-users.txt
$ sudo doveadm quota recalc -F /tmp/quota-users.txt
$ rm /tmp/quota-users.txt

• A list file is easier to review than a wildcard. Check it before invoking the command, since every listed user is a target.
• Remove the temporary file after the run if it contains private addresses.
• -A pulls users from the user database instead. With SQL or LDAP, the manpage warns the iteration settings must match the database or some users may be missed; with the passwd database, review the first_valid_uid boundary before using all-user operations.

7. Separate connection and configuration failures

A message saying the quota command is unavailable usually points to the quota plugin not being enabled in mail_plugins. A socket connection error points to the doveadm administration socket, permissions or the Dovecot service, not necessarily a bad quota value. When administration deliberately runs through another socket, pass its absolute UNIX socket path with -S:

$ sudo doveadm -S /run/dovecot/admin quota get -u '[email protected]'

Use the socket path configured for this host; the example path is only a placeholder. A remote TCP connection also accepts hostname:port, but treat that as a security-sensitive administration channel and use your host's documented authentication and network controls.