.\" Copyright (c) 2014-2018 Dovecot authors, see the included COPYING file
.TH DOVEADM\-ACL 1 "2015-05-09" "Dovecot v2.3" "Dovecot"
.SH NAME
doveadm\-acl \- Manage Access Control List (ACL)
.\"------------------------------------------------------------------------
.SH SYNOPSIS
.BR doveadm " [" \-Dv ]
[\fB\-f\fP \fIformatter\fP]
.BI acl \ command
.RI [ OPTIONS ]\ [ ARGUMENTS ]
.\"------------------------------------------------------------------------
.SH DESCRIPTION
The
.B doveadm acl
.I COMMANDS
can be used to execute various Access Control List related actions.
.\"------------------------------------------------------------------------
.SH OPTIONS
Global
.BR doveadm (1)
.IR options :
.TP
.B \-D
Enables verbosity and debug messages.
.TP
.BI \-f\  formatter
Specifies the
.I formatter
for formatting the output.
Supported formatters are:
.RS
.TP
.B flow
prints each line with
.IB key = value
pairs.
.TP
.B pager
prints each
.IR key :\  value
pair on its own line and separates records with form feed character
.RB ( ^L ).
.TP
.B tab
prints a table header followed by tab separated value lines.
.TP
.B table
prints a table header followed by adjusted value lines.
.RE
.TP
.BI \-o\  setting = value
Overrides the configuration
.I setting
from
.I /etc/dovecot/dovecot.conf
and from the userdb with the given
.IR value .
In order to override multiple settings, the
.B \-o
option may be specified multiple times.
.TP
.B \-v
Enables verbosity, including progress counter.
.\" --- command specific options --- "/.
.PP
This command uses by default the output formatter
.BR table .
.PP
Command specific
.IR options :
.\"-------------------------------------
.TP
.B \-A
If the
.B \-A
option is present, the
.I command
will be performed for all users.
Using this option in combination with system users from
.B userdb { driver = passwd }
is not recommended, because it contains also users with a lower UID than
the one configured with the
.I first_valid_uid
setting.
.sp
When the SQL userdb module is used make sure that the
.I iterate_query
setting in
.I /etc/dovecot/dovecot\-sql.conf.ext
matches your database layout.
When using the LDAP userdb module, make sure that the
.IR iterate_attrs " and " iterate_filter
settings in
.I /etc/dovecot/dovecot-ldap.conf.ext
match your LDAP schema.
Otherwise
.BR doveadm (1)
will be unable to iterate over all users.
.\"-------------------------------------
.TP
.BI \-F\  file
Execute the
.I command
for all the users in the
.IR file .
This is similar to the
.B \-A
option,
but instead of getting the list of users from the userdb,
they are read from the given
.IR file .
The
.I file
contains one username per line.
.\"-------------------------------------
.TP
.BI \-S\  socket_path
The option\(aqs argument is either an absolute path to a local UNIX domain
socket, or a hostname and port
.RI ( hostname : port ),
in order to connect a remote host via a TCP socket.
.sp
This allows an administrator to execute
.BR doveadm (1)
mail commands through the given socket.
.\"-------------------------------------
.TP
.BI \-u\  user/mask
Run the
.I command
only for the given
.IR user .
It\(aqs also possible to use
.RB \(aq * \(aq
and
.RB \(aq ? \(aq
wildcards (e.g. \-u *@example.org).
.br
When neither the
.B \-A
option, nor the
.BI \-F\  file
option, nor the
.BI \-u\  user
was specified, the
.I command
will be executed with the environment of the
currently logged in user.
.\"------------------------------------------------------------------------
.SH ARGUMENTS
.TP
.I id
The id (identifier) is one of:
.RS
.RS
.TP 4
*
.BR group\-override =\c
.I group_name
.\"-----------------
.TP
*
.BR user =\c
.I user_name
.\"-----------------
.TP
*
.B owner
.\"-----------------
.TP
*
.BR group =\c
.I group_name
.\"-----------------
.TP
*
.B authenticated
.\"-----------------
.TP
*
.BR anyone " (or " anonymous ", which is an alias for anyone)"
.\"-----------------
.RE
.PP
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.
.br
Group\-override identifier allows you to override users\(aq ACLs.
Probably the most useful reason to do this is to temporarily disable
access for some users.
For example:
.PP
.nf
user=timo rw
group\-override=tempdisabled
.fi
.PP
Now if timo is a member of the tempdisabled group, he has no access to the
mailbox.
This wouldn\(aqt be possible with a normal group identifier, because the
.B user=timo
would override it.
.RE
.\"-------------------------------------
.TP
.I mailbox
The name of the mailbox, for which the ACL manipulation should be done.
It\(aqs also possible to use the wildcard characters
.RB \(dq * "\(dq and/or \(dq" ? \(dq
in the mailbox name.
.\"-------------------------------------
.TP
.I right
Dovecot ACL right name. This isn\(aqt the same as the IMAP ACL letters,
which aren\(aqt currently supported.
Here is a mapping of the IMAP ACL letters to Dovecot ACL names:
.RS
.RS
.TP 4
.B l \(-> lookup
.I Mailbox
is visible in mailbox list.
.I Mailbox
can be subscribed to.
.\"-----------------
.TP
.B r \(-> read
.I Mailbox
can be opened for reading.
.\"-----------------
.TP
.B w \(-> write
Message flags and keywords can be changed, except
.BR \(rsSeen " and " \(rsDeleted .
.\"-----------------
.TP
.B s \(-> write\-seen
.B \(rsSeen
flag can be changed.
.\"-----------------
.TP
.B t \(-> write\-deleted
.B \(rsDeleted
flag can be changed.
.\"-----------------
.TP
.B i \(-> insert
Messages can be written or copied to the
.IR mailbox .
.\"-----------------
.TP
.B p \(-> post
Messages can be posted to the
.I mailbox
by
.BR dovecot\-lda ,
e.g. from Sieve scripts.
.\"-----------------
.TP
.B e \(-> expunge
Messages can be expunged.
.\"-----------------
.TP
.B k \(-> create
Mailboxes can be created/renamed directly under this
.I mailbox
(but not necessarily under its children, see
.I ACL Inheritance
in the wiki).
.br
Note: Renaming also requires the delete right.
.\"-----------------
.TP
.B x \(-> delete
.I Mailbox
can be deleted.
.\"-----------------
.TP
.B a \(-> admin
Administration rights to the
.I mailbox
(currently: ability to change ACLs for
.IR mailbox ).
.RE
.RE
.\"------------------------------------------------------------------------
.SH COMMANDS
.SS acl add
.B doveadm acl add
[\fB\-u\fP \fIuser\fP|\fB\-A\fP|\fB\-F\fP \fIfile\fP]
[\fB\-S\fP \fIsocket_path\fP]
.I mailbox id right
.RI [ right " ...]"
.PP
Add ACL rights to the
.IR mailbox / id .
If the
.I id
already exists, the existing rights are preserved.
.\"-------------------------------------
.SS acl debug
.B doveadm acl debug
[\fB\-u\fP \fIuser\fP|\fB\-A\fP|\fB\-F\fP \fIfile\fP]
[\fB\-S\fP \fIsocket_path\fP]
.I mailbox
.PP
This command can be used to debug why a shared mailbox isn\(aqt
accessible to the user.
It will list exactly what the problem is.
.\"-------------------------------------
.SS acl delete
.B doveadm acl delete
[\fB\-u\fP \fIuser\fP|\fB\-A\fP|\fB\-F\fP \fIfile\fP]
[\fB\-S\fP \fIsocket_path\fP]
.I mailbox id
.PP
Remove the whole ACL entry for the
.IR mailbox / id .
.\"-------------------------------------
.SS acl get
.B doveadm acl get
[\fB\-u\fP \fIuser\fP|\fB\-A\fP|\fB\-F\fP \fIfile\fP]
[\fB\-S\fP \fIsocket_path\fP]
.RB [ \-m ]
.I mailbox
.PP
Show all the ACLs for the
.IR mailbox .
.\"-------------------------------------
.SS acl recalc
.B doveadm acl recalc
[\fB\-u\fP \fIuser\fP|\fB\-A\fP|\fB\-F\fP \fIfile\fP]
[\fB\-S\fP \fIsocket_path\fP]
.PP
Make sure the
.IR user \(aqs
shared mailboxes exist correctly in the
.IR acl_shared_dict .
.\"-------------------------------------
.SS acl remove
.B doveadm acl remove
[\fB\-u\fP \fIuser\fP|\fB\-A\fP|\fB\-F\fP \fIfile\fP]
[\fB\-S\fP \fIsocket_path\fP]
.I mailbox id right
.RI [ right " ...]"
.PP
Remove the specified ACL rights from the
.IR mailbox / id .
If all rights are removed, the entry still exists without any rights.
.\"-------------------------------------
.SS acl rights
.B doveadm acl rights
[\fB\-u\fP \fIuser\fP|\fB\-A\fP|\fB\-F\fP \fIfile\fP]
[\fB\-S\fP \fIsocket_path\fP]
.I mailbox
.PP
Show the
.IR user \(aqs
current ACL rights for the
.IR mailbox .
.\"-------------------------------------
.SS acl set
.B doveadm acl set
[\fB\-u\fP \fIuser\fP|\fB\-A\fP|\fB\-F\fP \fIfile\fP]
[\fB\-S\fP \fIsocket_path\fP]
.I mailbox id right
.RI [ right " ...]"
.PP
Set ACL rights to the
.IR mailbox / id .
If the
.I id
already exists, the existing rights are replaced.
.\"------------------------------------------------------------------------
.SH REPORTING BUGS
Report bugs, including
.I doveconf \-n
output, to the Dovecot Mailing List <dovecot@dovecot.org>.
Information about reporting bugs is available at:
http://dovecot.org/bugreport.html
.\"------------------------------------------------------------------------
.SH SEE ALSO
.BR doveadm (1),
.BR dovecot\-lda (1)
.\"-------------------------------------
.PP
Additional resources:
.IP "ACL Inheritance"
http://wiki2.dovecot.org/ACL#ACL_Inheritance