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