dot-qmail - control the delivery of mail messages


       Normally  the  qmail-alias  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


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

       .qmail  contains one or more lines.  Each line is a deliv-
       ery instruction.  qmail-alias 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-alias ignores the line.

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

                 |/usr/ucb/vacation djb

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

       (3)  A forward line begins with an ampersand:


            qmail-alias  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
                 & (New Address)

            If  the  address  begins with a letter or number, you

            Note that qmail-alias 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:


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

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

            If  qmail-alias  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 orig-
            inal length.  However, it cannot prevent mailbox cor-
            ruption if the system crashes during delivery.

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


            qmail-alias 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-
       alias  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-alias appends the mail message to your system
       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 or group-writable, qmail-alias
       stops and indicates a temporary failure.

       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-alias 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

            chmod -t $HOME

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

            qmail-alias -n $USER $HOME $USER '' '' '' ''


       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    home-
       dir/.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-alias  is  handling  a
       message  addressed  to  local@domain,  where local is con-
       trolled by .qmail-ext.  Here is what it does.

       If .qmail-ext is completely empty, qmail-alias appends the
       mail message to your system mailbox.

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

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

       When qmail-alias  forwards  a  message  as  instructed  in
       .qmail-ext   (or   .qmail-default),   it   checks  whether
       sage.  Otherwise it retains the  envelope  sender  of  the
       original  message.   Exception: qmail-alias always retains
       the original envelope sender if it is the empty address or
       #@[], i.e., if this is a bounce message.

       qmail-alias  also  supports the owner hack: if .qmail-ext-
       owner and .qmail-ext-owner-default  both  exist,  it  uses
       local-owner-  as  the  envelope sender.  This will cause a
       recipient recip@reciphost to see  an  envelope  sender  of


       If a delivery instruction fails, qmail-alias stops immedi-
       ately and reports failure.  qmail-alias 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-alias 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-alias can  handle
       any number of forward lines simultaneously.


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