Debian Codegraph @

upstream/debian-trixie/man5/maildir.maildrop.5

raw
1 '\" t
2 .\"<!-- Copyright 1998 - 2007 Double Precision, Inc. See COPYING for -->
3 .\"<!-- distribution information. -->
4 .\" Title: maildir
5 .\" Author: Sam Varshavchik
6 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
7 .\" Date: 07/13/2024
8 .\" Manual: Double Precision, Inc.
9 .\" Source: Courier Mail Server
10 .\" Language: English
11 .\"
12 .TH "MAILDIR" "5" "07/13/2024" "Courier Mail Server" "Double Precision, Inc\&."
13 .\" -----------------------------------------------------------------
14 .\" * Define some portability stuff
15 .\" -----------------------------------------------------------------
16 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17 .\" http://bugs.debian.org/507673
18 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
19 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20 .ie \n(.g .ds Aq \(aq
21 .el .ds Aq '
22 .\" -----------------------------------------------------------------
23 .\" * set default formatting
24 .\" -----------------------------------------------------------------
25 .\" disable hyphenation
26 .nh
27 .\" disable justification (adjust text to left margin only)
28 .ad l
29 .\" -----------------------------------------------------------------
30 .\" * MAIN CONTENT STARTS HERE *
31 .\" -----------------------------------------------------------------
32 .SH "NAME"
33 maildir \- E\-mail directory
34 .SH "SYNOPSIS"
35 .sp
36 $HOME/Maildir
37 .SH "DESCRIPTION"
38 .PP
39 A
40 \(lqMaildir\(rq
41 is a structured directory that holds E\-mail messages\&. Maildirs were first implemented by the
42 Qmail
43 mail server\&. Qmail\*(Aqs maildirs were a simple data structure, nothing more than a single collection of E\-mail messages\&. The
44 Courier
45 mail server builds upon
46 Qmail\*(Aqs maildirs to provide extended functionality, such as folders and quotas\&. This document describes the
47 Courier
48 mail server\*(Aqs extended maildirs, without explicitly identifying The
49 Courier
50 mail server\-specific extensions\&. See
51 \fBmaildir\fR(5)
52 in Qmail\*(Aqs documentation for the original definition of maildirs\&.
53 .PP
54 Traditionally, E\-mail folders were saved as plain text files, called
55 \(lqmboxes\(rq\&. Mboxes have known limitations\&. Only one application can use an mbox at the same time\&. Locking is required in order to allow simultaneous concurrent access by different applications\&. Locking is often problematic, and not very reliable in network\-based filesystem requirements\&. Some network\-based filesystems don\*(Aqt offer any reliable locking mechanism at all\&. Furthermore, even bulletproof locking won\*(Aqt prevent occasional mbox corruption\&. A process can be killed or terminated in the middle of updating an mbox\&. This will likely result in corruption, and a loss of most messages in the mbox\&.
56 .PP
57 Maildirs allow multiple concurrent access by different applications\&. Maildirs do not require locking\&. Multiple applications can update a maildir at the same time, without stepping on each other\*(Aqs feet\&.
58 .SS "Maildir contents"
59 .PP
60 A
61 \(lqmaildir\(rq
62 is a directory that\*(Aqs created by
63 \m[blue]\fB\fBmaildirmake\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2\&. Naturally, maildirs should not have any group or world permissions, unless you want other people to read your mail\&. A maildir contains three subdirectories:
64 tmp,
65 new, and
66 cur\&. These three subdirectories comprise the primary folder, where new mail is delivered by the system\&.
67 .PP
68 Folders are additional subdirectories in the maildir whose names begin with a period: such as
69 \&.Drafts
70 or
71 \&.Sent\&. Each folder itself contains the same three subdirectories,
72 tmp,
73 new, and
74 cur, and an additional zero\-length file named
75 maildirfolder, whose purpose is to inform any mail delivery agent that it\*(Aqs really delivering to a folder, and that the mail delivery agent should look in the parent directory for any maildir\-related information\&.
76 .PP
77 Folders are not physically nested\&. A folder subdirectory, such as
78 \&.Sent
79 does not itself contain any subfolders\&. The main maildir contains a single, flat list of subfolders\&. These folders are logically nested, and periods serve to separate folder hierarchies\&. For example,
80 \&.Sent\&.2002
81 is considered to be a subfolder called
82 \(lq2002\(rq
83 which is a subfolder of
84 \(lqSent\(rq\&.
85 .sp
86 .it 1 an-trap
87 .nr an-no-space-flag 1
88 .nr an-break-flag 1
89 .br
90 .ps +1
91 \fBFolder name encoding\fR
92 .RS 4
93 .PP
94 Folder names can contain any Unicode character, except for control characters\&. US\-ASCII characters, U+0x0020 \- U+0x007F, except for the period, and forward\-slash\&. Non\-Latin characters are encoded in UTF\-8\&.
95 .RE
96 .sp
97 .it 1 an-trap
98 .nr an-no-space-flag 1
99 .nr an-break-flag 1
100 .br
101 .ps +1
102 \fBOther maildir contents\fR
103 .RS 4
104 .PP
105 Software that uses maildirs may also create additional files besides the
106 tmp,
107 new, and
108 cur
109 subdirectories \-\- in the main maildir or a subfolder \-\- for its own purposes\&.
110 .RE
111 .SS "Messages"
112 .PP
113 E\-mail messages are stored in separate, individual files, one E\-mail message per file\&. The
114 tmp
115 subdirectory temporarily stores E\-mail messages that are in the process of being delivered to this maildir\&.
116 tmp
117 may also store other kinds of temporary files, as long as they are created in the same way that message files are created in
118 tmp\&. The
119 new
120 subdirectory stores messages that have been delivered to this maildir, but have not yet been seen by any mail application\&. The
121 cur
122 subdirectory stores messages that have already been seen by mail applications\&.
123 .SS "Adding new mail to maildirs"
124 .PP
125 The following process delivers a new message to the maildir:
126 .PP
127 A new unique filename is created using one of two possible forms:
128 \(lqtime\&.MusecPpid\&.host\(rq, or
129 \(lqtime\&.MusecPpid_unique\&.host\(rq\&.
130 \(lqtime\(rq
131 and
132 \(lqusec\(rq
133 is the current system time, obtained from
134 \fBgettimeofday\fR(2)\&.
135 \(lqpid\(rq
136 is the process number of the process that is delivering this message to the maildir\&.
137 \(lqhost\(rq
138 is the name of the machine where the mail is being delivered\&. In the event that the same process creates multiple messages, a suffix unique to each message is appended to the process id; preferrably an underscore, followed by an increasing counter\&. This applies whether messages created by a process are all added to the same, or different, maildirs\&. This protocol allows multiple processes running on multiple machines on the same network to simultaneously create new messages without stomping on each other\&.
139 .PP
140 The filename created in the previous step is checked for existence by executing the
141 \fBstat\fR(2)
142 system call\&. If
143 \fBstat\fR(2)
144 results in ANYTHING OTHER than the system error
145 ENOENT, the process must sleep for two seconds, then go back and create another unique filename\&. This is an extra step to insure that each new message has a completely unique filename\&.
146 .PP
147 Other applications that wish to use
148 tmp
149 for temporary storage should observe the same protocol (but see READING MAIL FROM MAILDIRS below, because old files in
150 tmp
151 will be eventually deleted)\&.
152 .PP
153 If the
154 \fBstat\fR(2)
155 system call returned
156 ENOENT, the process may proceed to create the file in the
157 tmp
158 subdirectory, and save the entire message in the new file\&. The message saved MUST NOT have the
159 \(lqFrom_\(rq
160 header that is used to mboxes\&. The message also MUST NOT have any
161 \(lqFrom_\(rq
162 lines in the contents of the message prefixed by the
163 \(lq>\(rq
164 character\&.
165 .PP
166 When saving the message, the number of bytes returned by the
167 \fBwrite\fR(2)
168 system call must be checked, in order to make sure that the complete message has been written out\&.
169 .PP
170 After the message is saved, the file descriptor is
171 \fBfstat\fR(2)\-ed\&. The file\*(Aqs device number, inode number, and the its byte size, are saved\&. The file is closed and is then immediately moved/renamed into the
172 new
173 subdirectory\&. The name of the file in
174 new
175 should be
176 \(lqtime\&.MusecPpidVdevIino\&.host,S=\fIcnt\fR\(rq, or
177 \(lqtime\&.MusecPpidVdevIino_unique\&.host,S=\fIcnt\fR\(rq\&.
178 \(lqdev\(rq
179 is the message\*(Aqs device number,
180 \(lqino\(rq
181 is the message\*(Aqs inode number (from the previous
182 \fBfstat\fR(2)
183 call); and
184 \(lqcnt\(rq
185 is the message\*(Aqs size, in bytes\&.
186 .PP
187 The
188 \(lq,S=\fIcnt\fR\(rq
189 part optimizes the
190 \m[blue]\fBCourier\fR\m[]\&\s-2\u[2]\d\s+2
191 mail server\*(Aqs maildir quota enhancement; it allows the size of all the mail stored in the maildir to be added up without issuing the
192 \fBstat\fR(2)
193 system call for each individual message (this can be quite a performance drain with certain network filesystems)\&.
194 .SS "READING MAIL FROM MAILDIRS"
195 .PP
196 Applications that read mail from maildirs should do it in the following order:
197 .PP
198 When opening a maildir or a maildir folder, read the
199 tmp
200 subdirectory and delete any files in there that are at least 36 hours old\&.
201 .PP
202 Look for new messages in the
203 new
204 subdirectory\&. Rename
205 \fInew/filename\fR, as
206 \fIcur/filename:2,info\fR\&. Here,
207 \fIinfo\fR
208 represents the state of the message, and it consists of zero or more boolean flags chosen from the following:
209 \(lqD\(rq
210 \- this is a \*(Aqdraft\*(Aq message,
211 \(lqR\(rq
212 \- this message has been replied to,
213 \(lqS\(rq
214 \- this message has been viewed (seen),
215 \(lqT\(rq
216 \- this message has been marked to be deleted (trashed), but is not yet removed (messages are removed from maildirs simply by deleting their file),
217 \(lqF\(rq
218 \- this message has been marked by the user, for some purpose\&. These flags must be stored in alphabetical order\&. New messages contain only the
219 :2,
220 suffix, with no flags, indicating that the messages were not seen, replied, marked, or deleted\&.
221 .PP
222 Maildirs may have maximum size quotas defined, but these quotas are purely voluntary\&. If you need to implement mandatory quotas, you should use any quota facilities provided by the underlying filesystem that is used to store the maildirs\&. The maildir quota enhancement is designed to be used in certain situations where filesystem\-based quotas cannot be used for some reason\&. The implementation is designed to avoid the use of any locking\&. As such, at certain times the calculated quota may be imprecise, and certain anomalous situations may result in the maildir actually going over the stated quota\&. One such situation would be when applications create messages without updating the quota estimate for the maildir\&. Eventually it will be precisely recalculated, but wherever possible new messages should be created in compliance with the voluntary quota protocol\&.
223 .PP
224 The voluntary quota protocol involves some additional procedures that must be followed when creating or deleting messages within a given maildir or its subfolders\&. The
225 \m[blue]\fB\fBdeliverquota\fR(8)\fR\m[]\&\s-2\u[3]\d\s+2
226 command is a tiny application that delivers a single message to a maildir using the voluntary quota protocol, and hopefully it can be used as a measure of last resort\&. Alternatively, applications can use the
227 libmaildir\&.a
228 library to handle all the low\-level dirty details for them\&. The voluntary quota enhancement is described in the
229 \m[blue]\fB\fBmaildirquota\fR(7)\fR\m[]\&\s-2\u[4]\d\s+2
230 man page\&.
231 .SS "Maildir Quotas"
232 .PP
233 This is a voluntary mechanism for enforcing "loose" quotas on the maximum sizes of maildirs\&. This mechanism is enforced in software, and not by the operating system\&. Therefore it is only effective as long as the maildirs themselves are not directly accessible by their users, since this mechanism is trivially disabled\&.
234 .PP
235 If possible, operating system\-enforced quotas are preferrable\&. Where operating system quota enforcement is not available, or not possible, this voluntary quota enforcement mechanism might be an acceptable compromise\&. Since it\*(Aqs enforced in software, all software that modifies or accesses the maildirs is required to voluntary obey and enforce a quota\&. The voluntary quota implementation is flexible enough to allow non quota\-aware applications to also access the maildirs, without any drastic consequences\&. There will be some non\-drastic consequences, though\&. Of course, non quota\-aware applications will not enforce any defined quotas\&. Furthermore, this voluntary maildir quota mechanism works by estimating the current size of the maildir, with periodic exact recalculation\&. Obviously non quota\-aware maildir applications will not update the maildir size estimation, so the estimate will be thrown off for some period of time, until the next recalculation\&.
236 .PP
237 This voluntary quota mechanism is designed to be a reasonable compromise between effectiveness, and performance\&. The entire purpose of using maildir\-based mail storage is to avoid any kind of locking, and to permit parallel access to mail by multiple applications\&. In order to compute the exact size of a maildir, the maildir must be locked somehow to prevent any modifications while its contents are added up\&. Obviously something like that defeats the original purpose of using maildirs, therefore the voluntary quota mechanism does not use locking, and that\*(Aqs why the current recorded maildir size is always considered to be an estimate\&. Regular size recalculations will compensate for any occasional race conditions that result in the estimate to be thrown off\&.
238 .PP
239 A quota for an existing maildir is installed by running maildirmake with the
240 \-q
241 option, and naming an existing maildir\&. The
242 \-q
243 option takes a parameter,
244 \fIquota\fR, which is a comma\-separated list of quota specifications\&. A quota specification consists of a number followed by either \*(AqS\*(Aq, indicating the maximum message size in bytes, or \*(AqC\*(Aq, maximum number of messages\&. For example:
245 .sp
246 .if n \{\
247 .RS 4
248 .\}
249 .nf
250 \fBmaildirmake \-q 5000000S,1000C \&./Maildir\fR
251 .fi
252 .if n \{\
253 .RE
254 .\}
255 .PP
256 This sets the quota to 5,000,000 bytes or 1000 messages, whichever comes first\&.
257 .sp
258 .if n \{\
259 .RS 4
260 .\}
261 .nf
262 \fBmaildirmake \-q 1000000S \&./Maildir\fR
263 .fi
264 .if n \{\
265 .RE
266 .\}
267 .PP
268 This sets the quota to 1,000,000 bytes, without limiting the number of messages\&.
269 .PP
270 A quota of an existing maildir can be changed by rerunning the
271 \fBmaildirmake\fR
272 command with a new
273 \-q
274 option\&. To delete a quota entirely, delete the
275 \fIMaildir\fR/maildirsize
276 file\&.
277 .SH "SEE ALSO"
278 .PP
279 \m[blue]\fB\fBmaildirmake\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2\&.
280 .SH "AUTHOR"
281 .PP
282 \fBSam Varshavchik\fR
283 .RS 4
284 Author
285 .RE
286 .SH "NOTES"
287 .IP " 1." 4
288 \fBmaildirmake\fR(1)
289 .RS 4
290 \%http://www.courier-mta.org/maildirmake.html
291 .RE
292 .IP " 2." 4
293 Courier
294 .RS 4
295 \%https://www.courier-mta.org
296 .RE
297 .IP " 3." 4
298 \fBdeliverquota\fR(8)
299 .RS 4
300 \%http://www.courier-mta.org/deliverquota.html
301 .RE
302 .IP " 4." 4
303 \fBmaildirquota\fR(7)
304 .RS 4
305 \%http://www.courier-mta.org/maildirquota.html
306 .RE