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 or group-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 userBREAKanything, as well as the address user itself,
          where user is your account name.  Delivery to
          userBREAKanything 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)