.TH dot-qmail 5.SH NAMEdot-qmail \- control the delivery of mail messages.SH DESCRIPTIONNormally the.B qmail-localprogram delivers each incoming message to your system mailbox,.IR homedir\fB/Mailbox ,where.I homediris your home directory.It can insteadwrite 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 'sbehavior, set up a.B .qmailfile in your home directory..B .qmailcontains one or more lines.Each line is a delivery instruction..B qmail-localfollows 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-localignores the line..TP 5(2)A program line begins with a vertical bar:.EX     |preline /usr/ucb/vacation djb.EE.B qmail-localtakes 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-localtakes the rest of the line as a mail address;it uses.B qmail-queueto 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).EEIf the address begins with a letter or number,you may leave out the ampersand:.EX     me@new.job.com.EENote that.B qmail-localomits its new.B Return-Pathline when forwarding messages..TP 5(4)An .I mboxline begins with a slash or dot,and does not end with a slash:.EX     /home/djb/Mailbox.sos.EE.B qmail-localtakes the entire line as a filename.It appends the mail message to that file,using.BR flock -stylefile locking if possible..B qmail-localstores the mail message in.I mboxformat, as described in.BR mbox(5) ..B WARNING:On many systems,anyone who can read a file can.B flockit, and thus hold up.BR qmail-local 'sdelivery forever.Do not deliver mail to a publicly accessible file!If.B qmail-localis 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 systemcrashes during delivery..TP 5(5)A.I maildirline begins with a slash or dot,and ends with a slash:.EX     /home/djb/Maildir/.EE.B qmail-localtakes the entire line as the name of a directory in.I maildirformat.It reliably stores the incoming message in that directory.See.B maildir(5)for more details..PPIf.B .qmailhas the execute bit set,it must not contain anyprogram lines,.I mboxlines,or.I maildirlines.If.B qmail-localsees any such lines,it will stop and indicate a temporary failure.If.B .qmailis completely empty (0 bytes long), or does not exist,.B qmail-localfollows the.I defaultdeliveryinstructions set by your system administrator;normally.I defaultdeliveryis.BR ./Mailbox ,so.B qmail-localappends the mail message to.B Mailboxin.I mboxformat..B .qmailmay 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 .qmailis world-writable or group-writable,.B qmail-localstops and indicates a temporary failure..SH "SAFE QMAIL EDITING"Incoming messages can arrive at any moment.If you want to safely edit your.B .qmailfile, first set the sticky bit on your home directory:.EX     chmod +t $HOME.EE.B qmail-localwill temporarily defer delivery of any message to youif your home directory is sticky(or group-writable or other-writable,which should never happen).Make sure to.EX     chmod -t $HOME.EEwhen you are done!It's a good idea to test your new.B .qmailfile as follows:.EX     qmail-local -n $USER ~ $USER '' '' '' '' ./Mailbox.EE.SH "EXTENSION ADDRESSES"In the.B qmailsystem,you control all local addresses of the form.IR user\fBBREAK\fIanything ,as well as the address.I useritself,where.I useris your account name.Delivery to.I user\fBBREAK\fIanythingis 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 aliasuser controls all other addresses.Delivery to.I localis controlled by the file.IR homedir/\fB.qmail\-\fIlocal ,where.I homediris.BR alias 'shome directory.In the following description,.B qmail-localis handling a message addressed to.IR local@domain ,where.I localis controlled by.BR .qmail\-\fIext .Here is what it does.If.B .qmail\-\fIextis completely empty,.B qmail-localfollows the.I defaultdeliveryinstructions set by your system administrator.If.B .qmail\-\fIextdoesn't exist,.B qmail-localwill try some default.B .qmailfiles.For example,if.I extis.BR foo-bar ,.B qmail-localwill try first.BR .qmail-foo-bar ,then.BR .qmail-foo-default ,and finally.BR .qmail-default .If none of these exist,.B qmail-localwill bounce the message.(Exception: for the basic.I useraddress,.B qmail-localtreats a nonexistent.B .qmailthe same as an empty.BR .qmail .).B WARNING:For security,.B qmail-localreplaces any dots in.I extwith colons before checking.BR .qmail\-\fIext .For convenience,.B qmail-localconverts any uppercase letters in.I extto lowercase.When.B qmail-localforwards a message as instructed in.B .qmail\-\fIext(or.BR .qmail-default ),it checks whether.B .qmail\-\fIext\fB-owner\fPexists.If so,it uses.I local\fB-owner@\fIdomainas the envelope sender for the forwarded message.Otherwise it retains the envelope sender of the original message.Exception:.B qmail-localalways retains the original envelope senderif it is the empty address or.BR #@[] ,i.e., if this is a bounce message..B qmail-localalso supports.B variable envelope return paths(VERPs):if.B .qmail\-\fIext\fB-owner\fPand.B .qmail\-\fIext\fB-owner-default\fPboth exist, it uses.I local\fB\-owner\-@\fIdomain\fB-@[]as the envelope sender.This will cause a recipient.I recip\fB@\fIreciphostto see an envelope sender of.IR local\fB\-owner\-\fIrecip\fB=\fIreciphost\fB@\fIdomain ..SH "ERROR HANDLING"If a delivery instruction fails,.B qmail-localstops immediately and reports failure..B qmail-localhandles 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-localignores 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 instructiondoes not affect the others,move each instruction into a separate.B .qmail\-\fIextfile, and set up a central.B .qmailfile that forwards to all of the.BR .qmail\-\fIext s.Note that.B qmail-localcan 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)