MAILDROP(1)MAILDROP(1)NAMEmaildrop - mail delivery filter/agent
SYNOPSISmaildrop [ option ... ] [ -d user ] [ arg ... ]
maildrop [ option ... ] [ filename ] [ arg ... ]
DESCRIPTIONmaildrop 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 mail‐
drop 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 mes‐
sage 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 con‐
tain a From_ line, maildrop will create one (if needed).
If the file /etc/maildrop/maildroprc exists, mail delivery or mail fil‐
tering instructions are read from that file. maildrop's delivery/fil‐
tering 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/maildrop/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 dis‐
pose 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 and Qmail mail servers. Many other
mail servers also know how to read maildirs. When delivering to mail‐
box 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 differ‐
ences in behavior depending on maildrop delivery mode, which is deter‐
mined 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/maildrop/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 com‐
mand line. maildrop changes the current directory to the user's
home directory, then reads /etc/maildrop/maildroprc, then
$HOME/.mailfilter.
Embedded mode
maildrop functions as a part of another application. The embed‐
ded mode is used by the Courier 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. Courier
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, with‐
out 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 FILESmaildrop 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.
OPTIONS-A "Header: value"
Adds an additional header to the message. Specifying -A "Foo:
Bar" effectively adds this header to the message being deliv‐
ered.
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 pro‐
vided to maildrop directly, as standard input, and the addi‐
tional headers specified on the command line. Because the stan‐
dard 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 avail‐
able 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" and "Variable substitu‐
tion").
-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 permis‐
sions.
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/.mail‐
filters, maildrop will try to open $HOME/.mailfilters/filter‐
fileprefix-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, mail‐
drop removes the last dash and everything following it, then
tries again.
As a last resort maildrop tries to open $HOME/.mailfil‐
ters/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 -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.
-V level
Initialize the VERBOSE variable to level. Because maildrop
parses the entire 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 success‐
fully delivered the maildir was at least N percent full. The
warning message is copied verbatim from /etc/quotawarnmsg 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.
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, mail‐
drop 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/maildrop/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/maildrop/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 mail‐
drop is executed by another application, and is passed the -m or the -M
option. maildrop reads the message, then runs the filtering rules spec‐
ified in filename.
filename may contain any filtering instructions EXCEPT the following:
` ... `
Text strings delimited by back-tick characters (run shell com‐
mand) are not allowed.
cc The cc command is not allowed in embedded mode.
dotlock
The dotlock command is not allowed in embedded mode.
flock The flock command is not allowed in embedded mode.
gdbmopen
In embedded mode, GDBM databases may be opened only for reading.
log The log command is not allowed in embedded mode.
logfile
The logfile command is not allowed in embedded mode.
to The to command is not allowed in embedded mode.
xfilter
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 statement and the EXITCODE environment variable.
/etc/maildrop/MAILDROPRCS
If maildrop encounters an include statement where the filename starts
with /etc/maildrop/maildroprcs/, the normal restrictions for the embed‐
ded mode are suspended while executing the filter file in the
/etc/maildrop/maildroprcs directory. The restrictions are also sus‐
pended for any additional filter files that are included from
/etc/maildrop/maildroprcs. The restrictions resume once maildrop fin‐
ishes executing the file from /etc/maildrop/maildroprcs.
This allows the system administrator to have a controlled environment
for running external commands (via the backticks, or the xfilter com‐
mand).
The name of the file may not contain any periods (so that a creative
individual can't write include "/etc/maildrop/mail‐
droprcs/../../home/user/recipe").
Before executing the commands in the /etc/maildrop/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 val‐
ues of these variables (if they were changed) will NOT be restored once
maildrop finishes executing the commands from /etc/maildrop/mail‐
droprcs.
WATCHDOG TIMERmaildrop 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 termi‐
nates.
FILES
/etc/passwd
Sets user's home directory, and related variables. If NIS/YP is
install, that will be used as well.
/etc/maildrop/maildroprc
Global filtering instructions for delivery mode.
/var/spool/mail
System mailbox (actual directory defined by the system adminis‐
trator).
/usr/lib/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 ALSOlockmail(1), maildropfilter(7), makedat(1), maildropgdbm(7), mail‐
dropex(7), reformail(1), makeuserdb(1), makemime(1), reformime(1),
egrep(1), grep(1), , courier(8), sendmail(8), http://www.qmail.org.
Double Precision, Inc. 26 July 2004 MAILDROP(1)
