Provided by: maildrop_1.5.3-2_i386 bug

NAME

       maildrop - mail delivery filter/agent

SYNOPSIS

       maildrop [ option ... ] [ -d user ] [ arg ... ]

       maildrop [ option ... ] [ filename ] [ arg ... ]

DESCRIPTION

       maildrop  is  a  replacement  local mail delivery agent that includes a
       mail filtering language.  The system administrator can  either  replace
       the  existing  mail  delivery  agent  with  maildrop,  or users may run
       maildrop using the ’forward to program’ mechanism of the existing  mail
       delivery agent.

       maildrop  first  reads  the E-mail message on standard input.  Trailing
       carriage return  characters  are  automatically  stripped.   An  E-mail
       message consists of header lines, followed by a blank line, followed by
       the contents of the message. The  message  may  contain  an  mbox-style
       From_  line  before  the  first  header  line.  If the message does not
       contain a From_ line, maildrop will create one (if needed).

       If the file /etc/maildroprc exists, mail  delivery  or  mail  filtering
       instructions  are  read  from that file.  maildrop’s delivery/filtering
       instructions may direct  maildrop  to  save  the  message  in  specific
       mailbox,  discard it, return it to sender, or forward it to a different
       E-mail address.

       If /etc/maildroprc does not exist, or its mail delivery instructions do
       not  completely  dispose  of this message, maildrop then reads the mail
       delivery instructions from $HOME/.mailfilter.  If it doesn’t exist,  or
       its  mail  delivery  instructions  do  not  completely  dispose  of the
       message, maildrop then saves the E-mail message in the default mailbox.

       maildrop  knows  how  to  deliver mail to an standard mailbox files; it
       also knows how to deliver to maildirs. A maildir is  a  directory-based
       mail  format  used  by  the Courier and Qmail mail servers.  Many other
       mail servers also know  how  to  read  maildirs.   When  delivering  to
       mailbox  files,  maildrop will lock the mailbox for the duration of the
       delivery.

       At least one mail program writes an empty line before  a  From_  header
       when  saving a message into a file. maildrop ignores empty lines at the
       beginning of messages.  Therefore, maildrop requires that every message
       must have at least one header line.

       This   is   the  general  mail  delivery  behavior.   There  are  minor
       differences in behavior depending on maildrop delivery mode,  which  is
       determined  based  on  how  maildrop  was started.  maildrop uses three
       different primary operating modes:

       Manual mode
              A file containing filtering instructions - filename is specified
              as  an  argument  to  the maildrop command.  maildrop reads this
              filename (after /etc/maildroprc) and follows the instructions in
              it.   Unless  the  message  is  explicitly  forwarded,  bounced,
              deleted,  or  delivered  to  a  specific  mailbox,  it  will  be
              delivered to the user’s system mailbox.

       Delivery mode
              maildrop  is  the  mail  server’s mail delivery agent.  maildrop
              runs in delivery mode when  no  filename  is  specified  on  the
              command  line.   maildrop  changes  the current directory to the
              user’s  home  directory,  then   reads   /etc/maildroprc,   then
              $HOME/.mailfilter.

       Embedded mode
              maildrop  functions  as  a  part  of  another  application.  The
              embedded mode is used by the Courier mail  server  to  integrate
              mail  filtering directly into the process of receiving mail from
              a remote mail relay, thus rejecting unwanted mail before  it  is
              even  accepted  for  local mail delivery.  Embedded mode is used
              when either the -m, or the  -M,  option  is  specified,  and  is
              described  below.  See below for a more extensive description of
              the embedded mode.

SECURITY

       It is safe to install maildrop  as  a  root  setuid  program.   Courier
       installs  maildrop  as a root setuid program by default, in order to be
       able to use maildrop in embedded mode.  If root runs maildrop (or it is
       setuided  to  root)  the -d option may be used to specify the message’s
       recipient. maildrop immediately resets its userid to the one  specified
       by  the -d option. The user’s $HOME/.mailfilter is read (if it exists),
       and the message is delivered to the indicated user.

       The system administrator can configure  maildrop  to  restrict  the  -d
       option for everyone except the mail system itself.

       If  in  delivery mode the user’s home directory has the sticky bit set,
       maildrop immediately terminates  with  an  exit  code  of  EX_TEMPFAIL,
       without  doing  anything.   Mail servers interpret the EX_TEMPFAIL exit
       code as a request  to  reschedule  the  message  for  another  delivery
       attempt  later.  Setting  the sticky bit allows $HOME/.mailfilter to be
       edited while temporarily holding all incoming mail.

       maildrop also terminates with EX_TEMPFAIL if the user’s home  directory
       has world write permissions.

       maildrop immediately terminates with EX_TEMPFAIL if the filename is not
       owned by the user, or if it has any group or  world  permissions.  This
       includes  read  permissions.   The permissions on $HOME/.mailfilter may
       only include read and write privileges to the user.

       When using the special embedded mode (see below)  maildrop  immediately
       terminates  with the exit code set to EX_TEMPFAIL if $HOME/.mailfilters
       is not owned by the user, or if it has any group or world  permissions.

TEMPORARY FILES

       maildrop  is  heavily optimized and tries to use as little resources as
       possible. maildrop reads smalle  messages  into  memory,  then  filters
       and/or  delivers the message directly from memory. For larger messages,
       maildrop accesses the message directly from the file.  If the  standard
       input  is  not a file, maildrop writes the message to a temporary file,
       then accesses the message from the temporary file. The  temporary  file
       is automatically removed when the message is delivered.

OPTIONS

       -A "Header: value"
              Adds  an  additional  header to the message. Specifying -A "Foo:
              Bar"  effectively  adds  this  header  to  the   message   being
              delivered.

              The  mail  transport  agent usually adds additional headers when
              delivering a message to a local mailbox. The  way  it’s  usually
              done  is by the mail transport agent sending the message using a
              pipe to the local delivery agent - such as maildrop - and adding
              some  additional  headers  in  the  process.   Because  maildrop
              receives the message from a pipe, maildrop must either save  the
              message in memory or write the message into a temporary file.

              The  -A  option  enables  the  file containing the message to be
              provided to  maildrop  directly,  as  standard  input,  and  the
              additional  headers  specified on the command line.  Because the
              standard input is a file, maildrop will  not  need  a  temporary
              file.  Multiple -A options may be specified.

       -d user
              Run maildrop in delivery mode for this user ID.

              The  system  administrator may optionally restrict the -d option
              to be available to the mail  system  only,  so  it  may  not  be
              available  to  you.   In  all cases, the -d option is allowed if
              user is the same user who is running maildrop.  Also, for the -d
              option  to  work  at  all, maildrop must be executed by root, or
              maildrop must be a root-owned program with the setuid  bit  set.
              Absence  of a filename on maildrop’s command line implies the -d
              option for the user running maildrop.

              If -d is not specified, the first  argument  following  all  the
              options is a name of the file containing filtering instructions.
              The remaining arguments, if any, are assigned to  the  variables
              $1,   $2,   and   so   on   (see   "Environment"  and  "Variable
              substitution").

       -f address
              Sets the FROM variable (message  envelope  sender)  to  address.
              The  system  administrator  may optionally disable the -f option
              for users, so it may not be available to you.

       -m     Run maildrop in embedded mode.  It’s possible to  use  both  the
              -m, and the -d options, but it doesn’t make much sense to do so.
              Even if you really wanted to run your  message  through  someone
              else’s  .mailfilter,  that .mailfilter probably has at least one
              instruction which is not allowed in the embedded mode.

              The filename argument to maildrop should be specified.  filename
              is  a  file that includes filtering instructions to be processed
              in embedded mode.  The -m option is used  for  debugging  filter
              files  which  are  later  placed in $HOME/.mailfilters, and used
              with the -M option.

       -M filterfile
              Run maildrop in a special  embedded  mode.   The  -d  option  is
              implied when -M is used, and if absent it defaults to the userid
              running maildrop.

              All the requirements for the -d  option  apply.   maildrop  must
              either  be  executed  by  root,  or the maildrop program must be
              owned by root with the setuid  bit  set.   maildrop  immediately
              gives  up  root  privileges  by  changing its user ID to the one
              specified by -d, then reads  $HOME/.mailfilters/filterfile.  For
              security reasons the name of the file may not begin with a slash
              or  include  periods.    maildrop   is   very   paranoid:   both
              $HOME/.mailfilters,  and  $HOME/.mailfilters/filterfile  must be
              owned by  the  user,  and  may  not  have  any  group  or  world
              permissions.

              The  -M  option allows for some friendly cooperation between the
              user running the application, and the user who provides a filter
              for  the embedded mode. The user running the application can use
              someone else’s canned filter and be assured that the  filter  is
              not going to run amok and start sending mail or create files all
              over the place. The user who provides the filter can be  assured
              that  the environment variables are clean, and that there are no
              surprises.

              maildrop supports the concept of "default" filter files.  If the
              file   specified   by   the   -M   option  cannot  be  found  in
              $HOME/.mailfilters,    maildrop     will     try     to     open
              $HOME/.mailfilters/filterfileprefix-default.    filterfileprefix
              is the  initial  part  of  filterfile  up  until  the  last  ’-’
              character in filterfile.

              If  $HOME/.mailfilters/filterfileprefix-default  does not exist,
              and  there  are  any  other  dashes  left  in  filterfileprefix,
              maildrop removes the last dash and everything following it, then
              tries again.

              As    a    last    resort     maildrop     tries     to     open
              $HOME/.mailfilters/default.

              For  example,  if  the parameter to the -M option is mailfilter-
              lists-maildrop, maildrop will try to open the  following  files,
              in order:

              $HOME/.mailfilters/mailfilter-lists-maildrop
              $HOME/.mailfilters/mailfilter-lists-maildrop-default
              $HOME/.mailfilters/mailfilter-lists-default
              $HOME/.mailfilters/mailfilter-default
              $HOME/.mailfilters/default

       Note that maildrop looks for -default files ONLY if -M is used.

       -D uuu/ggg
              This  option is reserved for use by the version of maildrop that
              comes integrated with the Courier mail server.

       -V level
              Initialize the VERBOSE  variable  to  level.   Because  maildrop
              parses  the  entire   before  running it, this option is used to
              produce debugging output in the  parsing  phase.  Otherwise,  if
              filename has syntax errors, then no debugging output is possible
              because the VERBOSE variable is not yet set.

              -V is ignored when maildrop runs in delivery mode.

       -w N   The -w N option places a warning message into the maildir if the
              maildir   has  a  quota  setting,  and  after  the  message  was
              successfully delivered the maildir was at least N percent  full.
              The  warning  message  is copied verbatim from /etc/quotawarnmsg
              with the addition of the "Date:" and "Message-Id:" headers.  The
              warning is repeated every 24 hours (at least), until the maildir
              drops below N percent full.

DELIVERY MODE

       If a filename is not specified on the command line, or if the -d option
       is  used,  maildrop  will  run  in  delivery  mode.   In delivery mode,
       maildrop changes to the home directory of the user specified by the  -d
       option  (or  the  user who is running maildrop if the -d option was not
       given)  and  reads  $HOME/.mailfilter   for   filtering   instructions.
       $HOME/.mailfilter  must  be  owned  by  the  user, and have no group or
       global permissions (maildrop terminates if it does).

       If $HOME/.mailfilter does not exist, maildrop will simply  deliver  the
       message to the user’s mailbox.

       If   the   file   /etc/maildroprc   exists,  maildrop  reads  filtering
       instructions from this file first,  before  reading  $HOME/.mailfilter.
       This  allows  the  system  administrator  to  provide  global filtering
       instructions for all users.

              Note: /etc/maildroprc is read only in delivery mode.

EMBEDDED MODE

       The embedded mode is  used  when  maildrop’s  filtering  abilities  are
       desired,  but  no  actual  mail  delivery  is  needed. In embedded mode
       maildrop is executed by another application, and is passed  the  -m  or
       the  -M  option.  maildrop  reads  the message, then runs the filtering
       rules specified in filename.

       filename may contain any filtering instructions EXCEPT the following:

       ‘ ... ‘
              Text  strings  delimited  by  back-tick  characters  (run  shell
              command) are not allowed.

       cc     The cc command is not allowed in embedded mode.

       dotlock
              The dotlock command is not allowed in embedded mode.

       flock  The flock command is not allowed in embedded mode.

       gdbmopen
              In embedded mode, GDBM databases may be opened only for reading.

       log    The log command is not allowed in embedded mode.

       logfile
              The logfile command is not allowed in embedded mode.

       to     The to command is not allowed in embedded mode.

       xfilter
              The xfilter command is not allowed in embedded mode.

       Normally when the filename does  not  explicitly  delivers  a  message,
       maildrop  will  deliver the message to the user’s default mailbox. This
       is also disabled in embedded mode.

       The filename may communicate with the parent application by  using  the
       echo statement and the EXITCODE environment variable.

   @WITHETCDIR@/MAILDROPRCS
       If  maildrop  encounters an include statement where the filename starts
       with /etc/maildroprcs/, the normal restrictions for the  embedded  mode
       are  suspended  while executing the filter file in the /etc/maildroprcs
       directory. The restrictions  are  also  suspended  for  any  additional
       filter  files that are included from /etc/maildroprcs. The restrictions
       resume once maildrop finishes executing the file from /etc/maildroprcs.

       This  allows  the system administrator to have a controlled environment
       for running external  commands  (via  the  backticks,  or  the  xfilter
       command).

       The  name  of  the file may not contain any periods (so that a creative
       individual              can’t               write               include
       "/etc/maildroprcs/../../home/user/recipe").

       Before  executing  the  commands in the /etc/maildroprcs file, maildrop
       automatically resets the following variables to their  initial  values:
       DEFAULT,  HOME,  LOCKEXT, LOCKSLEEP, LOCKTIMEOUT, LOCKREFRESH, LOGNAME,
       PATH, SENDMAIL, and SHELL.  Please note that  the  previous  values  of
       these  variables  (if  they  were  changed)  will  NOT be restored once
       maildrop finishes executing the commands from /etc/maildroprcs.

WATCHDOG TIMER

       maildrop has a watchdog timer that attempts to abort runaway filtering.
       If filtering is not complete within a predefined time interval (defined
       by  the  system  administrator,   usually   five   minutes),   maildrop
       terminates.

FILES

       /etc/passwd
              Sets  user’s home directory, and related variables. If NIS/YP is
              install, that will be used as well.

       /etc/maildroprc
              Global filtering instructions for delivery mode.

       /var/mail
              System  mailbox  (actual  directory  defined   by   the   system
              administrator).

       /usr/sbin/sendmail
              Program  to  forward  mail  (exact program defined by the system
              administrator).

       $HOME/.mailfilter
              Filtering instructions in delivery mode.

       $HOME/.mailfilters
              Directory containing files used in special embedded mode.

SEE ALSO

       lockmail(1),    maildropfilter(5),     makedat(1),     maildropgdbm(5),
       maildropex(5),  reformail(1), makeuserdb(1), makemime(1), reformime(1),
       egrep(1), grep(1), , courier(8), sendmail(8), http://www.qmail.org.