Manage Dovecot Mailbox Permissions Safely with doveadm acl

You will grant, inspect, replace and remove a Dovecot mailbox ACL entry with doveadm acl, then verify the resulting rights. Allow about 15 minutes for one mailbox, provided the account and mailbox already exist. The examples describe the installed Dovecot 2.3 command from package dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5.

You need shell access to the mail host and a Dovecot installation using the ACL plugin. The commands that change another user's mailbox normally require the privileges of your Dovecot administration setup, so use the account and socket arrangement approved for that host. Do not add sudo automatically: it can hide a socket or configuration problem.

1. Check that ACL support is ready

The command is provided by the Dovecot core package, but the acl plugin must also be enabled for the server configuration. Check the effective configuration before changing a mailbox:

$ doveconf -n | grep -E '(^|[[:space:]])mail_plugins[[:space:]]*='

Look for acl in the relevant mail_plugins setting. On a system where the plugin is not enabled, doveadm acl can fail even though the executable and manual page are installed. Fix the Dovecot configuration through your normal deployment process, then recheck the service configuration before continuing.

Checkpoint: identify the target user and mailbox precisely. In the examples, [email protected] is the mailbox owner and shared/Support is the mailbox name. Replace both values before running a command.

2. Read the current ACL entry first

Use get to show every ACL entry on a mailbox. The -u option makes the user context explicit:

$ doveadm acl get -u [email protected] 'shared/Support'
ID               Global Rights
---------------  -------------
owner            lookup read write write-seen write-deleted insert post expunge create delete admin
[email protected] lookup read

The table columns and spacing can vary with the installed formatter, so use the entry values rather than copying the visual alignment. The command's default formatter is table. To make output easier to parse, select another global formatter, for example:

$ doveadm -f flow acl get -u [email protected] 'shared/Support'

Reading the ACL is a checkpoint, not decoration. It tells you whether the target entry already exists and prevents an accidental replacement with set.

3. Add only the rights you need

Use add when you want to preserve existing rights and grant more. This example lets Bob list and read the mailbox:

$ doveadm acl add -u [email protected] 'shared/Support' [email protected] lookup read

If the entry already exists, add preserves its existing rights and adds the requested ones. Check the result immediately:

$ doveadm acl get -u [email protected] 'shared/Support'
ID                    Global Rights
--------------------  -------------
[email protected]  lookup read

The right names are Dovecot names, not the single-letter IMAP ACL form. Common mappings are l to lookup, r to read, w to write, i to insert, k to create, x to delete and a to admin. For example, write-seen controls the \\Seen flag and write-deleted controls \\Deleted.

4. Replace an entry only when that is intentional

$ doveadm acl set -u [email protected] 'shared/Support' [email protected] lookup read insert

Verify that the old rights you did not name are gone:

$ doveadm acl get -u [email protected] 'shared/Support' | grep '[email protected]'

If you intended to add one right but used set, restore the complete previous list with another set. The earlier get output is why recording the old entry before a replacement matters.

5. Remove a right or the whole entry

Use remove to take away named rights while leaving the ACL entry in place:

$ doveadm acl remove -u [email protected] 'shared/Support' [email protected] insert

Run get again and confirm that Bob still has the rights you meant to retain. If you remove the last right, the entry still exists without rights.

$ doveadm acl delete -u [email protected] 'shared/Support' [email protected]
$ doveadm acl get -u [email protected] 'shared/Support'

Recovery is to add or set the entry again from your recorded ACL. If the mailbox has inherited or group-based access, deleting one entry does not remove those other sources of access.

6. Understand identifiers and precedence

The identifier selects who receives the rights. The command supports owner, group=NAME, user=NAME, authenticated, and anyone. anonymous is an alias for anyone. A mailbox name may contain * and ? wildcards, so quote mailbox arguments when the shell might interpret them.

Dovecot processes identifiers in this precedence order: group override, user, owner, group, authenticated, then anyone. A user entry can therefore override a group result. The special group-override=NAME identifier can override a user's rights; the documented use is temporarily disabling access for members of a group. Treat that as a security-sensitive change and record the previous ACL before applying it.

7. Diagnose access without guessing

If the user still cannot open the shared mailbox, use the command designed to explain the effective problem:

$ doveadm acl debug -u [email protected] 'shared/Support'

For the current user's effective rights, use:

$ doveadm acl rights -u [email protected] 'shared/Support'

These checks help separate an ACL problem from mailbox discovery, subscription, namespace or authentication problems. If the ACL data looks stale, doveadm acl recalc recalculates the user's shared-mailbox records in acl_shared_dict; run it only after checking the configuration and the command's diagnostic output.

For bulk work, -F FILE reads one username per line, while -A runs for all users. Treat both as high-impact options: review the user database or input file first, and test with one explicit -u invocation. A malformed list or an unsuitable iterate_query can produce incomplete coverage. The -S option selects a local Unix socket or a remote host:port; verify the endpoint before using it.