1MAILDIRMAKE(1)              Double Precision, Inc.              MAILDIRMAKE(1)
2
3
4

NAME

6       maildirmake - create maildirs and maildir folders
7

SYNOPSIS

9       maildirmake [options...] {maildir}
10

DESCRIPTION

12       The maildirmake command creates maildirs, and maildir folders and
13       performs some routine maintenance on them. This documentation describes
14       the maildirmake command from the Courier mail server, which creates an
15       extended form of maildirs that implements additional extensions beyond
16       the basic maildir properties that were first implemented in the Qmail
17       mail server.
18

OPTIONS

20       -S
21           create a "sharable" maildir. A sharable maildir has slightly
22           different permissions which allows creation of publicly-shared
23           folders.
24
25       -q quota
26           install a quota on the maildir. See maildirquota(7)[1] for more
27           information. The specified maildir gets automatically created if it
28           does not exist; otherwise the existing maildir's quota gets
29           updated.
30
31       -f folder
32           do not create a maildir, but create a folder in an existing
33           maildir.
34
35       -F folder
36           Like the -f option, except that the folder's name is given using
37           the system locale's character set. Non-Latin characters in the
38           folder's name must be given to the -f option using IMAP's UTF8
39           encoding. The -F option takes the folder name specified using the
40           console's character set.
41
42       -s mode
43           create a publicly accessible folder in an existing sharable
44           maildir. First, use the -S option to create a sharable maildir.
45           Then, run maildirmake again with the -s option to create publicly
46           accessible folders.  mode is a comma-separated list of the
47           following keywords: read - readonly folder, only you can write
48           messages to this folder; write - anyone can read and write messages
49           to this folder; group - only allow members of your own system group
50           to access messages in this folder (instead of everyone).
51
52       --add name=pathname, --del name
53           create or delete the directories and links needed to access shared
54           folders. See below for more information.
55
56       --checkutf8 maildir maildirfilter
57           Perform a sanity check to verify that a pre-unicode format maildir
58           can be converted to a unicode-format maildir. See “Converting
59           pre-unicode format maildirs”, below, for more information.
60
61       --convutf8 maildir maildirfilter
62           Convert a pre-unicode format maildir can be converted to a
63           unicode-format maildir. See “Converting pre-unicode format
64           maildirs”, below, for more information.
65
66   FOLDERS
67       This maildirmake command supports enhanced maildirs that contain
68       folders.
69
70       By itself, maildirmake makes a new subdirectory maildir, and creates
71       all the necessary structures. The -f option creates a new "folder"
72       within an existing maildir.  maildir must already exist, and the
73       maildirmake command will create a new folder in the maildir.
74
75       Folders are simply subdirectories inside the main maildir whose names
76       start with a period, and which are themselves maildirs. For example,
77       the command "maildirmake -f Drafts mail/Maildir" creates
78       mail/Maildir/.Drafts, that has the usual tmp, new and cur. You MUST use
79       the -f option, instead of specifying mail/Maildir/.Drafts directly, in
80       order to correctly initialize certain enhanced maildir features.
81
82       Folders cannot be created directly within other folders. Running
83       maildirmake -f Urgent mail/Maildir/.Drafts will not work. Instead, the
84       period character is designated as a hierarchy separator, run
85       maildirmake -f Drafts.Urgent mail/Maildir instead. This creates
86       mail/Maildir/.Drafts.Urgent, and all mail software that supports
87       enhanced maildirs will interpret it as a subfolder Urgent of the Drafts
88       folder.
89
90   SHARED FOLDERS
91       This is another extension to the Maildir format that allows folders to
92       be shared between multiple clients.
93
94           Note
95           The Courier IMAP server implements two types of shared folders:
96           filesystem permission-based shared folders, as well as virtual
97           shared folders based on IMAP access control lists. Use the
98           maildirmake command to implement shared folders based on filesystem
99           permissions. The maildiracl(1)[2] command manages access control
100           lists, which are used by virtual shared folders.
101
102           See the Courier IMAP server documentation for more information.
103
104       First, you need to create a collection of sharable folders, as a
105       separate maildir:
106
107           maildirmake -S /usr/local/share/maildirs/notices
108
109       Then, create individuals folders that will be accessed in shared mode:
110
111           maildirmake -s write -f Weekly /usr/local/share/maildirs/notices
112
113       In this example, the "Weekly" folder is created, with read/write access
114       to everyone. Multiple folders can be created in the same maildir, with
115       different access permissions. Everyone can create a sharable maildir.
116       The access privileges for individual folders are set by the -s option,
117       and are implemented using traditional filesystem permissions.
118
119       Use the --add and --del options to add a sharable maildir to an
120       existing maildir. Client software that implements this extension will
121       now know where to find sharable folders:
122
123           maildirmake --add notices=/usr/local/share/maildirs/notices $HOME/Maildir
124
125       $HOME/Maildir is your main maildir. The argument to -add is nick=path.
126       nick is a nickname for this collection of sharable folders, and path is
127       the location of the sharable maildir. All folders in the sharable
128       maildir that you have access to -- such as "Weekly", in this case, will
129       now be accessible. Multiple sharable maildirs can be added, by giving
130       each one a unique nick.
131
132       The --del option "disconnects" the sharable maildir from the main
133       maildir.
134
135   GLOBAL SHARED FOLDERS
136       Normally -add command must be run for every maildir which needs to
137       access the sharable maildir. Alternatively the file /etc/maildirshared
138       can be created, to specify a default set of sharable maildirs. Each
139       line in this file takes the following format:
140
141           nick<tab>path
142
143       nick is a short nickname for the sharable maildir, <tab> is a single
144       tab character, path is the pathname to the sharable maildir.
145
146   ACCESSING SHARED FOLDERS
147       You may have read or write access to a shared folder. If you have write
148       access, you can add messages to the shared folder. You can also delete
149       messages that you've added.
150
151       Anyone can create a sharable maildir, so if the sharable maildir is
152       actually created by you, can can delete any message, not just your own.
153

CONVERTING PRE-UNICODE FORMAT MAILDIRS

155       This section is relevant to:
156
157       ·   Updating Courier-IMAP to version 5.0, and later, from prior
158           versions of Courier-IMAP, or:
159
160       ·   Updating SqWebmail to version 6.0, and later, from prior versions
161           of SqWebmail, or:
162
163       ·   Updating Courier to version 1.0, and later, from prior versions of
164           Courier.
165
166       These versions have been updated to implement native Unicode support in
167       several E-mail-related protocols. It is already expected that updating
168       Internet standards to use native Unicode-formatted E-mail messages will
169       not be 100% backwards-compatible, in terms of E-mail client support.
170       Given that, this major update to Unicode will also introduce some
171       backwards-incompatible changes to the internal structure of maildirs,
172       as a major upgrade to simplify Unicode support going forward. Might as
173       well go through the pain of a major upgrade once.
174
175       maildirmake's --checkutf8 and --convutf8 options are tools to aid in
176       conversion of existing mailboxes to the new Unicode-based naming
177       standard.
178
179   Background
180       Mail folders in a maildir are hidden subdirectories. For example: a
181       folder name “Mailing list” is a maildir subdirectory named
182       $HOME/Maildir/.Mailing list ($HOME/Maildir is the main mailbox).
183
184       Prior to the unicode update, non-English characters in folder names
185       used a convention based on the non-standard “modified-UTF7” encoding
186       used by IMAP. A folder named “Résumé” is a maildir subdirectory named
187       $HOME/Maildir/.R&AOk-sum&AOk-. The current versions of Courier,
188       Courier-IMAP, and SqWebmail, now creates $HOME/Maildir/.Résumé using
189       the UTF8 encoding. This appears as plain “.Résumé” (hidden)
190       subdirectory on modern UTF8-based systems.
191
192       Consequently, any existing maildirs with folders that use non-English
193       names must be converted as part of updating to the current version of
194       Courier, Courier-IMAP, and SqWebmail from pre-unicode versions. This
195       does not happen automatically when updating to the current version.
196       This must be done manually given the wide variety of individual mail
197       server configurations that are possible.
198
199   Unicode conversion overview
200       Updating from pre-unicode versions involves:
201
202       ·   Renaming the actual maildir folders, $HOME/Maildir/.names into
203           unicode names (using UTF8).
204
205       ·   Updating the $HOME/Maildir/courierimapsubscribed file, which is a
206           list of subscribed IMAP folders, if it exists.
207
208       ·   Updating any maildrop mail filtering recipes, $HOME/.mailfilter, if
209           it exists, to reference the unicode maildir folders; or updating
210           any custom site mail filtering engine that delivers to maildir
211           folders, to reference the correct subdirectory names.
212
213   Unicode conversion steps
214       The --checkutf8 and --convutf8 options to maildirmake convert a single
215       maildir to the new unicode format:
216
217           $ ./maildirmake --checkutf8 ~/Maildir ~/.mailfilter
218           Checking /home/mrsam/Maildir:
219           Mail filter to INBOX.R&AOk-sum&AOk- updated to INBOX.Résumé
220           Subscription to INBOX.R&AOk-sum&AOk- changed to INBOX.Résumé
221           Rename INBOX.R&AOk-sum&AOk- to INBOX.Résumé
222           Verified /home/mrsam/Maildir/courierimapsubscribed
223           Verified /home/mrsam/.mailfilter
224           $ ./maildirmake --convutf8 ~/Maildir ~/.mailfilter
225           Checking /home/mrsam/Maildir:
226           Mail filter to INBOX.R&AOk-sum&AOk- updated to INBOX.Résumé
227           Subscription to INBOX.R&AOk-sum&AOk- changed to INBOX.Résumé
228           Rename INBOX.R&AOk-sum&AOk- to INBOX.Résumé
229           Updating /home/mrsam/Maildir/courierimapsubscribed
230           Updating /home/mrsam/.mailfilter
231
232       --checkutf8 goes through the motions of converting a single maildir to
233       Unicode, but without making any actual changes.  --convutf8 does the
234       conversion for real. The first required parameter is the maildir to
235       convert. The second parameter is optional, and specifies the
236       corresponding maildrop filtering recipe, but only if SqWebMail
237       generates the mail filtering recipes.  SqWebMail's mail filtering
238       recipes are parsable, and can be automatically-converted.
239       Non-SqWebMail-generated .mailfilters cannot be converted automatically.
240       The second parameter must be omitted, and the mail filtering recipe
241       must be converted by hand.
242
243           Note
244           All this work is only needed if maildirs have folders with
245           non-English names. Ignore everything you've just read if all folder
246           names are English-only.  --checkutf8 and --convutf8 will not do
247           anything, and nothing needs to be done.
248
249       To convert all mailboxes to Unicode all at once:
250
251       ·   A shell script needs to run the --checkutf8 option for every
252           mailbox. A list of all accounts' maildirs needs to be prepared in
253           advance, together with the corresponding .mailfilters (where
254           appropriate). courier-authlib's authenumerate command is usually a
255           good starting point. It's ok to explicitly specify each mailbox's
256           .mailfilter, when using SqWebMail even if a particular mailbox does
257           not use it. It will be ignored. The list of all accounts' maildirs
258           gets converted to a shell script that runs maildirmake with the
259           --checkutf8 option. The script should report any maildir whose
260           --checkutf8 option reports an error, and maildirmake exits with a
261           non-zero status.
262
263           It is safe to run --checkutf8 without shutting down your mail
264           server. A non-zero exit from --checkutf8 indicates a problem (see
265           below) for a particular maildir.
266
267       ·   Once --checkutf8 does not find any problems with any mailbox, shut
268           down the mail server, run --checkutf8 one more time for all
269           mailboxes, then if everything goes well, upgrade Courier,
270           Courier-IMAP, or SqWebMail and run --convutf8 on every mailbox
271           before restarting the server.
272
273           Note
274           --convutf8 is a one-shot deal. Do not run --convutf8 a second time
275           after it successfully converted a maildir. In nearly all cases
276           nothing will happen, but there are rare edge cases where some
277           folder names may get garbled, or it fails completely.
278
279   Resolving unicode conversion problems
280       The only likely problems that might be encountered is the fall-out from
281       buggy IMAP clients that did not follow the pre-Unicode naming
282       convention for non-Latin folder names. The customized IMAP
283       “modified-UTF7” encoding convention for non-Latin folder names is
284       mostly an IMAP client convention, and the pre-Unicode version of
285       Courier-IMAP did not enforce it. The server took the name from the IMAP
286       client, as is.
287
288       Unicode conversion (--checkutf8 or --convutf8) fails if it finds a
289       folder name that does not correctly use IMAP's “modified-UTF7”
290       encoding. This can only be resolved manually, by renaming the folder.
291       This may also involve manually editing courierimapsubscribed and
292       .mailfilter if they exist. The bad folder name should be removed from
293       courierimapsubscribed. For .mailfilter it is sufficient to remove only
294       the comments that precede the actual maildrop rule, and --convutf8 will
295       remove the entire rule, by itself.  --convutf8 actually reads only the
296       machine-parsable comments in SqWebMail-generated .mailfilter (plus a
297       few other things in the file), and replaces the .mailfilter with the
298       Unicode version based solely on the parsed data.
299
300   After the Unicode conversion
301       The current, Unicode version of Courier-IMAP supports both Unicode and
302       non-Unicode IMAP clients; however unlike the pre-Unicode version,
303       Courier-IMAP rejects requests from non-Unicode IMAP clients to use or
304       create folders that are not properly encoded.
305
306       Encountering a bad folder during conversion strongly suggests the
307       presence of an IMAP client that does not correctly encode non-English
308       folder names. Such an IMAP client will likely have problems after the
309       conversion.
310

SEE ALSO

312       maildir(5)[3], maildiracl(1)[2], maildirkw(1)[4], maildrop(1)[5],
313       maildirquota(7)[1], deliverquota(8)[6], maildropfilter(7)[7].
314

AUTHOR

316       Sam Varshavchik
317           Author
318

NOTES

320        1. maildirquota(7)
321           http://www.courier-mta.org/maildirquota.html
322
323        2. maildiracl(1)
324           http://www.courier-mta.org/maildiracl.html
325
326        3. maildir(5)
327           http://www.courier-mta.org/maildir.html
328
329        4. maildirkw(1)
330           http://www.courier-mta.org/maildirkw.html
331
332        5. maildrop(1)
333           http://www.courier-mta.org/maildrop.html
334
335        6. deliverquota(8)
336           http://www.courier-mta.org/deliverquota.html
337
338        7. maildropfilter(7)
339           http://www.courier-mta.org/maildropfilter.html
340
341
342
343Courier Mail Server               09/24/2019                    MAILDIRMAKE(1)
Impressum