trAvis - MANAGER

Edit File: maildrop.html

<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>maildrop</title><link rel="stylesheet" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"/><link rel="home" href="#idm255224223552" title="maildrop"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--

--></head><body><div class="refentry"><a id="idm255224223552" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2>maildrop — mail delivery filter/agent</div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><code class="command">maildrop</code> [option...] [-d <code>user</code>] [<code>arg</code>...]</div><div class="cmdsynopsis"><code class="command">maildrop</code> [option...] [<code>filename</code>] [<code>arg</code>...]</div></div><div class="refsect1"><a id="idm255220310992" shape="rect"> </a><h2>DESCRIPTION</h2>
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
 <code class="literal">From_</code>
 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
 <code class="literal">From_</code>
 line, use reformail -f0 to remove any initial
 empty lines, and replace a <code class="literal">From_</code> line with a
 proper “Return-Path:” header; then pipe it to
 maildrop.
If the file <code class="filename">/etc/maildroprc</code> 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 <code class="filename">/etc/maildroprc</code> does not exist, or
its mail delivery instructions do not completely dispose of this message,
maildrop then reads the mail delivery instructions
from <code class="filename">$HOME/.mailfilter</code>.
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 <code class="literal">maildir</code> is a
directory-based mail format used by the
<a class="ulink" href="http://www.courier-mta.org" target="_top" shape="rect">Courier</a>
and
<a class="ulink" href="http://www.qmail.org" target="_top" shape="rect">Qmail</a>
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:
<div class="variablelist"><dl class="variablelist"><dt>Manual mode</dt><dd>
A file containing filtering instructions -
<code>filename</code>
is specified as an argument to the maildrop command.
maildrop reads this
<code>filename</code> (after
<code class="filename">/etc/maildroprc</code>)
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.</dd><dt>Delivery mode</dt><dd>
maildrop
is the mail server's mail delivery agent.
maildrop runs in
delivery mode when no <code>filename</code>
is specified on the command line.
maildrop changes the current directory to the user's
home directory, then reads <code class="filename">/etc/maildroprc</code>,
then <code class="filename">$HOME/.mailfilter</code>.</dd><dt>Embedded mode</dt><dd>
maildrop functions as a part of another application.
The embedded mode is used by the
<a class="ulink" href="http://www.courier-mta.org" target="_top" shape="rect">Courier</a>
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.</dd></dl></div></div><div class="refsect1"><a id="idm255220272208" shape="rect"> </a><h2>SECURITY</h2>
It is safe to install maildrop as a root setuid program.
<a class="ulink" href="http://www.courier-mta.org" target="_top" shape="rect">The Courier mail server</a>
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 <code class="option">-d</code> option may be used to
specify the message's recipient. maildrop
immediately resets its userid to the one specified by the
<code class="option">-d</code> option. The
user's
<code class="filename">$HOME/.mailfilter</code>
is read (if it exists), and the message
is delivered to the indicated user.
The system administrator can configure maildrop to restrict
the <code class="option">-d</code> 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
<code class="filename">$HOME/.mailfilter</code> 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 <code class="filename">filename</code> is
not owned by the user,
or if it has any group or world permissions. This includes read permissions.
The permissions on
<code class="filename">$HOME/.mailfilter</code> 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
<code class="filename">$HOME/.mailfilters</code>
is not owned by the user, or if it has any
group or world permissions.</div><div class="refsect1"><a id="idm255220251776" shape="rect"> </a><h2>TEMPORARY FILES</h2>
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.</div><div class="refsect1"><a id="idm255220247344" shape="rect"> </a><h2>OPTIONS</h2><a id="options" shape="rect"> </a><div class="variablelist"><dl class="variablelist"><dt>-a</dt><dd>
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.<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
This setting may already be the default, depending on maildrop's
configuration.</div></dd><dt>-A "<code>Header: value</code>"</dt><dd>
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 <code class="option">-A</code> 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 <code class="option">-A</code> options may be specified.</dd><dt>-d <code>user</code></dt><dd>
Run maildrop in delivery mode for this user ID.
The system administrator may optionally restrict the
<code class="option">-d</code> option to be available to the mail system only, so
it may not be available to you.
In all cases, the <code class="option">-d</code> option is allowed if
<code>user</code> is the same user who is running
maildrop.
Also, for the <code class="option">-d</code> 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 <code class="filename">filename</code>
on
maildrop's command line
implies the <code class="option">-d</code> option for the user running
maildrop.
If <code class="option">-d</code> 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
<code class="varname">$1</code>,
<code class="varname">$2</code>, and so on (see
<a class="ulink" href="maildropfilter.html#environment" target="_top" shape="rect">"Environment"</a> and

<a class="ulink" href="maildropfilter.html#varsubst" target="_top" shape="rect">"Variable substitution"</a>).</dd><dt>-f <code>address</code></dt><dd>
Sets the FROM variable (message envelope sender) to
<code>address</code>.
The system administrator may optionally disable the
<code class="option">-f</code> option for users, so it may not be available to you.</dd><dt>-m</dt><dd>
Run maildrop in embedded mode.
It's possible to use both the <code class="option">-m</code>, and the
<code class="option">-d</code> options, but it doesn't make much sense to do so.
Even if you really wanted to run your message through someone else's
<code class="filename">.mailfilter</code>,
that <code class="filename">.mailfilter</code> probably has at least one
instruction which is not allowed in the embedded mode.
The <code class="filename">filename</code> argument to maildrop
should be specified.
<code class="filename">filename</code> is a file that includes filtering
instructions to be processed in embedded mode.
The <code class="filename">-m</code> option is used for debugging filter files which
are later placed in
<code class="filename">$HOME/.mailfilters</code>, and used with the
<code class="option">-M</code> option.</dd><dt>-M <code>filterfile</code></dt><dd><a id="moption" shape="rect"> </a>
Run maildrop in a special embedded mode.
The <code class="option">-d</code>
option is implied when <code class="option">-M</code> is used, and if absent it defaults
to the userid running maildrop.
All the requirements for the <code class="option">-d</code> 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 <code class="option">-d</code>,
then reads
<code class="filename">$HOME/.mailfilters/<code>filterfile</code></code>. For security reasons the name of the file may not begin with a slash or include
periods.
maildrop is very paranoid:
both <code class="filename">$HOME/.mailfilters</code>, and
<code class="filename">$HOME/.mailfilters/<code>filterfile</code></code>
must be owned by the user, and may not have any group or world
permissions.
The <code class="option">-M</code> 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
<code class="filename">$HOME/.mailfilters</code>,
maildrop will try to open
<code class="filename">$HOME/.mailfilters/<code>filterfileprefix</code>-default</code>.
<code>filterfileprefix</code> is the initial part
of <code>filterfile</code> up until the last '-' character in
<code>filterfile</code>.
If
<code class="filename">$HOME/.mailfilters/<code>filterfileprefix</code>-default</code>
does not exist, and there are any other dashes left in
<code>filterfileprefix</code>, maildrop
removes the last dash and everything
following it, then tries again.
As a last resort maildrop
tries to open <code class="filename">$HOME/.mailfilters/default</code>.
For example, if the parameter to the <code class="option">-M</code> option is
mailfilter-lists-maildrop, maildrop will try to open the following files, in order:
<div class="blockquote"><blockquote class="blockquote"><div class="literallayout"> 
<code class="filename">$HOME/.mailfilters/mailfilter-lists-maildrop</code> 
<code class="filename">$HOME/.mailfilters/mailfilter-lists-maildrop-default</code> 
<code class="filename">$HOME/.mailfilters/mailfilter-lists-default</code> 
<code class="filename">$HOME/.mailfilters/mailfilter-default</code> 
<code class="filename">$HOME/.mailfilters/default</code> 
</div></blockquote></div>

Note that maildrop looks for -default files ONLY if
<code class="option">-M</code> is used.</dd><dt>-D <code>uuu/ggg</code></dt><dd>
This option is reserved for use by the version of
maildrop that comes integrated with the
<a class="ulink" href="http://www.courier-mta.org" target="_top" shape="rect">Courier mail server</a>.</dd><dt>-V <code>level</code></dt><dd>
Initialize the <code class="varname">VERBOSE</code> variable to
<code>level</code>.
Because maildrop parses the
entire file before
running it, this option is used to produce debugging output in the
parsing phase. Otherwise, if <code class="filename">filename</code>
has syntax errors, then
no debugging output is possible because the <code class="varname">VERBOSE</code> variable
is not yet set.
<code class="option">-V</code> is ignored when maildrop runs in
delivery mode.</dd><dt>-w <code>N</code></dt><dd>
The <code class="option">-w N</code> 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
<code>N</code> percent full.
	 </dd><dt>-W <code>filename</code></dt><dd>
Copy the warning message from <code>filename</code>, or from
<code class="filename">/etc/quotawarnmsg</code> if this option is not specified,
with the addition of the
"<code class="literal">Date:</code>" and
"<code class="literal">Message-Id:</code>" headers.
The warning is repeated every 24 hours (at least), until the maildir drops
below
<code>N</code> percent full.</dd><dt>-t <code>socket</code></dt><dd>
	 This option is available if maildrop is compiled with optional
	 Dovecot authentication support. <code>socket</code>
	 specifies the location of Dovecot master authentication socket,
	 for example <code class="filename">/var/run/dovecot/auth-master</code>.
	 </dd></dl></div></div><div class="refsect1"><a id="idm255220164096" shape="rect"> </a><h2>DELIVERY MODE</h2>
If a <code class="filename">filename</code> is not specified on the command line, or
if the <code class="option">-d</code>
option is used, maildrop will run in delivery mode.
In delivery mode,
maildrop changes to the home directory of the user
specified by the <code class="option">-d</code>
option (or the user who is running maildrop if the
<code class="option">-d</code> option was not
given) and reads <code class="filename">$HOME/.mailfilter</code> for filtering
instructions. <code class="filename">$HOME/.mailfilter</code> must be owned by the
user, and have no group
or global permissions (maildrop terminates if it
does).
If <code class="filename">$HOME/.mailfilter</code> does not exist,
maildrop will
simply deliver the message to the user's mailbox.If the file <code class="filename">/etc/maildroprc</code> exists,
maildrop reads filtering instructions from this file first,
before reading
<code class="filename">$HOME/.mailfilter</code>. This allows the system administrator
to provide global filtering instructions for all users.<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<code class="filename">/etc/maildroprc</code> is read only in
delivery mode.</div></div><div class="refsect1"><a id="idm255220151792" shape="rect"> </a><h2>VIRTUAL ACCOUNTS</h2>
The <code class="option">-d</code> 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.</div><div class="refsect1"><a id="idm255220148688" shape="rect"> </a><h2>EMBEDDED MODE</h2><a id="embedded" shape="rect"> </a>
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
<a class="ulink" href="#options" target="_top" shape="rect">is
passed the ‐m or the ‐M option.</a> maildrop reads the
message, then runs the filtering rules specified in
<code class="filename">filename</code>.
<code class="filename">filename</code>
may contain any filtering instructions EXCEPT the following:
<div class="variablelist"><dl class="variablelist"><dt>` ... `</dt><dd>
Text strings delimited by back-tick characters (run shell
command) are not allowed.</dd><dt><a class="ulink" href="maildropfilter.html#cc" target="_top" shape="rect">cc</a></dt><dd>
The cc command is not allowed in embedded mode.</dd><dt><a class="ulink" href="maildropfilter.html#dotlock" target="_top" shape="rect">dotlock</a></dt><dd>
The dotlock command is not allowed in embedded mode.</dd><dt><a class="ulink" href="maildropfilter.html#flock" target="_top" shape="rect">flock</a></dt><dd>
The flock command is not allowed in embedded mode.</dd><dt><a class="ulink" href="maildropgdbm.html" target="_top" shape="rect">gdbmopen</a></dt><dd>
In embedded mode, GDBM
databases may be opened only for reading.</dd><dt><a class="ulink" href="maildropfilter.html#log" target="_top" shape="rect">log</a></dt><dd>
The log command is not allowed in embedded mode.</dd><dt><a class="ulink" href="maildropfilter.html#log" target="_top" shape="rect">logfile</a></dt><dd>
The logfile command is not allowed in embedded mode.</dd><dt><a class="ulink" href="maildropfilter.html#to" target="_top" shape="rect">to</a></dt><dd>
The to command is not allowed in embedded mode.</dd><dt><a class="ulink" href="maildropfilter.html#xfilter" target="_top" shape="rect">xfilter</a></dt><dd>
The xfilter command is not allowed in embedded mode.</dd></dl></div>
Normally when the <code class="filename">filename</code> 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 <code class="filename">filename</code> may communicate with the parent application
by
using the <a class="ulink" href="maildropfilter.html#echo" target="_top" shape="rect">echo</a> statement and the
<code class="varname">EXITCODE</code> environment variable.<div class="refsect2"><a id="idm255220116432" shape="rect"> </a><h3><code class="filename">/etc/maildroprcs</code></h3>If maildrop encounters an
<a class="ulink" href="maildropfilter.html#include" target="_top" shape="rect">include</a>
statement where the filename
starts with <code class="filename">/etc/maildroprcs/</code>,
the normal restrictions
for the embedded mode are suspended while executing the filter file in the
<code class="filename">/etc/maildroprcs</code> directory. The restrictions are
also
suspended for any additional filter files that are included from
<code class="filename">/etc/maildroprcs</code>. The restrictions resume once
maildrop finishes executing the file from
<code class="filename">/etc/maildroprcs</code>.
This allows the system administrator to have a controlled environment for
running external commands (via the backticks, or the
<a class="ulink" href="maildropfilter.html#xfilter" target="_top" shape="rect">xfilter</a> 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
<code class="filename">/etc/maildroprcs</code>
file, maildrop automatically resets the following variables to their
initial values: <code class="varname">DEFAULT</code>, <code class="varname">HOME</code>,
<code class="varname">LOCKEXT</code>, <code class="varname">LOCKSLEEP</code>,
<code class="varname">LOCKTIMEOUT</code>, <code class="varname">LOCKREFRESH</code>,
<code class="varname">LOGNAME</code>, <code class="varname">PATH</code>,
<code class="varname">SENDMAIL</code>, and <code class="varname">SHELL</code>.
Please note that the previous
values of these variables (if they were changed) will NOT be restored once
maildrop finishes executing the commands from
<code class="filename">/etc/maildroprcs</code>.</div></div><div class="refsect1"><a id="idm255220101152" shape="rect"> </a><h2>WATCHDOG TIMER</h2>
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.</div><div class="refsect1"><a id="idm255220098544" shape="rect"> </a><h2>FILES</h2><div class="variablelist"><dl class="variablelist"><dt><code class="filename">/etc/passwd</code></dt><dd>
Sets user's home directory, and related
variables. If NIS/YP is install, that will be used as well.</dd><dt><code class="filename">/etc/maildroprc</code></dt><dd>
Global filtering instructions for delivery mode.</dd><dt><code class="filename">/var/mail</code></dt><dd>
System mailbox (actual directory defined by the system administrator).</dd><dt><code class="filename">/usr/lib/sendmail</code></dt><dd>
Program to forward mail (exact program defined by the system
administrator).</dd><dt><code class="filename">$HOME/.mailfilter</code></dt><dd>
Filtering instructions in delivery mode.</dd><dt><code class="filename">$HOME/.mailfilters</code></dt><dd>
Directory containing files used in special embedded mode.</dd></dl></div></div><div class="refsect1"><a id="idm255220085696" shape="rect"> </a><h2>SEE ALSO</h2>
<a class="ulink" href="lockmail.html" target="_top" shape="rect">lockmail(1)</a>,
<a class="ulink" href="maildropfilter.html" target="_top" shape="rect">maildropfilter(7)</a>,
<a class="ulink" href="makedat.html" target="_top" shape="rect">makedat(1)</a>,
<a class="ulink" href="maildropgdbm.html" target="_top" shape="rect">maildropgdbm(7)</a>,
<a class="ulink" href="maildropex.html" target="_top" shape="rect">maildropex(7)</a>,
<a class="ulink" href="reformail.html" target="_top" shape="rect">reformail(1)</a>,
<a class="ulink" href="makemime.html" target="_top" shape="rect">makemime(1)</a>,
<a class="ulink" href="reformime.html" target="_top" shape="rect">reformime(1)</a>,
egrep(1),
grep(1),
,
<a class="ulink" href="courier.html" target="_top" shape="rect">courier(8)</a>,
sendmail(8),
<a class="ulink" href="http://www.qmail.org" target="_top" shape="rect">http://www.qmail.org</a>.</div></div></body></html>