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 from standard input and filters it according to instructions in a filter file. 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 mbox-formatted 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 mbox-formatted mailbox files, maildrop knows how to do dot-locking, or use flock or lockf locking mechanism (configured by the system administrator to be compatible with the existing mail software).

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 may be directed to filter the message instead of delivering it directly into the mailbox. Examples of filtering are: delivering the message into a different file instead of the system mailbox; forwarding the message to another mailbox; or rejecting the message. If a message is rejected, it is not delivered anywhere, and, if maildrop is invoked directly by the local mail transport agent, the message is returned to sender.

maildrop uses three different primary operating modes:

In delivery mode, maildrop changes the current directory to the home directory and reads $HOME/.mailfilter for filtering instructions. If this file is missing, it is treated as if it was empty, resulting in the message getting delivered to the user's default mailbox.

maildrop may be installed by the system administrator as a root setuid program. If maildrop is run 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. This results in the user's $HOME/.mailfilter file being read (if it exists), and the message being delivered to the indicated user.

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

When maildrop runs in delivery mode and the user's home directory has its 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.

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 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, and filters and/or delivers the message directly from memory. For larger messages, maildrop will access the message directly from the file. If the standard input is a pipe, maildrop will write the message to a temporary file, then access 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



DELIVERY MODE

maildrop runs in delivery mode when either the filter file is not specified, or the -d option is used. 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 will terminate 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 will first read filtering instructions from this file, 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 from within 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: Normally when the filter file does not provide an explicit mailbox to deliver the message to, maildrop delivers the message to the user's default mailbox. This behavior is also disabled in embedded mode.

The filter file may communicate the result of the filtering to the parent application by using the echo statement, and the EXITCODE environment variable.

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



SEE ALSO

dotlock(1), maildropfilter(1), maildropex(5), reformail(1), egrep(1), grep(1), sendmail(8), http://www.qmail.org