.TH dot-qmail 5

.SH NAME

dot-qmail \- control the delivery of mail messages

.SH DESCRIPTION

Normally the

.B qmail-local

program delivers each incoming message to your system mailbox,

.IR homedir\fB/Mailbox ,

where

.I 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.

.SH "THE QMAIL FILE"

To change

.BR qmail-local 's

behavior, set up a

.B .qmail

file in your home directory.

.B .qmail

contains one or more lines.

Each line is a delivery instruction.

.B qmail-local

follows each instruction in turn.

There are five types of delivery instructions:

(1) comment; (2) program; (3) forward; (4) mbox; (5) maildir.

.TP 5

(1)

A comment line begins with a number sign:

.EX

     # this is a comment

.EE

.B qmail-local

ignores the line.

.TP 5

(2)

A program line begins with a vertical bar:

.EX

     |preline /usr/ucb/vacation djb

.EE

.B qmail-local

takes the rest of the line as a command to supply to

.BR sh .

See

.B qmail-command(8)

for further information.

.TP 5

(3)

A forward line begins with an ampersand:

.EX

     &me@new.job.com

.EE

.B qmail-local

takes the rest of the line as a mail address;

it uses

.B 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:

.EX

     # the following examples are WRONG

.br

     &me@new

.br

     &<me@new.job.com>

.br

     & me@new.job.com

.br

     &me@new.job.com (New Address)

.EE

If the address begins with a letter or number,

you may leave out the ampersand:

.EX

     me@new.job.com

.EE

Note that

.B qmail-local

omits its new

.B Return-Path

line when forwarding messages.

.TP 5

(4)

An 

.I mbox

line begins with a slash or dot,

and does not end with a slash:

.EX

     /home/djb/Mailbox.sos

.EE

.B qmail-local

takes the entire line as a filename.

It appends the mail message to that file,

using

.BR flock -style

file locking if possible.

.B qmail-local

stores the mail message in

.I mbox

format, as described in

.BR mbox(5) .

.B WARNING:

On many systems,

anyone who can read a file can

.B flock

it, and thus hold up

.BR qmail-local 's

delivery forever.

Do not deliver mail to a publicly accessible file!

If

.B 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.

.TP 5

(5)

A

.I maildir

line begins with a slash or dot,

and ends with a slash:

.EX

     /home/djb/Maildir/

.EE

.B qmail-local

takes the entire line as the name of a directory in

.I maildir

format.

It reliably stores the incoming message in that directory.

See

.B maildir(5)

for more details.

.PP

If

.B .qmail

has the execute bit set,

it must not contain any

program lines,

.I mbox

lines,

or

.I maildir

lines.

If

.B qmail-local

sees any such lines,

it will stop and indicate a temporary failure.

If

.B .qmail

is completely empty (0 bytes long), or does not exist,

.B qmail-local

follows the

.I defaultdelivery

instructions set by your system administrator;

normally

.I defaultdelivery

is

.BR ./Mailbox ,

so

.B qmail-local

appends the mail message to

.B Mailbox

in

.I mbox

format.

.B .qmail

may contain extra spaces and tabs at the end of a line.

Blank lines are allowed, but not for the first line of

.BR .qmail .

If

.B .qmail

is world-writable or group-writable,

.B qmail-local

stops and indicates a temporary failure.

.SH "SAFE QMAIL EDITING"

Incoming messages can arrive at any moment.

If you want to safely edit your

.B .qmail

file, first set the sticky bit on your home directory:

.EX

     chmod +t $HOME

.EE

.B 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

.EX

     chmod -t $HOME

.EE

when you are done!

It's a good idea to test your new

.B .qmail

file as follows:

.EX

     qmail-local -n $USER ~ $USER '' '' '' '' ./Mailbox

.EE

.SH "EXTENSION ADDRESSES"

In the

.B qmail

system,

you control all local addresses of the form

.IR user\fBBREAK\fIanything ,

as well as the address

.I user

itself,

where

.I user

is your account name.

Delivery to

.I user\fBBREAK\fIanything

is controlled by the file

.IR homedir/\fB.qmail\-\fIanything .

(These rules may be changed by the system administrator;

see

.BR qmail-users (5).)

The

.B alias

user controls all other addresses.

Delivery to

.I local

is controlled by the file

.IR homedir/\fB.qmail\-\fIlocal ,

where

.I homedir

is

.BR alias 's

home directory.

In the following description,

.B qmail-local

is handling a message addressed to

.IR local@domain ,

where

.I local

is controlled by

.BR .qmail\-\fIext .

Here is what it does.

If

.B .qmail\-\fIext

is completely empty,

.B qmail-local

follows the

.I defaultdelivery

instructions set by your system administrator.

If

.B .qmail\-\fIext

doesn't exist,

.B qmail-local

will try some default

.B .qmail

files.

For example,

if

.I ext

is

.BR foo-bar ,

.B qmail-local

will try first

.BR .qmail-foo-bar ,

then

.BR .qmail-foo-default ,

and finally

.BR .qmail-default .

If none of these exist,

.B qmail-local

will bounce the message.

(Exception: for the basic

.I user

address,

.B qmail-local

treats a nonexistent

.B .qmail

the same as an empty

.BR .qmail .)

.B WARNING:

For security,

.B qmail-local

replaces any dots in

.I ext

with colons before checking

.BR .qmail\-\fIext .

For convenience,

.B qmail-local

converts any uppercase letters in

.I ext

to lowercase.

When

.B qmail-local

forwards a message as instructed in

.B .qmail\-\fIext

(or

.BR .qmail-default ),

it checks whether

.B .qmail\-\fIext\fB-owner\fP

exists.

If so,

it uses

.I local\fB-owner@\fIdomain

as the envelope sender for the forwarded message.

Otherwise it retains the envelope sender of the original message.

Exception:

.B qmail-local

always retains the original envelope sender

if it is the empty address or

.BR #@[] ,

i.e., if this is a bounce message.

.B qmail-local

also supports

.B variable envelope return paths

(VERPs):

if

.B .qmail\-\fIext\fB-owner\fP

and

.B .qmail\-\fIext\fB-owner-default\fP

both exist, it uses

.I local\fB\-owner\-@\fIdomain\fB-@[]

as the envelope sender.

This will cause a recipient

.I recip\fB@\fIreciphost

to see an envelope sender of

.IR local\fB\-owner\-\fIrecip\fB=\fIreciphost\fB@\fIdomain .

.SH "ERROR HANDLING"

If a delivery instruction fails,

.B qmail-local

stops immediately and reports failure.

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

.B qmail-local

ignores all succeeding lines in

.BR .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

.B .qmail\-\fIext

file, and set up a central

.B .qmail

file that forwards to all of the

.BR .qmail\-\fIext s.

Note that

.B qmail-local

can handle any number of forward lines simultaneously.

.SH "SEE ALSO"

envelopes(5),

maildir(5),

mbox(5),

qmail-users(5),

qmail-local(8),

qmail-command(8),

qmail-queue(8),

qmail-lspawn(8)