'\" t .\" .\" .\" Title: maildiracl .\" Author: Sam Varshavchik .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 10/28/2020 .\" Manual: Double Precision, Inc. .\" Source: Courier Mail Server .\" Language: English .\" .TH "MAILDIRACL" "1" "10/28/2020" "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 \%http://www.courier-mta.org/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 \%http://www.courier-mta.org/maildirkw.html .RE