Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MAILDROP(1)		    Double Precision, Inc.		   MAILDROP(1)

NAME
       maildrop	- mail delivery	filter/agent

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

       maildrop	[option...] [filename] [arg...]

DESCRIPTION
       maildrop	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
       maildrop	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
       message consists	of header lines, followed by a blank line, followed by
       the contents of the message.

       maildrop	does not accept	an mbox-style From_ line before	the first
       header line.  maildrop does not accept leading empty lines before the
       first non-blank header line. If the message can possibly	start with
       empty lines, and	a From_	line, use reformail -f0	to remove any initial
       empty lines, and	replace	a From_	line with a proper "Return-Path:"
       header; then pipe it to maildrop.

       If the file /usr/local/etc/maildroprc 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 /usr/local/etc/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
       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	maildir	is a directory-based
       mail format used	by the Courier[1] and Qmail[2] 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.

       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:

       Manual mode
	   A file containing filtering instructions - filename is specified as
	   an argument to the maildrop command.	 maildrop reads	this filename
	   (after /usr/local/etc/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 command line.
	   maildrop changes the	current	directory to the user's	home
	   directory, then reads /usr/local/etc/maildroprc, then
	   $HOME/.mailfilter.

       Embedded	mode
	   maildrop functions as a part	of another application.	The embedded
	   mode	is used	by the Courier[1] 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.	 The Courier
       mail server[1] 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,
       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 $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 FILES
       maildrop	is heavily optimized and tries to use as little	resources as
       possible.  maildrop reads small 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
	   Makes the Courier Authentication Library usage mandatory, i.e.
	   maildrop will throw a temporary error code if the call to the
	   authlib mechanism fails for some reason, such as authdaemon being
	   inaccessible.

	       Note
	       This setting may	already	be the default,	depending on
	       maildrop's configuration.

       -A "Header: value"
	   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 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.

       -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 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 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"[3] and "Variable
	   substitution"[4]).

       -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 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/filterfileprefix-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,	maildrop
	   removes the last dash and everything	following it, then tries
	   again.

	   As a	last resort maildrop tries 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:

	   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[1].

       -V level
	   Initialize the VERBOSE variable to level. Because maildrop parses
	   the entire file 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 successfully
	   delivered the maildir was at	least N	percent	full.

       -W filename
	   Copy	the warning message from filename, or from
	   /usr/local/etc/quotawarnmsg if this option is not specified,	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.

       -t socket
	   This	option is available if maildrop	is compiled with optional
	   Dovecot authentication support.  socket specifies the location of
	   Dovecot master authentication socket, for example
	   /var/run/dovecot/auth-master.

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, 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 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
	   /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 the makeuserdb(1) manual page in the	Courier	Authentication
       library's documentation 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.[5]maildrop reads the message, then runs the filtering
       rules specified in filename.

       filename	may contain any	filtering instructions EXCEPT the following:

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

       cc[6]
	   The cc command is not allowed in embedded mode.

       dotlock[7]
	   The dotlock command is not allowed in embedded mode.

       flock[8]
	   The flock command is	not allowed in embedded	mode.

       gdbmopen[9]
	   In embedded mode, GDBM databases may	be opened only for reading.

       log[10]
	   The log command is not allowed in embedded mode.

       logfile[10]
	   The logfile command is not allowed in embedded mode.

       to[11]
	   The to command is not allowed in embedded mode.

       xfilter[12]
	   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[13]	statement and the EXITCODE environment variable.

   /usr/local/etc/maildroprcs
       If maildrop encounters an include[14] 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[12]
       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.

FILES
       /etc/passwd
	   Sets	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/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/.mailfilter
	   Filtering instructions in delivery mode.

       $HOME/.mailfilters
	   Directory containing	files used in special embedded mode.

SEE ALSO
       lockmail(1)[15],	maildropfilter(7)[16], makedat(1)[17],
       maildropgdbm(7)[9], maildropex(7)[18], reformail(1)[19],
       makemime(1)[20],	reformime(1)[21], egrep(1), grep(1), , courier(8)[22],
       sendmail(8), http://www.qmail.org.

AUTHOR
       Sam Varshavchik
	   Author

NOTES
	1. Courier
	   http://www.courier-mta.org

	2. Qmail
	   http://www.qmail.org

	3. "Environment"
	   http://www.courier-mta.org/maildrop/maildropfilter.html#environment

	4. "Variable substitution"
	   http://www.courier-mta.org/maildrop/maildropfilter.html#varsubst

	5. is passed the -m or the -M option.
	   http://www.courier-mta.org/maildrop/#options

	6. cc
	   http://www.courier-mta.org/maildrop/maildropfilter.html#cc

	7. dotlock
	   http://www.courier-mta.org/maildrop/maildropfilter.html#dotlock

	8. flock
	   http://www.courier-mta.org/maildrop/maildropfilter.html#flock

	9. gdbmopen
	   http://www.courier-mta.org/maildrop/maildropgdbm.html

       10. log
	   http://www.courier-mta.org/maildrop/maildropfilter.html#log

       11. to
	   http://www.courier-mta.org/maildrop/maildropfilter.html#to

       12. xfilter
	   http://www.courier-mta.org/maildrop/maildropfilter.html#xfilter

       13. echo
	   http://www.courier-mta.org/maildrop/maildropfilter.html#echo

       14. include
	   http://www.courier-mta.org/maildrop/maildropfilter.html#include

       15. lockmail(1)
	   http://www.courier-mta.org/maildrop/lockmail.html

       16. maildropfilter(7)
	   http://www.courier-mta.org/maildrop/maildropfilter.html

       17. makedat(1)
	   http://www.courier-mta.org/maildrop/makedat.html

       18. maildropex(7)
	   http://www.courier-mta.org/maildrop/maildropex.html

       19. reformail(1)
	   http://www.courier-mta.org/maildrop/reformail.html

       20. makemime(1)
	   http://www.courier-mta.org/maildrop/makemime.html

       21. reformime(1)
	   http://www.courier-mta.org/maildrop/reformime.html

       22. courier(8)
	   http://www.courier-mta.org/maildrop/courier.html

Courier	Mail Server		  06/20/2015			   MAILDROP(1)

NAME | SYNOPSIS | DESCRIPTION | SECURITY | TEMPORARY FILES | OPTIONS | DELIVERY MODE | VIRTUAL ACCOUNTS | EMBEDDED MODE | WATCHDOG TIMER | FILES | SEE ALSO | AUTHOR | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=maildrop&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help