Provided by: courier-base_1.0.6-1build2_amd64 bug

NAME

       maildirmake - create maildirs and maildir folders

SYNOPSIS

       maildirmake [options...] {maildir}

DESCRIPTION

       The maildirmake command creates maildirs, and maildir folders and performs some routine
       maintenance on them. This documentation describes the maildirmake command from the Courier
       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.

OPTIONS

       -S
           create a "sharable" maildir. A sharable maildir has slightly different permissions
           which allows creation of publicly-shared folders.

       -q quota
           install a quota on the maildir. See maildirquota(7)[1] for more information. The
           specified maildir gets automatically created if it does not exist; otherwise the
           existing maildir's quota gets updated.

       -f folder
           do not create a maildir, but create a folder in an existing maildir.

       -F folder
           Like the -f 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 -f
           option using IMAP's UTF8 encoding. The -F option takes the folder name specified using
           the console's character set.

       -s mode
           create a publicly accessible folder in an existing sharable maildir. First, use the -S
           option to create a sharable maildir. Then, run maildirmake again with the -s option to
           create publicly accessible folders.  mode is a comma-separated list of the following
           keywords: read - readonly folder, only you can write messages to this folder; write -
           anyone can read and write messages to this folder; group - only allow members of your
           own system group to access messages in this folder (instead of everyone).

       --add name=pathname, --del name
           create or delete the directories and links needed to access shared folders. See below
           for more information.

       --checkutf8 maildir maildirfilter
           Perform a sanity check to verify that a pre-unicode format maildir can be converted to
           a unicode-format maildir. See “Converting pre-unicode format maildirs”, below, for
           more information.

       --convutf8 maildir maildirfilter
           Convert a pre-unicode format maildir can be converted to a unicode-format maildir. See
           “Converting pre-unicode format maildirs”, below, for more information.

   FOLDERS
       This maildirmake command supports enhanced maildirs that contain folders.

       By itself, maildirmake makes a new subdirectory maildir, and creates all the necessary
       structures. The -f option creates a new "folder" within an existing maildir.  maildir must
       already exist, and the maildirmake command will create a new folder in the maildir.

       Folders are simply subdirectories inside the main maildir whose names start with a period,
       and which are themselves maildirs. For example, the command "maildirmake -f Drafts
       mail/Maildir" creates mail/Maildir/.Drafts, that has the usual tmp, new and cur. You MUST
       use the -f option, instead of specifying mail/Maildir/.Drafts directly, in order to
       correctly initialize certain enhanced maildir features.

       Folders cannot be created directly within other folders. Running maildirmake -f Urgent
       mail/Maildir/.Drafts will not work. Instead, the period character is designated as a
       hierarchy separator, run maildirmake -f Drafts.Urgent mail/Maildir instead. This creates
       mail/Maildir/.Drafts.Urgent, and all mail software that supports enhanced maildirs will
       interpret it as a subfolder Urgent of the Drafts folder.

   SHARED FOLDERS
       This is another extension to the Maildir format that allows folders to be shared between
       multiple clients.

           Note
           The Courier 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 maildirmake command to implement shared folders based on
           filesystem permissions. The maildiracl(1)[2] command manages access control lists,
           which are used by virtual shared folders.

           See the Courier IMAP server documentation for more information.

       First, you need to create a collection of sharable folders, as a separate maildir:

           maildirmake -S /usr/local/share/maildirs/notices

       Then, create individuals folders that will be accessed in shared mode:

           maildirmake -s write -f Weekly /usr/local/share/maildirs/notices

       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 -s option, and are implemented using traditional filesystem permissions.

       Use the --add and --del options to add a sharable maildir to an existing maildir. Client
       software that implements this extension will now know where to find sharable folders:

           maildirmake --add notices=/usr/local/share/maildirs/notices $HOME/Maildir

       $HOME/Maildir is your main maildir. The argument to -add is nick=path.  nick is a nickname
       for this collection of sharable folders, and path 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 nick.

       The --del option "disconnects" the sharable maildir from the main maildir.

   GLOBAL SHARED FOLDERS
       Normally -add command must be run for every maildir which needs to access the sharable
       maildir. Alternatively the file /etc/courier/maildirshared can be created, to specify a
       default set of sharable maildirs. Each line in this file takes the following format:

           nick<tab>path

       nick is a short nickname for the sharable maildir, <tab> is a single tab character, path
       is the pathname to the sharable maildir.

   ACCESSING SHARED FOLDERS
       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.

       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.

CONVERTING PRE-UNICODE FORMAT MAILDIRS

       This section is relevant to:

       ·   Updating Courier-IMAP to version 5.0, and later, from prior versions of Courier-IMAP,
           or:

       ·   Updating SqWebmail to version 6.0, and later, from prior versions of SqWebmail, or:

       ·   Updating Courier to version 1.0, and later, from prior versions of Courier.

       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.

       maildirmake's --checkutf8 and --convutf8 options are tools to aid in conversion of
       existing mailboxes to the new Unicode-based naming standard.

   Background
       Mail folders in a maildir are hidden subdirectories. For example: a folder name “Mailing
       list” is a maildir subdirectory named $HOME/Maildir/.Mailing list ($HOME/Maildir is the
       main mailbox).

       Prior to the unicode update, non-English characters in folder names used a convention
       based on the non-standard “modified-UTF7” encoding used by IMAP. A folder named “Résumé”
       is a maildir subdirectory named $HOME/Maildir/.R&AOk-sum&AOk-. The current versions of
       Courier, Courier-IMAP, and SqWebmail, now creates $HOME/Maildir/.Résumé using the UTF8
       encoding. This appears as plain “.Résumé” (hidden) subdirectory on modern UTF8-based
       systems.

       Consequently, any existing maildirs with folders that use non-English names must be
       converted as part of updating to the current version of Courier, Courier-IMAP, 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.

   Unicode conversion overview
       Updating from pre-unicode versions involves:

       ·   Renaming the actual maildir folders, $HOME/Maildir/.names into unicode names (using
           UTF8).

       ·   Updating the $HOME/Maildir/courierimapsubscribed file, which is a list of subscribed
           IMAP folders, if it exists.

       ·   Updating any maildrop mail filtering recipes, $HOME/.mailfilter, 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.

   Unicode conversion steps
       The --checkutf8 and --convutf8 options to maildirmake convert a single maildir to the new
       unicode format:

           $ ./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

       --checkutf8 goes through the motions of converting a single maildir to Unicode, but
       without making any actual changes.  --convutf8 does the conversion for real. The first
       required parameter is the maildir to convert. The second parameter is optional, and
       specifies the corresponding maildrop filtering recipe, but only if SqWebMail generates the
       mail filtering recipes.  SqWebMail's mail filtering recipes are parsable, and can be
       automatically-converted. Non-SqWebMail-generated .mailfilters cannot be converted
       automatically. The second parameter must be omitted, and the mail filtering recipe must be
       converted by hand.

           Note
           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.  --checkutf8 and
           --convutf8 will not do anything, and nothing needs to be done.

       To convert all mailboxes to Unicode all at once:

       ·   A shell script needs to run the --checkutf8 option for every mailbox. A list of all
           accounts' maildirs needs to be prepared in advance, together with the corresponding
           .mailfilters (where appropriate). courier-authlib's authenumerate command is usually a
           good starting point. It's ok to explicitly specify each mailbox's .mailfilter, when
           using SqWebMail 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 maildirmake
           with the --checkutf8 option. The script should report any maildir whose --checkutf8
           option reports an error, and maildirmake exits with a non-zero status.

           It is safe to run --checkutf8 without shutting down your mail server. A non-zero exit
           from --checkutf8 indicates a problem (see below) for a particular maildir.

       ·   Once --checkutf8 does not find any problems with any mailbox, shut down the mail
           server, run --checkutf8 one more time for all mailboxes, then if everything goes well,
           upgrade Courier, Courier-IMAP, or SqWebMail and run --convutf8 on every mailbox before
           restarting the server.

           Note
           --convutf8 is a one-shot deal. Do not run --convutf8 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.

   Resolving unicode conversion problems
       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 “modified-UTF7” encoding convention for non-Latin folder names is mostly
       an IMAP client convention, and the pre-Unicode version of Courier-IMAP did not enforce it.
       The server took the name from the IMAP client, as is.

       Unicode conversion (--checkutf8 or --convutf8) fails if it finds a folder name that does
       not correctly use IMAP's “modified-UTF7” encoding. This can only be resolved manually, by
       renaming the folder. This may also involve manually editing courierimapsubscribed and
       .mailfilter if they exist. The bad folder name should be removed from
       courierimapsubscribed. For .mailfilter it is sufficient to remove only the comments that
       precede the actual maildrop rule, and --convutf8 will remove the entire rule, by itself.
       --convutf8 actually reads only the machine-parsable comments in SqWebMail-generated
       .mailfilter (plus a few other things in the file), and replaces the .mailfilter with the
       Unicode version based solely on the parsed data.

   After the Unicode conversion
       The current, Unicode version of Courier-IMAP supports both Unicode and non-Unicode IMAP
       clients; however unlike the pre-Unicode version, Courier-IMAP rejects requests from
       non-Unicode IMAP clients to use or create folders that are not properly encoded.

       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.

SEE ALSO

       maildir(5)[3], maildiracl(1)[2], maildirkw(1)[4], maildrop(1)[5], maildirquota(7)[1],
       deliverquota(8)[6], maildropfilter(7)[7], http://www.qmail.org/man/man5/maildir.html.

AUTHOR

       Sam Varshavchik
           Author

NOTES

        1. maildirquota(7)
           http://www.courier-mta.org/maildirquota.html

        2. maildiracl(1)
           http://www.courier-mta.org/maildiracl.html

        3. maildir(5)
           http://www.courier-mta.org/maildir.html

        4. maildirkw(1)
           http://www.courier-mta.org/maildirkw.html

        5. maildrop(1)
           http://www.courier-mta.org/maildrop.html

        6. deliverquota(8)
           http://www.courier-mta.org/deliverquota.html

        7. maildropfilter(7)
           http://www.courier-mta.org/maildropfilter.html