maildrop [options] [filter-file [arg] [arg] ...]
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:
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 are created in $HOME/.tmp. maildrop's use
of temporary files is completely secure.
The mail transport agent usually adds additional headers when delivering a message to an actual account. The way this is usually done is the mail transport agent sending the message via 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 buffer the message in memory, or write the message into a temporary file.
The -A option lets the file containing the message to be simply provided
to maildrop as standard input, with the additional headers specified
on the command line. Because the standard input is a file, maildrop doesn't
have to use a temporary file. Multiple -A options may be specified.
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 invoked by root, or maildrop must be a setuid root program. 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")
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.
All the requirements for the -d option apply. maildrop must be either a root setuid program, or invoked by root. maildrop immediately gives up root privileges by changing its userid to the one specified by the -d option, then reads $HOME/.mailfilters/filterfile as in embedded mode. The name of the file may not begin with a slash or include periods, for security reasons. maildrop is 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/defaultNote that attempts to find a -default file will be made only if the -M option is used.
The -V option is ignored when maildrop runs in delivery mode.
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.
The filter file may communicate the result of the filtering to
the parent application by using the echo
statement, and the EXITCODE environment variable.