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

    48      |preline /usr/ucb/vacation djb

    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

   176 .I defaultdelivery

   177 instructions set by your system administrator;

   178 normally

   179 .I defaultdelivery

   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

   227      qmail-local -n $USER ~ $USER '' '' '' '' ./Mailbox

   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

   277 .I defaultdelivery

   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)