Ubuntu Manpage: dot-courier - Local mail delivery instructions

Provided by: courier-mta_1.0.6-1build2_amd64

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)[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 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-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, 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.

Program/mailbox aliases
The directory /etc/courier/aliasdir/.courier-:xalias/ is created and maintained by the
makealiases(8)[2] script to implement aliases that deliver directly to programs or
mailboxes. See makealiases(8)[2] 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)[2] 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, 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.

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)[3] command.

Note
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)[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.

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[4]” section of the installation instructions;
see courier(8)[5] 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.

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

Alias-based deliveries
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.

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)[6] 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 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.

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

       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.

AUTHOR

       Sam Varshavchik
           Author

NOTES