1MAILDIRMAKE(1) Double Precision, Inc. MAILDIRMAKE(1)
2
6 maildirmake - create maildirs and maildir folders
7
9 maildirmake [options...] {maildir}
10
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
20 -S
21 create a "sharable" maildir. A sharable maildir has slightly
22 different permissions which allows creation of publicly-shared
23 folders.
24 -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 -f folder
32 do not create a maildir, but create a folder in an existing
33 maildir.
34 -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 -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 --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 --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 --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 FOLDERS
67 This maildirmake command supports enhanced maildirs that contain
68 folders.
69 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 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 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 SHARED FOLDERS
91 This is another extension to the Maildir format that allows folders to
92 be shared between multiple clients.
93 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 See the Courier IMAP server documentation for more information.
103 First, you need to create a collection of sharable folders, as a
105 separate maildir:
106 maildirmake -S /usr/local/share/maildirs/notices
108 Then, create individuals folders that will be accessed in shared mode:
110 maildirmake -s write -f Weekly /usr/local/share/maildirs/notices
112 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 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 maildirmake --add notices=/usr/local/share/maildirs/notices $HOME/Maildir
124 $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 The --del option "disconnects" the sharable maildir from the main
133 maildir.
134 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 nick<tab>path
142 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 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 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
155 This section is relevant to:
156 · Updating Courier-IMAP to version 5.0, and later, from prior
158 versions of Courier-IMAP, or:
159 · Updating SqWebmail to version 6.0, and later, from prior versions
161 of SqWebmail, or:
162 · Updating Courier to version 1.0, and later, from prior versions of
164 Courier.
165 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 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 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 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 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 Unicode conversion overview
200 Updating from pre-unicode versions involves:
201 · Renaming the actual maildir folders, $HOME/Maildir/.names into
203 unicode names (using UTF8).
204 · Updating the $HOME/Maildir/courierimapsubscribed file, which is a
206 list of subscribed IMAP folders, if it exists.
207 · 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 Unicode conversion steps
214 The --checkutf8 and --convutf8 options to maildirmake convert a single
215 maildir to the new unicode format:
216 $ ./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 --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 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 To convert all mailboxes to Unicode all at once:
250 · 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 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 · 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 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 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 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 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 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
312 maildir(5)[3], maildiracl(1)[2], maildirkw(1)[4], maildrop(1)[5],
313 maildirquota(7)[1], deliverquota(8)[6], maildropfilter(7)[7],
314 http://www.qmail.org/man/man5/maildir.html.
315
317 Sam Varshavchik
318 Author
319
321 1. maildirquota(7)
322 http://www.courier-mta.org/maildirquota.html
323 2. maildiracl(1)
325 http://www.courier-mta.org/maildiracl.html
326 3. maildir(5)
328 http://www.courier-mta.org/maildir.html
329 4. maildirkw(1)
331 http://www.courier-mta.org/maildirkw.html
332 5. maildrop(1)
334 http://www.courier-mta.org/maildrop.html
335 6. deliverquota(8)
337 http://www.courier-mta.org/deliverquota.html
338 7. maildropfilter(7)
340 http://www.courier-mta.org/maildropfilter.html
341Courier Mail Server 09/13/2018 MAILDIRMAKE(1)