Provided by: courier-mta_0.58.0.20080127-1ubuntu1_i386 bug

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 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)[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 Courier 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, 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)[3]
       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)[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, 100, 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)[4] 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)[5], maildirmake(1)[3], maildrop(1)[1], courier(8)[6].

REFERENCES

        1. maildrop(1)
           maildrop.html

        2. makealiases(8)
           makealiases.html

        3. maildirmake(1)
           maildirmake.html

        4. preline(1)
           preline.html

        5. dot-forward(1)
           dot-forward.html

        6. courier(8)
           courier.html