Current File : //usr/local/share/courier-imap/man/man1/maildiracl.1
'\" t
.\"<!-- Copyright 2003-2009 Double Precision, Inc. See COPYING for -->
.\"<!-- distribution information. -->
.\" Title: maildiracl
.\" Author: Sam Varshavchik
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\" Date: 06/27/2015
.\" Manual: Double Precision, Inc.
.\" Source: Courier Mail Server
.\" Language: English
.\"
.TH "MAILDIRACL" "1" "06/27/2015" "Courier Mail Server" "Double Precision, Inc\&."
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
maildiracl \- manage access control lists
.SH "SYNOPSIS"
.HP \w'\fBmaildiracl\fR\ 'u
\fBmaildiracl\fR {\-reset} {\fImaildir\fR}
.HP \w'\fBmaildiracl\fR\ 'u
\fBmaildiracl\fR {\-list} {\fImaildir\fR} {\fIINBOX[\&.folder]\fR}
.HP \w'\fBmaildiracl\fR\ 'u
\fBmaildiracl\fR {\-set} {\fImaildir\fR} {\fIINBOX[\&.folder]\fR} {\fI[\-]identifier\fR} {\fI[+/\-]rights\fR}
.HP \w'\fBmaildiracl\fR\ 'u
\fBmaildiracl\fR {\-delete} {\fImaildir\fR} {\fIINBOX[\&.folder]\fR} {\fI[\-]identifier\fR}
.HP \w'\fBmaildiracl\fR\ 'u
\fBmaildiracl\fR {\-compute} {\fImaildir\fR} {\fIINBOX[\&.folder]\fR} {\fIidentifier\fR...}
.SH "DESCRIPTION"
.PP
\fBmaildiracl\fR
manages
\(lqaccess control lists\(rq
(or ACLs) of the
Courier
IMAP server maildir folders\&. Access control lists are used primarily to provide fine\-grained control for accessing virtual shared folders via IMAP\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
The
Courier
IMAP server 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
\m[blue]\fB\fBmaildirmake\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2, command to implement shared folders based on filesystem permissions\&.
.PP
See the
Courier
IMAP server documentation for additional information on setting up virtual shared folders\&.
.sp .5v
.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
\(lqidentifier\(rq
and
\(lqrights\(rq
pairs\&. Each
\(lqidentifier\(rq
and
\(lqrights\(rq
pair means that an entity called
\(lqidentifier\(rq
(using the
UTF\-8
character set) is allowed to do
\(lqrights\(rq
on this folder\&.
\(lqrights\(rq
consists of one or more letters, each letter signifies a particular action:
.PP
a
.RS 4
\fIidentifier\fR
may modify this folder\*(Aqs ACLs\&.
.RE
.PP
c
.RS 4
\fIidentifier\fR
may create subfolders of this folder (this includes renaming another folder as this folder\*(Aqs subfolders)\&.
.RE
.PP
e
.RS 4
\fIidentifier\fR
may remove deleted messages from this folder\&.
.RE
.PP
i
.RS 4
\fIidentifier\fR
may add messages to this folder (either uploading them one by one, or copying messages from another folder)\&.
.RE
.PP
l
.RS 4
\fIidentifier\fR
may actually see that this folder exists\&. If
\fIidentifier\fR
does not have the
\(lql\(rq
right on this folder, the folder is effectively invisible to
\fIidentifier\fR\&.
.RE
.PP
r
.RS 4
\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
\(lql\(rq
right on this folder\&.
.RE
.PP
s
.RS 4
\fIidentifier\fR
may mark messages in this folder as seen, or unseen\&.
.RE
.PP
t
.RS 4
\fIidentifier\fR
may mark messages in this folder as deleted, or undeleted\&.
.RE
.PP
w
.RS 4
\fIidentifier\fR
may change other status flags of messages in this folder\&. May also add or remove custom keywords on individual messages\&.
.RE
.PP
x
.RS 4
\fIidentifier\fR
may delete this folder (which includes renaming this folder as another mailbox\*(Aqs subfoler\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNegative rights\fR
.RS 4
.PP
An ACL entry of
\(lq\-identifier\(rq
and
\(lqrights\(rq
is called a
\(lqnegative right\(rq, which explicitly removes
\(lqrights\(rq
from
\(lqidentifier\(rq\&. More than one
\(lqidentifier\(rq
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\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBIdentifiers\fR
.RS 4
.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:
.PP
owner
.RS 4
The owner of the maildir containing this folder\&. The maildir\*(Aqs INBOX\*(Aqs ACL defaults to all rights for its owner\&. A new folder\*(Aqs ACL is the same as its parent\*(Aqs ACL\&. In all cases, trying to remove the
\(lqa\(rq
right from the owner (either directly or using a negative right) results in an error\&.
.RE
.PP
anyone
.RS 4
This identifier refers literally to every userid\&. The associated rights (or negative rights) are always used\&.
.RE
.PP
anonymous
.RS 4
This is a synonym from
\(lqanyone\(rq\&.
.RE
.PP
user=\fIloginid\fR
.RS 4
Rights (or negative rights) for IMAP account
\(lqloginid\(rq\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
\(lqloginid\(rq
is what\*(Aqs logged to syslog after a succesful login\&. In some situations
\(lqloginid\(rq
is not exactly the actual login ID used by the IMAP client\&.
.sp .5v
.RE
.RE
.PP
group=\fIname\fR
.RS 4
Rights (or negative rights) for account group
\(lqname\(rq\&. Access rights are granted to an account group as a whole\&. The account options feature of the Courier Authentication Library specifies which account belongs to which account group\&. See courier\-authlib\*(Aqs documentation for more information\&.
.RE
.PP
administrators
.RS 4
This is an alias for
\(lqgroup=administrators\(rq\&. Accounts that are members of an account group called
\(lqadministrators\(rq
are considered administrative accounts, and automatically receive all access rights on all accessible folders\&.
.RE
.PP
Consider the following access control list:
.sp
.if n \{\
.RS 4
.\}
.nf
owner aceilrstwx
anyone lr
user=john w
\-user=mary r
administrators aceilrstwx
.fi
.if n \{\
.RE
.\}
.PP
This access control list specifies that the folder\*(Aqs owner has complete control over the mailbox (as well as the administrators, which have complete access to every folder); everyone else can see it and open it, except for
\(lqmary\(rq
who can see that the mailbox exists, but can\*(Aqt open it; additionally,
\(lqjohn\(rq
can change the status and keywords of individual messages (but not mark them as deleted/undeleted or seen/unseen, which requires additional rights)\&.
.RE
.SH "OPTIONS"
.HP \w'\fBmaildiracl\ \-reset\ \fR\fB\fImaildir\fR\fR\ 'u
\fBmaildiracl \-reset \fR\fB\fImaildir\fR\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\*(Aqs 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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
The
Courier
IMAP server normally performs this maintenance function automatically\&. It is not necessary to run this command under normal conditions\&.
.sp .5v
.RE
.HP \w'\fBmaildiracl\ \-list\ \fR\fB\fImaildir\fR\fR\fB\ \fR\fB\fIfolder\fR\fR\fB\ \fR\ 'u
\fBmaildiracl \-list
\fR\fB\fImaildir\fR\fR\fB
\fR\fB\fIfolder\fR\fR\fB
\fR
.PP
This command lists the access control lists set for
\fIfolder\fR\&.
\fIfolder\fR
must be either
\(lqINBOX\(rq
or
\(lqINBOX\&.folder\&.subfolder\(rq, which is the same naming convention for the
Courier
IMAP server\&.
.HP \w'\fBmaildiracl\ \-set\ \fR\fB\fImaildir\fR\fR\fB\ \fR\fB\fIfolder\fR\fR\fB\ \fR\fB\fIidentifier\fR\fR\fB\ \fR\fB\fIrights\fR\fR\ 'u
\fBmaildiracl \-set
\fR\fB\fImaildir\fR\fR\fB
\fR\fB\fIfolder\fR\fR\fB
\fR\fB\fIidentifier\fR\fR\fB
\fR\fB\fIrights\fR\fR
.PP
Puts
\fIidentifier\fR
(which may begin with a minus sign to specify a negative right) and
\fIrights\fR
in
\fIfolder\fR\*(Aqs access control list\&. Existing rights for
\fIidentifier\fR
(or
\fIidentifier\fR) are replaced by
\fIrights\fR
unless
\(lqrights\(rq
begins with
\(lq+\(rq
or
\(lq\-\(rq, which modifies the existing rights by adding or removing from them accordingly\&. Some examples:
.sp
.if n \{\
.RS 4
.\}
.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
.if n \{\
.RE
.\}
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
Observe that the last command
\fIrevokes\fR
the
\(lqr\(rq
right from
\(lqtom\(rq, by adding it as a negative right\&.
.sp .5v
.RE
.HP \w'\fBmaildiracl\ \-delete\ \fR\fB\fImaildir\fR\fR\fB\ \fR\fB\fIfolder\fR\fR\fB\ \fR\fB\fIidentifier\fR\fR\ 'u
\fBmaildiracl \-delete
\fR\fB\fImaildir\fR\fR\fB
\fR\fB\fIfolder\fR\fR\fB
\fR\fB\fIidentifier\fR\fR
.PP
This command removes
\fIidentifier\fR
from
\fIfolder\fR\*(Aqs access control list, if it exists\&. Use
\(lq\-\fIidentifier\fR\(rq
to remove negative rights\&.
.HP \w'\fBmaildiracl\ \-compute\ \fR\fB\fImaildir\fR\fR\fB\ \fR\fB\fIfolder\fR\fR\fB\ [\fR\fB\fIidentifier\fR\fR\fB]+\fR\ 'u
\fBmaildiracl \-compute
\fR\fB\fImaildir\fR\fR\fB
\fR\fB\fIfolder\fR\fR\fB
[\fR\fB\fIidentifier\fR\fR\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 the
Courier
IMAP server:
.sp
.if n \{\
.RS 4
.\}
.nf
maildiracl \-compute /home/tom46/Maildir INBOX\&.Sent owner user=tom46
.fi
.if n \{\
.RE
.\}
.PP
This command computes access rights
\(lqtom46\(rq
has on his own folder\&.
.sp
.if n \{\
.RS 4
.\}
.nf
maildiracl \-compute /home/john34/Maildir INBOX\&.Public user=tom46
.fi
.if n \{\
.RE
.\}
.PP
This command computes access rights
\(lqtom46\(rq
has on
\(lqjohn34\(rq\*(Aqs folder\&.
.SH "IRREVOCABLE ACCESS RIGHTS"
.PP
The owner of the mailbox must always have the
\(lqa\(rq
amd
\(lql\(rq
access rights\&. The
administrators
group must always have all access rights to all folders\&. Attempts to set access control lists, that do not include these minimum access rights, will be rejected\&.
.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
\(lqACL2\(rq) of IMAP access control lists, which is a work\-in\-progress\&. The existing IMAP ACL,
\m[blue]\fBRFC 2086\fR\m[]\&\s-2\u[2]\d\s+2
is transparently implemented inside the ACL2 model\&.
.PP
If history\*(Aqs 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
\(lqACL overview\(rq
portion of this manual page is a
\fIvery\fR
brief summary of ACL2, which leaves out optional parts of ACL2 that are not implemented\&.
.SH "SEE ALSO"
.PP
\m[blue]\fB\fBmaildirmake\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2,
\m[blue]\fB\fBmaildirkw\fR(1)\fR\m[]\&\s-2\u[3]\d\s+2,
.SH "AUTHOR"
.PP
\fBSam Varshavchik\fR
.RS 4
Author
.RE
.SH "NOTES"
.IP " 1." 4
\fBmaildirmake\fR(1)
.RS 4
\%[set $man.base.url.for.relative.links]/maildirmake.html
.RE
.IP " 2." 4
RFC 2086
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2086.txt
.RE
.IP " 3." 4
\fBmaildirkw\fR(1)
.RS 4
\%[set $man.base.url.for.relative.links]/maildirkw.html
.RE
Mini Shell