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



NAME
     dot-qmail - control the delivery of mail messages

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

THE QMAIL FILE
     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 delivery
     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 infor-
          mation.

     (3)  A forward line begins with an ampersand:

               &me@new.job.com

          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  quali-
          fied  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)




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:

               me@new.job.com

          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:

               /home/djb/Mailbox.sos

          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 mbox(5).

          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  accessible
          file!

          If  qmail-alias 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:

               /home/djb/Maildir/

          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.




SunOS 5.5                 Last change:                          2






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



     If .qmail is world-writable or  group-writable,  qmail-alias
     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-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 to

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

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-alias 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-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  nonexistent
     .qmail the same as an empty .qmail.)

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



SunOS 5.5                 Last change:                          3






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



     When  qmail-alias  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-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  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-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.

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




















SunOS 5.5                 Last change:                          4