Provided by:
courier-mta_0.47-13ubuntu5_i386 
NAME
dot-courier - Local mail delivery instructions
SYNOPSIS
$HOME/.courier
$HOME/.courier-foo
/etc/courier/aliasdir/.courier-foo
DESCRIPTION
In most cases delivering mail to an account means simply placing the
message in the account’s system mailbox, but that does not have to be
the case. Alternate mail delivery instructions include running a
separate program to process the message, or forwarding the message to
another address. The various .courier files specify some basic mail
delivery instructions. If sophisticated mail filtering is required, the
delivery instructions should include running an external mail filter,
such as maildrop(1).
The file $HOME/.courier specifies how messages are delivered to this
account. If this file does not exist, default instructions set by the
system administrator are used. The system administrator’s default
instructions specify the location of the account’s system mailbox.
In addition to receiving mail addressed user@domain, it is also
possible for user to receive mail addressed to user-foo@domain, for
arbitrary values of foo. To do this, install $HOME/.courier-foo, with
delivery instructions for mail addressed to user-foo@domain.
The system administrator can configure Courier to accept mail without
regard to whether addresses are in uppercase and lowercase. In that
case the name of a .courier file must contain only lowercase
characters. In any event, all periods in the address must be replaced
with colons. For example, to specify delivery instructions for user-
Foo.Bar@domain, put the delivery instructions in ~user/.courier-
foo:bar.
The file $HOME/.courier-foo-default specifies delivery instructions for
any user-foo-bar@domain address, where bar can be anything. However, it
does NOT control mail delivery to user-foo@domain, which is controlled
by $HOME/.courier-foo.
Possible mail delivery instructions include: whether each message
should be delivered to a non-standard mailbox; forwarded to another E-
mail address; or if another program should be executed to handle the
message. Programs executed from a .courier file have access to some
environment variables (see ENVIRONMENT VARIABLES). Programs executed
from a -default file can read those environment variables to determine
the exact E-mail address the message was delivered to.
DEFAULT DELIVERY INSTRUCTIONS
The /etc/courier/aliasdir directory is searched as the last resort,
when all attempts to figure out how to deliver mail to a local address
have failed.
/etc/courier/aliasdir’s functionality is very similar to how the alias
account is implemented in Qmail, except that no actual system account
is needed. If <user@example.com> is a local address, and there is no
such system account, nor is there an alias defined for this address,
Courier attempts to read delivery instructions from
/etc/courier/aliasdir/.courier-user.
All the usual aspects of .courier deliveries apply. If there is no
account that corresponds to the address <user-foo@example.com>, Courier
looks for /etc/courier/aliasdir/.courier-user-foo, then
/etc/courier/aliasdir/.courier-user-default, and finally
/etc/courier/aliasdir/.courier-default.
It therefore follows that you can use /etc/courier/aliasdir/.courier-
default to specify local mail delivery instructions for addresses that
do not exist. Combined with dynamic mail delivery instructions (see
below), that’s one way to specify non-standard locations of mailboxes.
PROGRAM/MAILBOX ALIASES
The directory /etc/courier/aliasdir/.courier-:xalias/ is created and
maintained by the makealiases(8) script to implement aliases that
deliver directly to programs or mailboxes. See makealiases(8) for more
information. (This directory corresponds to local addresses that begin
with ".xalias/", but Courier prohibits explicit local addresses that
begin with a period).
Additionally, makealiases(8) creates subdirectories named
/etc/courier/aliasdir/.courier-:xalias-protocol/, where "protocol" is
set by the -m option.
DELIVERY INSTRUCTIONS
Each .courier file specifies zero or more delivery instructions. If
the .courier file is zero bytes long, it means that default mail
delivery instructions set by the system administrator should be used.
If the file is not a zero length file, and does not specify any
delivery instructions, messages to the corresponding E-mail address are
silently discarded.
Note: If $HOME/.courier does not exist, it is treated as a zero-
length file, resulting in a delivery to a default mailbox. If
$HOME/.courier-foo does not exist, it is treated as a non-
existent address, returning the message as undeliverable.
If home directories have global read and execute permissions, Courier
will be able to reject mail to non-existent mailboxes right away.
Courier’s ESMTP server runs as a non-privileged process. It will not be
able to access home directories which do not have global read and
execute permissions. Therefore, the message will be accepted for
delivery, by Courier. As soon as an attempt to deliver the message is
made, the missing .courier file will result in the message being
returned as undeliverable. However, here Courier has to accept the
message for delivery first, before generating a non-delivery report.
Delivery instructions in .courier are executed one at a time. If the
execution of a delivery instruction fails for some reason, the message
is either returned as undeliverable, or requeued for another delivery
attempt. Messages that remain queued for a long period of time are
returned as undeliverable.
Note: Even if one delivery instruction fails (and the message is
returned as undeliverable) previous delivery instructions in the
file will have been completed anyway.
Blank lines in the file are ignored. Lines starting with the #
character are comments, and are also ignored. Otherwise, each line
specifies one of three possible delivery instructions: deliver to a
system mailbox or a Maildir; run an external program; or forward the
message to another address.
DELIVERY TO A SYSTEM MAILBOX OR A MAILDIR
Lines that start with the . or the / character specify a mailbox or a
Maildir delivery. The line must specify the complete location of the
mailbox file, or a Maildir. Filenames starting with . are relative to
the account’s home directory. A mailbox file is a traditional mailbox
file that’s readable by most mail software. A Maildir is a directory
based mail storage format that offers several advantages over mailbox
files. Mailbox files must be locked, and therefore they do not permit
concurrent mail deliveries. The mailbox file must be locked while a new
message is appended to it, otherwise multiple messages being delivered
at the same time will trample all over each other. Maildirs do not
require locking, and multiple concurrent deliveries can be made to the
same Maildir. You can create Maildirs by using the maildirmake(1)
command.
Note: Courier does not implement the "dot-locking" form of
mailbox file locking. Courier’s locking abilities are limited
solely to system file locking facilities (namely the lockf, or
flock system calls). You can always use maildrop(1), which
offers additional locking options.
RUNNING AN EXTERNAL PROGRAM
Lines that begin with a single | character run an external program. The
rest of the line specifies the command to be executed by the shell.
Long commands can be continued on another line by terminating the
previous line with the \ character.
Courier runs the specified command, and provides the contents of the
message on standard input.
Courier waits until the external command completes execution before
going to the next delivery instruction. Courier examines the exit code
of the external command in order to determine whether the delivery
failed, or not.
If the external command terminates with the exit code of zero, the next
delivery instruction is executed. If the command was the last delivery
instruction in the file, the message is considered to be successfully
delivered.
If the external command terminates with the exit code of 99, any
additional delivery instructions in the file are NOT executed, but the
message is considered to be successfully delivered.
If the external command terminates with any of the following exit
codes: 64, 65, 67, 68, 69, 70, 76, 77, 78, or 112, the E-mail message
will be returned as undeliverable, and no further delivery instructions
will take place.
If the external command terminates with any other exit code, it is
interpreted as a temporary error, and the message will be requeued for
another delivery attempt later.
Note: On subsequent delivery attempts, delivery instructions
will be carried out from the beginning of the .courier file.
DYNAMIC DELIVERY INSTRUCTIONS
Lines that begin with the || characters also run an external program.
The rest of the line specifies the command to be executed by the shell.
Long commands can be continued on another line by terminating the
previous line with the \ character.
However, programs that are executed by the || instruction, unlike |,
have their standard output captured, and reinterpreted as additional
delivery instructions to be carried out. This feature allows an
external program to be invoked to generate dynamic delivery
instructions to be carried out by Courier.
The standard output of the external program is read and parsed as if it
contained .courier delivery instructions. There’s a fixed upper limit
on the number of bytes in dynamically-generated delivery instructions.
For glibc, the limit is 8191 bytes, other systems’s upper limit should
be similar.
The dynamically generated delivery instructions may also specify ||
instructions, recursively. There is an upper limit of four recursive
dynamically-generated delivery instructions.
The exit code of the program invoked by the || instructions are
interpreted exactly like the exit code of a program invoked by |, with
the following exceptions. Dynamically-generated delivery instructions
are carried out only if the external program terminates with an exit
code of 0 or 99. Any other exit code discards any dynamically-
generated delivery instructions. All other aspects of exit code
treatment of external programs remains the same. If the exit code is
99, the delivery is deemed to be successful, and any additional
instructions in the original .courier file are ignored. If the exit
code is 0, the remaining instructions in the original .courier file are
executed.
ALIAS-BASED DELIVERIES
When Courier delivers to default delivery instructions in
/etc/courier/aliasdir, those delivery instructions are carried out
under Courier’s installed system user and group id. That means that any
executed programs or mailboxes are accessed as Courier’s mail system
user and group.
ENVIRONMENT VARIABLES
External commands executed from the .courier file will have the
following environment variables:
HOME The home directory.
USER The recipient’s userid.
SENDER The message envelope return address.
RECIPIENT
The complete receipient address.
HOST When RECIPIENT is of the form user@domain, HOST contains the
domain part of the address.
LOCAL When RECIPIENT is of the form user@domain, LOCAL contains the
user part of the address.
EXT When USER is of the form $USER-foobar, EXT will contain the
foobar part.
EXT2 The portion of EXT that follows the first dash.
EXT3 The portion of EXT2 that follows the first dash.
EXT4 The portion of EXT3 that follows the first dash.
DEFAULT
When delivery instructions for the address user-foo-bar@domain
come from the file $HOME/.courier-foo-default, DEFAULT will
contain the bar part.
UFLINE This environment variable contains the entire From_ header that
should be prepended to the message if it is to be delivered to a
mailbox.
RPLINE This environment variable contains the entire Return-Path:
header.
DTLINE This environment variable contains the entire Delivered-To:
header.
Note: When the external program reads the message from standard
input, the message will NOT have the customary From_, Return-
Path:, and Delivered-To: headers which are customary for
locally-delivered messages. The external program can find those
headers in the respective environment variables. If you have a
command that expects to see those headers as a part of the
message, you can use the preline(1) wrapper to add them to the
message. For example, the procmail mail filter requires those
headers.
Note: The maildrop mail filter will not require preline if the
system administrator correctly configures Courier. The system
administrator can optionally configure Courier to recognize
maildrop, and activate certain maildrop-specific optimizations
in Courier. If these arrangemenets have been made, you can run
maildrop directly from the .courier file, in a straightforward
fashion, but those headers will automatically appear in the
message, as seen by maildrop. Because the message is provided
directly on standard input, without using a pipe, maildrop will
be able to deliver the message directly from Courier’s message
queue, without using a temporary file.
FORWARDING
Lines that do not start with the ., /, or the | character specify a
comma-separated list of E-mail addresses to forward the message to. If
the line starts with either the & or the ! character, the character is
ignored; this is a legacy compatibility option.
BUGS
Courier’s .courier may seem to be exactly like Qmail’s .qmail, but
there are some minor differences. Qmail, as of 1.03, does not implement
dynamic delivery instructions. Courier also uses a slightly different
set of return codes which are classified as hard errors. Courier’s
implementation of forwarding differs from Qmail’s. According to Qmail’s
documentation, if any external command terminates in a permanent or
temporary failure, the message is not forwarded to any forwarding
address in the .qmail file, even to addresses that precede the failed
delivery instruction. The message is forwarded only after it is
successfully delivered. Courier forwards messages to addresses
immediately. Also, in some cases Qmail resets the return address on the
message to the address of the account being forwarded.
To make things more confusing, there is a configuration setting to have
Courier read $HOME/.qmail files, instead of $HOME/.courier.
SEE ALSO
dot-forward(1), maildirmake(1), maildrop(1), courier(8).