MAN PAGES FOR QMAIL 1.03
NAME
dot-qmail - control the delivery of mail messages
DESCRIPTION
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-
trol.
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 infor-
mation.
(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 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)
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 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-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 userBREAKany-
thing 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 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
defaultdelivery instructions set by your system administra-
tor.
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 lower-
case.
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 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.
SEE ALSO
envelopes(5), maildir(5), mbox(5), qmail-users(5), qmail-
local(8), qmail-command(8), qmail-queue(8), qmail-lspawn(8)