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 FCFrom_F line before the first header line. If the message does not contain a FCFrom_F line, maildrop will create one (if needed).
If the file FC/etc/maildroprcF 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 FC/etc/maildroprcF does not exist, or its mail delivery instructions do not completely dispose of this message, maildrop then reads the mail delivery instructions from FC$HOME/.mailfilterF. 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 FCmaildirF is a directory-based mail format used by the m[blue]Courierm and m[blue]Qmailm 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:
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 FC/etc/maildroprcF, then FC$HOME/.mailfilterF.
maildrop functions as a part of another application. The embedded mode is used by the m[blue]Courierm 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.
It is safe to install maildrop as a root setuid program. m[blue]The Courier mail serverm 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 FC$HOME/.mailfilterF 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 FC$HOME/.mailfilterF 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 FCfilenameF is not owned by the user, or if it has any group or world permissions. This includes read permissions. The permissions on FC$HOME/.mailfilterF 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 FC$HOME/.mailfiltersF is not owned by the user, or if it has any group or world permissions.
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.
-A "Header: value"
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.
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 FCfilenameF 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 m[blue]"Environment"m and m[blue]"Variable substitution"m).
The FCfilenameF argument to maildrop should be specified. FCfilenameF is a file that includes filtering instructions to be processed in embedded mode. The FC-mF option is used for debugging filter files which are later placed in FC$HOME/.mailfiltersF, and used with the -M option.
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 FC$HOME/.mailfilters/filterfileF. For security reasons the name of the file may not begin with a slash or include periods. maildrop is very paranoid: both FC$HOME/.mailfiltersF, and FC$HOME/.mailfilters/filterfileF 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 FC$HOME/.mailfiltersF, maildrop will try to open FC$HOME/.mailfilters/filterfileprefix-defaultF. filterfileprefix is the initial part of filterfile up until the last '-' character in filterfile.
If FC$HOME/.mailfilters/filterfileprefix-defaultF 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 FC$HOME/.mailfilters/defaultF.
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.
-V is ignored when maildrop runs in delivery mode.
If a FCfilenameF 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 FC$HOME/.mailfilterF for filtering instructions. FC$HOME/.mailfilterF must be owned by the user, and have no group or global permissions (maildrop terminates if it does).
If FC$HOME/.mailfilterF does not exist, maildrop will simply deliver the message to the user's mailbox.
If the file FC/etc/maildroprcF exists, maildrop reads filtering instructions from this file first, before reading FC$HOME/.mailfilterF. This allows the system administrator to provide global filtering instructions for all users.
FC/etc/maildroprcF is read only in delivery mode.
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.
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 m[blue]is passed the -m or the -M option.m maildrop reads the message, then runs the filtering rules specified in FCfilenameF.
FCfilenameF may contain any filtering instructions EXCEPT the following:
` ... `
Normally when the FCfilenameF 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 FCfilenameF may communicate with the parent application by using the m[blue]echom statement and the EXITCODE environment variable.
If maildrop encounters an m[blue]includem statement where the filename starts with FC/etc/maildroprcs/F, the normal restrictions for the embedded mode are suspended while executing the filter file in the FC/etc/maildroprcsF directory. The restrictions are also suspended for any additional filter files that are included from FC/etc/maildroprcsF. The restrictions resume once maildrop finishes executing the file from FC/etc/maildroprcsF.
This allows the system administrator to have a controlled environment for running external commands (via the backticks, or the m[blue]xfilterm 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 FC/etc/maildroprcsF 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 FC/etc/maildroprcsF.
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.
m[blue]lockmail(1)m, m[blue]maildropfilter(7)m, m[blue]makedat(1)m, m[blue]maildropgdbm(7)m, m[blue]maildropex(7)m, m[blue]reformail(1)m, m[blue]makemime(1)m, m[blue]reformime(1)m, egrep(1), grep(1), , m[blue]courier(8)m, sendmail(8), m[blue]http://www.qmail.orgm.