dot-qmail(5)							File Formats Manual						      dot-qmail(5)

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 direc-
       tory.

       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 possi-
	    ble.  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.  (Excep-
       tion: 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  mes-
       sage.   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)