1MAILDROP(1) Double Precision, Inc. MAILDROP(1)
2
6 maildrop - mail delivery filter/agent
7
9 maildrop [option...] [-d user] [arg...]
10 maildrop [option...] [filename] [arg...]
12
14 maildrop is a replacement local mail delivery agent that includes a
15 mail filtering language. The system administrator can either replace
16 the existing mail delivery agent with maildrop, or users may run
17 maildrop using the ´forward to program´ mechanism of the existing mail
18 delivery agent.
19 maildrop first reads the E-mail message on standard input. Trailing
21 carriage return characters are automatically stripped. An E-mail
22 message consists of header lines, followed by a blank line, followed by
23 the contents of the message. The message may contain an mbox-style
24 From_ line before the first header line. If the message does not
25 contain a From_ line, maildrop will create one (if needed).
26 If the file /etc/maildroprc exists, mail delivery or mail filtering
28 instructions are read from that file. maildrop´s delivery/filtering
29 instructions may direct maildrop to save the message in specific
30 mailbox, discard it, return it to sender, or forward it to a different
31 E-mail address.
32 If /etc/maildroprc does not exist, or its mail delivery instructions do
34 not completely dispose of this message, maildrop then reads the mail
35 delivery instructions from $HOME/.mailfilter. If it doesn´t exist, or
36 its mail delivery instructions do not completely dispose of the
37 message, maildrop then saves the E-mail message in the default mailbox.
38 maildrop knows how to deliver mail to an standard mailbox files; it
40 also knows how to deliver to maildirs. A maildir is a directory-based
41 mail format used by the Courier[1] and Qmail[2] mail servers. Many
42 other mail servers also know how to read maildirs. When delivering to
43 mailbox files, maildrop will lock the mailbox for the duration of the
44 delivery.
45 At least one mail program writes an empty line before a From_ header
47 when saving a message into a file. maildrop ignores empty lines at the
48 beginning of messages. Therefore, maildrop requires that every message
49 must have at least one header line.
50 This is the general mail delivery behavior. There are minor differences
52 in behavior depending on maildrop delivery mode, which is determined
53 based on how maildrop was started. maildrop uses three different
54 primary operating modes:
55 Manual mode
57 A file containing filtering instructions - filename is specified as
58 an argument to the maildrop command. maildrop reads this filename
59 (after /etc/maildroprc) and follows the instructions in it. Unless
60 the message is explicitly forwarded, bounced, deleted, or delivered
61 to a specific mailbox, it will be delivered to the user´s system
62 mailbox.
63 Delivery mode
65 maildrop is the mail server´s mail delivery agent. maildrop runs
67 in delivery mode when no filename is specified on the command line.
68 maildrop changes the current directory to the user´s home
69 directory, then reads /etc/maildroprc, then $HOME/.mailfilter.
70 Embedded mode
72 maildrop functions as a part of another application. The embedded
74 mode is used by the Courier[1] mail server to integrate mail
75 filtering directly into the process of receiving mail from a remote
76 mail relay, thus rejecting unwanted mail before it is even accepted
77 for local mail delivery. Embedded mode is used when either the -m,
78 or the -M, option is specified, and is described below. See below
79 for a more extensive description of the embedded mode.
80
82 It is safe to install maildrop as a root setuid program. The Courier
83 mail server[1] installs maildrop as a root setuid program by default,
84 in order to be able to use maildrop in embedded mode. If root runs
85 maildrop (or it is setuided to root) the -d option may be used to
86 specify the message´s recipient. maildrop immediately resets its
87 userid to the one specified by the -d option. The user´s
88 $HOME/.mailfilter is read (if it exists), and the message is delivered
89 to the indicated user.
90 The system administrator can configure maildrop to restrict the -d
92 option for everyone except the mail system itself.
93 If in delivery mode the user´s home directory has the sticky bit set,
95 maildrop immediately terminates with an exit code of EX_TEMPFAIL,
96 without doing anything. Mail servers interpret the EX_TEMPFAIL exit
97 code as a request to reschedule the message for another delivery
98 attempt later. Setting the sticky bit allows $HOME/.mailfilter to be
99 edited while temporarily holding all incoming mail.
100 maildrop also terminates with EX_TEMPFAIL if the user´s home directory
102 has world write permissions.
103 maildrop immediately terminates with EX_TEMPFAIL if the filename is not
105 owned by the user, or if it has any group or world permissions. This
106 includes read permissions. The permissions on $HOME/.mailfilter may
107 only include read and write privileges to the user.
108 When using the special embedded mode (see below) maildrop immediately
110 terminates with the exit code set to EX_TEMPFAIL if $HOME/.mailfilters
111 is not owned by the user, or if it has any group or world permissions.
112
114 maildrop is heavily optimized and tries to use as little resources as
115 possible. maildrop reads small messages into memory, then filters
116 and/or delivers the message directly from memory. For larger messages,
117 maildrop accesses the message directly from the file. If the standard
118 input is not a file, maildrop writes the message to a temporary file,
119 then accesses the message from the temporary file. The temporary file
120 is automatically removed when the message is delivered.
121
123 -a
124 Makes the Courier Authentication Library usage mandatory, i.e.
125 maildrop will throw a temporary error code if the call to the
126 authlib mechanism fails for some reason, such as authdaemon being
127 inaccessible.
128 Note
130 This setting may already be the default, depending on
131 maildrop´s configuration.
132 -A "Header: value"
134 Adds an additional header to the message. Specifying -A "Foo: Bar"
135 effectively adds this header to the message being delivered.
136 The mail transport agent usually adds additional headers when
138 delivering a message to a local mailbox. The way it´s usually done
139 is by the mail transport agent sending the message using a pipe to
140 the local delivery agent - such as maildrop - and adding some
141 additional headers in the process. Because maildrop receives the
142 message from a pipe, maildrop must either save the message in
143 memory or write the message into a temporary file.
144 The -A option enables the file containing the message to be
146 provided to maildrop directly, as standard input, and the
147 additional headers specified on the command line. Because the
148 standard input is a file, maildrop will not need a temporary file.
149 Multiple -A options may be specified.
150 -d user
152 Run maildrop in delivery mode for this user ID.
153 The system administrator may optionally restrict the -d option to
155 be available to the mail system only, so it may not be available to
156 you. In all cases, the -d option is allowed if user is the same
157 user who is running maildrop. Also, for the -d option to work at
158 all, maildrop must be executed by root, or maildrop must be a
159 root-owned program with the setuid bit set. Absence of a filename
160 on maildrop´s command line implies the -d option for the user
161 running maildrop.
162 If -d is not specified, the first argument following all the
164 options is a name of the file containing filtering instructions.
165 The remaining arguments, if any, are assigned to the variables $1,
166 $2, and so on (see "Environment"[3] and "Variable
167 substitution"[4]).
168 -f address
170 Sets the FROM variable (message envelope sender) to address. The
171 system administrator may optionally disable the -f option for
172 users, so it may not be available to you.
173 -m
175 Run maildrop in embedded mode. It´s possible to use both the -m,
176 and the -d options, but it doesn´t make much sense to do so. Even
177 if you really wanted to run your message through someone else´s
178 .mailfilter, that .mailfilter probably has at least one instruction
179 which is not allowed in the embedded mode.
180 The filename argument to maildrop should be specified. filename is
182 a file that includes filtering instructions to be processed in
183 embedded mode. The -m option is used for debugging filter files
184 which are later placed in $HOME/.mailfilters, and used with the -M
185 option.
186 -M filterfile
188 Run maildrop in a special embedded mode. The -d option is implied
189 when -M is used, and if absent it defaults to the userid running
190 maildrop.
191 All the requirements for the -d option apply. maildrop must either
193 be executed by root, or the maildrop program must be owned by root
194 with the setuid bit set. maildrop immediately gives up root
195 privileges by changing its user ID to the one specified by -d, then
196 reads $HOME/.mailfilters/filterfile. For security reasons the name
197 of the file may not begin with a slash or include periods.
198 maildrop is very paranoid: both $HOME/.mailfilters, and
199 $HOME/.mailfilters/filterfile must be owned by the user, and may
200 not have any group or world permissions.
201 The -M option allows for some friendly cooperation between the user
203 running the application, and the user who provides a filter for the
204 embedded mode. The user running the application can use someone
205 else´s canned filter and be assured that the filter is not going to
206 run amok and start sending mail or create files all over the place.
207 The user who provides the filter can be assured that the
208 environment variables are clean, and that there are no surprises.
209 maildrop supports the concept of "default" filter files. If the
212 file specified by the -M option cannot be found in
213 $HOME/.mailfilters, maildrop will try to open
214 $HOME/.mailfilters/filterfileprefix-default. filterfileprefix is
215 the initial part of filterfile up until the last ´-´ character in
216 filterfile.
217 If $HOME/.mailfilters/filterfileprefix-default does not exist, and
219 there are any other dashes left in filterfileprefix, maildrop
220 removes the last dash and everything following it, then tries
221 again.
222 As a last resort maildrop tries to open $HOME/.mailfilters/default.
224 For example, if the parameter to the -M option is
226 mailfilter-lists-maildrop, maildrop will try to open the following
227 files, in order:
228 Note that maildrop looks for -default files ONLY if -M is used.
230 -D uuu/ggg
232 This option is reserved for use by the version of maildrop that
233 comes integrated with the Courier mail server[1].
234 -V level
236 Initialize the VERBOSE variable to level. Because maildrop parses
237 the entire file before running it, this option is used to produce
238 debugging output in the parsing phase. Otherwise, if filename has
239 syntax errors, then no debugging output is possible because the
240 VERBOSE variable is not yet set.
241 -V is ignored when maildrop runs in delivery mode.
244 -w N
246 The -w N option places a warning message into the maildir if the
247 maildir has a quota setting, and after the message was successfully
248 delivered the maildir was at least N percent full.
249 -W filename
251 Copy the warning message from filename, or from /etc/quotawarnmsg
252 if this option is not specified, with the addition of the "Date:"
253 and "Message-Id:" headers. The warning is repeated every 24 hours
254 (at least), until the maildir drops below N percent full.
255
257 If a filename is not specified on the command line, or if the -d option
258 is used, maildrop will run in delivery mode. In delivery mode, maildrop
259 changes to the home directory of the user specified by the -d option
260 (or the user who is running maildrop if the -d option was not given)
261 and reads $HOME/.mailfilter for filtering instructions.
262 $HOME/.mailfilter must be owned by the user, and have no group or
263 global permissions (maildrop terminates if it does).
264 If $HOME/.mailfilter does not exist, maildrop will simply deliver the
266 message to the user´s mailbox.
267 If the file /etc/maildroprc exists, maildrop reads filtering
269 instructions from this file first, before reading $HOME/.mailfilter.
270 This allows the system administrator to provide global filtering
271 instructions for all users.
272 Note
274 /etc/maildroprc is read only in delivery mode.
275
277 The -d option can also specify a name of a virtual account or mailbox.
278 See the makeuserdb(1) manual page in the Courier Authentication
279 library´s documentation for more information.
280
282 The embedded mode is used when maildrop´s filtering abilities are
283 desired, but no actual mail delivery is needed. In embedded mode
284 maildrop is executed by another application, and is passed the -m or
285 the -M option.[5] maildrop reads the message, then runs the filtering
286 rules specified in filename.
287 filename may contain any filtering instructions EXCEPT the following:
289 ` ... `
291 Text strings delimited by back-tick characters (run shell command)
292 are not allowed.
293 cc[6]
295 The cc command is not allowed in embedded mode.
296 dotlock[7]
298 The dotlock command is not allowed in embedded mode.
299 flock[8]
301 The flock command is not allowed in embedded mode.
302 gdbmopen[9]
304 In embedded mode, GDBM databases may be opened only for reading.
305 log[10]
307 The log command is not allowed in embedded mode.
308 logfile[10]
310 The logfile command is not allowed in embedded mode.
311 to[11]
313 The to command is not allowed in embedded mode.
314 xfilter[12]
316 The xfilter command is not allowed in embedded mode.
317 Normally when the filename does not explicitly delivers a message,
319 maildrop will deliver the message to the user´s default mailbox. This
320 is also disabled in embedded mode.
321 The filename may communicate with the parent application by using the
323 echo[13] statement and the EXITCODE environment variable.
324 /etc/maildroprcs
326 If maildrop encounters an include[14] statement where the filename
327 starts with /etc/maildroprcs/, the normal restrictions for the embedded
328 mode are suspended while executing the filter file in the
329 /etc/maildroprcs directory. The restrictions are also suspended for any
330 additional filter files that are included from /etc/maildroprcs. The
331 restrictions resume once maildrop finishes executing the file from
332 /etc/maildroprcs.
333 This allows the system administrator to have a controlled environment
335 for running external commands (via the backticks, or the xfilter[12]
336 command).
337 The name of the file may not contain any periods (so that a creative
339 individual can´t write include
340 "/etc/maildroprcs/../../home/user/recipe").
341 Before executing the commands in the /etc/maildroprcs file, maildrop
343 automatically resets the following variables to their initial values:
344 DEFAULT, HOME, LOCKEXT, LOCKSLEEP, LOCKTIMEOUT, LOCKREFRESH, LOGNAME,
345 PATH, SENDMAIL, and SHELL. Please note that the previous values of
346 these variables (if they were changed) will NOT be restored once
347 maildrop finishes executing the commands from /etc/maildroprcs.
348
350 maildrop has a watchdog timer that attempts to abort runaway filtering.
351 If filtering is not complete within a predefined time interval (defined
352 by the system administrator, usually five minutes), maildrop
353 terminates.
354
356 /etc/passwd
357 Sets user´s home directory, and related variables. If NIS/YP is
358 install, that will be used as well.
359 /etc/maildroprc
361 Global filtering instructions for delivery mode.
362 /var/mail
364 System mailbox (actual directory defined by the system
365 administrator).
366 /usr/lib/sendmail
368 Program to forward mail (exact program defined by the system
369 administrator).
370 $HOME/.mailfilter
372 Filtering instructions in delivery mode.
373 $HOME/.mailfilters
375 Directory containing files used in special embedded mode.
376
378 lockmail(1)[15], maildropfilter(7)[16], makedat(1)[17],
379 maildropgdbm(7)[9], maildropex(7)[18], reformail(1)[19],
380 makemime(1)[20], reformime(1)[21], egrep(1), grep(1), , courier(8)[22],
381 sendmail(8), http://www.qmail.org.
382
384 1. Courier
385 http://www.courier-mta.org
386 2. Qmail
388 http://www.qmail.org
389 3. "Environment"
391 [set
392 $man.base.url.for.relative.links]/maildropfilter.html#environment
393 4. "Variable substitution"
395 [set $man.base.url.for.relative.links]/maildropfilter.html#varsubst
396 5. is passed the -m or the -M option.
398 [set $man.base.url.for.relative.links]/#options
399 6. cc
401 [set $man.base.url.for.relative.links]/maildropfilter.html#cc
402 7. dotlock
404 [set $man.base.url.for.relative.links]/maildropfilter.html#dotlock
405 8. flock
407 [set $man.base.url.for.relative.links]/maildropfilter.html#flock
408 9. gdbmopen
410 [set $man.base.url.for.relative.links]/maildropgdbm.html
411 10. log
413 [set $man.base.url.for.relative.links]/maildropfilter.html#log
414 11. to
416 [set $man.base.url.for.relative.links]/maildropfilter.html#to
417 12. xfilter
419 [set $man.base.url.for.relative.links]/maildropfilter.html#xfilter
420 13. echo
422 [set $man.base.url.for.relative.links]/maildropfilter.html#echo
423 14. include
425 [set $man.base.url.for.relative.links]/maildropfilter.html#include
426 15. lockmail(1)
428 [set $man.base.url.for.relative.links]/lockmail.html
429 16. maildropfilter(7)
431 [set $man.base.url.for.relative.links]/maildropfilter.html
432 17. makedat(1)
434 [set $man.base.url.for.relative.links]/makedat.html
435 18. maildropex(7)
437 [set $man.base.url.for.relative.links]/maildropex.html
438 19. reformail(1)
440 [set $man.base.url.for.relative.links]/reformail.html
441 20. makemime(1)
443 [set $man.base.url.for.relative.links]/makemime.html
444 21. reformime(1)
446 [set $man.base.url.for.relative.links]/reformime.html
447 22. courier(8)
449 [set $man.base.url.for.relative.links]/courier.html
450Double Precision, Inc. 03/24/2010 MAILDROP(1)