qmail-alias(8)

NAME
qmail-alias - deliver or forward a mail message

SYNOPSIS
qmail-alias [ -nN ] user homedir ext domain sender

DESCRIPTION
Normally qmail-alias reads a mail message and tosses it into user's system mailbox, homedir/Mailbox. 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 the control of the user. See below for more details. The message's envelope recipient is userext@domain. qmail-alias records userext@domain in a new Delivered-To header field. If exactly the same Delivered-To: userext@domain already appears in the header, qmail-alias bounces the message, to prevent mail forwarding loops. The message's envelope sender is sender. qmail-alias records sender in a new Return-Path header field. The standard input for qmail-alias must be a seekable file, so that qmail-alias can read it more than once.

THE QMAIL FILE
The user can change qmail's behavior by setting up a .qmail file in his home directory, homedir. Note that homedir must be an absolute directory name. .qmail contains one or more lines. Each line is a delivery 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 may leave out the ampersand:
             me@new.job.com
    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 (actually, mboxrd) format: it starts the message with a UUCP-style From (no colon) line, it ends the message with a blank line, and it inserts > before any line starting From or >From or >>From etc. 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 accessible 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 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-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 the user's system mailbox in mbox format. .qmail may contain extra spaces and tabs at the end of a line. It may also contain blank lines. If .qmail is world-writable or group-writable, qmail-alias 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-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 '' '' ''

EXTENSION ADDRESSES
In the qmail system, each user controls all mail addresses of the form user-anything. The ext argument to qmail-alias is then -anything. For the usual user mail address, ext is the empty string. Delivery to userext is controlled by the file .qmailext in homedir. If this file is completely empty, qmail-alias appends the mail message to the user's system mailbox. If .qmailext doesn't exist, and ext contains dashes, 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 empty extension, i.e., a plain user address, qmail-alias treats a nonexistent .qmail the same as an empty .qmail.) WARNING: For security, qmail-alias replaces any dots in ext with colons. When qmail-alias forwards a message as instructed in .qmailext (or .qmail-default), it checks whether .qmailext-owner exists. If so, it uses userext-owner@domain as the envelope sender for the forwarded message. 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.

ERROR HANDLING
If a delivery instruction fails, qmail-alias stops immediately 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 .qmailext file, and set up a central .qmail file that forwards to all of the .qmailexts. Note that qmail-alias can handle any number of forward lines simultaneously.

OPTIONS

-n  Instead of reading and delivering the message, print a description of the delivery instructions.

-N  (Default.) Read and deliver the message.

EXIT CODES
0 if the delivery is completely successful; nonzero if any delivery instruction failed. Exit codes 71, 74, 75, 111, and 120 indicate temporary failures.

SEE ALSO
envelopes(5), qmail-command(8), qmail-queue(8), qmail-send(8), qmail-lspawn(8)