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. quota may be:
30 ####S
32 Specifies the quota in the total number of bytes for all
33 messages. “10000000S” specifies a quota of ten million bytes.
34 ####C
36 Specifies the quota in the total number of messages in the
37 maildir. “10000S” specifies a quota of ten thousand messages.
38 -f folder
40 do not create a maildir, but create a folder in an existing
41 maildir.
42 -F folder
44 Like the -f option, except that the folder's name is given using
45 the system locale's character set. Non-Latin characters in the
46 folder's name must be given to the -f option using IMAP's UTF8
47 encoding. The -F option takes the folder name specified using the
48 console's character set.
49 -s mode
51 create a publicly accessible folder in an existing sharable
52 maildir. First, use the -S option to create a sharable maildir.
53 Then, run maildirmake again with the -s option to create publicly
54 accessible folders. mode is a comma-separated list of the
55 following keywords: read - readonly folder, only you can write
56 messages to this folder; write - anyone can read and write messages
57 to this folder; group - only allow members of your own system group
58 to access messages in this folder (instead of everyone).
59 --add name=pathname, --del name
61 create or delete the directories and links needed to access shared
62 folders. See below for more information.
63 --checkutf8 maildir maildirfilter
65 Perform a sanity check to verify that a pre-unicode format maildir
66 can be converted to a unicode-format maildir. See “Converting
67 pre-unicode format maildirs”, below, for more information.
68 --convutf8 maildir maildirfilter
70 Convert a pre-unicode format maildir can be converted to a
71 unicode-format maildir. See “Converting pre-unicode format
72 maildirs”, below, for more information.
73 FOLDERS
75 This maildirmake command supports enhanced maildirs that contain
76 folders.
77 By itself, maildirmake makes a new subdirectory maildir, and creates
79 all the necessary structures. The -f option creates a new "folder"
80 within an existing maildir. maildir must already exist, and the
81 maildirmake command will create a new folder in the maildir.
82 Folders are simply subdirectories inside the main maildir whose names
84 start with a period, and which are themselves maildirs. For example,
85 the command "maildirmake -f Drafts mail/Maildir" creates
86 mail/Maildir/.Drafts, that has the usual tmp, new and cur. You MUST use
87 the -f option, instead of specifying mail/Maildir/.Drafts directly, in
88 order to correctly initialize certain enhanced maildir features.
89 Folders cannot be created directly within other folders. Running
91 maildirmake -f Urgent mail/Maildir/.Drafts will not work. Instead, the
92 period character is designated as a hierarchy separator, run
93 maildirmake -f Drafts.Urgent mail/Maildir instead. This creates
94 mail/Maildir/.Drafts.Urgent, and all mail software that supports
95 enhanced maildirs will interpret it as a subfolder Urgent of the Drafts
96 folder.
97 SHARED FOLDERS
99 This is another extension to the Maildir format that allows folders to
100 be shared between multiple clients.
101 Note
103 The Courier IMAP server implements two types of shared folders:
104 filesystem permission-based shared folders, as well as virtual
105 shared folders based on IMAP access control lists. Use the
106 maildirmake command to implement shared folders based on filesystem
107 permissions. The maildiracl(1)[2] command manages access control
108 lists, which are used by virtual shared folders.
109 See the Courier IMAP server documentation for more information.
111 First, you need to create a collection of sharable folders, as a
113 separate maildir:
114 maildirmake -S /usr/local/share/maildirs/notices
116 Then, create individuals folders that will be accessed in shared mode:
118 maildirmake -s write -f Weekly /usr/local/share/maildirs/notices
120 In this example, the "Weekly" folder is created, with read/write access
122 to everyone. Multiple folders can be created in the same maildir, with
123 different access permissions. Everyone can create a sharable maildir.
124 The access privileges for individual folders are set by the -s option,
125 and are implemented using traditional filesystem permissions.
126 Use the --add and --del options to add a sharable maildir to an
128 existing maildir. Client software that implements this extension will
129 now know where to find sharable folders:
130 maildirmake --add notices=/usr/local/share/maildirs/notices $HOME/Maildir
132 $HOME/Maildir is your main maildir. The argument to -add is nick=path.
134 nick is a nickname for this collection of sharable folders, and path is
135 the location of the sharable maildir. All folders in the sharable
136 maildir that you have access to -- such as "Weekly", in this case, will
137 now be accessible. Multiple sharable maildirs can be added, by giving
138 each one a unique nick.
139 The --del option "disconnects" the sharable maildir from the main
141 maildir.
142 GLOBAL SHARED FOLDERS
144 Normally -add command must be run for every maildir which needs to
145 access the sharable maildir. Alternatively the file /etc/maildirshared
146 can be created, to specify a default set of sharable maildirs. Each
147 line in this file takes the following format:
148 nick<tab>path
150 nick is a short nickname for the sharable maildir, <tab> is a single
152 tab character, path is the pathname to the sharable maildir.
153 ACCESSING SHARED FOLDERS
155 You may have read or write access to a shared folder. If you have write
156 access, you can add messages to the shared folder. You can also delete
157 messages that you've added.
158 Anyone can create a sharable maildir, so if the sharable maildir is
160 actually created by you, can can delete any message, not just your own.
161
163 This section is relevant to:
164 • Updating Courier-IMAP to version 5.0, and later, from prior
166 versions of Courier-IMAP, or:
167 • Updating SqWebmail to version 6.0, and later, from prior versions
169 of SqWebmail, or:
170 • Updating Courier to version 1.0, and later, from prior versions of
172 Courier.
173 These versions have been updated to implement native Unicode support in
175 several E-mail-related protocols. It is already expected that updating
176 Internet standards to use native Unicode-formatted E-mail messages will
177 not be 100% backwards-compatible, in terms of E-mail client support.
178 Given that, this major update to Unicode will also introduce some
179 backwards-incompatible changes to the internal structure of maildirs,
180 as a major upgrade to simplify Unicode support going forward. Might as
181 well go through the pain of a major upgrade once.
182 maildirmake's --checkutf8 and --convutf8 options are tools to aid in
184 conversion of existing mailboxes to the new Unicode-based naming
185 standard.
186 Background
188 Mail folders in a maildir are hidden subdirectories. For example: a
189 folder name “Mailing list” is a maildir subdirectory named
190 $HOME/Maildir/.Mailing list ($HOME/Maildir is the main mailbox).
191 Prior to the unicode update, non-English characters in folder names
193 used a convention based on the non-standard “modified-UTF7” encoding
194 used by IMAP. A folder named “Résumé” is a maildir subdirectory named
195 $HOME/Maildir/.R&AOk-sum&AOk-. The current versions of Courier,
196 Courier-IMAP, and SqWebmail, now creates $HOME/Maildir/.Résumé using
197 the UTF8 encoding. This appears as plain “.Résumé” (hidden)
198 subdirectory on modern UTF8-based systems.
199 Consequently, any existing maildirs with folders that use non-English
201 names must be converted as part of updating to the current version of
202 Courier, Courier-IMAP, and SqWebmail from pre-unicode versions. This
203 does not happen automatically when updating to the current version.
204 This must be done manually given the wide variety of individual mail
205 server configurations that are possible.
206 Unicode conversion overview
208 Updating from pre-unicode versions involves:
209 • Renaming the actual maildir folders, $HOME/Maildir/.names into
211 unicode names (using UTF8).
212 • Updating the $HOME/Maildir/courierimapsubscribed file, which is a
214 list of subscribed IMAP folders, if it exists.
215 • Updating any maildrop mail filtering recipes, $HOME/.mailfilter, if
217 it exists, to reference the unicode maildir folders; or updating
218 any custom site mail filtering engine that delivers to maildir
219 folders, to reference the correct subdirectory names.
220 Unicode conversion steps
222 The --checkutf8 and --convutf8 options to maildirmake convert a single
223 maildir to the new unicode format:
224 $ ./maildirmake --checkutf8 ~/Maildir ~/.mailfilter
226 Checking /home/mrsam/Maildir:
227 Mail filter to INBOX.R&AOk-sum&AOk- updated to INBOX.Résumé
228 Subscription to INBOX.R&AOk-sum&AOk- changed to INBOX.Résumé
229 Rename INBOX.R&AOk-sum&AOk- to INBOX.Résumé
230 Verified /home/mrsam/Maildir/courierimapsubscribed
231 Verified /home/mrsam/.mailfilter
232 $ ./maildirmake --convutf8 ~/Maildir ~/.mailfilter
233 Checking /home/mrsam/Maildir:
234 Mail filter to INBOX.R&AOk-sum&AOk- updated to INBOX.Résumé
235 Subscription to INBOX.R&AOk-sum&AOk- changed to INBOX.Résumé
236 Rename INBOX.R&AOk-sum&AOk- to INBOX.Résumé
237 Updating /home/mrsam/Maildir/courierimapsubscribed
238 Updating /home/mrsam/.mailfilter
239 --checkutf8 goes through the motions of converting a single maildir to
241 Unicode, but without making any actual changes. --convutf8 does the
242 conversion for real. The first required parameter is the maildir to
243 convert. The second parameter is optional, and specifies the
244 corresponding maildrop filtering recipe, but only if SqWebMail
245 generates the mail filtering recipes. SqWebMail's mail filtering
246 recipes are parsable, and can be automatically-converted.
247 Non-SqWebMail-generated .mailfilters cannot be converted automatically.
248 The second parameter must be omitted, and the mail filtering recipe
249 must be converted by hand.
250 Note
252 All this work is only needed if maildirs have folders with
253 non-English names. Ignore everything you've just read if all folder
254 names are English-only. --checkutf8 and --convutf8 will not do
255 anything, and nothing needs to be done.
256 To convert all mailboxes to Unicode all at once:
258 • A shell script needs to run the --checkutf8 option for every
260 mailbox. A list of all accounts' maildirs needs to be prepared in
261 advance, together with the corresponding .mailfilters (where
262 appropriate). courier-authlib's authenumerate command is usually a
263 good starting point. It's ok to explicitly specify each mailbox's
264 .mailfilter, when using SqWebMail even if a particular mailbox does
265 not use it. It will be ignored. The list of all accounts' maildirs
266 gets converted to a shell script that runs maildirmake with the
267 --checkutf8 option. The script should report any maildir whose
268 --checkutf8 option reports an error, and maildirmake exits with a
269 non-zero status.
270 It is safe to run --checkutf8 without shutting down your mail
272 server. A non-zero exit from --checkutf8 indicates a problem (see
273 below) for a particular maildir.
274 • Once --checkutf8 does not find any problems with any mailbox, shut
276 down the mail server, run --checkutf8 one more time for all
277 mailboxes, then if everything goes well, upgrade Courier,
278 Courier-IMAP, or SqWebMail and run --convutf8 on every mailbox
279 before restarting the server.
280 Note
282 --convutf8 is a one-shot deal. Do not run --convutf8 a second time
283 after it successfully converted a maildir. In nearly all cases
284 nothing will happen, but there are rare edge cases where some
285 folder names may get garbled, or it fails completely.
286 Resolving unicode conversion problems
288 The only likely problems that might be encountered is the fall-out from
289 buggy IMAP clients that did not follow the pre-Unicode naming
290 convention for non-Latin folder names. The customized IMAP
291 “modified-UTF7” encoding convention for non-Latin folder names is
292 mostly an IMAP client convention, and the pre-Unicode version of
293 Courier-IMAP did not enforce it. The server took the name from the IMAP
294 client, as is.
295 Unicode conversion (--checkutf8 or --convutf8) fails if it finds a
297 folder name that does not correctly use IMAP's “modified-UTF7”
298 encoding. This can only be resolved manually, by renaming the folder.
299 This may also involve manually editing courierimapsubscribed and
300 .mailfilter if they exist. The bad folder name should be removed from
301 courierimapsubscribed. For .mailfilter it is sufficient to remove only
302 the comments that precede the actual maildrop rule, and --convutf8 will
303 remove the entire rule, by itself. --convutf8 actually reads only the
304 machine-parsable comments in SqWebMail-generated .mailfilter (plus a
305 few other things in the file), and replaces the .mailfilter with the
306 Unicode version based solely on the parsed data.
307 After the Unicode conversion
309 The current, Unicode version of Courier-IMAP supports both Unicode and
310 non-Unicode IMAP clients; however unlike the pre-Unicode version,
311 Courier-IMAP rejects requests from non-Unicode IMAP clients to use or
312 create folders that are not properly encoded.
313 Encountering a bad folder during conversion strongly suggests the
315 presence of an IMAP client that does not correctly encode non-English
316 folder names. Such an IMAP client will likely have problems after the
317 conversion.
318
320 maildir(5)[3], maildiracl(1)[2], maildirkw(1)[4], maildirwatch(1)[5],
321 maildrop(1)[6], maildirquota(7)[1], deliverquota(8)[7],
322 maildropfilter(7)[8].
323
325 Sam Varshavchik
326 Author
327
329 1. maildirquota(7)
330 http://www.courier-mta.org/maildirquota.html
331 2. maildiracl(1)
333 http://www.courier-mta.org/maildiracl.html
334 3. maildir(5)
336 http://www.courier-mta.org/maildir.html
337 4. maildirkw(1)
339 http://www.courier-mta.org/maildirkw.html
340 5. maildirwatch(1)
342 http://www.courier-mta.org/maildirwatch.html
343 6. maildrop(1)
345 http://www.courier-mta.org/maildrop.html
346 7. deliverquota(8)
348 http://www.courier-mta.org/deliverquota.html
349 8. maildropfilter(7)
351 http://www.courier-mta.org/maildropfilter.html
352Courier Mail Server 04/08/2022 MAILDIRMAKE(1)