diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/wiki/ACL.txt | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/doc/wiki/ACL.txt b/doc/wiki/ACL.txt new file mode 100644 index 0000000..486d71c --- /dev/null +++ b/doc/wiki/ACL.txt @@ -0,0 +1,258 @@ +Access Control Lists +==================== + +This page talks mainly about how ACLs work, for more general description of how +shared mailboxes work, see <SharedMailboxes.txt>. + +Dovecot v1.0 and v1.1 supports administrator-configured ACL files. v1.2+ +supports also IMAP ACL extension, which allows users to change ACLs themselves. +The ACL code was written to allow multiple ACL backends, but currently Dovecot +supports only virtual ACL files. Note that 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> +[SharedMailboxes.Permissions.txt] to be able to access the mailboxes. When +testing you could first try accessing shared/public mailboxes without ACL +plugin even enabled. + +ACLs can be enabled in dovecot.conf with: + +---%<------------------------------------------------------------------------- +mail_plugins = acl +protocol imap { + mail_plugins = $mail_plugins imap_acl +} + +plugin { + # Without global ACLs: + acl = vfile + + # With global ACL files in /etc/dovecot/dovecot-acls file (v2.2.11+): + #acl = vfile:/etc/dovecot/dovecot-acl + + # With global ACLs in /etc/dovecot/acls/ directory (obsolete): + #acl = vfile:/etc/dovecot/acls + + # 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. +(v2.2.31+) + #acl_globals_only = yes +} +---%<------------------------------------------------------------------------- + +ACL groups support works by returning a comma-separated 'acl_groups' <extra +field> [UserDatabase.ExtraFields.txt] from userdb, which contains all the +groups the user belongs to. User's UNIX groups have no effect on ACLs (you can +"enable" them by using a special <post-login script> [PostLoginScripting.txt]). + +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. + +Master users +------------ + +Note that master users have their own ACLs. They're not the the mailbox owners, +so by default they have no permissions to any of the mailboxes. See +Authentication/MasterUsers#ACLs for more information. + +ACL vfile backend +----------------- + +vfile backend supports per-mailbox ACLs and global ACLs. + +Per-mailbox ACLs are stored in 'dovecot-acl' named file, which exists in: + + * maildir: The Maildir's mail directory (eg. '~/Maildir', + '~/Maildir/.folder/') + * mbox: Control directory. You should explicitly specify ':CONTROL=<path>' in + mail location. + * dbox: dbox's mail directory (eg. '~/dbox/INBOX/dbox-Mails/') + +ACL Inheritance +--------------- + +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. + + * Maildir: Namespace's default ACLs are read from "dovecot-acl" file in the + namespace's mail root directory (e.g.'/var/public/Maildir'). Note that + currently these default ACLs are used only when creating new mailboxes, they + aren't used for mailboxes without ACLs. + * v2.2.2+: If 'plugin { acl_defaults_from_inbox=yes } ', 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. + +*NOTE*: 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 can be used to apply ACLs globally to all user's specific +mailboxes. 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 + <Authentication/MasterUsers#ACLs> [Authentication.MasterUsers.txt] for more + information. + +If a mailbox has both global ACLs and the per-mailbox ACL file, both of them +are read and the ACLs are merged. If there are any conflicts, the global ACL +file overrides per-mailbox ACL file. This is because users can modify their own +per-mailbox ACL files via IMAP ACL extension. Global ACLs can only be modified +by administrator, so users shouldn't be able to override them. + +Global ACL file (v2.2.11+) +-------------------------- + +Global ACL file path is specified as a parameter to vfile backend in 'acl' +setting ('/etc/dovecot/dovecot-acl' in the above example). The file contains +otherwise the same data as regular per-mailbox 'dovecot-acl' files, except each +line is prefixed by the mailbox name pattern. The pattern may contain "*" and +"?" wildcards. For example: + +---%<------------------------------------------------------------------------- +* user=foo lrw +Public user=bar lrwstipekxa +Public/* user=bar lrwstipekxa +---%<------------------------------------------------------------------------- + +Global ACL directory (obsolete) +------------------------------- + +Global ACL directory is specified as a parameter to vfile backend in 'acl' +setting ('/etc/dovecot/acls/' in the above example). They are looked up using +the mailbox's virtual name. For example: + + * INBOX: '/etc/dovecot/acls/INBOX' + * archives.2007: '/etc/dovecot/acls/archives.2007' + * archives/2007: '/etc/dovecot/acls/archives/2007' + +The filenames must start with namespace prefix (if it has one). For example +with namespace 'prefix=INBOX/' containing mailbox "foo" use +'/etc/dovecot/acls/INBOX/foo'. + +There is an extra problem with mailbox formats that use '/' as the separator +(e.g. mbox, dbox): For example if you have mailboxes "foo" and "foo/bar" and +you wish to give ACLs to both of them, you can't create both +'/etc/dovecot/acls/foo' and '/etc/dovecot/acls/foo/bar' files. The 'foo' has to +be either a directory or a file, it can't be both. To solve this problem, you +can instead create a .DEFAULT file for "foo": + + * foo: '/etc/dovecot/acls/foo/.DEFAULT' + * foo/bar: '/etc/dovecot/acls/foo/bar' + +ACL files +--------- + +The files themselves 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, which is alias for anyone) + +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=timo rw +group-override=tempdisabled +---%<------------------------------------------------------------------------- + +Now if /timo/ is in /tempdisabled/ group, he has no access to the mailbox. This +wouldn't be possible with a normal group identifier, because the 'user=timo' +would override it. + +The currently supported ACLs and their corresponding named ACLs are: ++---+---------------+---------------------------------------------------------+ +| 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.txt>, e.g.| +| | | from <Sieve> [Pigeonhole.Sieve.txt] scripts | ++---+---------------+---------------------------------------------------------+ +| 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 section above) (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, updated version). + +Unknown ACL letters are complained about, but unknown named ACLs are ignored. +Named ACLs are mostly intended for future extensions. + +Note that the file is rather picky about formatting; using a tab (or multiple +spaces) instead of a space character between fields may not work. If you are +having problems, make sure to check for tabs, extra spaces and other unwanted +characters. + +Examples +-------- + +Mailbox owner has all privileges, "timo" has list-read privileges: + +---%<------------------------------------------------------------------------- +owner lrwstipekxa +user=timo lr +---%<------------------------------------------------------------------------- + +Allow everyone to list and read a public mailbox (public namespace has no +owner): + +---%<------------------------------------------------------------------------- +anyone lr +---%<------------------------------------------------------------------------- + +Prevent all users from deleting their Spam folder (notice no x flag) + +---%<------------------------------------------------------------------------- +INBOX.Spam owner lrwstipeka +---%<------------------------------------------------------------------------- + +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. + +(This file was created from the wiki on 2019-06-19 12:42) |