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 mail servers. Many other
47 mail servers also know how to read maildirs. When delivering to mailbox
48 files, maildrop will lock the mailbox for the duration of the delivery.
49 This is the general mail delivery behavior. There are minor differences
51 in behavior depending on maildrop delivery mode, which is determined
52 based on how maildrop was started. maildrop uses three different
53 primary operating modes:
54 Manual mode
56 A file containing filtering instructions - filename is specified as
57 an argument to the maildrop command. maildrop reads this filename
58 and follows the instructions in it. Unless the message is
59 explicitly forwarded, bounced, deleted, or delivered to a specific
60 mailbox, it will be delivered to the user's system mailbox.
61 Delivery mode
63 maildrop is the mail server's mail delivery agent. maildrop runs
64 in delivery mode when no filename is specified on the command line.
65 maildrop changes the current directory to the user's home
66 directory, then reads /etc/maildroprc, then $HOME/.mailfilter.
67 Embedded mode
69 maildrop functions as a part of another application. The embedded
70 mode is used by the Courier[1] mail server to integrate mail
71 filtering directly into the process of receiving mail from a remote
72 mail relay, thus rejecting unwanted mail before it is even accepted
73 for local mail delivery. Embedded mode is used when either the -m,
74 or the -M, option is specified, and is described below. See below
75 for a more extensive description of the embedded mode.
76
78 It is safe to install maildrop as a root setuid program. The Courier
79 mail server[1] installs maildrop as a root setuid program by default,
80 in order to be able to use maildrop in embedded mode. If root runs
81 maildrop (or it is setuided to root) the -d option may be used to
82 specify the message's recipient. maildrop immediately resets its
83 userid to the one specified by the -d option. The user's
84 $HOME/.mailfilter is read (if it exists), and the message is delivered
85 to the indicated user.
86 The system administrator can configure maildrop to restrict the -d
88 option for everyone except the mail system itself.
89 If in delivery mode the user's home directory has the sticky bit set,
91 maildrop immediately terminates with an exit code of EX_TEMPFAIL,
92 without doing anything. Mail servers interpret the EX_TEMPFAIL exit
93 code as a request to reschedule the message for another delivery
94 attempt later. Setting the sticky bit allows $HOME/.mailfilter to be
95 edited while temporarily holding all incoming mail.
96 maildrop also terminates with EX_TEMPFAIL if the user's home directory
98 has world write permissions.
99 maildrop immediately terminates with EX_TEMPFAIL if the filename is not
101 owned by the user, or if it has any group or world permissions. This
102 includes read permissions. The permissions on $HOME/.mailfilter may
103 only include read and write privileges to the user.
104 When using the special embedded mode (see below) maildrop immediately
106 terminates with the exit code set to EX_TEMPFAIL if $HOME/.mailfilters
107 is not owned by the user, or if it has any group or world permissions.
108
110 maildrop is heavily optimized and tries to use as little resources as
111 possible. maildrop reads small messages into memory, then filters
112 and/or delivers the message directly from memory. For larger messages,
113 maildrop accesses the message directly from the file. If the standard
114 input is not a file, maildrop writes the message to a temporary file,
115 then accesses the message from the temporary file. The temporary file
116 is automatically removed when the message is delivered.
117
119 -a
120 Makes the Courier Authentication Library usage mandatory, i.e.
121 maildrop will throw a temporary error code if the call to the
122 authlib mechanism fails for some reason, such as authdaemon being
123 inaccessible.
124 Note
126 This setting may already be the default, depending on
127 maildrop's configuration.
128 -A "Header: value"
130 Adds an additional header to the message. Specifying -A "Foo: Bar"
131 effectively adds this header to the message being delivered.
132 The mail transport agent usually adds additional headers when
134 delivering a message to a local mailbox. The way it's usually done
135 is by the mail transport agent sending the message using a pipe to
136 the local delivery agent - such as maildrop - and adding some
137 additional headers in the process. Because maildrop receives the
138 message from a pipe, maildrop must either save the message in
139 memory or write the message into a temporary file.
140 The -A option enables the file containing the message to be
142 provided to maildrop directly, as standard input, and the
143 additional headers specified on the command line. Because the
144 standard input is a file, maildrop will not need a temporary file.
145 Multiple -A options may be specified.
146 -d user
148 Run maildrop in delivery mode for this user ID.
149 The system administrator may optionally restrict the -d option to
151 be available to the mail system only, so it may not be available to
152 you. In all cases, the -d option is allowed if user is the same
153 user who is running maildrop. Also, for the -d option to work at
154 all, maildrop must be executed by root, or maildrop must be a
155 root-owned program with the setuid bit set. Absence of a filename
156 on maildrop's command line implies the -d option for the user
157 running maildrop.
158 If -d is not specified, the first argument following all the
160 options is a name of the file containing filtering instructions.
161 The remaining arguments, if any, are assigned to the variables $1,
162 $2, and so on (see "Environment"[2] and "Variable
163 substitution"[3]).
164 -f address
166 Sets the FROM variable (message envelope sender) to address. The
167 system administrator may optionally disable the -f option for
168 users, so it may not be available to you.
169 -m
171 Run maildrop in embedded mode. It's possible to use both the -m,
172 and the -d options, but it doesn't make much sense to do so. Even
173 if you really wanted to run your message through someone else's
174 .mailfilter, that .mailfilter probably has at least one instruction
175 which is not allowed in the embedded mode.
176 The filename argument to maildrop should be specified. filename is
178 a file that includes filtering instructions to be processed in
179 embedded mode. The -m option is used for debugging filter files
180 which are later placed in $HOME/.mailfilters, and used with the -M
181 option.
182 -M filterfile
184 Run maildrop in a special embedded mode. The -d option is implied
185 when -M is used, and if absent it defaults to the userid running
186 maildrop.
187 All the requirements for the -d option apply. maildrop must either
189 be executed by root, or the maildrop program must be owned by root
190 with the setuid bit set. maildrop immediately gives up root
191 privileges by changing its user ID to the one specified by -d, then
192 reads $HOME/.mailfilters/filterfile. For security reasons the name
193 of the file may not begin with a slash or include periods.
194 maildrop is very paranoid: both $HOME/.mailfilters, and
195 $HOME/.mailfilters/filterfile must be owned by the user, and may
196 not have any group or world permissions.
197 The -M option allows for some friendly cooperation between the user
199 running the application, and the user who provides a filter for the
200 embedded mode. The user running the application can use someone
201 else's canned filter and be assured that the filter is not going to
202 run amok and start sending mail or create files all over the place.
203 The user who provides the filter can be assured that the
204 environment variables are clean, and that there are no surprises.
205 maildrop supports the concept of "default" filter files. If the
207 file specified by the -M option cannot be found in
208 $HOME/.mailfilters, maildrop will try to open
209 $HOME/.mailfilters/filterfileprefix-default. filterfileprefix is
210 the initial part of filterfile up until the last '-' character in
211 filterfile.
212 If $HOME/.mailfilters/filterfileprefix-default does not exist, and
214 there are any other dashes left in filterfileprefix, maildrop
215 removes the last dash and everything following it, then tries
216 again.
217 As a last resort maildrop tries to open $HOME/.mailfilters/default.
219 For example, if the parameter to the -M option is
221 mailfilter-lists-maildrop, maildrop will try to open the following
222 files, in order:
223 Note that maildrop looks for -default files ONLY if -M is used.
225 -D uuu/ggg
227 This option is reserved for use by the version of maildrop that
228 comes integrated with the Courier mail server[1].
229 -V level
231 Initialize the VERBOSE variable to level. Because maildrop parses
232 the entire file before running it, this option is used to produce
233 debugging output in the parsing phase. Otherwise, if filename has
234 syntax errors, then no debugging output is possible because the
235 VERBOSE variable is not yet set.
236 -V is ignored when maildrop runs in delivery mode.
238 -w N
240 The -w N option places a warning message into the maildir if the
241 maildir has a quota setting, and after the message was successfully
242 delivered the maildir was at least N percent full.
243 -W filename
245 Copy the warning message from filename, or from /etc/quotawarnmsg
246 if this option is not specified, with the addition of the "Date:"
247 and "Message-Id:" headers. The warning is repeated every 24 hours
248 (at least), until the maildir drops below N percent full.
249 -t socket
251 This option is available if maildrop is compiled with optional
252 Dovecot authentication support. socket specifies the location of
253 Dovecot master authentication socket, for example
254 /var/run/dovecot/auth-master.
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.[4] 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[5]
295 The cc command is not allowed in embedded mode.
296 dotlock[6]
298 The dotlock command is not allowed in embedded mode.
299 flock[7]
301 The flock command is not allowed in embedded mode.
302 gdbmopen[8]
304 In embedded mode, GDBM databases may be opened only for reading.
305 log[9]
307 The log command is not allowed in embedded mode.
308 logfile[9]
310 The logfile command is not allowed in embedded mode.
311 system[10]
313 The system command is not allowed in embedded mode.
314 to[11]
316 The to command is not allowed in embedded mode.
317 xfilter[12]
319 The xfilter command is not allowed in embedded mode.
320 Normally when the filename does not explicitly delivers a message,
322 maildrop will deliver the message to the user's default mailbox. This
323 is also disabled in embedded mode.
324 The filename may communicate with the parent application by using the
326 echo[13] statement and the EXITCODE environment variable.
327 /etc/maildroprcs
329 If maildrop encounters an include[14] statement where the filename
330 starts with /etc/maildroprcs/, the normal restrictions for the embedded
331 mode are suspended while executing the filter file in the
332 /etc/maildroprcs directory. The restrictions are also suspended for any
333 additional filter files that are included from /etc/maildroprcs. The
334 restrictions resume once maildrop finishes executing the file from
335 /etc/maildroprcs.
336 This allows the system administrator to have a controlled environment
338 for running external commands (via the backticks, the system[10] or the
339 xfilter[12] commands).
340 The name of the file may not contain any periods (so that a creative
342 individual can't write include
343 "/etc/maildroprcs/../../home/user/recipe").
344 Before executing the commands in the /etc/maildroprcs file, maildrop
346 automatically resets the following variables to their initial values:
347 DEFAULT, HOME, LOCKEXT, LOCKSLEEP, LOCKTIMEOUT, LOCKREFRESH, LOGNAME,
348 PATH, SENDMAIL, and SHELL. Please note that the previous values of
349 these variables (if they were changed) will NOT be restored once
350 maildrop finishes executing the commands from /etc/maildroprcs.
351
353 maildrop has a watchdog timer that attempts to abort runaway filtering.
354 If filtering is not complete within a predefined time interval (defined
355 by the system administrator, usually five minutes), maildrop
356 terminates.
357
359 /etc/passwd
360 Sets user's home directory, and related variables. If NIS/YP is
361 install, that will be used as well.
362 /etc/maildroprc
364 Global filtering instructions for delivery mode.
365 /var/mail
367 System mailbox (actual directory defined by the system
368 administrator).
369 /usr/lib/sendmail
371 Program to forward mail (exact program defined by the system
372 administrator).
373 $HOME/.mailfilter
375 Filtering instructions in delivery mode.
376 $HOME/.mailfilters
378 Directory containing files used in special embedded mode.
379
381 lockmail(1)[15], maildropfilter(7)[16], makedat(1)[17],
382 maildropgdbm(7)[8], maildropex(7)[18], reformail(1)[19],
383 makemime(1)[20], reformime(1)[21], egrep(1), grep(1), , courier(8)[22],
384 sendmail(8).
385
387 Sam Varshavchik
388 Author
389
391 1. Courier
392 http://www.courier-mta.org
393 2. "Environment"
395 http://www.courier-mta.org/maildrop/maildropfilter.html#environment
396 3. "Variable substitution"
398 http://www.courier-mta.org/maildrop/maildropfilter.html#varsubst
399 4. is passed the ‐m or the ‐M option.
401 http://www.courier-mta.org/maildrop/#options
402 5. cc
404 http://www.courier-mta.org/maildrop/maildropfilter.html#cc
405 6. dotlock
407 http://www.courier-mta.org/maildrop/maildropfilter.html#dotlock
408 7. flock
410 http://www.courier-mta.org/maildrop/maildropfilter.html#flock
411 8. gdbmopen
413 http://www.courier-mta.org/maildrop/maildropgdbm.html
414 9. log
416 http://www.courier-mta.org/maildrop/maildropfilter.html#log
417 10. system
419 http://www.courier-mta.org/maildrop/maildropfilter.html#system
420 11. to
422 http://www.courier-mta.org/maildrop/maildropfilter.html#to
423 12. xfilter
425 http://www.courier-mta.org/maildrop/maildropfilter.html#xfilter
426 13. echo
428 http://www.courier-mta.org/maildrop/maildropfilter.html#echo
429 14. include
431 http://www.courier-mta.org/maildrop/maildropfilter.html#include
432 15. lockmail(1)
434 http://www.courier-mta.org/maildrop/lockmail.html
435 16. maildropfilter(7)
437 http://www.courier-mta.org/maildrop/maildropfilter.html
438 17. makedat(1)
440 http://www.courier-mta.org/maildrop/makedat.html
441 18. maildropex(7)
443 http://www.courier-mta.org/maildrop/maildropex.html
444 19. reformail(1)
446 http://www.courier-mta.org/maildrop/reformail.html
447 20. makemime(1)
449 http://www.courier-mta.org/maildrop/makemime.html
450 21. reformime(1)
452 http://www.courier-mta.org/maildrop/reformime.html
453 22. courier(8)
455 http://www.courier-mta.org/maildrop/courier.html
456Courier Mail Server 09/24/2019 MAILDROP(1)