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.
24 maildrop does not accept an mbox-style From_ line before the first
26 header line. maildrop does not accept leading empty lines before the
27 first non-blank header line. If the message can possibly start with
28 empty lines, and a From_ line, use reformail -f0 to remove any initial
29 empty lines, and replace a From_ line with a proper “Return-Path:”
30 header; then pipe it to maildrop.
31 If the file /etc/maildroprc exists, mail delivery or mail filtering
33 instructions are read from that file. maildrop's delivery/filtering
34 instructions may direct maildrop to save the message in specific
35 mailbox, discard it, return it to sender, or forward it to a different
36 E-mail address.
37 If /etc/maildroprc does not exist, or its mail delivery instructions do
39 not completely dispose of this message, maildrop then reads the mail
40 delivery instructions from $HOME/.mailfilter. If it doesn't exist, or
41 its mail delivery instructions do not completely dispose of the
42 message, maildrop then saves the E-mail message in the default mailbox.
43 maildrop knows how to deliver mail to an standard mailbox files; it
45 also knows how to deliver to maildirs. A maildir is a directory-based
46 mail format used by the Courier[1] and Qmail[2] mail servers. Many
47 other mail servers also know how to read maildirs. When delivering to
48 mailbox files, maildrop will lock the mailbox for the duration of the
49 delivery.
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
66 in delivery mode when no filename is specified on the command line.
67 maildrop changes the current directory to the user's home
68 directory, then reads /etc/maildroprc, then $HOME/.mailfilter.
69 Embedded mode
71 maildrop functions as a part of another application. The embedded
72 mode is used by the Courier[1] mail server to integrate mail
73 filtering directly into the process of receiving mail from a remote
74 mail relay, thus rejecting unwanted mail before it is even accepted
75 for local mail delivery. Embedded mode is used when either the -m,
76 or the -M, option is specified, and is described below. See below
77 for a more extensive description of the embedded mode.
78
80 It is safe to install maildrop as a root setuid program. The Courier
81 mail server[1] installs maildrop as a root setuid program by default,
82 in order to be able to use maildrop in embedded mode. If root runs
83 maildrop (or it is setuided to root) the -d option may be used to
84 specify the message's recipient. maildrop immediately resets its
85 userid to the one specified by the -d option. The user's
86 $HOME/.mailfilter is read (if it exists), and the message is delivered
87 to the indicated user.
88 The system administrator can configure maildrop to restrict the -d
90 option for everyone except the mail system itself.
91 If in delivery mode the user's home directory has the sticky bit set,
93 maildrop immediately terminates with an exit code of EX_TEMPFAIL,
94 without doing anything. Mail servers interpret the EX_TEMPFAIL exit
95 code as a request to reschedule the message for another delivery
96 attempt later. Setting the sticky bit allows $HOME/.mailfilter to be
97 edited while temporarily holding all incoming mail.
98 maildrop also terminates with EX_TEMPFAIL if the user's home directory
100 has world write permissions.
101 maildrop immediately terminates with EX_TEMPFAIL if the filename is not
103 owned by the user, or if it has any group or world permissions. This
104 includes read permissions. The permissions on $HOME/.mailfilter may
105 only include read and write privileges to the user.
106 When using the special embedded mode (see below) maildrop immediately
108 terminates with the exit code set to EX_TEMPFAIL if $HOME/.mailfilters
109 is not owned by the user, or if it has any group or world permissions.
110
112 maildrop is heavily optimized and tries to use as little resources as
113 possible. maildrop reads small messages into memory, then filters
114 and/or delivers the message directly from memory. For larger messages,
115 maildrop accesses the message directly from the file. If the standard
116 input is not a file, maildrop writes the message to a temporary file,
117 then accesses the message from the temporary file. The temporary file
118 is automatically removed when the message is delivered.
119
121 -a
122 Makes the Courier Authentication Library usage mandatory, i.e.
123 maildrop will throw a temporary error code if the call to the
124 authlib mechanism fails for some reason, such as authdaemon being
125 inaccessible.
126 Note
128 This setting may already be the default, depending on
129 maildrop's configuration.
130 -A "Header: value"
132 Adds an additional header to the message. Specifying -A "Foo: Bar"
133 effectively adds this header to the message being delivered.
134 The mail transport agent usually adds additional headers when
136 delivering a message to a local mailbox. The way it's usually done
137 is by the mail transport agent sending the message using a pipe to
138 the local delivery agent - such as maildrop - and adding some
139 additional headers in the process. Because maildrop receives the
140 message from a pipe, maildrop must either save the message in
141 memory or write the message into a temporary file.
142 The -A option enables the file containing the message to be
144 provided to maildrop directly, as standard input, and the
145 additional headers specified on the command line. Because the
146 standard input is a file, maildrop will not need a temporary file.
147 Multiple -A options may be specified.
148 -d user
150 Run maildrop in delivery mode for this user ID.
151 The system administrator may optionally restrict the -d option to
153 be available to the mail system only, so it may not be available to
154 you. In all cases, the -d option is allowed if user is the same
155 user who is running maildrop. Also, for the -d option to work at
156 all, maildrop must be executed by root, or maildrop must be a
157 root-owned program with the setuid bit set. Absence of a filename
158 on maildrop's command line implies the -d option for the user
159 running maildrop.
160 If -d is not specified, the first argument following all the
162 options is a name of the file containing filtering instructions.
163 The remaining arguments, if any, are assigned to the variables $1,
164 $2, and so on (see "Environment"[3] and "Variable
165 substitution"[4]).
166 -f address
168 Sets the FROM variable (message envelope sender) to address. The
169 system administrator may optionally disable the -f option for
170 users, so it may not be available to you.
171 -m
173 Run maildrop in embedded mode. It's possible to use both the -m,
174 and the -d options, but it doesn't make much sense to do so. Even
175 if you really wanted to run your message through someone else's
176 .mailfilter, that .mailfilter probably has at least one instruction
177 which is not allowed in the embedded mode.
178 The filename argument to maildrop should be specified. filename is
180 a file that includes filtering instructions to be processed in
181 embedded mode. The -m option is used for debugging filter files
182 which are later placed in $HOME/.mailfilters, and used with the -M
183 option.
184 -M filterfile
186 Run maildrop in a special embedded mode. The -d option is implied
187 when -M is used, and if absent it defaults to the userid running
188 maildrop.
189 All the requirements for the -d option apply. maildrop must either
191 be executed by root, or the maildrop program must be owned by root
192 with the setuid bit set. maildrop immediately gives up root
193 privileges by changing its user ID to the one specified by -d, then
194 reads $HOME/.mailfilters/filterfile. For security reasons the name
195 of the file may not begin with a slash or include periods.
196 maildrop is very paranoid: both $HOME/.mailfilters, and
197 $HOME/.mailfilters/filterfile must be owned by the user, and may
198 not have any group or world permissions.
199 The -M option allows for some friendly cooperation between the user
201 running the application, and the user who provides a filter for the
202 embedded mode. The user running the application can use someone
203 else's canned filter and be assured that the filter is not going to
204 run amok and start sending mail or create files all over the place.
205 The user who provides the filter can be assured that the
206 environment variables are clean, and that there are no surprises.
207 maildrop supports the concept of "default" filter files. If the
209 file specified by the -M option cannot be found in
210 $HOME/.mailfilters, maildrop will try to open
211 $HOME/.mailfilters/filterfileprefix-default. filterfileprefix is
212 the initial part of filterfile up until the last '-' character in
213 filterfile.
214 If $HOME/.mailfilters/filterfileprefix-default does not exist, and
216 there are any other dashes left in filterfileprefix, maildrop
217 removes the last dash and everything following it, then tries
218 again.
219 As a last resort maildrop tries to open $HOME/.mailfilters/default.
221 For example, if the parameter to the -M option is
223 mailfilter-lists-maildrop, maildrop will try to open the following
224 files, in order:
225 Note that maildrop looks for -default files ONLY if -M is used.
227 -D uuu/ggg
229 This option is reserved for use by the version of maildrop that
230 comes integrated with the Courier mail server[1].
231 -V level
233 Initialize the VERBOSE variable to level. Because maildrop parses
234 the entire file before running it, this option is used to produce
235 debugging output in the parsing phase. Otherwise, if filename has
236 syntax errors, then no debugging output is possible because the
237 VERBOSE variable is not yet set.
238 -V is ignored when maildrop runs in delivery mode.
240 -w N
242 The -w N option places a warning message into the maildir if the
243 maildir has a quota setting, and after the message was successfully
244 delivered the maildir was at least N percent full.
245 -W filename
247 Copy the warning message from filename, or from /etc/quotawarnmsg
248 if this option is not specified, with the addition of the "Date:"
249 and "Message-Id:" headers. The warning is repeated every 24 hours
250 (at least), until the maildir drops below N percent full.
251 -t socket
253 This option is available if maildrop is compiled with optional
254 Dovecot authentication support. socket specifies the location of
255 Dovecot master authentication socket, for example
256 /var/run/dovecot/auth-master.
257
259 If a filename is not specified on the command line, or if the -d option
260 is used, maildrop will run in delivery mode. In delivery mode, maildrop
261 changes to the home directory of the user specified by the -d option
262 (or the user who is running maildrop if the -d option was not given)
263 and reads $HOME/.mailfilter for filtering instructions.
264 $HOME/.mailfilter must be owned by the user, and have no group or
265 global permissions (maildrop terminates if it does).
266 If $HOME/.mailfilter does not exist, maildrop will simply deliver the
268 message to the user's mailbox.
269 If the file /etc/maildroprc exists, maildrop reads filtering
271 instructions from this file first, before reading $HOME/.mailfilter.
272 This allows the system administrator to provide global filtering
273 instructions for all users.
274 Note
276 /etc/maildroprc is read only in delivery mode.
277
279 The -d option can also specify a name of a virtual account or mailbox.
280 See the makeuserdb(1) manual page in the Courier Authentication
281 library's documentation for more information.
282
284 The embedded mode is used when maildrop's filtering abilities are
285 desired, but no actual mail delivery is needed. In embedded mode
286 maildrop is executed by another application, and is passed the ‐m or
287 the ‐M option.[5] maildrop reads the message, then runs the filtering
288 rules specified in filename.
289 filename may contain any filtering instructions EXCEPT the following:
291 ` ... `
293 Text strings delimited by back-tick characters (run shell command)
294 are not allowed.
295 cc[6]
297 The cc command is not allowed in embedded mode.
298 dotlock[7]
300 The dotlock command is not allowed in embedded mode.
301 flock[8]
303 The flock command is not allowed in embedded mode.
304 gdbmopen[9]
306 In embedded mode, GDBM databases may be opened only for reading.
307 log[10]
309 The log command is not allowed in embedded mode.
310 logfile[10]
312 The logfile command is not allowed in embedded mode.
313 system[11]
315 The system command is not allowed in embedded mode.
316 to[12]
318 The to command is not allowed in embedded mode.
319 xfilter[13]
321 The xfilter command is not allowed in embedded mode.
322 Normally when the filename does not explicitly delivers a message,
324 maildrop will deliver the message to the user's default mailbox. This
325 is also disabled in embedded mode.
326 The filename may communicate with the parent application by using the
328 echo[14] statement and the EXITCODE environment variable.
329 /etc/maildroprcs
331 If maildrop encounters an include[15] statement where the filename
332 starts with /etc/maildroprcs/, the normal restrictions for the embedded
333 mode are suspended while executing the filter file in the
334 /etc/maildroprcs directory. The restrictions are also suspended for any
335 additional filter files that are included from /etc/maildroprcs. The
336 restrictions resume once maildrop finishes executing the file from
337 /etc/maildroprcs.
338 This allows the system administrator to have a controlled environment
340 for running external commands (via the backticks, the system[11] or the
341 xfilter[13] commands).
342 The name of the file may not contain any periods (so that a creative
344 individual can't write include
345 "/etc/maildroprcs/../../home/user/recipe").
346 Before executing the commands in the /etc/maildroprcs file, maildrop
348 automatically resets the following variables to their initial values:
349 DEFAULT, HOME, LOCKEXT, LOCKSLEEP, LOCKTIMEOUT, LOCKREFRESH, LOGNAME,
350 PATH, SENDMAIL, and SHELL. Please note that the previous values of
351 these variables (if they were changed) will NOT be restored once
352 maildrop finishes executing the commands from /etc/maildroprcs.
353
355 maildrop has a watchdog timer that attempts to abort runaway filtering.
356 If filtering is not complete within a predefined time interval (defined
357 by the system administrator, usually five minutes), maildrop
358 terminates.
359
361 /etc/passwd
362 Sets user's home directory, and related variables. If NIS/YP is
363 install, that will be used as well.
364 /etc/maildroprc
366 Global filtering instructions for delivery mode.
367 /var/mail
369 System mailbox (actual directory defined by the system
370 administrator).
371 /usr/lib/sendmail
373 Program to forward mail (exact program defined by the system
374 administrator).
375 $HOME/.mailfilter
377 Filtering instructions in delivery mode.
378 $HOME/.mailfilters
380 Directory containing files used in special embedded mode.
381
383 lockmail(1)[16], maildropfilter(7)[17], makedat(1)[18],
384 maildropgdbm(7)[9], maildropex(7)[19], reformail(1)[20],
385 makemime(1)[21], reformime(1)[22], egrep(1), grep(1), , courier(8)[23],
386 sendmail(8), http://www.qmail.org.
387
389 Sam Varshavchik
390 Author
391
393 1. Courier
394 http://www.courier-mta.org
395 2. Qmail
397 http://www.qmail.org
398 3. "Environment"
400 http://www.courier-mta.org/maildrop/maildropfilter.html#environment
401 4. "Variable substitution"
403 http://www.courier-mta.org/maildrop/maildropfilter.html#varsubst
404 5. is passed the ‐m or the ‐M option.
406 http://www.courier-mta.org/maildrop/#options
407 6. cc
409 http://www.courier-mta.org/maildrop/maildropfilter.html#cc
410 7. dotlock
412 http://www.courier-mta.org/maildrop/maildropfilter.html#dotlock
413 8. flock
415 http://www.courier-mta.org/maildrop/maildropfilter.html#flock
416 9. gdbmopen
418 http://www.courier-mta.org/maildrop/maildropgdbm.html
419 10. log
421 http://www.courier-mta.org/maildrop/maildropfilter.html#log
422 11. system
424 http://www.courier-mta.org/maildrop/maildropfilter.html#system
425 12. to
427 http://www.courier-mta.org/maildrop/maildropfilter.html#to
428 13. xfilter
430 http://www.courier-mta.org/maildrop/maildropfilter.html#xfilter
431 14. echo
433 http://www.courier-mta.org/maildrop/maildropfilter.html#echo
434 15. include
436 http://www.courier-mta.org/maildrop/maildropfilter.html#include
437 16. lockmail(1)
439 http://www.courier-mta.org/maildrop/lockmail.html
440 17. maildropfilter(7)
442 http://www.courier-mta.org/maildrop/maildropfilter.html
443 18. makedat(1)
445 http://www.courier-mta.org/maildrop/makedat.html
446 19. maildropex(7)
448 http://www.courier-mta.org/maildrop/maildropex.html
449 20. reformail(1)
451 http://www.courier-mta.org/maildrop/reformail.html
452 21. makemime(1)
454 http://www.courier-mta.org/maildrop/makemime.html
455 22. reformime(1)
457 http://www.courier-mta.org/maildrop/reformime.html
458 23. courier(8)
460 http://www.courier-mta.org/maildrop/courier.html
461Courier Mail Server 07/24/2017 MAILDROP(1)