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