1<?xml version="1.0"?>
2<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>maildiracl</title><link rel="stylesheet" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"/><link rel="home" href="#maildiracl" title="maildiracl"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--
3
4Copyright 1998 - 2009 Double Precision, Inc.  See COPYING for distribution
5information.
6
7--></head><body><div class="refentry"><a id="maildiracl" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>maildiracl — manage access control lists</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">maildiracl</code>  {-reset} {<em class="replaceable"><code>maildir</code></em>}</p></div><div class="cmdsynopsis"><p><code class="command">maildiracl</code>  {-list} {<em class="replaceable"><code>maildir</code></em>} {<em class="replaceable"><code>INBOX[.folder]</code></em>}</p></div><div class="cmdsynopsis"><p><code class="command">maildiracl</code>  {-set} {<em class="replaceable"><code>maildir</code></em>} {<em class="replaceable"><code>INBOX[.folder]</code></em>} {<em class="replaceable"><code>[-]identifier</code></em>} {<em class="replaceable"><code>[+/-]rights</code></em>}</p></div><div class="cmdsynopsis"><p><code class="command">maildiracl</code>  {-delete} {<em class="replaceable"><code>maildir</code></em>} {<em class="replaceable"><code>INBOX[.folder]</code></em>} {<em class="replaceable"><code>[-]identifier</code></em>}</p></div><div class="cmdsynopsis"><p><code class="command">maildiracl</code>  {-compute} {<em class="replaceable"><code>maildir</code></em>} {<em class="replaceable"><code>INBOX[.folder]</code></em>} {<em class="replaceable"><code>identifier</code></em>...}</p></div></div><div class="refsect1"><a id="maildiracl_description" shape="rect"> </a><h2>DESCRIPTION</h2><p>
8<span class="command"><strong>maildiracl</strong></span>
9manages <span class="quote">“<span class="quote">access control lists</span>”</span> (or ACLs)
10of the <span class="application">Courier</span> IMAP server maildir folders.
11Access control lists are used primarily to provide fine-grained control
12for accessing virtual shared folders via IMAP.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
13The <span class="application">Courier</span> IMAP server server implements
14two types of shared folders:
15filesystem permission-based shared folders,
16as well as virtual shared folders based on IMAP access control lists.
17Use the <span class="command"><strong>maildiracl</strong></span>
18command to set up access control lists for virtual shared folders.
19Use the
20<a class="ulink" href="maildirmake.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildirmake</span>(1)</span></a>,
21command
22to implement shared folders based on
23filesystem permissions.</p><p>
24See the <span class="application">Courier</span> IMAP
25server documentation for additional information
26on setting up virtual shared folders.</p></div><div class="refsect2"><a id="maildiracl_acl_overview" shape="rect"> </a><h3>ACL overview</h3><p>
27ACLs provide a fine-grained mechanism for controlling
28access to shared folders.
29ACLs may be used to specify, for example, that
30<code class="literal">user1</code> may only open and read the messages in the folder;
31and <code class="literal">user2</code> can not only do that, but also delete messages,
32and create subfolders.</p><p>
33Each folder maintains its own individual access control list, that specifies
34who can do what to the folder.
35An ACL is a list of <span class="quote">“<span class="quote">identifier</span>”</span> and <span class="quote">“<span class="quote">rights</span>”</span>
36pairs.
37Each <span class="quote">“<span class="quote">identifier</span>”</span> and <span class="quote">“<span class="quote">rights</span>”</span> pair means that an
38entity called <span class="quote">“<span class="quote">identifier</span>”</span>
39(using the <code class="literal">UTF-8</code> character set)
40is allowed to do <span class="quote">“<span class="quote">rights</span>”</span>
41on this folder.
42<span class="quote">“<span class="quote">rights</span>”</span> consists of one or more letters, each letter
43signifies a particular action:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">a</span></dt><dd><p>
44<em class="replaceable"><code>identifier</code></em>
45may modify this folder's ACLs.</p></dd><dt><span class="term">c</span></dt><dd><p>
46<em class="replaceable"><code>identifier</code></em>
47may create subfolders of this folder (this includes renaming another
48folder as this folder's subfolders).</p></dd><dt><span class="term">e</span></dt><dd><p>
49<em class="replaceable"><code>identifier</code></em>
50may remove deleted messages from this folder.</p></dd><dt><span class="term">i</span></dt><dd><p>
51<em class="replaceable"><code>identifier</code></em>
52may add messages to this folder (either uploading them one by one,
53or copying messages from another folder).</p></dd><dt><span class="term">l</span></dt><dd><p>
54<em class="replaceable"><code>identifier</code></em>
55may actually see that this folder exists.
56If <em class="replaceable"><code>identifier</code></em> does not have the <span class="quote">“<span class="quote">l</span>”</span>
57right on this folder, the folder is effectively invisible to
58<em class="replaceable"><code>identifier</code></em>.</p></dd><dt><span class="term">r</span></dt><dd><p>
59<em class="replaceable"><code>identifier</code></em>
60may open this folder.
61Note that if <em class="replaceable"><code>identifier</code></em>
62knows the name of this folder, it can open it even if
63<em class="replaceable"><code>identifier</code></em> does not the <span class="quote">“<span class="quote">l</span>”</span>
64right on this folder.</p></dd><dt><span class="term">s</span></dt><dd><p>
65<em class="replaceable"><code>identifier</code></em>
66may mark messages in this folder as seen, or unseen.</p></dd><dt><span class="term">t</span></dt><dd><p>
67<em class="replaceable"><code>identifier</code></em>
68may mark messages in this folder as deleted, or undeleted.</p></dd><dt><span class="term">w</span></dt><dd><p>
69<em class="replaceable"><code>identifier</code></em>
70may change other status flags of messages in this folder.
71May also add or remove custom keywords on individual messages.</p></dd><dt><span class="term">x</span></dt><dd><p>
72<em class="replaceable"><code>identifier</code></em>
73may delete this folder (which includes renaming this folder as another
74mailbox's subfoler.</p></dd></dl></div><div class="refsect3"><a id="maildiracl_negative_rights" shape="rect"> </a><h4>Negative rights</h4><p>
75An ACL entry of <span class="quote">“<span class="quote">-identifier</span>”</span> and <span class="quote">“<span class="quote">rights</span>”</span>
76is called a <span class="quote">“<span class="quote">negative right</span>”</span>, which
77explicitly removes <span class="quote">“<span class="quote">rights</span>”</span> from <span class="quote">“<span class="quote">identifier</span>”</span>.
78More than one <span class="quote">“<span class="quote">identifier</span>”</span> is usually used to determine the
79actual rights someone has for the given folder.
80The actual access rights are determined by taking all rights from all
81applicable <em class="replaceable"><code>identifier</code></em>, than subtracting any
82negative rights, as specified in the following section.</p></div><div class="refsect3"><a id="maildiracl_identifiers" shape="rect"> </a><h4>Identifiers</h4><p>
83Access rights on a given folder are computed by obtained the rights
84on the following identifiers, then subtracting the negative rights on the
85same identifiers:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">owner</code></span></dt><dd><p>
86The owner of the maildir containing this folder.
87The maildir's INBOX's ACL defaults to all rights for its owner.
88A new folder's ACL is the same as its parent's ACL.
89In all cases, trying to remove the <span class="quote">“<span class="quote">a</span>”</span> right from the owner
90(either directly or using a negative right) results in an error.</p></dd><dt><span class="term"><code class="literal">anyone</code></span></dt><dd><p>
91This identifier refers literally to every userid.
92The associated rights (or negative rights) are always used.</p></dd><dt><span class="term"><code class="literal">anonymous</code></span></dt><dd><p>
93This is a synonym from <span class="quote">“<span class="quote">anyone</span>”</span>.</p></dd><dt><span class="term"><code class="literal">user=</code><em class="replaceable"><code>loginid</code></em></span></dt><dd><p>
94Rights (or negative rights) for IMAP account <span class="quote">“<span class="quote">loginid</span>”</span>.
95</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
96<span class="quote">“<span class="quote">loginid</span>”</span> is what's logged to syslog after a succesful
97login.
98In some situations <span class="quote">“<span class="quote">loginid</span>”</span> is not exactly the actual login ID
99used by the IMAP client.</p></div><p>
100</p></dd><dt><span class="term"><code class="literal">group=</code><em class="replaceable"><code>name</code></em></span></dt><dd><p>
101Rights (or negative rights) for account group <span class="quote">“<span class="quote">name</span>”</span>.
102Access rights are granted to an account group as a whole.
103The account options feature of the Courier Authentication Library specifies
104which account belongs to which account group.
105See courier-authlib's documentation for more information.
106</p></dd><dt><span class="term"><code class="literal">administrators</code></span></dt><dd><p>
107This is an alias for <span class="quote">“<span class="quote">group=administrators</span>”</span>.
108Accounts that are members of an account group called
109<span class="quote">“<span class="quote">administrators</span>”</span> are considered administrative accounts, and
110automatically receive all access rights on all accessible folders.</p></dd></dl></div><p>
111Consider the following access control list:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
112owner          aceilrstwx
113anyone         lr
114user=john      w
115-user=mary     r
116administrators aceilrstwx
117</pre></div><p>
118This access control list specifies that the folder's owner has complete
119control over the mailbox (as well as the administrators, which have complete
120access to every folder); everyone else can see it and open it,
121except for <span class="quote">“<span class="quote">mary</span>”</span> who can see that the mailbox exists, but
122can't open it; additionally, <span class="quote">“<span class="quote">john</span>”</span> can change the status and
123keywords of individual messages (but not mark them as deleted/undeleted or
124seen/unseen, which requires additional rights).</p></div></div></div><div class="refsect1"><a id="maildiracl_options" shape="rect"> </a><h2>OPTIONS</h2><div class="cmdsynopsis"><p><code class="command">maildiracl -reset <em class="replaceable"><code>maildir</code></em></code> </p></div><p>
125This command resets access control lists in
126<code class="filename"><em class="replaceable"><code>maildir</code></em></code>
127which as a path to a maildir.
128Under certain conditions, the files where a folder's ACLs are saved may
129continue to exist after the folder is removed.
130The <code class="literal">-reset</code> options goes through
131<em class="replaceable"><code>maildir</code></em>
132and removes all stale ACL files for removed folders.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
133The <span class="application">Courier</span> IMAP server
134normally performs this maintenance
135function automatically.
136It is not necessary to run this command under normal conditions.</p></div><div class="cmdsynopsis"><p><code class="command">maildiracl -list
137<em class="replaceable"><code>maildir</code></em>
138<em class="replaceable"><code>folder</code></em>
139</code> </p></div><p>
140This command
141lists the access control lists set for <em class="replaceable"><code>folder</code></em>.
142<em class="replaceable"><code>folder</code></em> must be either
143<span class="quote">“<span class="quote">INBOX</span>”</span> or <span class="quote">“<span class="quote">INBOX.folder.subfolder</span>”</span>, which is the
144same naming convention for
145the <span class="application">Courier</span> IMAP server.</p><div class="cmdsynopsis"><p><code class="command">maildiracl -set
146<em class="replaceable"><code>maildir</code></em>
147<em class="replaceable"><code>folder</code></em>
148<em class="replaceable"><code>identifier</code></em>
149<em class="replaceable"><code>rights</code></em></code> </p></div><p>
150Puts <em class="replaceable"><code>identifier</code></em> (which may begin with a minus
151sign to specify a negative right) and
152<em class="replaceable"><code>rights</code></em> in
153<em class="replaceable"><code>folder</code></em>'s access control list.
154Existing rights for
155<em class="replaceable"><code>identifier</code></em>
156(or <em class="replaceable"><code>identifier</code></em>) are replaced by
157<em class="replaceable"><code>rights</code></em> unless <span class="quote">“<span class="quote">rights</span>”</span> begins with
158<span class="quote">“<span class="quote">+</span>”</span> or <span class="quote">“<span class="quote">-</span>”</span>, which modifies the existing rights
159by adding or removing from them accordingly.
160Some examples:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
161maildiracl -set /home/user1/Maildir INBOX.Sent user=john lr
162
163maildiracl -set /home/user2/Maildir INBOX.Notes anyone -r
164
165maildiracl -set /home/user3/Maildir INBOX.Private -user=tom +r
166</pre></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
167Observe that the last command <span class="emphasis"><em>revokes</em></span> the <span class="quote">“<span class="quote">r</span>”</span>
168right from <span class="quote">“<span class="quote">tom</span>”</span>, by adding it as a negative right.</p></div><div class="cmdsynopsis"><p><code class="command">maildiracl -delete
169<em class="replaceable"><code>maildir</code></em>
170<em class="replaceable"><code>folder</code></em>
171<em class="replaceable"><code>identifier</code></em></code> </p></div><p>
172This command removes <em class="replaceable"><code>identifier</code></em>
173from
174<em class="replaceable"><code>folder</code></em>'s access control list, if it exists.
175Use <span class="quote">“<span class="quote">-<em class="replaceable"><code>identifier</code></em></span>”</span> to remove
176negative rights.</p><div class="cmdsynopsis"><p><code class="command">maildiracl -compute
177<em class="replaceable"><code>maildir</code></em>
178<em class="replaceable"><code>folder</code></em>
179[<em class="replaceable"><code>identifier</code></em>]+</code> </p></div><p>
180This command takes a list of one or more
181<em class="replaceable"><code>identifier</code></em>s.
182All access rights for the
183<em class="replaceable"><code>identifier</code></em>s are combined together, then
184any appropriate negative rights are removed, and the result is printed
185on standard output.
186Use the following procedure to compute access rights the same way as they
187are computed by
188the <span class="application">Courier</span> IMAP server:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
189maildiracl -compute /home/tom46/Maildir INBOX.Sent owner user=tom46
190</pre></div><p>
191This command computes access rights <span class="quote">“<span class="quote">tom46</span>”</span> has on
192his own folder.</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
193maildiracl -compute /home/john34/Maildir INBOX.Public user=tom46
194</pre></div><p>
195This command computes access rights <span class="quote">“<span class="quote">tom46</span>”</span> has on
196<span class="quote">“<span class="quote">john34</span>”</span>'s folder.</p></div><div class="refsect1"><a id="maildiracl_irrevocable_access_rights" shape="rect"> </a><h2>IRREVOCABLE ACCESS RIGHTS</h2><p>
197The owner of the mailbox must always have the <span class="quote">“<span class="quote">a</span>”</span> amd
198<span class="quote">“<span class="quote">l</span>”</span> access rights.
199The <code class="literal">administrators</code> group must always have all access
200rights to all folders.
201Attempts to set access control lists, that do not include these minimum
202access rights, will be rejected.</p></div><div class="refsect1"><a id="maildiracl_bugs" shape="rect"> </a><h2>BUGS</h2><p>
203All identifiers are specified using the <code class="literal">UTF-8</code> character
204set.</p><p>
205All non-Latin letters in folder names are specified using the
206<code class="literal">modified-UTF7</code> coding as used in IMAP.</p><p>
207This implementation of access control lists is based on
208version 2 (or <span class="quote">“<span class="quote">ACL2</span>”</span>) of IMAP
209access control lists, which is a work-in-progress.
210The existing IMAP ACL,
211<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2086.txt" target="_top" shape="rect">RFC 2086</a>
212is transparently implemented inside the ACL2 model.</p><p>
213If history's of any guidance, ACL2 is subject to change at any time.
214Be sure to check the release notes
215when upgrading to a newer version of this software.
216The <span class="quote">“<span class="quote">ACL overview</span>”</span> portion of this manual page is a
217<span class="emphasis"><em>very</em></span> brief summary of ACL2, which leaves out optional
218parts of ACL2 that are not implemented.</p></div><div class="refsect1"><a id="maildiracl_see_also" shape="rect"> </a><h2>SEE ALSO</h2><p>
219<a class="ulink" href="maildirmake.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildirmake</span>(1)</span></a>,
220<a class="ulink" href="maildirkw.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildirkw</span>(1)</span></a>,</p></div></div></body></html>
221