dot-qmail(5)       Headers, Tables, and Macros       dot-qmail(5)

     dot-qmail - control the delivery of mail messages

     Normally the qmail-local program delivers each incoming mes-
     sage  to your system mailbox, homedir/Mailbox, where homedir
     is your home directory.

     It can instead write the mail to a different file or  direc-
     tory,  forward  it  to  another  address, distribute it to a
     mailing list, or even execute programs, all under your  con-

     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:

               |/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 infor-

     (3)  A forward line begins with an ampersand:


          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  quali-
          fied  domain  name;  it  must not contain extra spaces,
          angle brackets, or comments:

               # the following examples are WRONG
               & (New Address)

SunOS 5.5                 Last change:                          1

dot-qmail(5)       Headers, Tables, and Macros       dot-qmail(5)

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


          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:


          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

          If qmail-local is able to lock the file, but has  trou-
          ble  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:


          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

     If .qmail is completely empty (0 bytes long),  or  does  not
     exist,  qmail-local  follows the aliasempty instructions set
     by your system administrator; normally aliasempty is ./Mail-
     box,  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

SunOS 5.5                 Last change:                          2

dot-qmail(5)       Headers, Tables, and Macros       dot-qmail(5)

     of .qmail.

     If .qmail is world-writable or  group-writable,  qmail-local
     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-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 $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 homedir/.qmail-anything.  (These
     rules may  be  changed  by  the  system  administrator;  see

     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 mes-
     sage 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
     aliasempty 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,

SunOS 5.5                 Last change:                          3

dot-qmail(5)       Headers, Tables, and Macros       dot-qmail(5)

     qmail-local converts any uppercase letters in ext to  lower-

     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

     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.

     If a delivery instruction fails, qmail-local  stops  immedi-
     ately  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.

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

SunOS 5.5                 Last change:                          4