dot-qmail - control the delivery of mail messages
DESCRIPTION
Normally the qmail-alias 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-alias's behavior, set up a .qmail file in
your home directory.
.qmail contains one or more lines. Each line is a deliv-
ery 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
information.
(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
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
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 accessi-
ble file!
If qmail-alias 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 orig-
inal length. However, it cannot prevent mailbox cor-
ruption 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.
If .qmail is world-writable or group-writable, qmail-alias
stops and indicates a temporary failure.
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 home-
dir/.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
message addressed to local@domain, where local is con-
trolled 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 nonexis-
tent .qmail the same as an empty .qmail.)
WARNING: For security, qmail-alias replaces any dots in
ext with colons before checking .qmail-ext. For conve-
nience, qmail-alias converts any uppercase letters in ext
to lowercase.
When qmail-alias forwards a message as instructed in
.qmail-ext (or .qmail-default), it checks whether
sage. 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 the owner hack: if .qmail-ext-
owner and .qmail-ext-owner-default both exist, it uses
local-owner- 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)