File: //proc/self/root/usr/share/doc/maildrop/maildirmake.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>maildirmake</title><link rel="stylesheet" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"/><link rel="home" href="#maildirmake" title="maildirmake"/><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="maildirmake" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>maildirmake — create maildirs and maildir folders</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">maildirmake</code> [options...] {<em class="replaceable"><code>maildir</code></em>}</p></div></div><div class="refsect1"><a id="description" shape="rect"> </a><h2>DESCRIPTION</h2><p>
The <span class="command"><strong>maildirmake</strong></span> command creates maildirs, and
maildir folders and performs some routine maintenance on them.
This documentation
describes the <span class="command"><strong>maildirmake</strong></span> command from the
<span class="application">Courier</span> mail server,
which creates an extended form of maildirs that implements
additional extensions beyond the basic maildir properties that were first
implemented in the Qmail mail server.</p></div><div class="refsect1"><a id="options" shape="rect"> </a><h2>OPTIONS</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">-S</code></span></dt><dd><p>create a "sharable" maildir. A sharable maildir has
slightly different permissions which allows creation of publicly-shared
folders.</p></dd><dt><span class="term"><code class="literal">-q</code> <em class="replaceable"><code>quota</code></em></span></dt><dd><p>install a quota on the maildir.
See
<a class="ulink" href="maildirquota.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildirquota</span>(7)</span></a>
for more information.
The specified maildir gets automatically created if it does not
exist; otherwise the existing maildir's quota gets updated.
<em class="replaceable"><code>quota</code></em> may be:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>####S</code></em></span></dt><dd><p>
Specifies the quota in the total number of bytes for all
messages.
<span class="quote">“<span class="quote">10000000S</span>”</span> specifies a quota of ten million
bytes.
</p></dd><dt><span class="term"><em class="replaceable"><code>####C</code></em></span></dt><dd><p>
Specifies the quota in the total number of messages in
the maildir.
<span class="quote">“<span class="quote">10000S</span>”</span> specifies a quota of ten thousand
messages.
</p></dd></dl></div></dd><dt><span class="term"><code class="literal">-f</code> <em class="replaceable"><code>folder</code></em></span></dt><dd><p>do not create a maildir, but create a folder in an
existing maildir.</p></dd><dt><span class="term"><code class="literal">-F</code> <em class="replaceable"><code>folder</code></em></span></dt><dd><p>Like the <code class="literal">-f</code> option, except
that the folder's name is given using the system locale's
character set. Non-Latin characters in the folder's name
must be given to the <code class="literal">-f</code> option using IMAP's
UTF8 encoding. The <code class="literal">-F</code> option
takes the folder name specified using the console's character
set.</p></dd><dt><span class="term"><code class="literal">-s</code> <em class="replaceable"><code>mode</code></em></span></dt><dd><p>create a publicly accessible folder in an
existing sharable maildir. First, use the <code class="option">-S</code> option to
create a sharable maildir.
Then, run <span class="command"><strong>maildirmake</strong></span> again with the
<code class="option">-s</code> option to create
publicly accessible folders.
<em class="replaceable"><code>mode</code></em> is a comma-separated list of
the following keywords: <code class="literal">read</code> - readonly folder, only you can
write messages to this folder;
<code class="literal">write</code> - anyone can read and
write messages to this folder;
<code class="literal">group</code> - only allow members of
your own system group to access messages in this folder (instead of
everyone).</p></dd><dt><span class="term"><code class="literal">--add</code> <em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>pathname</code></em>,
<code class="literal">--del</code> <em class="replaceable"><code>name</code></em></span></dt><dd><p>
create or delete the directories and links needed to
access shared folders. See below for more information.</p></dd><dt><span class="term"><code class="literal">--checkutf8</code> <em class="replaceable"><code>maildir</code></em> <em class="replaceable"><code>maildirfilter</code></em></span></dt><dd><p>
Perform a sanity check to verify that a pre-unicode format
maildir can be converted to a unicode-format maildir.
See <span class="quote">“<span class="quote">Converting pre-unicode format maildirs</span>”</span>, below,
for more information.
</p></dd><dt><span class="term"><code class="literal">--convutf8</code> <em class="replaceable"><code>maildir</code></em> <em class="replaceable"><code>maildirfilter</code></em></span></dt><dd><p>
Convert a pre-unicode format
maildir can be converted to a unicode-format maildir.
See <span class="quote">“<span class="quote">Converting pre-unicode format maildirs</span>”</span>, below,
for more information.
</p></dd></dl></div><div class="refsect2"><a id="folders" shape="rect"> </a><h3>FOLDERS</h3><p>
This <span class="command"><strong>maildirmake</strong></span> command supports enhanced maildirs that
contain folders.</p><p>
By itself, <span class="command"><strong>maildirmake</strong></span> makes a new subdirectory
<em class="replaceable"><code>maildir</code></em>,
and creates all the necessary structures.
The <code class="option">-f</code> option
creates a new "folder" within an existing
<em class="replaceable"><code>maildir</code></em>. <em class="replaceable"><code>maildir</code></em> must
already exist, and the <span class="command"><strong>maildirmake</strong></span> command will create a new
folder in the maildir.</p><p>
Folders are simply subdirectories inside the main maildir whose names start
with a period, and which are themselves maildirs.
For example, the command
"<span class="command"><strong>maildirmake -f Drafts mail/Maildir</strong></span>" creates
<code class="filename">mail/Maildir/.Drafts</code>,
that has the usual <code class="filename">tmp</code>,
<code class="filename">new</code> and <code class="filename">cur</code>.
You MUST use the <code class="option">-f</code> option, instead of
specifying <code class="filename">mail/Maildir/.Drafts</code> directly,
in order to correctly
initialize certain enhanced maildir features.</p><p>Folders cannot be created directly within other folders.
Running
<span class="command"><strong>maildirmake -f Urgent mail/Maildir/.Drafts</strong></span> will not work.
Instead, the period character is designated as a hierarchy separator, run
<span class="command"><strong>maildirmake -f Drafts.Urgent mail/Maildir</strong></span> instead.
This creates
<code class="filename">mail/Maildir/.Drafts.Urgent</code>, and all mail software
that supports
enhanced maildirs will interpret it as a subfolder Urgent of the Drafts
folder.</p></div><div class="refsect2"><a id="sharedfolders" shape="rect"> </a><h3>SHARED FOLDERS</h3><p>
This is another extension to the Maildir format that allows folders to be
shared between multiple clients.</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 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>maildirmake</strong></span> command
to implement shared folders based on
filesystem permissions.
The
<a class="ulink" href="maildiracl.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildiracl</span>(1)</span></a>
command manages access control lists, which
are used by virtual shared folders.</p><p>
See the <span class="application">Courier</span>
IMAP server documentation for more information.</p></div><p>
First, you need to create a collection of
sharable folders, as a separate maildir:</p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><div class="literallayout"><p><span class="command"><strong>maildirmake -S /usr/local/share/maildirs/notices</strong></span></p></div></div></blockquote></div><p>
Then, create individuals folders that will be accessed in shared mode:</p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><div class="literallayout"><p><span class="command"><strong>maildirmake -s write -f Weekly /usr/local/share/maildirs/notices</strong></span></p></div></div></blockquote></div><p>In this example, the "Weekly" folder is created,
with read/write access to everyone.
Multiple folders can be created in the same maildir, with different access
permissions. Everyone can create a sharable maildir. The access privileges
for individual folders are set by the <code class="option">-s</code> option, and are
implemented using traditional filesystem permissions.</p><p>Use the <code class="option">--add</code> and
<code class="option">--del</code> options to add a sharable maildir to
an existing maildir. Client software that implements this extension will now
know where to find sharable folders:</p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><div class="literallayout"><p><span class="command"><strong>maildirmake --add notices=/usr/local/share/maildirs/notices $HOME/Maildir</strong></span></p></div></div></blockquote></div><p>
<code class="filename">$HOME/Maildir</code> is your main maildir.
The argument to <code class="option">-add</code>
is <em class="replaceable"><code>nick</code></em>=<em class="replaceable"><code>path</code></em>.
<em class="replaceable"><code>nick</code></em> is a nickname for this collection of
sharable folders, and <em class="replaceable"><code>path</code></em> is the location of the
sharable maildir.
All folders in the sharable maildir that you have access to -- such
as "Weekly", in this case, will now be accessible.
Multiple sharable maildirs can be added, by giving each one a unique
<em class="replaceable"><code>nick</code></em>.</p><p>
The <code class="option">--del</code> option "disconnects" the sharable maildir from
the main maildir.</p></div><div class="refsect2"><a id="globalsharedfolders" shape="rect"> </a><h3>GLOBAL SHARED FOLDERS</h3><p>
Normally <code class="option">-add</code> command must be run for every maildir
which needs
to access the sharable maildir. Alternatively the file
<code class="filename">/etc/maildirshared</code> can be created,
to specify a default set of sharable maildirs.
Each line in this file takes the following format:</p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><div class="literallayout"><p><em class="replaceable"><code>nick</code></em><span class="token"><tab></span><em class="replaceable"><code>path</code></em></p></div></div></blockquote></div><p><em class="replaceable"><code>nick</code></em> is a short nickname for
the sharable maildir, <span class="token"><tab></span>
is a single tab character, <em class="replaceable"><code>path</code></em>
is the pathname to the sharable maildir.</p></div><div class="refsect2"><a id="sharedaccess" shape="rect"> </a><h3>ACCESSING SHARED FOLDERS</h3><p>
You may have read or write access to a shared folder.
If you have write
access, you can add messages to the shared folder. You can also delete
messages that you've added.</p><p>Anyone can create a sharable maildir, so if the sharable maildir
is actually created by you, can can delete any message, not just your
own.</p></div></div><div class="refsect1"><a id="converting" shape="rect"> </a><h2>Converting pre-unicode format maildirs</h2><p>
This section is relevant to:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Updating <span class="application">Courier-IMAP</span> to version 5.0, and
later, from prior versions of <span class="application">Courier-IMAP</span>, or:
</p></li><li class="listitem"><p>
Updating <span class="application">SqWebmail</span> to version 6.0, and
later, from prior versions of <span class="application">SqWebmail</span>, or:
</p></li><li class="listitem"><p>
Updating Courier to version 1.0, and
later, from prior versions of Courier.
</p></li></ul></div><p>
These versions have been updated to implement native Unicode
support in several E-mail-related protocols. It is already expected
that updating Internet standards to use native Unicode-formatted
E-mail messages will not be 100% backwards-compatible, in terms of
E-mail client support.
Given that, this major update to Unicode will also introduce some
backwards-incompatible changes to the internal structure of maildirs,
as a major upgrade to simplify Unicode support going forward.
Might as well go through the pain of a major upgrade once.
</p><p>
<span class="command"><strong>maildirmake</strong></span>'s <code class="option">--checkutf8</code> and
<code class="option">--convutf8</code> options are tools to aid in conversion of
existing mailboxes to the new Unicode-based naming standard.
</p><div class="refsect2"><a id="background" shape="rect"> </a><h3>Background</h3><p>
Mail folders in a maildir are hidden subdirectories. For example:
a folder name <span class="quote">“<span class="quote">Mailing list</span>”</span> is a maildir subdirectory
named <code class="filename">$HOME/Maildir/.Mailing list</code>
(<code class="filename">$HOME/Maildir</code> is the main mailbox).
</p><p>
Prior to the unicode update, non-English characters in folder names
used a convention based on the
non-standard <span class="quote">“<span class="quote">modified-UTF7</span>”</span> encoding used by IMAP.
A folder named <span class="quote">“<span class="quote">Résumé</span>”</span> is a maildir subdirectory
named <code class="filename">$HOME/Maildir/.R&AOk-sum&AOk-</code>.
The current versions of Courier,
<span class="application">Courier-IMAP</span>, and SqWebmail,
now creates <code class="filename">$HOME/Maildir/.Résumé</code>
using the <acronym class="acronym">UTF8</acronym> encoding. This appears as plain
<span class="quote">“<span class="quote">.Résumé</span>”</span> (hidden) subdirectory on modern
UTF8-based systems.
</p><p>
Consequently, any existing maildirs with folders that use non-English
names
must be converted as part of updating to the current version of
Courier, <span class="application">Courier-IMAP</span>, and SqWebmail from pre-unicode versions.
This does not happen automatically when updating to the current
version. This must be done manually given the wide variety of individual
mail server configurations that are possible.
</p></div><div class="refsect2"><a id="unicode" shape="rect"> </a><h3>Unicode conversion overview</h3><p>
Updating from pre-unicode versions involves:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Renaming the actual maildir folders,
<code class="filename">$HOME/Maildir/.<em class="replaceable"><code>names</code></em></code>
into unicode names (using <acronym class="acronym">UTF8</acronym>).
</p></li><li class="listitem"><p>
Updating the
<code class="filename">$HOME/Maildir/courierimapsubscribed</code> file,
which is a list of subscribed IMAP folders, if it exists.
</p></li><li class="listitem"><p>
Updating any
<span class="application">maildrop</span>
mail filtering recipes,
<code class="filename">$HOME/.mailfilter</code>, if it exists, to reference
the unicode maildir folders; or updating any custom site mail
filtering engine that delivers to maildir folders, to reference
the correct subdirectory names.
</p></li></ul></div></div><div class="refsect2"><a id="unicodesteps" shape="rect"> </a><h3>Unicode conversion steps</h3><p>
The <code class="option">--checkutf8</code> and
<code class="option">--convutf8</code> options to
<span class="command"><strong>maildirmake</strong></span> convert a single maildir to the new
unicode format:
</p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><pre class="programlisting" xml:space="preserve">
$ ./maildirmake --checkutf8 ~/Maildir ~/.mailfilter
Checking /home/mrsam/Maildir:
Mail filter to INBOX.R&AOk-sum&AOk- updated to INBOX.Résumé
Subscription to INBOX.R&AOk-sum&AOk- changed to INBOX.Résumé
Rename INBOX.R&AOk-sum&AOk- to INBOX.Résumé
Verified /home/mrsam/Maildir/courierimapsubscribed
Verified /home/mrsam/.mailfilter
$ ./maildirmake --convutf8 ~/Maildir ~/.mailfilter
Checking /home/mrsam/Maildir:
Mail filter to INBOX.R&AOk-sum&AOk- updated to INBOX.Résumé
Subscription to INBOX.R&AOk-sum&AOk- changed to INBOX.Résumé
Rename INBOX.R&AOk-sum&AOk- to INBOX.Résumé
Updating /home/mrsam/Maildir/courierimapsubscribed
Updating /home/mrsam/.mailfilter</pre></div></blockquote></div><p>
<code class="option">--checkutf8</code> goes through the motions of converting
a single maildir to Unicode, but without making any actual changes.
<code class="option">--convutf8</code> does the conversion for real.
The first required parameter is the maildir to convert. The
second parameter is optional, and specifies the corresponding
<span class="command"><strong>maildrop</strong></span> filtering recipe,
<span class="emphasis"><em>but only if <span class="application">SqWebMail</span></em></span>
generates the mail filtering recipes.
<span class="application">SqWebMail</span>'s mail filtering recipes are
parsable, and can be automatically-converted.
Non-<span class="application">SqWebMail</span>-generated
<code class="filename">.mailfilter</code>s cannot be converted automatically.
The second parameter must be omitted, and the mail filtering recipe
must be converted by hand.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
All this work is only needed if maildirs have folders with
non-English names. Ignore everything you've just read if all
folder names are English-only.
<code class="option">--checkutf8</code> and
<code class="option">--convutf8</code> will not do anything, and nothing
needs to be done.
</p></div><p>
To convert all mailboxes to Unicode all at once:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A shell script needs to run the <code class="option">--checkutf8</code>
option for every mailbox. A list of all accounts' maildirs
needs to be prepared in advance, together with the corresponding
<code class="filename">.mailfilter</code>s (where appropriate).
courier-authlib's <span class="command"><strong>authenumerate</strong></span> command is usually
a good starting point.
It's ok to explicitly specify each mailbox's
<code class="filename">.mailfilter</code>, when using
<span class="application">SqWebMail</span> even if a particular
mailbox does not use it. It will be ignored.
The list of all accounts' maildirs gets converted to a shell
script that runs <span class="command"><strong>maildirmake</strong></span> with the
<code class="option">--checkutf8</code> option. The script should report
any maildir whose <code class="option">--checkutf8</code> option reports
an error, and
<span class="command"><strong>maildirmake</strong></span> exits with a non-zero status.
</p><p>
It is safe to run <code class="option">--checkutf8</code> without shutting
down your mail server. A non-zero exit from
<code class="option">--checkutf8</code> indicates a problem (see below)
for a particular maildir.
</p></li><li class="listitem"><p>
Once <code class="option">--checkutf8</code> does not find any problems
with any mailbox, shut down the mail server, run
<code class="option">--checkutf8</code> one more time for all mailboxes,
then if everything goes well, upgrade
<span class="application">Courier</span>,
<span class="application">Courier-IMAP</span>, or
<span class="application">SqWebMail</span> and
run
<code class="option">--convutf8</code> on every mailbox before restarting
the server.
</p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
<code class="option">--convutf8</code> is a one-shot deal. Do not run
<code class="option">--convutf8</code> a second time after it successfully
converted a maildir. In nearly all cases nothing will happen,
but there are rare edge cases where some folder names may
get garbled, or it fails completely.
</p></div></div><div class="refsect2"><a id="unicodeconvproblems" shape="rect"> </a><h3>Resolving unicode conversion problems</h3><p>
The only likely problems that might be encountered is the fall-out
from buggy IMAP clients that did not follow the pre-Unicode naming
convention for non-Latin folder names. The customized IMAP
<span class="quote">“<span class="quote">modified-UTF7</span>”</span> encoding convention for non-Latin
folder names is mostly an IMAP client convention, and the
pre-Unicode version of <span class="application">Courier-IMAP</span> did
not enforce it. The server took the name from the IMAP client,
as is.
</p><p>
Unicode conversion (<code class="option">--checkutf8</code> or
<code class="option">--convutf8</code>) fails if it finds a folder name that
does not correctly use IMAP's
<span class="quote">“<span class="quote">modified-UTF7</span>”</span> encoding. This can only be resolved
manually, by renaming the folder. This may also involve manually
editing <code class="filename">courierimapsubscribed</code> and
<code class="filename">.mailfilter</code> if they exist. The bad folder name
should be removed from
<code class="filename">courierimapsubscribed</code>. For
<code class="filename">.mailfilter</code> it is sufficient to remove only
the comments that precede the actual <span class="command"><strong>maildrop</strong></span> rule,
and <code class="option">--convutf8</code> will remove the entire rule, by itself.
<code class="option">--convutf8</code> actually reads only the machine-parsable
comments in <span class="command"><strong>SqWebMail</strong></span>-generated
<code class="filename">.mailfilter</code> (plus a few other things in the
file), and replaces the
<code class="filename">.mailfilter</code> with the Unicode version based
solely on the parsed data.
</p></div><div class="refsect2"><a id="unicodeafter" shape="rect"> </a><h3>After the Unicode conversion</h3><p>
The current, Unicode version of <span class="application">Courier-IMAP</span>
supports both Unicode and non-Unicode
IMAP clients; however unlike the pre-Unicode version,
<span class="application">Courier-IMAP</span> rejects requests from
non-Unicode IMAP clients to use or create folders that are not
properly encoded.
</p><p>
Encountering a bad folder during conversion strongly suggests the
presence of an IMAP client that does not correctly encode non-English
folder names. Such an IMAP client will likely have problems after
the conversion.
</p></div></div><div class="refsect1"><a id="seealso" shape="rect"> </a><h2>SEE ALSO</h2><p>
<a class="ulink" href="maildir.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildir</span>(5)</span></a>,
<a class="ulink" href="maildiracl.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildiracl</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>,
<a class="ulink" href="maildirwatch.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildirwatch</span>(1)</span></a>,
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>,
<a class="ulink" href="maildirquota.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildirquota</span>(7)</span></a>,
<a class="ulink" href="deliverquota.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">deliverquota</span>(8)</span></a>,
<a class="ulink" href="maildropfilter.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildropfilter</span>(7)</span></a>.
</p></div></div></body></html>