maildrop(1)

NAME
maildrop - mail delivery agent with filtering abilities

SYNOPSIS
maildrop [options] [-d user] [arg] [arg] ...

maildrop [options] [filter-file [arg] [arg] ...]

DESCRIPTION
maildrop is a replacement local mail delivery agent that includes integrated mail filtering abilities. The system administrator can either replace the existing mail delivery agent with maildrop, or a user may run maildrop through the 'forward to program' mechanism of the existing mail delivery agent.

maildrop reads the message, then carries out the instructions found in a filter file. Instead of delivering the message directly to your mailbox, the filter file may direct maildrop to save the message in another mailbox, delete it, return it to sender, or forward it to a different E-mail address. If a message contains lines that end in a carriage return, maildrop transparently strips the carriage returns from the message, before filtering it or delivering the message to a mailbox.

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

maildrop knows how to deliver mail to an standard mailbox files; it also knows how to deliver to maildir mailboxes. maildir is a directory-based mailbox format used by qmail (http://www.qmail.org). maildrop does NOT deliver to regular directories. If you need to save messages in a directory, one per file, create a maildir using the maildirmake program. 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 will ignore any empty lines at the beginning of the message, therefore, maildrop requires that every message must contain at least one header line.

maildrop uses three different primary operating modes:

Manual mode
    a file containing filtering instructions - a filter file - is specified as an argument to the maildrop program. maildrop reads this filter file and interprets 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
    this mode is intended to be used when maildrop is used as the default local delivery agent. maildrop runs in delivery mode when no filter file is specified on the command line.

Embedded mode
    this is a special case of a delivery mode. In embedded mode, maildrop functions as a part of another application. Embedded mode is used when either the -m, or the -M, option is specified. See below for a more extensive description of the embedded mode. In delivery mode, maildrop changes the current directory to the user's home directory, then reads $HOME/.mailfilter for filtering instructions. If this file is missing, it is treated as if it was empty, and the message is delivered to the user's default mailbox.

maildrop can be installed with the set-userid and set-groupid permissions. If maildrop executes as root, the -d option is used to specify the user to whom the message should be delivered. maildrop will immediately reset 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 disable 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. When maildrop is invoked by a properly-written mail transport agent (MTA), the MTA interprets the EX_TEMPFAIL exit code as a request to reschedule the message for another delivery attempt later. Setting the sticky bit allows $HOME/.mailfilter file to be edited by the user while temporarily holding all incoming mail.

maildrop immediately terminates with the exit code set to EX_TEMPFAIL if the user's home directory has world write permissions.

maildrop immediately terminates with the exit code set to EX_TEMPFAIL if the filter file 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. maildrop is designed to use as little resources as possible. maildrop reads smaller 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.

Temporary files are created in $HOME/.tmp. maildrop's use of temporary files is completely secure.

OPTIONS

-A 'header'
    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 makes it possible to have the file containing the message to be provided to maildrop directly, as standard input. The additional headers are specified on the command line. Because the standard input is a file, maildrop will not use 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 disable the -d option for users, 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 filter file 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 the 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 filter-file argument to maildrop should be specified. filter-file is the filename of the file that includes filtering instructions to be processed in embedded mode. The -m option is used for debugging filter files which will later be 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 the -M option is used. If the -d option is not specified, the -d option for the user running maildrop is used.

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 the -d option, 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/file-default. If that file does not exist, maildrop will check if file has any dashes. If it does, everything following the last dash is replaced by "default", and maildrop tries again. maildrop will keep trying until there are no more dashes left. As a last resort, maildrop will try 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 the -M option 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 VERBOSE variable to level. Because maildrop parses the entire filter file before running it, this option is used to produce debugging output in the parsing phase. Otherwise, if filter file has syntax errors, then no debugging output is possible because the VERBOSE variable will not get set.

The -V option is ignored when maildrop runs in delivery mode.

DELIVERY MODE
If a filter file 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 /usr/local/etc/maildroprc exists, maildrop will read filtering instructions from this file first, before reading $HOME/.mailfilter. This allows the system administrator to provide global filtering instructions for all users.

NOTE - /usr/local/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 makeuserdb(1) 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. maildrop reads the message, then runs the filtering rules specified in the filter file. The filter file may contain any filtering instructions EXCEPT the following:

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

cc

dotlock

flock

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

log

logfile

to

xfilter
    Normally when the filter file does not explicitly delivers a message, maildrop will deliver the message to the user's default mailbox. This behavior is also disabled in embedded mode.

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

  /usr/local/etc/maildroprcs in embedded mode
This is a new feature to version 0.55. If maildrop encounters an include statement where the filename starts with /usr/local/etc/maildroprcs/, the normal restrictions for the embedded mode are suspended while executing the filter file in the /usr/local/etc/maildroprcs directory. The restrictions are also suspended for any additional filter files that are included from /usr/local/etc/maildroprcs. The restrictions resume once maildrop finishes executing the file from /usr/local/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 "/usr/local/etc/maildroprcs/../../home/user/recipe").

Before executing the commands in the /usr/local/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 /usr/local/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. Hopefully this will take care of runaway filters.

FILES

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

/usr/local/etc/maildroprc
    global filtering instructions for delivery mode.

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

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

$HOME/.tmp
    directory for temporary files.

$HOME/.mailfilter
    filter file used in delivery mode.

$HOME/.mailfilters
    directory containing filter files to be used for special embedded mode.

SEE ALSO
dotlock(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