Check and Recalculate Mail Quotas with doveadm

You will finish with a repeatable way to inspect one Dovecot user's quota and, when the stored figures are stale, recalculate them. The local system has Dovecot 2.3.21+dfsg1-2ubuntu6.5 from the dovecot-core package. The command syntax here is the installed Dovecot v2.3 interface.

Allow about ten minutes for a single user, plus 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. These do not change mailbox data:

$ 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 are available only 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

The exact output depends on the host. Look for quota in the effective mail_plugins value and for the quota settings in the plugin section. Do not add configuration merely to make this test pass: confirm that the host's existing quota design is the one you 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. The 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.

Checkpoint: save the command's status immediately if this is part of a script:

$ 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 that 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 emitted by your host 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. Before running it, warn anyone operating the mail service and choose a maintenance window if the mailbox is large. 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 the host's Dovecot administration model requires them. If the command can connect and operate under the service's approved administrative account, do not add sudo just because the command is a repair operation. The command does not delete messages, change quota limits or rewrite the quota configuration, but it can read a large amount of mailbox data.

There is no separate undo command for a recalculation. The recovery path is to correct the underlying quota configuration or mailbox state, then run the recalculation again. Take a configuration backup and record the before-and-after output if you need an audit trail.

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 operation, add -v to enable verbosity including a progress counter. Add -D only when you need debug messages for an incident report. Keep diagnostic output out of routine scripts unless you have a reason to retain it.

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

The list-file method is easier to review than a broad wildcard. Check the file before invoking the command, because every listed user is a target. Remove the temporary file after the run if it contains private addresses. If you use -A, Dovecot obtains the users from the user database. With a SQL or LDAP user database, the manpage warns that the iteration settings must match the database or some users may be missed. With the passwd user database, review the first_valid_uid boundary before using all-user operations.

7. Separate connection and configuration failures

A message saying that 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 to a bad quota value. When administration is deliberately performed 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. For a remote TCP connection, the installed syntax also accepts hostname:port, but treat that as a security-sensitive administration channel and use the host's documented authentication and network controls.