1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
|
<!-- DSTART -->
<!-- -->
<!-- maildrop - mail delivery agent with filtering abilities -->
<!-- -->
<!-- Copyright 1998, Double Precision Inc. -->
<!-- -->
<!-- This program is distributed under the terms of the GNU General Publi -->
<!-- License. See COPYING for additional information. -->
<!-- DEND -->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.05 [en] (X11; I; Linux 2.0.34 i586) [Netscape]">
<TITLE>maildrop - mail delivery agent with filtering abilities</TITLE>
<!-- $Id: maildrop.html 1.6 1998/08/11 02:15:26 mrsam Exp $ -->
<!-- SECTION 1 -->
</HEAD>
<BODY>
<H1>
maildrop - mail delivery agent with filtering abilities</H1>
<BR><BR>
<H2>
SYNOPSIS</H2>
<TT>maildrop [options] [-d user] [arg] [arg] ...</TT>
<P><TT>maildrop [options] [filter-file [arg] [arg] ...]</TT>
<BR><BR>
<H2>
DESCRIPTION</H2>
<I>maildrop</I> is a replacement local mail delivery agent that includes integrated
mail filtering abilities. The system administrator can either replace the
existing mail delivery agent with <I>maildrop</I>, or a user may run <I>maildrop</I>
through the 'forward to program' mechanism of the existing mail delivery
agent.
<P><I>maildrop</I> reads the message from standard input and filters it according
to instructions in a <I>filter file</I>. If a message contains lines that
end in a carriage return, <I>maildrop</I> transparently strips the carriage
returns from the message, before filtering it or delivering the message
to a mailbox.
<P>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, <I>maildrop</I> will create one (if needed).
<P><I>maildrop</I> knows how to deliver mail to an mbox-formatted mailbox files;
it also knows how to deliver to maildir mailboxes. <I>maildir</I> is a
directory-based mailbox format used by <I>qmail</I> (<A HREF="http://www.qmail.org">http://www.qmail.org</A>).
<I>maildrop</I> does <I>NOT</I> deliver to regular directories, if you need
to save messages in a directory, one per file, create a maildir using the
<TT>maildirmake</TT> program. When delivering to mbox-formatted mailbox
files, <I>maildrop</I> 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).
<P>At least one mail program writes an empty line before a "From " header
when saving a message into a file. <I>maildrop</I> will ignore any empty lines
at the beginning of the message, therefore, <I>maildrop</I> requires that every
message must contain at least one header line.
<P><I>maildrop</I> 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 <I>maildrop</I> is invoked
directly by the local mail transport agent, the message is returned to
sender.
<P><I>maildrop</I> uses three different primary operating modes:
<UL>
<LI>
Manual mode - a file containing filtering instructions - a <I>filter file</I>
- is specified as an argument to the <I>maildrop</I> program. <I>maildrop</I> reads
this <I>filter file</I> and interprets the filtering instructions contained
in it. Unless the message is explicitly forwarded, bounced, deleted, or
delivered into a non-default mailbox, it will be delivered to the user's
system mailbox.</LI>
<BR><TT> </TT>
<LI>
Delivery mode - this mode is intended to be used when <I>maildrop</I> is used
as the default local delivery agent. <I>maildrop</I> runs in delivery mode when
no <I>filter file</I> is specified on the command line.</LI>
<BR><TT> </TT>
<LI>
Embedded mode - this is a special case of a delivery mode. In embedded
mode, <I>maildrop</I> functions as a part of another application. Embedded mode
is used when either the -m, or the -M, option is specified. See below for
a more extensive description of the embedded mode.</LI>
</UL>
In delivery mode, <I>maildrop</I> changes the current directory to the home
directory and reads <TT>$HOME/.mailfilter</TT> for filtering instructions.
If this file is missing, it is treated as if it was empty, resulting in
the message getting delivered to the user's default mailbox.
<P><I>maildrop</I> may be installed by the system administrator as a root setuid
program. If <I>maildrop</I> is run as root, the -d option is used to specify
the user to whom the message should be delivered. <I>maildrop</I> will immediately
reset its userid to the one specified by the -d option. This results in
the user's <TT>$HOME/.mailfilter</TT> file being read (if it exists), and
the message being delivered to the indicated user.
<P>The system administrator can configure <I>maildrop</I> to disable the -d
option for everyone except the mail system itself.
<P>When <I>maildrop</I> runs in delivery mode and the user's home directory
has its sticky bit set, <I>maildrop</I> immediately terminates with an exit
code of <TT>EX_TEMPFAIL</TT>, without doing anything. When <I>maildrop</I> is
invoked by a properly-written mail transport agent (MTA), the MTA interprets
the <TT>EX_TEMPFAIL</TT> exit code as a request to reschedule the message
for another delivery attempt later. Setting the sticky bit allows <TT>$HOME/.mailfilter</TT>
file to be edited by the user, while temporarily holding all incoming mail.
<P><I>maildrop</I> immediately terminates with the exit code set to <TT>EX_TEMPFAIL</TT>
if the user's home directory has world write permissions.
<P><I>maildrop</I> immediately terminates with the exit code set to <TT>EX_TEMPFAIL</TT>
if the <I>filter file</I> is not owned by the user, or if it has any group
or world permissions.
<P>When using the special embedded mode (see below) <I>maildrop</I> immediately
terminates with the exit code set to <TT>EX_TEMPFAIL</TT> if <TT>$HOME/.mailfilters</TT>
is not owned by the user, or has any group or world permissions.
<BR><BR>
<H2>
TEMPORARY FILES</H2>
<I>maildrop</I> is heavily optimized. <I>maildrop</I> is designed to use as little
resources as possible. <I>maildrop</I> reads smaller messages into memory, and
filters and/or delivers the message directly from memory. For larger messages,
<I>maildrop</I> will access the message directly from the file. If the standard
input is a pipe, <I>maildrop</I> will write the message to a temporary file,
then access the message from the temporary file. The temporary file is
automatically removed when the message is delivered.
<P>Temporary files are created in <TT>$HOME/.tmp</TT>. <I>maildrop</I>'s use
of temporary files is completely secure. <A NAME="options"></A>
<BR><BR>
<H2>
OPTIONS</H2>
<UL>
<LI>
-A 'header' - adds an additional header to the message. Specifying <I>-A
"Foo: Bar"</I> effectively adds this header to the message being delivered.</LI>
<P>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 <I>maildrop</I>, and adding some additional headers in the process.
Because <I>maildrop</I> receives the message from a pipe, <I>maildrop</I> must either
buffer the message in memory, or write the message into a temporary file.
<P>The -A option lets the file containing the message to be simply provided
to <I>maildrop</I> as standard input, with the additional headers specified
on the command line. Because the standard input is a file, <I>maildrop</I> doesn't
have to use a temporary file. Multiple -A options may be specified.
<BR><TT> </TT>
<LI>
-d user - run <I>maildrop</I> in delivery mode for this userid.</LI>
<P>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 <I>user</I> is the same user who is running <I>maildrop</I>. Also, for the
-d option to work at all, <I>maildrop</I> must be invoked by root, or <I>maildrop</I>
must be a setuid root program. Absence of a <I>filter file</I> implies
the -d option for the user running <I>maildrop</I> .
<P>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
<A HREF="maildropfilter.html#environment">"Environment"</A> and <A HREF="maildropfilter.html#varsubst">"Variable
substitution"</A>)
<BR><TT> </TT>
<LI>
-m - run <I>maildrop</I> 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 <I>.mailfilter</I>,
that <I>.mailfilter</I> probably has at least one instruction which is
not allowed in the embedded mode.</LI>
<P>The <I>filter-file</I> argument to <I>maildrop</I> should be specified. <I>filter-file</I>
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 <TT>$HOME/.mailfilters</TT>, and used
with the -M option.
<BR>
<BR><A NAME="moption"></A>
<LI>
-M filterfile - run <I>maildrop</I> in a special embedded mode. The -d option
is implied when the -M option is used. If the -d option is not specified,
the -d option for the user running <I>maildrop</I> is used.</LI>
<P>All the requirements for the -d option apply. <I>maildrop</I> must be either
a root setuid program, or invoked by root. <I>maildrop</I> immediately gives
up root privileges by changing its userid to the one specified by the -d
option, then reads <TT>$HOME/.mailfilters/filterfile</TT> as in embedded
mode. The name of the file may not begin with a slash or include periods,
for security reasons. <I>maildrop</I> is paranoid: both <TT>$HOME/.mailfilters</TT>,
and <TT>$HOME/.mailfilters/filterfile</TT> must be owned by the user, and
may not have any group or world permissions.
<P>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.
<P><I>maildrop</I> supports the concept of "default" filter files. If the file
specified by the -M option cannot be found in <TT>$HOME/.mailfilters</TT>,
<I>maildrop</I> will try to open <TT>$HOME/.mailfilters/<B>file</B>-default</TT>.
If that file does not exist, <I>maildrop</I> will check if <B><TT>file</TT></B>
has any dashes. If it does, everything following the last dash is replaced
by "default", and <I>maildrop</I> tries again. <I>maildrop</I> will keep trying until
there are no more dashes left. As a last resort, <I>maildrop</I> will try to
open <TT>$HOME/.mailfilters/default</TT>.
<P>For example, if the parameter to the -M option is <TT>mailfilter-lists-maildrop</TT>,
<I>maildrop</I> will try to open the following files, in order:
<PRE>
<TT> $HOME/.mailfilters/mailfilter-lists-maildrop
$HOME/.mailfilters/mailfilter-lists-maildrop-default
$HOME/.mailfilters/mailfilter-lists-default
$HOME/.mailfilters/mailfilter-default
$HOME/.mailfilters/default</TT></PRE>
Note that attempts to find a -default file will be made only if the -M
option is used.
<BR><TT> </TT>
<LI>
-V level - initialize <TT>VERBOSE</TT> variable to <I>level</I>. Because
<I>maildrop</I> parses the entire <I>filter file</I> before running it, this
option is used to produce debugging output in the parsing phase. Otherwise,
if <I>filter file</I> has syntax errors, then no debugging output is possible
because the <TT>VERBOSE</TT> variable will not get set.</LI>
<P>The -V option is ignored when <I>maildrop</I> runs in delivery mode.</UL>
<BR><BR>
<H2>
DELIVERY MODE</H2>
<I>maildrop</I> runs in delivery mode when either the filter file is not specified,
or the -d option is used. In delivery mode, <I>maildrop</I> changes to the home
directory of the user specified by the -d option (or the user who is running
<I>maildrop</I> if the -d option was not given) and reads <TT>$HOME/.mailfilter</TT>
for filtering instructions. <TT>$HOME/.mailfilter</TT> must be owned by
the user, and have no group or global permissions (<I>maildrop</I> will terminate
if it does).
<P>If <TT>$HOME/.mailfilter</TT> does not exist, <I>maildrop</I> will simply
deliver the message to the user's mailbox.
<P>If the file <TT>/etc/maildroprc</TT> exists, <I>maildrop</I> will first read
filtering instructions from this file, before reading <TT>$HOME/.mailfilter</TT>.
This allows the system administrator to provide global filtering instructions
for all users.
<P>NOTE - <TT>/etc/maildroprc</TT> is read only in delivery mode.
<P><A NAME="embedded"></A>
<BR><BR>
<H2>
EMBEDDED MODE</H2>
The embedded mode is used when <I>maildrop</I>'s filtering abilities are desired,
but no actual mail delivery is needed. In embedded mode <I>maildrop</I> is executed
from within another application, and <A HREF="#options">is passed the -m
or the -M option.</A> <I>maildrop</I> reads the message, then runs the filtering
rules specified in the <I>filter file</I>. The <I>filter file</I> may contain
any filtering instructions EXCEPT the following:
<UL>
<LI>
` ... ` - text strings delimited by back-tick characters (run shell command)
are not allowed.</LI>
<LI>
<A HREF="maildropfilter.html#cc">cc</A></LI>
<LI>
<A HREF="maildropfilter.html#dotlock">dotlock</A></LI>
<LI>
<A HREF="maildropfilter.html#flock">flock</A></LI>
<LI>
<A HREF="maildropfilter.html#log">log</A></LI>
<LI>
<A HREF="maildropfilter.html#log">logfile</A></LI>
<LI>
<A HREF="maildropfilter.html#to">to</A></LI>
<LI>
<A HREF="maildropfilter.html#xfilter">xfilter</A></LI>
</UL>
Normally when the <I>filter file</I> does not provide an explicit mailbox
to deliver the message to, <I>maildrop</I> delivers the message to the user's
default mailbox. This behavior is also disabled in embedded mode.
<P>The <I>filter file</I> may communicate the result of the filtering to
the parent application by using the <A HREF="maildropfilter.html#echo">echo</A>
statement, and the <I>EXITCODE</I> environment variable.
<BR><BR>
<H2>
WATCHDOG TIMER</H2>
<I>maildrop</I> 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), <I>maildrop</I> terminates.
Hopefully this will take care of runaway filters.
<BR><BR>
<H2>
FILES</H2>
<UL>
<LI>
<TT>/etc/passwd </TT>- to set user's home directory, and related variables.
If NIS/YP is install, that will be used as well.</LI>
<LI>
<TT>/etc/maildroprc</TT> - global filtering instructions for delivery mode.</LI>
<LI>
<TT>/var/spool/mail</TT> - system mailbox (actual directory defined by
the system administrator).</LI>
<LI>
<TT>/usr/lib/sendmail</TT> - program to forward mail (exact program defined
by the system administrator).</LI>
<LI>
<TT>$HOME/.tmp </TT>- directory for temporary files.</LI>
<LI>
<TT>$HOME/.mailfilter</TT> - filter file used in delivery mode.</LI>
<LI>
<TT>$HOME/.mailfilters</TT> - directory containing filter files to be used
for special embedded mode.</LI>
</UL>
<BR><BR>
<H2>
SEE ALSO</H2>
<A HREF="dotlock.html">dotlock(1),</A> <A HREF="maildropfilter.html">maildropfilter(1),</A>
<A HREF="maildropex.html">maildropex(5),</A> <A HREF="reformail.html">reformail(1),</A>
egrep(1), grep(1), sendmail(8), <A HREF="http://www.qmail.org">http://www.qmail.org</A>
</BODY>
</HTML>
|
