dot-courier — Local mail delivery instructions
$HOME/.courier $HOME/.courier-foo /etc/courier/aliasdir/.courier-foo
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 either
user-
foo@domainuser+,
for arbitrary values of foo@domainfoo. To do
this, install $HOME/.courier-, with delivery
instructions for mail addressed to
either foouser-foo@domain or
either user+foo@domain.
Whether it's
user+ or
foo@domainuser-, this is
controlled by
foo@domain$HOME/.courier-.
All occurences of “+” characters in the email address
are replaced by a “-”. The corresponding
foo.courier file then gets processed.
All examples in the following documentation use “-”
in E-mail addresses, but this also applies to
“+” as well (however
note that all actual .courier
filenames always use “-” for a separator character).
“+” is the default content of
the /etc/courier/defaultsep configuration file,
if it does not exist. This configuration file
contains a single line with a list of all punctuation characters
that are considered to be equivalent to “-”.
A single, empty, blank line in
/etc/courier/defaultsep results in recognizing
only “-” as the separator character.
The system administrator can configure the
Courier mail server 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- address, where
bar@domainbar 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.
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, the Courier mail server
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>, the
Courier mail server 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.
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 the
Courier mail server prohibits explicit
local addresses that
begin with a period).
Additionally,
makealiases(8)
creates subdirectories named
/etc/courier/aliasdir/.courier-:xalias-, where
"protocol/protocol" is set by the -m option.
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.
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, the
Courier mail server will
be able to reject mail to non-existent mailboxes right away. the
Courier mail server'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 the
Courier mail server. 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 the
Courier mail server
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.
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.
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.
The Courier mail server does not
implement the "dot-locking" form of
mailbox file locking. The Courier mail
server'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.
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.
The Courier mail server runs the specified command, and provides the contents of the message on standard input.
The Courier mail server waits until the external command completes execution before going to the next delivery instruction. The Courier mail server 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 the “EX_SOFTWARE” exit code, which is usually 70, on most platforms, the E-mail message gets returned as undeliverable, a non-delivery report, and no further delivery instructions takes place.
If the external command terminates with any of the following exit codes: 64, 65, 67, 68, 69, 76, 77, 78, 100, or 112, the delivery attempt is considered to be failed, and the next course of action gets selected by Courier mail server's backscatter suppression settings, as described in the “ Backscatter Suppression” section of the installation instructions; see courier(8) for more information.
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.
On subsequent delivery attempts, delivery
instructions will be carried out from the beginning of the
.courier file.
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 the Courier mail server.
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.
When the Courier mail server delivers to default delivery instructions in
/etc/courier/aliasdir, those delivery instructions are carried
out under the Courier mail server's installed system user and group id. That means that any
executed programs or mailboxes are accessed as the Courier mail server's mail system user and
group.
External commands executed from the .courier file will have the
following environment variables:
HOMEThe home directory.
USERThe recipient's userid.
SENDERThe message envelope return address.
RECIPIENTThe 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.
EXT,
EXT2,
EXT3 and
EXT4 use “-” as a separator even if the
recipient address used the equivalent “+” characters,
or any suitable separator character specified in the
/etc/courier/defaultsep configuration file,
instead.
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.
The maildrop mail filter will not require
preline if the system administrator correctly configures
the Courier mail server.
The system administrator can optionally configure the Courier mail server to recognize
maildrop, and activate certain
maildrop-specific
optimizations in the Courier mail server. 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 the Courier mail server's message queue, without
using a temporary file.
The Courier mail server'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. The Courier mail server also uses a slightly
different set of return codes which are classified as hard errors. The Courier mail server'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.
The Courier mail server 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
the Courier mail server read $HOME/.qmail files, instead of
$HOME/.courier.