ACL: Access Control List Plugin (acl)

This page talks mainly about how ACLs work, for more general description of how shared mailboxes work, see shared mailboxes.

Dovecot supports both administrator-configured ACLs and the IMAP ACL extension (see imap-acl plugin, which allows users to change ACLs themselves). Administrator ACLs are configured in dovecot.conf; users' own ACLs are stored in per-mailbox dovecot-acl files.

The ACL code was written to allow multiple ACL drivers, but currently Dovecot supports only virtual ACL files.

WARNING

Using ACLs doesn't grant mail processes any extra filesystem permissions that they already don't have.

You must make sure that the processes have enough permissions to be able to access the mailboxes.

To test, you can first try accessing shared/public mailboxes without ACL plugin enabled.

Settings (dovecot.conf)

acl

Value	Named Filter
See Also	acl_id acl_rights
Changes	Added: 3.1.0 Changed: 3.3.0 These entries are now global ACLs. Previously they were handled like the rights in a per-mailbox dovecot-acl file.

Specifies an ACL entry on global, namespace or mailbox level. The filter name refers to the acl_id setting.

These entries are global ACLs: they override the rights of the same identifier in a per-mailbox dovecot-acl file, they apply also to the mailbox owner, users can't change them with the IMAP ACL extension, and they are never copied into dovecot-acl files.

Has two settings:

acl_id

The identifier in ACL.

acl_rights

The permission to grant - or deny - for this user.

acl_cache_ttl

Default	30s
Value	time

How long to cache the ACLs read from dovecot-acl files. Set to 0 to re-read the files on every lookup.

acl_defaults_from_inbox

Default	no
Value	boolean

If enabled, the default ACLs for private and shared namespaces (but not public namespaces) are taken from the INBOX. This means that giving somebody access to your INBOX will give them access to all your other mailboxes as well, unless the specific mailboxes' ACLs override the INBOX's.

acl_dict_index

Default	yes
Value	boolean
Changes	Added: 3.1.0

Should ACL dict updates assume that there is a reverse lookup index. This should be used with SQL/CQL based dicts.

acl_driver

Default	[None]
Value	string
Changes	Added: 3.1.0

The ACL driver to use. This setting is REQUIRED - if empty, the acl plugin is disabled.

Currently, there is a single driver available: vfile. This driver supports two ways of defining the ACL configuration:

• global: ACL rules are applied to all users.

• per-mailbox: Each mailbox has separate ACL rules. They are stored in a dovecot-acl file in each mailbox (or mail_control_path) directory. This is the default.

acl_global_path

Default	[None]
Value	string
See Also	acl
Changes	Removed: 3.2.0

Location of global ACL configuration file. This option is deprecated, you should use acl instead.

acl_globals_only

Default	no
Value	boolean

If enabled, don't try to find dovecot-acl files from mailbox directories. This reduces unnecessary disk I/O when only global ACLs are used.

acl_groups

Default	[None]
Value	string

A comma-separated string which contains all the groups the user belongs to.

A user's UNIX groups have no effect on ACLs (you can enable them by using a special post-login scripting.

The default ACL for mailboxes is to give the mailbox owner all permissions and other users none. Mailboxes in public namespaces don't have owners, so by default no one can access them.

acl_id

Default	[None]
Value	string
See Also	acl ACL File Format
Changes	Added: 3.1.0

Specifies identity to match. See ACL File Format for values. The acl filter name refers to this setting.

acl_ignore

Default	no
Value	boolean
Changes	Added: 3.1.0

Can be used in global config, namespace, or mailbox level to ignore ACLs.

namespace ignore {
  acl_ignore = yes
}

acl_rights

Default	[None]
Value	string
See Also	acl ACL File Format
Changes	Added: 3.1.0

Specifies rights for this acl. See ACL File Format for values. This is usually used in acl block.

acl_sharing_map

Value	Named Filter
See Also	dictionary
Changes	Added: 3.1.0

A shared mailbox dictionary that defines which users may LIST mailboxes shared by other users.

Not every dictionary driver is supported here. The map needs dict_iterate which is not supported by redis and ldap.

See shared mailbox listing for further details on the contents of the dictionary entries.

Example:

acl_sharing_map {
  dict file {
    path = /var/lib/dovecot/shared-mailboxes
  }
}

acl_user

Default	[None]
Value	string
See Also	ACL Master Users

See auth_master_user_separator for the format of this setting.

Configuration

Groups

The acl_groups setting can be dynamically set via userdb: Extra Fields.

IMAP ACLs

To enable the IMAP ACL commands, you must load the imap_acl plugin. This plugin should only be loaded inside a protocol imap {} block.

Sample Configuration

# Enable internal ACL support
mail_plugins {
  acl = yes
}

# Enable the IMAP ACL commands
protocol imap {
  mail_plugins {
    imap_acl = yes
  }
}

acl_driver = vfile
# If enabled, don't try to find dovecot-acl files from mailbox directories.
# This reduces unnecessary disk I/O when only global ACLs are used.
acl_globals_only = yes

namespace inbox {
  inbox = yes
  mailbox Foo {
    acl owner {
      rights = lr
    }
  }

  acl user=admin {
    rights = lwristepai
 }
 ## Set this to yes to ignore ACLS for this namespace
 #acl_ignore = yes
}

## setting ACLs here will affect all shared mailboxes
namespace shared {
  mailbox Public {
    acl anyone {
      rights = lr
    }
  }
}

# Dict for mapping which users have shared mailboxes to each other.
#acl_sharing_map {
#  dict file {
#    path = /var/lib/dovecot/dovecot-acl.db
#  }
#}

# ACL username
# defaults to master_user, but if it expands to empty, will use current user.
#acl_user = %{master_user}

Creating rule sets with group

You can also simplify ACL rule set management by defining rule sets. Group settings expand as configuration where they are used, so they can include values from other filters too.

# define rule sets

group @acl_rule_set set1 {
   acl user=user1 {
     rights = lri
   }
}

group @acl_rule_set set2 {
   acl user=user2 {
     rights = lri
   }
}

group @acl_rule_set set3 {
   acl user=user3 {
     rights = lri
   }
}

group @acl_rule_set default {
  acl user=admin {
     rights = lwristepai
  }
}

namespace public {
   @acl_rule_set = default
   mailbox "Secret" {
     @acl_rule_set = set1
   }
   mailbox "TopSecret" {
     @acl_rule_set = set2
   }
   mailbox "Foo*" {
     @acl_rule_set = set3
   }
   mailbox "FooBar" {
     @acl_rule_set = set1
   }
}

With this configuration user admin will have full rights to all folders under public unless negated. Folders Secret and FooBar will have user1 with rights, while folders TopSecret has user2 with rights. This includes user admin from namespace level.

User user3 will have rights on anything that starts with Foo, including FooBar.

Master Users

Master users have their own ACLs. They're not the mailbox owners, so by default they have no permissions to any of the mailboxes. See ACL Master Users for more information.

ACL vfile Driver

vfile driver stores per-mailbox ACLs in a dovecot-acl file. Global ACLs are not read from a file; they are defined in dovecot.conf with the acl filter, see Global ACLs.

The dovecot-acl file exists in:

• Maildir:: The Maildir's mail directory (e.g., ~/Maildir, ~/Maildir/.folder/).
• mbox: Control directory. You should explicitly specify mail_control_path.
• dbox: dbox's mail directory (e.g., ~/dbox/INBOX/dbox-Mails/).

ACL File Format

The ACL files are in format:

<identifier> <ACLs> [:<named ACLs>]

Where identifier is one of:

• group-override=<group name>
• user=<user name>
• owner
• group=<group name>
• authenticated
• anyone (or anonymous)
• Negative rights can be given by prepending the identifier with -

The ACLS are processed in the precedence given above, so for example if you have given read-access to a group, you can still remove that from specific users inside the group.

Group-override identifier allows you to override users' ACLs. Probably the most useful reason to do this is to temporarily disable access for some users. For example:

user=foo rw
group-override=tempdisabled

Now if foo is in tempdisabled group, he has no access to the mailbox. This wouldn't be possible with a normal group identifier, because the user=foo would override it.

Negative rights can be used to remove rights. For example a user may be given full rights to all mailboxes, except some of the rights removed from some specific mailboxes.

Supported ACLs

ID	Type	Description
l	lookup	Mailbox is visible in mailbox list. Mailbox can be subscribed to.
r	read	Mailbox can be opened for reading.
w	write	Message flags and keywords can be changed, except \Seen and \Deleted
s	write-seen	\Seen flag can be changed
t	write-deleted	\Deleted flag can be changed
i	insert	Messages can be written or copied to the mailbox
p	post	Messages can be posted to the mailbox by LDA, e.g. from Sieve
e	expunge	Messages can be expunged
k	create	Mailboxes can be created (or renamed) directly under this mailbox (but not necessarily under its children, see ACL Inheritance) (renaming also requires delete rights)
x	delete	Mailbox can be deleted
a	admin	Administration rights to the mailbox (currently: ability to change ACLs for mailbox)

The ACLs are compatible with RFC 4314 (IMAP ACL extension).

Unknown ACL letters are complained about, but unknown named ACLs are ignored. Named ACLs are mostly intended for future extensions.

TIP

Changed: 3.3.0 Any whitespace (spaces, tabs) between the identifier and the ACLs is accepted, so user=foo lr and user=foo lr are equivalent. If you are having problems, make sure to check for other unwanted characters around the fields.

Examples

Mailbox owner has all privileges, foo has list-read privileges:

owner lrwstipekxa
user=foo lr

Allow everyone to list and read a public mailbox (public namespace has no owner):

anyone lr

Prevent users from deleting the Spam folder (notice no x flag), in the dovecot-acl file of that folder:

owner lrwstipeka

Note that dovecot-acl files apply only to the mailbox they live in. Rules that apply to more than one mailbox belong in dovecot.conf, see Global ACLs. The same example as configuration:

namespace inbox {
  mailbox Spam {
    acl owner {
      rights = lrwstipeka
    }
  }
}

ACL Inheritance and Default ACLs

Every time you create a new mailbox, it gets its ACLs from the parent mailbox. If you're creating a root-level mailbox, it uses the namespace's default ACLs. There is no actual inheritance, however: If you modify parent's ACLs, the child's ACLs stay the same. There is currently no support for ACL inheritance.

There are default ACLs though:

• In private namespace, the owner has all ACL rights for mailboxes in the namespace.
• In shared and public namespaces, there are no ACL rights by default.
• However, optionally the default ACLs can be taken from the INBOX for private and shared namespaces. See acl_defaults_from_inbox.

WARNING

Currently the default ACLs are merged with the mailbox-specific ACLs. So if a default ACL gives access to user1 and a per-mailbox ACL gives access to user2, the user1 still has access to that mailbox.

Global ACLs

Global ACLs are set by the administrator and apply to all users. Unlike per-mailbox dovecot-acl files, users cannot change them with the IMAP ACL extension. They are used mainly for two purposes:

1. Removing some permissions from users' personal mailboxes. For example each user might have an Invoices mailbox which will be read-only.
2. Giving permissions to master user logins. See ACL Master Users for more information.

Removed: 3.2.0 Global ACLs used to be read from a separate global ACL file, configured with the acl_global_path setting. Both the setting and the file format are gone; there is no ACL file that takes a mailbox name prefix. See ACL Settings Migration for how to convert an existing global ACL file or global ACL directory.

Global ACLs are defined in dovecot.conf with the acl filter. The filter can be used at global, namespace or mailbox level, and the level it is used at is what limits which mailboxes it applies to:

# applies to every mailbox of every namespace
acl user=foo {
  rights = lrw
}

namespace inbox {
  # applies to every mailbox of this namespace
  acl user=admin {
    rights = lrwstipekxa
  }

  mailbox Public {
    acl user=bar {
      rights = lrwstipekxa
    }
  }
  mailbox "Public/*" {
    acl user=bar {
      rights = lrwstipekxa
    }
  }
}

mailbox filter names may contain * and ? wildcards that do shell-string matching, not stopping at any boundaries. The pattern is matched against the mailbox name without the namespace prefix. All matching mailbox filters apply, not just the first one.

To deny rights, prefix acl_rights with -:

namespace inbox {
  mailbox INBOX {
    acl user=masteruser {
      rights = -lrwstipekxa
    }
  }
}

Changed: 3.3.0 If a mailbox has both configured ACLs and a per-mailbox dovecot-acl file, both are read, and the configured ACLs override the rights of the same identifier in the file.

Set acl_globals_only = yes if dovecot-acl files are not used at all. This skips looking for them and saves disk I/O.

List Cache

dovecot-acl-list file lists all mailboxes that have l rights assigned. If you manually add/edit dovecot-acl files, you may need to delete the dovecot-acl-list to get the mailboxes visible.

Dictionaries

In order for an ACL to be fully useful, it has to be communicated to IMAP clients. For example, if you use ACL to share a mailbox to another user, the client has to be explicitly told to check out the other user's mailbox too, as that one is shared.

Placing the ACL file makes the ACL effective, but Dovecot doesn't take care of the user to shared mailboxes mapping out of the box, and as a result, it won't publish shared mailboxes to clients if this is not set up. You have to configure this manually by defining an appropriate dictionary to store the map using acl_sharing_map.

acl_sharing_map {
  dict file {
    path = /var/lib/dovecot/dovecot-acl.db
  }
}