<?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 S. Varshavchik.  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">@sysconfdir@/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">&lt;tab&gt;</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">&lt;tab&gt;</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&amp;AOk-sum&amp;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&amp;AOk-sum&amp;AOk- updated to INBOX.Résumé
Subscription to INBOX.R&amp;AOk-sum&amp;AOk- changed to INBOX.Résumé
Rename INBOX.R&amp;AOk-sum&amp;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&amp;AOk-sum&amp;AOk- updated to INBOX.Résumé
Subscription to INBOX.R&amp;AOk-sum&amp;AOk- changed to INBOX.Résumé
Rename INBOX.R&amp;AOk-sum&amp;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>
