1MAILDROP(1)                 Double Precision, Inc.                 MAILDROP(1)
2
3
4

NAME

6       maildrop - mail delivery filter/agent
7

SYNOPSIS

9       maildrop [option...] [-d user] [arg...]
10
11       maildrop [option...] [filename] [arg...]
12

DESCRIPTION

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
20       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
25       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
32       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
38       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
44       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
50       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
55       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
62       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
68       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

SECURITY

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
87       The system administrator can configure maildrop to restrict the -d
88       option for everyone except the mail system itself.
89
90       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
97       maildrop also terminates with EX_TEMPFAIL if the user's home directory
98       has world write permissions.
99
100       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
105       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

TEMPORARY FILES

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

OPTIONS

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
125               Note
126               This setting may already be the default, depending on
127               maildrop's configuration.
128
129       -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
133           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
141           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
147       -d user
148           Run maildrop in delivery mode for this user ID.
149
150           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
159           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
165       -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
170       -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
177           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
183       -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
188           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
198           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
206           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
213           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
218           As a last resort maildrop tries to open $HOME/.mailfilters/default.
219
220           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
224           Note that maildrop looks for -default files ONLY if -M is used.
225
226       -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
230       -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
237           -V is ignored when maildrop runs in delivery mode.
238
239       -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
244       -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
250       -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

DELIVERY MODE

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
265       If $HOME/.mailfilter does not exist, maildrop will simply deliver the
266       message to the user's mailbox.
267
268       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
273           Note
274           /etc/maildroprc is read only in delivery mode.
275

VIRTUAL ACCOUNTS

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

EMBEDDED MODE

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
288       filename may contain any filtering instructions EXCEPT the following:
289
290       ` ... `
291           Text strings delimited by back-tick characters (run shell command)
292           are not allowed.
293
294       cc[5]
295           The cc command is not allowed in embedded mode.
296
297       dotlock[6]
298           The dotlock command is not allowed in embedded mode.
299
300       flock[7]
301           The flock command is not allowed in embedded mode.
302
303       gdbmopen[8]
304           In embedded mode, GDBM databases may be opened only for reading.
305
306       log[9]
307           The log command is not allowed in embedded mode.
308
309       logfile[9]
310           The logfile command is not allowed in embedded mode.
311
312       system[10]
313           The system command is not allowed in embedded mode.
314
315       to[11]
316           The to command is not allowed in embedded mode.
317
318       xfilter[12]
319           The xfilter command is not allowed in embedded mode.
320
321       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
325       The filename may communicate with the parent application by using the
326       echo[13] statement and the EXITCODE environment variable.
327
328   /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
337       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
341       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
345       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

WATCHDOG TIMER

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

FILES

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
363       /etc/maildroprc
364           Global filtering instructions for delivery mode.
365
366       /var/mail
367           System mailbox (actual directory defined by the system
368           administrator).
369
370       /usr/lib/sendmail
371           Program to forward mail (exact program defined by the system
372           administrator).
373
374       $HOME/.mailfilter
375           Filtering instructions in delivery mode.
376
377       $HOME/.mailfilters
378           Directory containing files used in special embedded mode.
379

SEE ALSO

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

AUTHOR

387       Sam Varshavchik
388           Author
389

NOTES

391        1. Courier
392           http://www.courier-mta.org
393
394        2. "Environment"
395           http://www.courier-mta.org/maildrop/maildropfilter.html#environment
396
397        3. "Variable substitution"
398           http://www.courier-mta.org/maildrop/maildropfilter.html#varsubst
399
400        4. is passed the ‐m or the ‐M option.
401           http://www.courier-mta.org/maildrop/#options
402
403        5. cc
404           http://www.courier-mta.org/maildrop/maildropfilter.html#cc
405
406        6. dotlock
407           http://www.courier-mta.org/maildrop/maildropfilter.html#dotlock
408
409        7. flock
410           http://www.courier-mta.org/maildrop/maildropfilter.html#flock
411
412        8. gdbmopen
413           http://www.courier-mta.org/maildrop/maildropgdbm.html
414
415        9. log
416           http://www.courier-mta.org/maildrop/maildropfilter.html#log
417
418       10. system
419           http://www.courier-mta.org/maildrop/maildropfilter.html#system
420
421       11. to
422           http://www.courier-mta.org/maildrop/maildropfilter.html#to
423
424       12. xfilter
425           http://www.courier-mta.org/maildrop/maildropfilter.html#xfilter
426
427       13. echo
428           http://www.courier-mta.org/maildrop/maildropfilter.html#echo
429
430       14. include
431           http://www.courier-mta.org/maildrop/maildropfilter.html#include
432
433       15. lockmail(1)
434           http://www.courier-mta.org/maildrop/lockmail.html
435
436       16. maildropfilter(7)
437           http://www.courier-mta.org/maildrop/maildropfilter.html
438
439       17. makedat(1)
440           http://www.courier-mta.org/maildrop/makedat.html
441
442       18. maildropex(7)
443           http://www.courier-mta.org/maildrop/maildropex.html
444
445       19. reformail(1)
446           http://www.courier-mta.org/maildrop/reformail.html
447
448       20. makemime(1)
449           http://www.courier-mta.org/maildrop/makemime.html
450
451       21. reformime(1)
452           http://www.courier-mta.org/maildrop/reformime.html
453
454       22. courier(8)
455           http://www.courier-mta.org/maildrop/courier.html
456
457
458
459Courier Mail Server               09/24/2019                       MAILDROP(1)
Impressum