Provided by: maildrop_2.9.3-2.1_amd64 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.

       maildrop does not accept an mbox-style From_ line before the first header line.  maildrop
       does not accept leading empty lines before the first non-blank header line. If the message
       can possibly start with empty lines, and a From_ line, use reformail -f0 to remove any
       initial empty lines, and replace a From_ line with a proper “Return-Path:” header; then
       pipe it to maildrop.

       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[1] and
       Qmail[2] 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.

       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[1] 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.  The Courier mail server[1]
       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 small 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
           Makes the Courier Authentication Library usage mandatory, i.e. maildrop will throw a
           temporary error code if the call to the authlib mechanism fails for some reason, such
           as authdaemon being inaccessible.

               Note
               This setting may already be the default, depending on maildrop's configuration.

       -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"[3] and "Variable
           substitution"[4]).

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

           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[1].

       -V level
           Initialize the VERBOSE variable to level. Because maildrop parses the entire file
           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.

       -W filename
           Copy the warning message from filename, or from /etc/quotawarnmsg if this option is
           not specified, 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.

       -t socket
           This option is available if maildrop is compiled with optional Dovecot authentication
           support.  socket specifies the location of Dovecot master authentication socket, for
           example /var/run/dovecot/auth-master.

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.

VIRTUAL ACCOUNTS

       The -d option can also specify a name of a virtual account or mailbox. See the
       makeuserdb(1) manual page in the Courier Authentication library's documentation for more
       information.

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.[5] 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[6]
           The cc command is not allowed in embedded mode.

       dotlock[7]
           The dotlock command is not allowed in embedded mode.

       flock[8]
           The flock command is not allowed in embedded mode.

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

       log[10]
           The log command is not allowed in embedded mode.

       logfile[10]
           The logfile command is not allowed in embedded mode.

       system[11]
           The system command is not allowed in embedded mode.

       to[12]
           The to command is not allowed in embedded mode.

       xfilter[13]
           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[14] statement
       and the EXITCODE environment variable.

   /etc/maildroprcs
       If maildrop encounters an include[15] 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, the system[11] or the xfilter[13] commands).

       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)[16], maildropfilter(7)[17], makedat(1)[18], maildropgdbm(7)[9],
       maildropex(7)[19], reformail(1)[20], makemime(1)[21], reformime(1)[22], egrep(1), grep(1),
       , courier(8)[23], sendmail(8), http://www.qmail.org.

AUTHOR

       Sam Varshavchik
           Author

NOTES

        1. Courier
           http://www.courier-mta.org

        2. Qmail
           http://www.qmail.org

        3. "Environment"
           http://www.courier-mta.org/maildrop/maildropfilter.html#environment

        4. "Variable substitution"
           http://www.courier-mta.org/maildrop/maildropfilter.html#varsubst

        5. is passed the ‐m or the ‐M option.
           http://www.courier-mta.org/maildrop/#options

        6. cc
           http://www.courier-mta.org/maildrop/maildropfilter.html#cc

        7. dotlock
           http://www.courier-mta.org/maildrop/maildropfilter.html#dotlock

        8. flock
           http://www.courier-mta.org/maildrop/maildropfilter.html#flock

        9. gdbmopen
           http://www.courier-mta.org/maildrop/maildropgdbm.html

       10. log
           http://www.courier-mta.org/maildrop/maildropfilter.html#log

       11. system
           http://www.courier-mta.org/maildrop/maildropfilter.html#system

       12. to
           http://www.courier-mta.org/maildrop/maildropfilter.html#to

       13. xfilter
           http://www.courier-mta.org/maildrop/maildropfilter.html#xfilter

       14. echo
           http://www.courier-mta.org/maildrop/maildropfilter.html#echo

       15. include
           http://www.courier-mta.org/maildrop/maildropfilter.html#include

       16. lockmail(1)
           http://www.courier-mta.org/maildrop/lockmail.html

       17. maildropfilter(7)
           http://www.courier-mta.org/maildrop/maildropfilter.html

       18. makedat(1)
           http://www.courier-mta.org/maildrop/makedat.html

       19. maildropex(7)
           http://www.courier-mta.org/maildrop/maildropex.html

       20. reformail(1)
           http://www.courier-mta.org/maildrop/reformail.html

       21. makemime(1)
           http://www.courier-mta.org/maildrop/makemime.html

       22. reformime(1)
           http://www.courier-mta.org/maildrop/reformime.html

       23. courier(8)
           http://www.courier-mta.org/maildrop/courier.html