File: dot-qmail.9

package info (click to toggle)
qmail 1.01-5
  • links: PTS
  • area: non-free
  • in suites: hamm
  • size: 2,188 kB
  • ctags: 1,711
  • sloc: ansic: 13,993; makefile: 1,914; perl: 448; sh: 377
file content (394 lines) | stat: -rw-r--r-- 7,355 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
.TH dot-qmail 5
.SH NAME
dot-qmail \- control the delivery of mail messages
.SH DESCRIPTION
Normally the
.B qmail-local
program delivers each incoming message to your system mailbox,
.IR homedir\fB/Mailbox ,
where
.I homedir
is your home directory.

It can instead
write the mail to a different file or directory,
forward it to another address,
distribute it to a mailing list,
or even execute programs,
all under your control.
.SH "THE QMAIL FILE"
To change
.BR qmail-local 's
behavior, set up a
.B .qmail
file in your home directory.

.B .qmail
contains one or more lines.
Each line is a delivery instruction.
.B qmail-local
follows each instruction in turn.
There are five types of delivery instructions:
(1) comment; (2) program; (3) forward; (4) mbox; (5) maildir.
.TP 5
(1)
A comment line begins with a number sign:

.EX
     # this is a comment
.EE

.B qmail-local
ignores the line.
.TP 5
(2)
A program line begins with a vertical bar:

.EX
     |/usr/ucb/vacation djb
.EE

.B qmail-local
takes the rest of the line as a command to supply to
.BR sh .
See
.B qmail-command(8)
for further information.
.TP 5
(3)
A forward line begins with an ampersand:

.EX
     &me@new.job.com
.EE

.B qmail-local
takes the rest of the line as a mail address;
it uses
.B qmail-queue
to forward the message to that address.
The address must contain a fully qualified domain name;
it must not contain extra spaces, angle brackets, or comments:

.EX
     # the following examples are WRONG
.br
     &me@new
.br
     &<me@new.job.com>
.br
     & me@new.job.com
.br
     &me@new.job.com (New Address)
.EE

If the address begins with a letter or number,
you may leave out the ampersand:

.EX
     me@new.job.com
.EE

Note that
.B qmail-local
omits its new
.B Return-Path
line when forwarding messages.
.TP 5
(4)
An 
.I mbox
line begins with a slash or dot,
and does not end with a slash:

.EX
     /home/djb/Mailbox.sos
.EE

.B qmail-local
takes the entire line as a filename.
It appends the mail message to that file,
using
.BR flock -style
file locking if possible.
.B qmail-local
stores the mail message in
.I mbox
format, as described in
.BR mbox(5) .

.B WARNING:
On many systems,
anyone who can read a file can
.B flock
it, and thus hold up
.BR qmail-local 's
delivery forever.
Do not deliver mail to a publicly accessible file!

If
.B qmail-local
is able to lock the file, but has trouble writing to it
(because, for example, the disk is full),
it will truncate the file back to its original length.
However, it cannot prevent mailbox corruption if the system
crashes during delivery.
.TP 5
(5)
A
.I maildir
line begins with a slash or dot,
and ends with a slash:

.EX
     /home/djb/Maildir/
.EE

.B qmail-local
takes the entire line as the name of a directory in
.I maildir
format.
It reliably stores the incoming message in that directory.
See
.B maildir(5)
for more details.
.PP
If
.B .qmail
has the execute bit set,
it must not contain any
program lines,
.I mbox
lines,
or
.I maildir
lines.
If
.B qmail-local
sees any such lines,
it will stop and indicate a temporary failure.

If
.B .qmail
is completely empty (0 bytes long), or does not exist,
.B qmail-local
follows the
.I aliasempty
instructions set by your system administrator;
normally
.I aliasempty
is
.BR ./Mailbox ,
so
.B qmail-local
appends the mail message to
.B Mailbox
in
.I mbox
format.

.B .qmail
may contain extra spaces and tabs at the end of a line.
Blank lines are allowed, but not for the first line of
.BR .qmail .

If
.B .qmail
is world-writable or group-writable,
.B qmail-local
stops and indicates a temporary failure.
.SH "SAFE QMAIL EDITING"
Incoming messages can arrive at any moment.
If you want to safely edit your
.B .qmail
file, first set the sticky bit on your home directory:

.EX
     chmod +t $HOME
.EE

.B qmail-local
will temporarily defer delivery of any message to you
if your home directory is sticky
(or group-writable or other-writable,
which should never happen).
Make sure to

.EX
     chmod -t $HOME
.EE

when you are done!
It's a good idea to test your new
.B .qmail
file as follows:

.EX
     qmail-local -n $USER $HOME $USER '' '' '' ''
.EE
.SH "EXTENSION ADDRESSES"
In the
.B qmail
system,
you control all local addresses of the form
.IR user\fBBREAK\fIanything ,
as well as the address
.I user
itself,
where
.I user
is your account name.
Delivery to
.I user\fBBREAK\fIanything
is controlled by the file
.IR homedir/\fB.qmail\-\fIanything .
(These rules may be changed by the system administrator;
see
.BR qmail-users (5).)

The
.B alias
user controls all other addresses.
Delivery to
.I local
is controlled by the file
.IR homedir/\fB.qmail\-\fIlocal ,
where
.I homedir
is
.BR alias 's
home directory.

In the following description,
.B qmail-local
is handling a message addressed to
.IR local@domain ,
where
.I local
is controlled by
.BR .qmail\-\fIext .
Here is what it does.

If
.B .qmail\-\fIext
is completely empty,
.B qmail-local
follows the
.I aliasempty
instructions set by your system administrator.

If
.B .qmail\-\fIext
doesn't exist,
.B qmail-local
will try some default
.B .qmail
files.
For example,
if
.I ext
is
.BR foo-bar ,
.B qmail-local
will try first
.BR .qmail-foo-bar ,
then
.BR .qmail-foo-default ,
and finally
.BR .qmail-default .
If none of these exist,
.B qmail-local
will bounce the message.
(Exception: for the basic
.I user
address,
.B qmail-local
treats a nonexistent
.B .qmail
the same as an empty
.BR .qmail .)

.B WARNING:
For security,
.B qmail-local
replaces any dots in
.I ext
with colons before checking
.BR .qmail\-\fIext .
For convenience,
.B qmail-local
converts any uppercase letters in
.I ext
to lowercase.

When
.B qmail-local
forwards a message as instructed in
.B .qmail\-\fIext
(or
.BR .qmail-default ),
it checks whether
.B .qmail\-\fIext\fB-owner\fP
exists.
If so,
it uses
.I local\fB-owner@\fIdomain
as the envelope sender for the forwarded message.
Otherwise it retains the envelope sender of the original message.
Exception:
.B qmail-local
always retains the original envelope sender
if it is the empty address or
.BR #@[] ,
i.e., if this is a bounce message.

.B qmail-local
also supports
.B variable envelope return paths
(VERPs):
if
.B .qmail\-\fIext\fB-owner\fP
and
.B .qmail\-\fIext\fB-owner-default\fP
both exist, it uses
.I local\fB\-owner\-@\fIdomain\fB-@[]
as the envelope sender.
This will cause a recipient
.I recip\fB@\fIreciphost
to see an envelope sender of
.IR local\fB\-owner\-\fIrecip\fB=\fIreciphost\fB@\fIdomain .
.SH "ERROR HANDLING"
If a delivery instruction fails,
.B qmail-local
stops immediately and reports failure.
.B qmail-local
handles forwarding after all other instructions,
so any error in another type of delivery will prevent all forwarding.

If a program returns exit code 99,
.B qmail-local
ignores all succeeding lines in
.BR .qmail ,
but it still pays attention to previous forward lines.

To set up independent instructions,
where a temporary or permanent failure in one instruction
does not affect the others,
move each instruction into a separate
.B .qmail\-\fIext
file, and set up a central
.B .qmail
file that forwards to all of the
.BR .qmail\-\fIext s.
Note that
.B qmail-local
can handle any number of forward lines simultaneously.
.SH "SEE ALSO"
envelopes(5),
maildir(5),
mbox(5),
qmail-users(5),
qmail-local(8),
qmail-command(8),
qmail-queue(8),
qmail-lspawn(8)