Ubuntu Manpage: dot-qmail - control the delivery of mail messages

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, 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.
(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