Commit | Line | Data |
---|---|---|
2117e02e MW |
1 | .TH dot-qmail 5 |
2 | .SH NAME | |
3 | dot-qmail \- control the delivery of mail messages | |
4 | .SH DESCRIPTION | |
5 | Normally the | |
6 | .B qmail-local | |
7 | program delivers each incoming message to your system mailbox, | |
8 | .IR homedir\fB/Mailbox , | |
9 | where | |
10 | .I homedir | |
11 | is your home directory. | |
12 | ||
13 | It can instead | |
14 | write the mail to a different file or directory, | |
15 | forward it to another address, | |
16 | distribute it to a mailing list, | |
17 | or even execute programs, | |
18 | all under your control. | |
19 | .SH "THE QMAIL FILE" | |
20 | To change | |
21 | .BR qmail-local 's | |
22 | behavior, set up a | |
23 | .B .qmail | |
24 | file in your home directory. | |
25 | ||
26 | .B .qmail | |
27 | contains one or more lines. | |
28 | Each line is a delivery instruction. | |
29 | .B qmail-local | |
30 | follows each instruction in turn. | |
31 | There are five types of delivery instructions: | |
32 | (1) comment; (2) program; (3) forward; (4) mbox; (5) maildir. | |
33 | .TP 5 | |
34 | (1) | |
35 | A comment line begins with a number sign: | |
36 | ||
37 | .EX | |
38 | # this is a comment | |
39 | .EE | |
40 | ||
41 | .B qmail-local | |
42 | ignores the line. | |
43 | .TP 5 | |
44 | (2) | |
45 | A program line begins with a vertical bar: | |
46 | ||
47 | .EX | |
212b6f5d | 48 | |preline /usr/ucb/vacation djb |
2117e02e MW |
49 | .EE |
50 | ||
51 | .B qmail-local | |
52 | takes the rest of the line as a command to supply to | |
53 | .BR sh . | |
54 | See | |
55 | .B qmail-command(8) | |
56 | for further information. | |
57 | .TP 5 | |
58 | (3) | |
59 | A forward line begins with an ampersand: | |
60 | ||
61 | .EX | |
62 | &me@new.job.com | |
63 | .EE | |
64 | ||
65 | .B qmail-local | |
66 | takes the rest of the line as a mail address; | |
67 | it uses | |
68 | .B qmail-queue | |
69 | to forward the message to that address. | |
70 | The address must contain a fully qualified domain name; | |
71 | it must not contain extra spaces, angle brackets, or comments: | |
72 | ||
73 | .EX | |
74 | # the following examples are WRONG | |
75 | .br | |
76 | &me@new | |
77 | .br | |
78 | &<me@new.job.com> | |
79 | .br | |
80 | & me@new.job.com | |
81 | .br | |
82 | &me@new.job.com (New Address) | |
83 | .EE | |
84 | ||
85 | If the address begins with a letter or number, | |
86 | you may leave out the ampersand: | |
87 | ||
88 | .EX | |
89 | me@new.job.com | |
90 | .EE | |
91 | ||
92 | Note that | |
93 | .B qmail-local | |
94 | omits its new | |
95 | .B Return-Path | |
96 | line when forwarding messages. | |
97 | .TP 5 | |
98 | (4) | |
99 | An | |
100 | .I mbox | |
101 | line begins with a slash or dot, | |
102 | and does not end with a slash: | |
103 | ||
104 | .EX | |
105 | /home/djb/Mailbox.sos | |
106 | .EE | |
107 | ||
108 | .B qmail-local | |
109 | takes the entire line as a filename. | |
110 | It appends the mail message to that file, | |
111 | using | |
112 | .BR flock -style | |
113 | file locking if possible. | |
114 | .B qmail-local | |
115 | stores the mail message in | |
116 | .I mbox | |
117 | format, as described in | |
118 | .BR mbox(5) . | |
119 | ||
120 | .B WARNING: | |
121 | On many systems, | |
122 | anyone who can read a file can | |
123 | .B flock | |
124 | it, and thus hold up | |
125 | .BR qmail-local 's | |
126 | delivery forever. | |
127 | Do not deliver mail to a publicly accessible file! | |
128 | ||
129 | If | |
130 | .B qmail-local | |
131 | is able to lock the file, but has trouble writing to it | |
132 | (because, for example, the disk is full), | |
133 | it will truncate the file back to its original length. | |
134 | However, it cannot prevent mailbox corruption if the system | |
135 | crashes during delivery. | |
136 | .TP 5 | |
137 | (5) | |
138 | A | |
139 | .I maildir | |
140 | line begins with a slash or dot, | |
141 | and ends with a slash: | |
142 | ||
143 | .EX | |
144 | /home/djb/Maildir/ | |
145 | .EE | |
146 | ||
147 | .B qmail-local | |
148 | takes the entire line as the name of a directory in | |
149 | .I maildir | |
150 | format. | |
151 | It reliably stores the incoming message in that directory. | |
152 | See | |
153 | .B maildir(5) | |
154 | for more details. | |
155 | .PP | |
156 | If | |
157 | .B .qmail | |
158 | has the execute bit set, | |
159 | it must not contain any | |
160 | program lines, | |
161 | .I mbox | |
162 | lines, | |
163 | or | |
164 | .I maildir | |
165 | lines. | |
166 | If | |
167 | .B qmail-local | |
168 | sees any such lines, | |
169 | it will stop and indicate a temporary failure. | |
170 | ||
171 | If | |
172 | .B .qmail | |
173 | is completely empty (0 bytes long), or does not exist, | |
174 | .B qmail-local | |
175 | follows the | |
212b6f5d | 176 | .I defaultdelivery |
2117e02e MW |
177 | instructions set by your system administrator; |
178 | normally | |
212b6f5d | 179 | .I defaultdelivery |
2117e02e MW |
180 | is |
181 | .BR ./Mailbox , | |
182 | so | |
183 | .B qmail-local | |
184 | appends the mail message to | |
185 | .B Mailbox | |
186 | in | |
187 | .I mbox | |
188 | format. | |
189 | ||
190 | .B .qmail | |
191 | may contain extra spaces and tabs at the end of a line. | |
192 | Blank lines are allowed, but not for the first line of | |
193 | .BR .qmail . | |
194 | ||
195 | If | |
196 | .B .qmail | |
197 | is world-writable or group-writable, | |
198 | .B qmail-local | |
199 | stops and indicates a temporary failure. | |
200 | .SH "SAFE QMAIL EDITING" | |
201 | Incoming messages can arrive at any moment. | |
202 | If you want to safely edit your | |
203 | .B .qmail | |
204 | file, first set the sticky bit on your home directory: | |
205 | ||
206 | .EX | |
207 | chmod +t $HOME | |
208 | .EE | |
209 | ||
210 | .B qmail-local | |
211 | will temporarily defer delivery of any message to you | |
212 | if your home directory is sticky | |
213 | (or group-writable or other-writable, | |
214 | which should never happen). | |
215 | Make sure to | |
216 | ||
217 | .EX | |
218 | chmod -t $HOME | |
219 | .EE | |
220 | ||
221 | when you are done! | |
222 | It's a good idea to test your new | |
223 | .B .qmail | |
224 | file as follows: | |
225 | ||
226 | .EX | |
212b6f5d | 227 | qmail-local -n $USER ~ $USER '' '' '' '' ./Mailbox |
2117e02e MW |
228 | .EE |
229 | .SH "EXTENSION ADDRESSES" | |
230 | In the | |
231 | .B qmail | |
232 | system, | |
233 | you control all local addresses of the form | |
234 | .IR user\fBBREAK\fIanything , | |
235 | as well as the address | |
236 | .I user | |
237 | itself, | |
238 | where | |
239 | .I user | |
240 | is your account name. | |
241 | Delivery to | |
242 | .I user\fBBREAK\fIanything | |
243 | is controlled by the file | |
244 | .IR homedir/\fB.qmail\-\fIanything . | |
245 | (These rules may be changed by the system administrator; | |
246 | see | |
247 | .BR qmail-users (5).) | |
248 | ||
249 | The | |
250 | .B alias | |
251 | user controls all other addresses. | |
252 | Delivery to | |
253 | .I local | |
254 | is controlled by the file | |
255 | .IR homedir/\fB.qmail\-\fIlocal , | |
256 | where | |
257 | .I homedir | |
258 | is | |
259 | .BR alias 's | |
260 | home directory. | |
261 | ||
262 | In the following description, | |
263 | .B qmail-local | |
264 | is handling a message addressed to | |
265 | .IR local@domain , | |
266 | where | |
267 | .I local | |
268 | is controlled by | |
269 | .BR .qmail\-\fIext . | |
270 | Here is what it does. | |
271 | ||
272 | If | |
273 | .B .qmail\-\fIext | |
274 | is completely empty, | |
275 | .B qmail-local | |
276 | follows the | |
212b6f5d | 277 | .I defaultdelivery |
2117e02e MW |
278 | instructions set by your system administrator. |
279 | ||
280 | If | |
281 | .B .qmail\-\fIext | |
282 | doesn't exist, | |
283 | .B qmail-local | |
284 | will try some default | |
285 | .B .qmail | |
286 | files. | |
287 | For example, | |
288 | if | |
289 | .I ext | |
290 | is | |
291 | .BR foo-bar , | |
292 | .B qmail-local | |
293 | will try first | |
294 | .BR .qmail-foo-bar , | |
295 | then | |
296 | .BR .qmail-foo-default , | |
297 | and finally | |
298 | .BR .qmail-default . | |
299 | If none of these exist, | |
300 | .B qmail-local | |
301 | will bounce the message. | |
302 | (Exception: for the basic | |
303 | .I user | |
304 | address, | |
305 | .B qmail-local | |
306 | treats a nonexistent | |
307 | .B .qmail | |
308 | the same as an empty | |
309 | .BR .qmail .) | |
310 | ||
311 | .B WARNING: | |
312 | For security, | |
313 | .B qmail-local | |
314 | replaces any dots in | |
315 | .I ext | |
316 | with colons before checking | |
317 | .BR .qmail\-\fIext . | |
318 | For convenience, | |
319 | .B qmail-local | |
320 | converts any uppercase letters in | |
321 | .I ext | |
322 | to lowercase. | |
323 | ||
324 | When | |
325 | .B qmail-local | |
326 | forwards a message as instructed in | |
327 | .B .qmail\-\fIext | |
328 | (or | |
329 | .BR .qmail-default ), | |
330 | it checks whether | |
331 | .B .qmail\-\fIext\fB-owner\fP | |
332 | exists. | |
333 | If so, | |
334 | it uses | |
335 | .I local\fB-owner@\fIdomain | |
336 | as the envelope sender for the forwarded message. | |
337 | Otherwise it retains the envelope sender of the original message. | |
338 | Exception: | |
339 | .B qmail-local | |
340 | always retains the original envelope sender | |
341 | if it is the empty address or | |
342 | .BR #@[] , | |
343 | i.e., if this is a bounce message. | |
344 | ||
345 | .B qmail-local | |
346 | also supports | |
347 | .B variable envelope return paths | |
348 | (VERPs): | |
349 | if | |
350 | .B .qmail\-\fIext\fB-owner\fP | |
351 | and | |
352 | .B .qmail\-\fIext\fB-owner-default\fP | |
353 | both exist, it uses | |
354 | .I local\fB\-owner\-@\fIdomain\fB-@[] | |
355 | as the envelope sender. | |
356 | This will cause a recipient | |
357 | .I recip\fB@\fIreciphost | |
358 | to see an envelope sender of | |
359 | .IR local\fB\-owner\-\fIrecip\fB=\fIreciphost\fB@\fIdomain . | |
360 | .SH "ERROR HANDLING" | |
361 | If a delivery instruction fails, | |
362 | .B qmail-local | |
363 | stops immediately and reports failure. | |
364 | .B qmail-local | |
365 | handles forwarding after all other instructions, | |
366 | so any error in another type of delivery will prevent all forwarding. | |
367 | ||
368 | If a program returns exit code 99, | |
369 | .B qmail-local | |
370 | ignores all succeeding lines in | |
371 | .BR .qmail , | |
372 | but it still pays attention to previous forward lines. | |
373 | ||
374 | To set up independent instructions, | |
375 | where a temporary or permanent failure in one instruction | |
376 | does not affect the others, | |
377 | move each instruction into a separate | |
378 | .B .qmail\-\fIext | |
379 | file, and set up a central | |
380 | .B .qmail | |
381 | file that forwards to all of the | |
382 | .BR .qmail\-\fIext s. | |
383 | Note that | |
384 | .B qmail-local | |
385 | can handle any number of forward lines simultaneously. | |
386 | .SH "SEE ALSO" | |
387 | envelopes(5), | |
388 | maildir(5), | |
389 | mbox(5), | |
390 | qmail-users(5), | |
391 | qmail-local(8), | |
392 | qmail-command(8), | |
393 | qmail-queue(8), | |
394 | qmail-lspawn(8) |