Provided by: qmail_1.06-4_i386 bug

NAME

       dot-qmail - control the delivery of mail messages

DESCRIPTION

       Normally the qmail-local program delivers each incoming message to your
       system mailbox, homedir/Mailbox, where 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.

THE QMAIL FILE

       To change qmail-local's behavior, set up a .qmail  file  in  your  home
       directory.

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

       (1)  A comment line begins with a number sign:

                 # this is a comment

            qmail-local ignores the line.

       (2)  A program line begins with a vertical bar:

                 |preline /usr/ucb/vacation djb

            qmail-local takes the rest of the line as a command to  supply  to
            sh.  See qmail-command(8) for further information.

       (3)  A forward line begins with an ampersand:

                 &me@new.job.com

            qmail-local  takes the rest of the line as a mail address; it uses
            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:

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

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

                 me@new.job.com

            Note   that  qmail-local  omits  its  new  Return-Path  line  when
            forwarding messages.

       (4)  An mbox line begins with a slash or dot, and does not end  with  a
            slash:

                 /home/djb/Mailbox.sos

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

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

            If 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.

       (5)  A maildir line begins with a slash or dot, and ends with a slash:

                 /home/djb/Maildir/

            qmail-local  takes  the  entire line as the name of a directory in
            maildir format.  It reliably stores the incoming message  in  that
            directory.  See maildir(5) for more details.

       If  .qmail  has  the  execute  bit set, it must not contain any program
       lines, mbox lines, or maildir lines.   If  qmail-local  sees  any  such
       lines, it will stop and indicate a temporary failure.

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

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

       If   .qmail  is  world-writable,  qmail-local  stops  and  indicates  a
       temporary failure.

SAFE QMAIL EDITING

       Incoming messages can arrive at any moment.  If you want to safely edit
       your .qmail file, first set the sticky bit on your home directory:

            chmod +t $HOME

       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

            chmod -t $HOME

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

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

EXTENSION ADDRESSES

       In the qmail system, you control all local addresses of the form  user-
       anything,  as  well  as  the  address  user  itself, where user is your
       account name.  Delivery to user-anything  is  controlled  by  the  file
       homedir/.qmail-anything.   (These  rules  may  be changed by the system
       administrator; see qmail-users(5).)

       The alias user controls all other  addresses.   Delivery  to  local  is
       controlled  by  the file homedir/.qmail-local, where homedir is alias's
       home directory.

       In  the  following  description,  qmail-local  is  handling  a  message
       addressed  to  local@domain,  where  local is controlled by .qmail-ext.
       Here is what it does.

       If  .qmail-ext   is   completely   empty,   qmail-local   follows   the
       defaultdelivery instructions set by your system administrator.

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

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

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

       qmail-local also supports variable envelope return  paths  (VERPs):  if
       .qmail-ext-owner  and  .qmail-ext-owner-default  both  exist,  it  uses
       local-owner-@domain-@[] as the envelope  sender.   This  will  cause  a
       recipient    recip@reciphost    to    see   an   envelope   sender   of
       local-owner-recip=reciphost@domain.

ERROR HANDLING

       If a delivery instruction  fails,  qmail-local  stops  immediately  and
       reports  failure.   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, qmail-local ignores all succeeding
       lines in .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 .qmail-ext  file,  and  set  up  a  central
       .qmail  file that forwards to all of the .qmail-exts.  Note that qmail-
       local can handle any number of forward lines simultaneously.

SEE ALSO

       envelopes(5),  maildir(5),  mbox(5),  qmail-users(5),   qmail-local(8),
       qmail-command(8), qmail-queue(8), qmail-lspawn(8)

                                                                  dot-qmail(5)