HEX

File: //usr/lib/courier-imap/man/man1/maildiracl.1

.\" 
.\" 
.\" 
.\" This manpage has been automatically generated by docbook2man
.\" from a DocBook document. This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
.\" Please send any bug reports, improvements, comments, patches,
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "MAILDIRACL" "1" "02 September 2004" "Double Precision, Inc." ""

.SH NAME
maildiracl \- manage access control lists
.SH SYNOPSIS

\fBmaildiracl\fR \fB-reset\fR \fB\fImaildir\fB\fR

\fBmaildiracl\fR \fB-list\fR \fB\fImaildir\fB\fR \fB\fIINBOX[.folder]\fB\fR

\fBmaildiracl\fR \fB-set\fR \fB\fImaildir\fB\fR \fB\fIINBOX[.folder]\fB\fR \fB\fI[-]identifier\fB\fR \fB\fI[+/-]rights\fB\fR

\fBmaildiracl\fR \fB-delete\fR \fB\fImaildir\fB\fR \fB\fIINBOX[.folder]\fB\fR \fB\fI[-]identifier\fB\fR

\fBmaildiracl\fR \fB-compute\fR \fB\fImaildir\fB\fR \fB\fIINBOX[.folder]\fB\fR \fB\fIidentifier\fB\fR\fI ...\fR

.SH "DESCRIPTION"
.PP
\fBmaildiracl\fR
manages ``access control lists'' (or ACLs)
of \fBCourier-IMAP\fR maildir folders.
Access control lists are used primarily to provide fine-grained control
for accessing virtual shared folders via IMAP.
.sp
.RS
.B "Note:"
.PP
The \fBCourier-IMAP\fR server implements two types of shared folders:
filesystem permission-based shared folders,
as well as virtual shared folders based on IMAP access control lists.
Use the \fBmaildiracl\fR
command to set up access control lists for virtual shared folders.
Use the
\fBmaildirmake\fR(1),
command
to implement shared folders based on
filesystem permissions.
.PP
See the \fBCourier-IMAP\fR server documentation for additional information
on setting up virtual shared folders.
.RE
.SS "ACL OVERVIEW"
.PP
ACLs provide a fine-grained mechanism for controlling
access to shared folders.
ACLs may be used to specify, for example, that
user1 may only open and read the messages in the folder;
and user2 can not only do that, but also delete messages,
and create subfolders.
.PP
Each folder maintains its own individual access control list, that specifies
who can do what to the folder.
An ACL is a list of ``identifier'' and ``rights''
pairs.
Each ``identifier'' and ``rights'' pair means that an
entity called ``identifier''
(using the UTF-8 character set)
is allowed to do ``rights''
on this folder.
``rights'' consists of one or more letters, each letter
signifies a particular action:
.TP
\fBa\fR
\fIidentifier\fR
may modify this folder's ACLs.
.TP
\fBc\fR
\fIidentifier\fR
may create subfolders of this folder (this includes renaming another
folder as this folder's subfolders).
.TP
\fBe\fR
\fIidentifier\fR
may remove deleted messages from this folder.
.TP
\fBi\fR
\fIidentifier\fR
may add messages to this folder (either uploading them one by one,
or copying messages from another folder).
.TP
\fBl\fR
\fIidentifier\fR
may actually see that this folder exists.
If \fIidentifier\fR does not have the ``l''
right on this folder, the folder is effectively invisible to
\fIidentifier\fR\&.
.TP
\fBr\fR
\fIidentifier\fR
may open this folder.
Note that if \fIidentifier\fR
knows the name of this folder, it can open it even if
\fIidentifier\fR does not the ``l''
right on this folder.
.TP
\fBs\fR
\fIidentifier\fR
may mark messages in this folder as seen, or unseen.
.TP
\fBt\fR
\fIidentifier\fR
may mark messages in this folder as deleted, or undeleted.
.TP
\fBw\fR
\fIidentifier\fR
may change other status flags of messages in this folder.
May also add or remove custom keywords on individual messages.
.TP
\fBx\fR
\fIidentifier\fR
may delete this folder (which includes renaming this folder as another
mailbox's subfoler.
.SS "NEGATIVE RIGHTS"
.PP
An ACL entry of ``-identifier'' and ``rights''
is called a ``negative right'', which
explicitly removes ``rights'' from ``identifier''\&.
More than one ``identifier'' is usually used to determine the
actual rights someone has for the given folder.
The actual access rights are determined by taking all rights from all
applicable \fIidentifier\fR, than subtracting any
negative rights, as specified in the following section.
.SS "IDENTIFIERS"
.PP
Access rights on a given folder are computed by obtained the rights
on the following identifiers, then subtracting the negative rights on the
same identifiers:
.TP
\fBowner\fR
The owner of the maildir containing this folder.
The maildir's INBOX's ACL defaults to all rights for its owner.
A new folder's ACL is the same as its parent's ACL.
In all cases, trying to remove the ``a'' right from the owner
(either directly or using a negative right) results in an error.
.TP
\fBanyone\fR
This identifier refers literally to every userid.
The associated rights (or negative rights) are always used.
.TP
\fBanonymous\fR
This is a synonym from ``anyone''\&.
.TP
\fBuser=\fIloginid\fB\fR
Rights (or negative rights) for IMAP account ``loginid''\&.
.sp
.RS
.B "Note:"
``loginid'' is what's logged to syslog after a succesful
login.
In some situations ``loginid'' is not exactly the actual login ID
used by the IMAP client.
.RE
.PP
Consider the following access control list:
.PP

.nf
owner aceilrstwx
anyone lr
user=john w
-user=mary r
.fi
.PP
This access control list specifies that the folder's owner has complete
control over the mailbox; everyone else can see it and open it,
except for ``mary'' who can see that the mailbox exists, but
can't open it; additionally, ``john'' can change the status and
keywords of individual messages (but not mark them as deleted/undeleted or
seen/unseen, which requires additional rights).
.SH "OPTIONS"

\fBmaildiracl -reset \fImaildir\fB\fR

.PP
This command resets access control lists in
\fImaildir\fR
which as a path to a maildir.
Under certain conditions, the files where a folder's ACLs are saved may
continue to exist after the folder is removed.
The -reset options goes through
\fImaildir\fR
and removes all stale ACL files for removed folders.
.sp
.RS
.B "Note:"
The \fBCourier-IMAP\fR server normally performs this maintenance
function automatically.
It is not necessary to run this command under normal conditions.
.RE

\fBmaildiracl -list
\fImaildir\fB
\fIfolder\fB\fR

.PP
This command
lists the access control lists set for \fIfolder\fR\&.
\fIfolder\fR must be either
``INBOX'' or ``INBOX.folder.subfolder'', which is the
same naming convention for \fBCourier-IMAP\fR\&.

\fBmaildiracl -set
\fImaildir\fB
\fIfolder\fB
\fIidentifier\fB
\fIrights\fB\fR

.PP
Puts \fIidentifier\fR (which may begin with a minus
sign to specify a negative right) and
\fIrights\fR in
\fIfolder\fR\&'s access control list.
Existing rights for
\fIidentifier\fR
(or \fIidentifier\fR) are replaced by
\fIrights\fR unless ``rights'' begins with
``+'' or ``-'', which modifies the existing rights
by adding or removing from them accordingly.
Some examples:
.PP

.nf
maildiracl -set /home/user1/Maildir INBOX.Sent user=john lr

maildiracl -set /home/user2/Maildir INBOX.Notes anyone -r

maildiracl -set /home/user3/Maildir INBOX.Private -user=tom +r
.fi
.sp
.RS
.B "Note:"
Observe that the last command \fBrevokes\fR the ``r''
right from ``tom'', by adding it as a negative right.
.RE

\fBmaildiracl -delete
\fImaildir\fB
\fIfolder\fB
\fIidentifier\fB\fR

.PP
This command removes \fIidentifier\fR
from
\fIfolder\fR\&'s access control list, if it exists.
Use ``-\fIidentifier\fR'' to remove
negative rights.

\fBmaildiracl -compute
\fImaildir\fB
\fIfolder\fB
[\fIidentifier\fB]+\fR

.PP
This command takes a list of one or more
\fIidentifier\fRs.
All access rights for the
\fIidentifier\fRs are combined together, then
any appropriate negative rights are removed, and the result is printed
on standard output.
Use the following procedure to compute access rights the same way as they
are computed by \fBCourier-IMAP\fR:
.PP

.nf
maildiracl -compute /home/tom46/Maildir INBOX.Sent owner user=tom46
.fi
.PP
This command computes access rights ``tom46'' has on
his own folder.
.PP

.nf
maildiracl -compute /home/john34/Maildir INBOX.Public user=tom46
.fi
.PP
This command computes access rights ``tom46'' has on
``john34''\&'s folder.
.SH "BUGS"
.PP
All identifiers are specified using the UTF-8 character
set.
.PP
All non-Latin letters in folder names are specified using the
modified-UTF7 coding as used in IMAP.
.PP
This implementation of access control lists is based on
version 2 (or ``ACL2'') of IMAP
access control lists, which is a work-in-progress.
The existing IMAP ACL,
RFC 2086
is transparently implemented inside the ACL2 model.
.PP
If history's of any guidance, ACL2 is subject to change at any time.
Be sure to check the release notes
when upgrading to a newer version of this software.
The ``ACL overview'' portion of this manual page is a
\fBvery\fR brief summary of ACL2, which leaves out optional
parts of ACL2 that are not implemented.
.SH "SEE ALSO"
.PP
\fBmaildirmake\fR(1),
\fBmaildirkw\fR(1),