Provided by: courier-mta_0.47-13ubuntu5_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).

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