/usr/share/doc/courier-doc/html/maildiracl.html

<?xml version="1.0"?>
<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 V1.78.1"/><link rel="home" href="#idm255242695568" 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"/><!--

Copyright 1998 - 2009 Double Precision, Inc.  See COPYING for distribution
information.

--></head><body><div class="refentry"><a id="idm255242695568" 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="idm255241497872" shape="rect"> </a><h2>DESCRIPTION</h2><p>
<span class="command"><strong>maildiracl</strong></span>
manages <span class="quote">“<span class="quote">access control lists</span>”</span> (or ACLs)
of the <span class="application">Courier</span> IMAP server maildir folders.
Access control lists are used primarily to provide fine-grained control
for 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>
The <span class="application">Courier</span> 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 <span class="command"><strong>maildiracl</strong></span>
command to set up access control lists for virtual shared folders.
Use the
<a class="ulink" href="maildirmake.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildirmake</span>(1)</span></a>,
command
to implement shared folders based on
filesystem permissions.</p><p>
See the <span class="application">Courier</span> IMAP
server documentation for additional information
on setting up virtual shared folders.</p></div><div class="refsect2"><a id="idm255241490800" shape="rect"> </a><h3>ACL overview</h3><p>
ACLs provide a fine-grained mechanism for controlling
access to shared folders.
ACLs may be used to specify, for example, that
<code class="literal">user1</code> may only open and read the messages in the folder;
and <code class="literal">user2</code> can not only do that, but also delete messages,
and create subfolders.</p><p>
Each folder maintains its own individual access control list, that specifies
who can do what to the folder.
An ACL is a list of <span class="quote">“<span class="quote">identifier</span>”</span> and <span class="quote">“<span class="quote">rights</span>”</span>
pairs.
Each <span class="quote">“<span class="quote">identifier</span>”</span> and <span class="quote">“<span class="quote">rights</span>”</span> pair means that an
entity called <span class="quote">“<span class="quote">identifier</span>”</span>
(using the <code class="literal">UTF-8</code> character set)
is allowed to do <span class="quote">“<span class="quote">rights</span>”</span>
on this folder.
<span class="quote">“<span class="quote">rights</span>”</span> consists of one or more letters, each letter
signifies a particular action:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">a</span></dt><dd><p>
<em class="replaceable"><code>identifier</code></em>
may modify this folder's ACLs.</p></dd><dt><span class="term">c</span></dt><dd><p>
<em class="replaceable"><code>identifier</code></em>
may create subfolders of this folder (this includes renaming another
folder as this folder's subfolders).</p></dd><dt><span class="term">e</span></dt><dd><p>
<em class="replaceable"><code>identifier</code></em>
may remove deleted messages from this folder.</p></dd><dt><span class="term">i</span></dt><dd><p>
<em class="replaceable"><code>identifier</code></em>
may add messages to this folder (either uploading them one by one,
or copying messages from another folder).</p></dd><dt><span class="term">l</span></dt><dd><p>
<em class="replaceable"><code>identifier</code></em>
may actually see that this folder exists.
If <em class="replaceable"><code>identifier</code></em> does not have the <span class="quote">“<span class="quote">l</span>”</span>
right on this folder, the folder is effectively invisible to
<em class="replaceable"><code>identifier</code></em>.</p></dd><dt><span class="term">r</span></dt><dd><p>
<em class="replaceable"><code>identifier</code></em>
may open this folder.
Note that if <em class="replaceable"><code>identifier</code></em>
knows the name of this folder, it can open it even if
<em class="replaceable"><code>identifier</code></em> does not the <span class="quote">“<span class="quote">l</span>”</span>
right on this folder.</p></dd><dt><span class="term">s</span></dt><dd><p>
<em class="replaceable"><code>identifier</code></em>
may mark messages in this folder as seen, or unseen.</p></dd><dt><span class="term">t</span></dt><dd><p>
<em class="replaceable"><code>identifier</code></em>
may mark messages in this folder as deleted, or undeleted.</p></dd><dt><span class="term">w</span></dt><dd><p>
<em class="replaceable"><code>identifier</code></em>
may change other status flags of messages in this folder.
May also add or remove custom keywords on individual messages.</p></dd><dt><span class="term">x</span></dt><dd><p>
<em class="replaceable"><code>identifier</code></em>
may delete this folder (which includes renaming this folder as another
mailbox's subfoler.</p></dd></dl></div><div class="refsect3"><a id="idm255241462272" shape="rect"> </a><h4>Negative rights</h4><p>
An ACL entry of <span class="quote">“<span class="quote">-identifier</span>”</span> and <span class="quote">“<span class="quote">rights</span>”</span>
is called a <span class="quote">“<span class="quote">negative right</span>”</span>, which
explicitly removes <span class="quote">“<span class="quote">rights</span>”</span> from <span class="quote">“<span class="quote">identifier</span>”</span>.
More than one <span class="quote">“<span class="quote">identifier</span>”</span> 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 <em class="replaceable"><code>identifier</code></em>, than subtracting any
negative rights, as specified in the following section.</p></div><div class="refsect3"><a id="idm255241458160" shape="rect"> </a><h4>Identifiers</h4><p>
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:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">owner</code></span></dt><dd><p>
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 <span class="quote">“<span class="quote">a</span>”</span> right from the owner
(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>
This identifier refers literally to every userid.
The associated rights (or negative rights) are always used.</p></dd><dt><span class="term"><code class="literal">anonymous</code></span></dt><dd><p>
This 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>
Rights (or negative rights) for IMAP account <span class="quote">“<span class="quote">loginid</span>”</span>.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
<span class="quote">“<span class="quote">loginid</span>”</span> is what's logged to syslog after a succesful
login.
In some situations <span class="quote">“<span class="quote">loginid</span>”</span> is not exactly the actual login ID
used by the IMAP client.</p></div><p>
</p></dd><dt><span class="term"><code class="literal">group=</code><em class="replaceable"><code>name</code></em></span></dt><dd><p>
Rights (or negative rights) for account group <span class="quote">“<span class="quote">name</span>”</span>.
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's documentation for more information.
</p></dd><dt><span class="term"><code class="literal">administrators</code></span></dt><dd><p>
This is an alias for <span class="quote">“<span class="quote">group=administrators</span>”</span>.
Accounts that are members of an account group called
<span class="quote">“<span class="quote">administrators</span>”</span> are considered administrative accounts, and
automatically receive all access rights on all accessible folders.</p></dd></dl></div><p>
Consider the following access control list:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
owner          aceilrstwx
anyone         lr
user=john      w
-user=mary     r
administrators aceilrstwx
</pre></div><p>
This access control list specifies that the folder's 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 <span class="quote">“<span class="quote">mary</span>”</span> who can see that the mailbox exists, but
can't open it; additionally, <span class="quote">“<span class="quote">john</span>”</span> can change the status and
keywords of individual messages (but not mark them as deleted/undeleted or
seen/unseen, which requires additional rights).</p></div></div></div><div class="refsect1"><a id="idm255241436064" 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>
This command resets access control lists in
<code class="filename"><em class="replaceable"><code>maildir</code></em></code>
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 <code class="literal">-reset</code> options goes through
<em class="replaceable"><code>maildir</code></em>
and 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>
The <span class="application">Courier</span> IMAP server
normally performs this maintenance
function automatically.
It is not necessary to run this command under normal conditions.</p></div><div class="cmdsynopsis"><p><code class="command">maildiracl -list
<em class="replaceable"><code>maildir</code></em>
<em class="replaceable"><code>folder</code></em>
</code> </p></div><p>
This command
lists the access control lists set for <em class="replaceable"><code>folder</code></em>.
<em class="replaceable"><code>folder</code></em> must be either
<span class="quote">“<span class="quote">INBOX</span>”</span> or <span class="quote">“<span class="quote">INBOX.folder.subfolder</span>”</span>, which is the
same naming convention for
the <span class="application">Courier</span> IMAP server.</p><div class="cmdsynopsis"><p><code class="command">maildiracl -set
<em class="replaceable"><code>maildir</code></em>
<em class="replaceable"><code>folder</code></em>
<em class="replaceable"><code>identifier</code></em>
<em class="replaceable"><code>rights</code></em></code> </p></div><p>
Puts <em class="replaceable"><code>identifier</code></em> (which may begin with a minus
sign to specify a negative right) and
<em class="replaceable"><code>rights</code></em> in
<em class="replaceable"><code>folder</code></em>'s access control list.
Existing rights for
<em class="replaceable"><code>identifier</code></em>
(or <em class="replaceable"><code>identifier</code></em>) are replaced by
<em class="replaceable"><code>rights</code></em> unless <span class="quote">“<span class="quote">rights</span>”</span> begins with
<span class="quote">“<span class="quote">+</span>”</span> or <span class="quote">“<span class="quote">-</span>”</span>, which modifies the existing rights
by adding or removing from them accordingly.
Some examples:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
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
</pre></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Observe that the last command <span class="emphasis"><em>revokes</em></span> the <span class="quote">“<span class="quote">r</span>”</span>
right 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
<em class="replaceable"><code>maildir</code></em>
<em class="replaceable"><code>folder</code></em>
<em class="replaceable"><code>identifier</code></em></code> </p></div><p>
This command removes <em class="replaceable"><code>identifier</code></em>
from
<em class="replaceable"><code>folder</code></em>'s access control list, if it exists.
Use <span class="quote">“<span class="quote">-<em class="replaceable"><code>identifier</code></em></span>”</span> to remove
negative rights.</p><div class="cmdsynopsis"><p><code class="command">maildiracl -compute
<em class="replaceable"><code>maildir</code></em>
<em class="replaceable"><code>folder</code></em>
[<em class="replaceable"><code>identifier</code></em>]+</code> </p></div><p>
This command takes a list of one or more
<em class="replaceable"><code>identifier</code></em>s.
All access rights for the
<em class="replaceable"><code>identifier</code></em>s 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 <span class="application">Courier</span> IMAP server:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
maildiracl -compute /home/tom46/Maildir INBOX.Sent owner user=tom46
</pre></div><p>
This command computes access rights <span class="quote">“<span class="quote">tom46</span>”</span> has on
his own folder.</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
maildiracl -compute /home/john34/Maildir INBOX.Public user=tom46
</pre></div><p>
This command computes access rights <span class="quote">“<span class="quote">tom46</span>”</span> has on
<span class="quote">“<span class="quote">john34</span>”</span>'s folder.</p></div><div class="refsect1"><a id="idm255241403232" shape="rect"> </a><h2>IRREVOCABLE ACCESS RIGHTS</h2><p>
The owner of the mailbox must always have the <span class="quote">“<span class="quote">a</span>”</span> amd
<span class="quote">“<span class="quote">l</span>”</span> access rights.
The <code class="literal">administrators</code> 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.</p></div><div class="refsect1"><a id="idm255241400512" shape="rect"> </a><h2>BUGS</h2><p>
All identifiers are specified using the <code class="literal">UTF-8</code> character
set.</p><p>
All non-Latin letters in folder names are specified using the
<code class="literal">modified-UTF7</code> coding as used in IMAP.</p><p>
This implementation of access control lists is based on
version 2 (or <span class="quote">“<span class="quote">ACL2</span>”</span>) of IMAP
access control lists, which is a work-in-progress.
The existing IMAP ACL,
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2086.txt" target="_top" shape="rect">RFC 2086</a>
is transparently implemented inside the ACL2 model.</p><p>
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 <span class="quote">“<span class="quote">ACL overview</span>”</span> portion of this manual page is a
<span class="emphasis"><em>very</em></span> brief summary of ACL2, which leaves out optional
parts of ACL2 that are not implemented.</p></div><div class="refsect1"><a id="idm255241394736" shape="rect"> </a><h2>SEE ALSO</h2><p>
<a class="ulink" href="maildirmake.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildirmake</span>(1)</span></a>,
<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>
courier-doc 0.78.0-2ubuntu2 / usr / share / doc / courier-doc / html / maildiracl.html
