1MAILDROPFILTER(7) Double Precision, Inc. MAILDROPFILTER(7)
2
3
4
6 maildropfilter - maildrop's filtering language
7
9 /etc/maildroprc, $HOME/.mailfilter, $HOME/.mailfilters/*, and
10 friends...
11
13 This manual page describes the language used by maildrop to filter
14 E-mail messages. The mail filtering instructions are read from a file.
15 The language is loosely structured, it is based on pattern matching.
16 The language has a distinct lexical and syntactical structure, very
17 similar to Perl's, but it is important to note that it is not Perl, and
18 is very different from Perl, in certain cases.
19
20 If the filtering instructions do not exist, maildrop delivers the
21 message to the default mailbox without doing any additional processing,
22 making it indistinguishable from the usual mail delivery agent.
23
24 It is important to note that maildrop reads and parses the filter file
25 before doing anything. If there are any errors maildrop prints an error
26 message, and terminates with the exit code set to EX_TEMPFAIL. A
27 compliant mail transport agent should re-queue the message for a later
28 delivery attempt. Hopefully, most simple syntax errors will not cause
29 mail to be bounced back if the error is caught and fixed quickly.
30
31 Environment
32 maildrop uses variables to access and manipulate messages. Variables
33 are arbitrary text accessed by referring to the name of the variable,
34 such as HOME, or DEFAULT. Text is placed into a variable by using an
35 assignment statement, such as:
36
37 FILE="IN.junk"
38
39
40 This statement puts the text "IN.junk" (without the quotes) into a
41 variable whose name is FILE. Later, the contents of a variable are
42 accessed by using the $ symbol and the name for the variable. For
43 example:
44
45 to $FILE
46
47
48 This will deliver the current message to the mailbox file (or a maildir
49 directory) named "IN.junk".
50
51 maildrop initially creates variables from the environment variables of
52 the operating system, UNLESS maildrop runs in delivery mode. Each
53 operating system environment variable becomes a maildrop variable. When
54 running in delivery mode, maildrop does not import the environment for
55 security reasons, except for the environment variables that define the
56 process locale (LANG, LANGUAGE, and LC_*), which are still imported.
57
58 In all cases maildrop resets the following variables to their default
59 values: HOME, DEFAULT, SHELL, PATH, LOCKEXT, LOCKREFRESH, LOCKSLEEP,
60 LOCKTIMEOUT, MAILDIRQUOTA, SENDMAIL and LOGNAME.
61
62 There's one exception to this rule which applies to the version of
63 maildrop that comes with the Courier mail server[1]. The following does
64 not apply to the standalone version of maildrop: when running in
65 delivery mode, if the -d flag was not used, or if it specifies the same
66 userid as the one that's running maildrop: the following variables are
67 automatically imported from the environment: HOME, SHELL, LOGNAME and
68 MAILDIRQUOTA. These environment variables are initialized by the
69 Courier mail server prior to running maildrop. Additionally, the
70 initial value for the DEFAULT maildrop variable is imported from the
71 MAILDROPDEFAULT environment variable. This is because the Courier mail
72 server overloads the DEFAULT environment variable to store the
73 defaulted portion of the local mailbox address. See the
74 dot-courier(5)[2] man page in the Courier mail server distribution. You
75 can get the Courier mail server's DEFAULT value by using the import
76 command. Note, however, that this will clobber the old contents of
77 DEFAULT, which is probably not what you want. The right way to do this
78 would be something like this:
79
80 SAVEDEFAULT=$DEFAULT
81 import DEFAULT
82 LOCALDEFAULT=$DEFAULT
83 DEFAULT=$SAVEDEFAULT
84
85
86 All internal variables are exported back as environment variables when
87 maildrop runs an external command. Changes to internal variables, made
88 by the filter file, are reflected in the exported environment.
89
90 Lexical structure
91 Most whitespace is generally ignored. The # character introduces a
92 comment running to the end of the line, which is also ignored. Unlike
93 other mail filters, maildrop parses the filter file before taking any
94 action with the message. If there are syntax errors in the file,
95 maildrop displays an error message, and returns EX_TEMPFAIL. That
96 should cause the mail message to remain in the queue, and, hopefully
97 allow the problem to be corrected, without bouncing any mail.
98
99 Note
100 In maildrop, the end of line is a lexical token. In order to
101 continue a long statement on the next line, terminate the line with
102 a backslash character.
103
104 Literal text
105 Literal text in the maildrop filtering language is surrounded by either
106 single or double quotes. In order to enter a single quote into a text
107 literal surrounded by single quotes, or a double quote into a literal
108 surrounded by double quotes, prefix it with a backslash character. Use
109 two backslash characters characters to enter one backslash character in
110 the text literal.
111
112 Note
113 A backslash followed by either a backslash, or a matching quote, is
114 the only situation where the backslash character is actually
115 removed, leaving only the following character in the actual text
116 literal. If a backslash character is followed by any other
117 character, the backslash is NOT removed.
118
119 Multiple text literals in a row are automatically concatenated, even if
120 they use different quotes. For example:
121
122 FOOBAR="Foo"'bar'
123 SAVEDEFAULT=$DEFAULT
124 import DEFAULT
125 LOCALDEFAULT=$DEFAULT
126 DEFAULT=$SAVEDEFAULT
127
128
129 This sets the variable FOOBAR to the text "Foobar".
130
131 Variable substitution
132 Variable substitution is performed on text literals that's surrounded
133 by double quotation marks. The "$" character, followed by a variable
134 name, is replaced by that variable's contents.
135
136 MAILBOX="$HOME/Mailbox"
137
138
139 This sets the variable MAILBOX to the contents of the variable HOME
140 followed by "/Mailbox". Variable names must begin with an uppercase
141 letter, a lowercase letter, or an underscore. Following that, all
142 letters, digits, and underscores are taken as a variable name, and its
143 contents replace the $ sign, and the variable name. It is possible to
144 access variables whose name includes other characters, by using braces
145 as follows:
146
147 MAILBOX="${HOME-WORD}/Mailbox"
148
149
150 Inserts the contents of the HOME-WORD variable. If the variable does
151 not exist, the empty text literal is used to replace the variable name.
152 It is not possible to access variables whose names include the }
153 character.
154
155 If the $ character is not followed by a left brace, letter, or an
156 underscore, the $ character remains unmolested in the text literal. A
157 backslash followed by the $ character results in a $ character in the
158 text literal, without doing any variable substitution.
159
160 Variable substitution is not done in text literals which are surrounded
161 by single quotes (apostrophes).
162
163 Command line arguments
164 maildrop initializes special variables: $1, $2, and so on, with
165 additional parameters specified on the maildrop command line. A filter
166 file may use those variables just like any other variables.
167
168 Predefined variables
169 The following variables are automatically defined by maildrop. The
170 default values for the following variables may be changed by the system
171 administrator. For security reasons, the values of the following
172 variables are always reset to their default values, and are never
173 imported from the environment:
174
175 DEFAULT
176 The default mailbox to deliver the message to. If the filter file
177 does not indicate a mailbox to deliver this message to, the message
178 is delivered to this mailbox. The default mailbox is defined by the
179 system administrator.
180
181 FROM
182 Message envelope sender. This is usually the same address as what
183 appears in the From: header, but may not be. This information may
184 or may not be available to maildrop on your system. The message
185 envelope sender is usually specified with the -f option to
186 maildrop. If the -f option is not given, maildrop looks for the
187 Return-Path: header in the message. As the last resort, FROM
188 defaults to “MAILER-DAEMON”. Note that FROM may be empty - the
189 message envelope sender is empty for bounce messages.
190
191 HOME
192 Home directory of the user running maildrop.
193
194 HOSTNAME
195 Network name of the machine running maildrop. Obtained from
196 gethostname(3).
197
198 LOCKEXT
199 Extension for dot-lock files (default: .lock).
200
201 LOCKREFRESH
202 Refresh interval, in seconds, for dot-locks (default: 15). When
203 maildrop dot-locks a mailbox, maildrop tries to refresh the lock
204 periodically in order to keep other programs from removing a stale
205 dot-lock. This is only required if a dot-lock exists for a
206 prolonged period of time, which should be discouraged anyway.
207
208 LOCKSLEEP
209 Number of seconds to wait to try again to create a dot-lock file,
210 if one already exists (default: 5).
211
212 LOCKTIMEOUT
213 Number of seconds to wait before removing a stale dot-lock file
214 (default: 60). If a dot-lock file still exists after LOCKTIMEOUT
215 seconds, maildrop assumes that the process holding the lock no
216 longer exists, and the dot-lock file can be safely removed. After
217 removing the dot-lock file, maildrop waits LOCKSLEEP seconds before
218 trying to create its own dot-lock file, in order to avoid a race
219 condition with another process which is also trying to remove the
220 same stale dot-lock, at the same time.
221
222 LOGNAME
223 Name of the user to who the message is being delivered.
224
225 MAILDROP_OLD_REGEXP
226 Revert to using the old legacy pattern matching engine. Versions of
227 maildrop prior to version 2.0 (included in the Courier mail server
228 0.51, and earlier), used a built-in pattern matching engine,
229 instead of using the PCRE library (see the “Patterns” section).
230 maildrop 1.x used a different syntax for patterns, which is no
231 longer described in this manual page. The old pattern matching
232 engine is still available, by setting MAILDROP_OLD_REGEXP to “1”.
233 Setting this variable will use the legacy pattern matching engine
234 for the rest of the maildrop recipe file.
235
236 The pattern matching engine will be removed completely in a future
237 version of maildrop. This setting provides for a transitional
238 period of converting old recipes. MAILDROP_OLD_REGEXP can be set
239 to “1” in the global maildroprc file, then reset to “0” in each
240 individual maildrop recipe file, after it gets converted to the new
241 syntax.
242
243 MAILFILTER
244 This is the name of the original filter file that was given to
245 maildrop on the command line. This is mostly useful to -default
246 filter files, it allows them to obtain the value of the -M
247 option[3] specified on the command line.
248
249 PATH
250 Command execution path. maildrop resets PATH to the system default
251 (usually /bin:/usr/bin:/usr/local/bin).
252
253 SENDMAIL
254 The mail delivery agent. When maildrop is instructed to deliver the
255 message to a mailbox whose name begins with the ! character, this
256 is interpreted as a request to forward the message. The SENDMAIL
257 command is executed to forward the message.
258
259 SHELL
260 The login shell. The shell is used to execute all commands invoked
261 by maildrop.
262
263 VERBOSE
264 Current Debug level (default: 0). Setting VERBOSE to progressive
265 higher values, between 1 and 9, produces debugging output on
266 standard error. maildrop ignores the VERBOSE variable in delivery
267 mode (in order not to confuse the mail transport agent).
268
269 UMASK
270 The file creation mode mask, in octal. The default setting of 077
271 creates mailboxes that are readable and writable by the owner only.
272 Use 007 to create mailboxes that are readable/writable by both
273 owner and the group. Use 037 to create mailboxes that are readable
274 by both owner and group, but writable by owner only. Permissions on
275 existing mailboxes are not changed, this setting affects only new
276 mailboxes. When delivering to maildirs this setting sets the
277 permissions on new messages only. Access permissions on messages in
278 maildirs are also affected by the permissions on the maildir
279 directories.
280
281 Other special variables
282 The following variables are automatically used by maildrop when the
283 filter file is being processed:
284
285 EXITCODE
286 Return code for maildrop. When maildrop successfully delivers a
287 message, it terminates with this exit code, which defaults to 0.
288 When the to or the cc command is used to deliver the message to an
289 external process, via a pipe, maildrop will set this variable to
290 the exit code of the external process. Since maildrop immediately
291 terminates after completing the to command this means that
292 maildrop's exit code will be the exit code of the external process.
293 If the to command does not deliver the message to a process you
294 must set EXITCODE before the to command, since maildrop terminates
295 immediately after finishing the delivery.
296
297 FLAGS
298 The FLAGS variable is used only when delivering a message to a
299 maildir, and may contain only the following letters: “D”, “F”, “R”,
300 and “S”. They may appear in any order. When the message gets
301 delivered to the maildir, the message will be marked with a draft,
302 flag, replied, or seen, attribute, correspondingly.
303
304 FLAGS must be set before the message is delivered to a maildir. The
305 contents of FLAGS are ignored, when delivering on an mbox folder.
306
307 KEYWORDS
308 The KEYWORDS variable is used only when delivering a message to a
309 maildir, and implements the optional IMAP keyword extension as
310 implemented in the Courier IMAP server[1]. It may be optionally
311 initialized to contain a comma-separate list of keywords. The to,
312 or the cc command, delivers the message to the maildir normally,
313 but also associated the list of keywords in KEYWORDS with the newly
314 delivered message.
315
316 KEYWORDS must be set before the message is delivered to a maildir.
317 The contents of KEYWORDS are ignored, when delivering on an mbox
318 folder.
319
320 LINES
321 Number of lines in the current message. Note that this may be an
322 approximation. It may or may not take into account the -A option.
323 Use this as criteria for filtering, nothing more.
324
325 MAILDIRQUOTA
326 Set this variable in order to manually enforce a maximum size on
327 ANY maildir where the message is delivered. This is an optional
328 feature that must be enabled by the system administrator, see
329 maildirquota(8)[4] for more information.
330
331 RETURNCODE
332 This variable is set when maildrop runs the system[5] command,
333 xfilter[6] command, or a command that's specified within a pair of
334 backtick characters ( command substitution ). The RETURNCODE
335 variable will be set to the exit code of the command, after it
336 completes.
337
338 SIZE
339 Number of bytes in the message. This may or may not include the -A
340 option. Use this as a criteria for filtering, nothing more.
341
342 Unquoted text
343 All text strings in filter files should be in single, or double quotes.
344 However, for convenience sake, quotes can be omitted under certain
345 circumstances.
346
347 Text that includes ONLY letters, digits, and the following characters:
348 _-.:/${}@ may appear without quotes. Note that this does not allow
349 spaces, or backslashes to be entered, however the text is still
350 variable-substituted, and the substituted text may contain other
351 characters.
352
353 Also, note that patterns (see below) begin with the slash character.
354 Normally, anything that begins with the slash is interpreted as a
355 pattern. However, text immediately after “VARIABLE=” is interpreted as
356 a string even if it begins with a slash. This is why something like:
357
358 MAILDIR=/var/mail
359
360
361 works as expected. Using quotes, though, is highly recommended. You
362 must use quotes to set a variable to a lone slash, because an unquoted
363 slash is interpreted as a division sign.
364
365 Long double or singly-quoted text can be broken across multiple lines
366 by ending the line with a lone backslash character, like this:
367
368 TEXT="This is a long \
369 text string"
370
371
372 The backslash, the newline, and all leading whitespace on the next line
373 is removed, resulting in "This is a long text string".
374
375 Command substitution
376 Text enclosed in back-tick characters is interpreted as a shell
377 command. The shell command is executed as a child process by maildrop.
378 Its output is used in place of the command. For example:
379
380 DIR=`ls`
381
382
383 places the names of the files in the current directory into the DIR
384 variable.
385
386 The output of the command will have all newline characters replaced by
387 spaces, and leading and trailing spaces will be stripped (multiple
388 spaces are not removed, though). Also, the contents of the message
389 being delivered is made available to the command on standard input.
390
391 Patterns
392 The pattern syntax in maildrop is similar to the grep command's syntax,
393 with some minor differences. A pattern takes the following form in the
394 filter file:
395
396 /pattern/:options
397
398
399 pattern specifies the text to look for in the message, in the UTF-8
400 codeset. pattern must not begin with a space, otherwise the leading
401 slash will then be interpreted as a division sign. If you must search
402 for text that starts with a space, use something like "/[ ] ... /".
403
404 The general syntax of maildrop's patterns is described in the
405 pcrepattern(3) manual page, with certain exceptions noted below.
406 maildrop uses the PCRE[7] library to implement pattern matching. Not
407 all features in PCRE are available in maildrop, and the “options” part,
408 which follows the pattern specification, changes the pattern matching
409 further. Consult the pcrepattern(3) manual page for more information,
410 but note the following exceptions:
411
412 · Internal options settings are not supported (but see the “D”
413 maildrop option, below). Do not include option settings in the
414 pattern, doing so will lead to undefined results.
415
416 · Named subpatterns are not implemented. Numbered subpatterns are
417 implemented, see “Pattern Match Results”, below.
418
419 · The search pattern gets executed not against the raw message text,
420 but the message transcoded into a canonical UTF-8-based format.
421 This process involves transcoding any non-UTF-8 message content
422 into UTF-8. Additionally, message headers get converted into a
423 canonical format before the search pattern gets executed.
424
425 For structured headers with email addresses, the process involves
426 removing extraneous punctuation, or adding missing ones (in
427 situations where a missing punctuation character can be deduced).
428 Additionally certain pre-RFC822 obsolete header formats get
429 converted to canonical form.
430
431 This means that header search patterns that include punctuation
432 character may appear not to work against obviously-matching message
433 text. Use “reformime -u <message.txt”, with message.txt containing
434 the sample message, to see exactly the actual text that gets
435 searched by patterns.
436
437 Pattern options
438 Following /pattern/, there may be an optional colon, followed by one.
439 or more options. The following options may be specified in any order:
440
441 h
442 Match this pattern against the message header.
443
444 b
445 Match this pattern against the message body.
446
447 D
448 This is a case sensitive match. Normally the patterns match either
449 uppercase or lowercase text. /john/ will match "John", "john", or
450 "JOHN". Specify the D option for a case-sensitive search: lowercase
451 letters in the pattern must match lowercase letters in the message;
452 ditto for uppercase.
453
454 If neither 'h' or 'b' is specified, the pattern is matched against the
455 header only. Specifying the 'b' option causes the pattern to be matched
456 against the message body. Specifying both causes the pattern to be
457 matched against the entire message.
458
459 Normally, each line in the message gets matched against the pattern
460 individually. When applying patterns to a header, multi-line headers
461 (headers split on several lines by beginning each continuation line
462 with whitespace) are silently combined into a single line, before the
463 pattern is applied.
464
465 MIME encoding
466 The pattern must be a valid text string in the UTF-8 codeset, and
467 maildrop should handle messages that use MIME encodings in other known
468 character sets. Options that specify a message header search result in
469 maildrop searching the initial message headers, and any headers of
470 additional MIME sections, in a multipart MIME message. Options that
471 specify a message body search will search through all "text" MIME
472 content.
473
474 For a MIME search to succeed, the message must be a well-formed MIME
475 message (with a Mime-Version: 1.0 header).
476
477 Weighted scoring
478 Patterns are evaluated by maildrop as any other numerical expression.
479 If a pattern is found, maildrop's filter interprets the results of the
480 pattern match as number 1, or true, for filtering purposes. If a
481 pattern is not found the results of the pattern search is zero. Once a
482 pattern is found, the search stops. Second, and subsequent occurrences
483 of the same pattern are NOT searched for.
484
485 maildrop can also do weighted scoring. In weighted scoring, multiple
486 occurrences of the same pattern are used to calculate a numerical
487 score.
488
489 To use a weighted search, specify the pattern as follows:
490
491 /pattern/:options,xxx,yyy
492
493
494 where xxx and yyy are two numbers. yyy is optional -- it will default
495 to 1, if missing.
496
497 The first occurrence of the pattern is evaluated as xxx. The second
498 occurrence of the pattern is evaluated as xxx*yyy, the third as
499 xxx*yyy*yyy, etc... All occurrences of the pattern are added up to
500 calculate the final score.
501
502 Note
503 maildrop does not recognize multiple occurrences of the same
504 pattern in the same line. Multiple occurences of the same pattern
505 in one line count as one occurence.
506
507 Pattern Match Results
508 After a pattern is successfully matched, the actual text that is
509 matched is placed in the MATCH variable. For example:
510
511 /^From:.*/
512
513
514 matches a line of the form:
515
516 From: postmaster@localhost
517
518
519 Here the variable MATCH will be set to "From: postmaster@localhost",
520 which can be used in subsequent statements.
521
522 If the pattern contains subpatterns, the portions of the text that
523 match the first subpattern is placed in the MATCH1 variable. The second
524 subpattern, if any, is placed in MATCH2, and so on:
525
526 /^From:\s+(.*)@(.*)/
527
528
529 matched against the same line will set MATCH to “From:
530 postmaster@localhost”, MATCH1 to “postmaster”, and MATCH2 to
531 “localhost”. Of course, in real world the “From:” header is usually
532 much more complicated, and can't be handled that easily. This is just
533 an illustrative example.
534
535 Note
536 Subpatterns are not processed in the foreach statement.
537
538 Conversion of maildrop 1.x patterns to 2.0
539 Although the new PCRE-based pattern matching code in maildrop is
540 completely different from the built-in pattern matching code in
541 maildrop 1.x, very few changes will be required to convert recipes to
542 the new syntax. The only major differences are:
543
544 · The subexpression format has changed. Any pattern that uses
545 subexpression needs to be converted. Additionally, references to
546 MATCH2 must be replaced with MATCH1, MATCH3 to MATCH2, and so on.
547 References to plain old MATCH will remain the same.
548
549 · The “w” pattern option is no longer possible, with PCRE. The very
550 few recipes that use this option, if any actually exist, will have
551 to be rewritten in some other fashion.
552
553 Expressions
554 Although maildrop evaluates expressions numerically, results of
555 expressions are stored as text literals. When necessary, text literals
556 are converted to numbers, then the results of a mathematical operation
557 is converted back into a text literal.
558
559 Operators
560 The following operators carry their usual meaning, and are listed
561 in order from lowest precedence, to the highest:
562
563
564 ||
565 &&
566 < <= > >= == != lt le gt ge eq ne
567 |
568 &
569 + -
570 * /
571 =~ /pattern/
572 /pattern/ ! ~ function()
573
574
575 Variable assignment
576 VARIABLE=expression
577
578
579 Assigns the result of the expression to VARIABLE (note no leading $
580 in front of variable).
581
582 Note
583 If VARIABLE is NOT surrounded by quotes, then it may contain
584 only letters, numbers, underscores, dashes, and a selected few
585 other characters. In order to initialize a variable whose name
586 contains non-standard punctuation marks, surround the name of
587 the variable with quotes.
588
589 cc - deliver a copy of the message
590 cc expression
591
592
593 The cc statement is very similar to the to statement, except that
594 after delivering the message maildrop continues to process the
595 filter file, unlike the to statement which immediately terminates
596 maildrop after the delivery is complete. Essentially, the message
597 is carbon copied to the given mailbox, and may be delivered again
598 to another mailbox by another cc or to statement.
599
600 See the to statement[8] for more details. When cc is used to
601 deliver a message to a process maildrop will set the EXITCODE
602 variable to the process's exit code.
603
604 dotlock - create a manual dot-lock
605 dotlock expression {
606
607 ...
608
609 }
610
611
612 maildrop automatically creates a lock when a message is delivered
613 to a mailbox. Depending upon your system configuration, maildrop
614 will use either dot-locks, or the flock() system call.
615
616 The dotlock statement creates an explicit dot-lock file. Use the
617 flock statement[9] to create an explicit flock() lock.
618
619 The expression is a filename that should be used as a lock file.
620 maildrop creates the indicated dot-lock, executes the filtering
621 instructions contained within the { ... } block, and removes the
622 lock. The expression must be the name of the dot-lock file itself,
623 NOT the name of the mailbox file you want to lock.
624
625 Note
626 With manual locking, it is possible to deadlock multiple
627 maildrop processes (or any other processes that try to claim
628 the same locks).
629
630 No deadlock detection is possible with dot-locks, and since
631 maildrop automatically refreshes all of its dot-locks
632 regularly, they will never go stale. You'll have maildrop
633 processes hanging in limbo, until their watchdog timers go off,
634 aborting the mail delivery.
635
636 echo - output diagnostic information
637 echo expression
638
639
640 maildrop will print the given text. This is usually used when
641 maildrop runs in embedded mode, but can be used for debugging
642 purposes. Normally, a newline is printed after the text. If text is
643 terminated with a \c, no newline will be printed.
644
645 exception - trap fatal errors
646 exception {
647
648 ...
649
650 }
651
652
653 The exception statement traps errors that would normally cause
654 maildrop to terminate. If a fatal error is encountered anywhere
655 within the block of statements enclosed by the exception clause,
656 execution will resume immediately following the exception clause.
657
658 exit - terminate filtering unconditionally
659 exit
660
661
662 The exit statement immediately terminates filtering. maildrop's
663 return code is set to the value of the EXITCODE variable. Normally,
664 maildrop terminates immediately after successfully delivering the
665 message[8] to a mailbox. The exit statement causes maildrop to
666 terminate without delivering the message anywhere.
667
668 The exit statement is usually used when maildrop runs in embedded
669 mode[10], when message delivery instructions are not allowed.
670
671 flock - create an manual flock() lock
672 flock expression {
673
674 ...
675
676 }
677
678
679 maildrop automatically creates a lock when a message is delivered
680 to a mailbox. Depending upon your system configuration, maildrop
681 will use either dot-locks, or the flock() system call.
682
683 The flock statement creates a manual flock() lock. Use the dotlock
684 statement[11] to create a manual dot-lock file.
685
686 The expression is the name of the file that should be locked.
687 maildrop creates the lock on the indicated file, executes the
688 filtering instructions contained within the { ... } block, and
689 removes the lock.
690
691 Note
692 With manual locking, it is possible to deadlock multiple
693 maildrop processes (or any other processes that try to claim
694 the same locks). The operating system will automatically break
695 flock() deadlocks. When that happens, one of the maildrop
696 processes will terminate immediately. Use the exception
697 statement in order to trap this exception condition, and
698 execute an alternative set of filtering instructions.
699
700 foreach - iterate over text sections matched by a pattern
701 foreach /pattern/:options
702 {
703 ...
704 }
705
706 foreach (expression) =~ /pattern/:options
707 {
708 ...
709 }
710
711
712 The foreach statement executes a block of statements for each
713 occurrence of the given pattern in the given message, or
714 expression. On every iteration MATCH variable will be set to the
715 matched string. All the usual options may be applied to the pattern
716 match, EXCEPT the following:
717
718 ,xxx,yyy
719 Weighted scoring is meaningless, in this context.
720
721 ( ... )
722 Subpatterns are not processed. Only the MATCH variable will be
723 set for each found pattern.
724
725 if - conditional execution
726 if (expression)
727 {
728 ...
729 }
730 else
731 {
732 ...
733 }
734
735
736 Conditional execution. If expression evaluates to a logical true
737 (note - parenthesis are required) then the first set of statements
738 is executed. The else keyword, and the subsequent statements, are
739 optional. If present, and the expression evaluates to a logical
740 false, the else part is executed.
741
742 maildrop evaluates all expression as text strings. In the context
743 of a logical expression, an empty string, or the number 0
744 constitutes a logical false value, anything else is a logical true
745 value.
746
747 If the if part, or the else part consists of only one statement,
748 the braces may be omitted.
749
750 Note
751 The grammar of this if statement is stricter than usual. If you
752 get baffling syntax errors from maildrop, make sure that the
753 braces, and the if statement, appear on separate lines.
754 Specifically: the closing parenthesis, the closing braces, and
755 the else statement, must be at the end of the line (comments
756 are allowed), and there may not be any blank lines in between
757 (not even ones containing comments only).
758
759 If the else part contains a single if, and nothing else, this may
760 be combined into an elsif:
761
762 if (expression)
763 {
764 ...
765 }
766 elsif (expression)
767 {
768 ...
769 }
770
771
772 The above example is logically identical to:
773
774 if (expression)
775 {
776 ...
777 }
778 else
779 {
780 if (expression)
781 {
782 ...
783 }
784 }
785
786
787 Consecutive elsif sequences are allowed:
788
789 if (expression)
790 {
791 ...
792 }
793 elsif (expression)
794 {
795 ...
796 }
797 elsif (expression)
798 {
799 ...
800 }
801
802
803 Consecutive occurences of elsif commands eliminate a significant
804 amount of indentation, and the resulting code is more readable.
805
806 import - access original environment variable
807 import variable
808
809
810 When maildrop starts, it normally imports the contents of the
811 environment variables, and assigns them to internal maildrop
812 variables. For example, if there was an environment variable FOO,
813 the internal maildrop variable FOO will have the contents of the
814 environment variable. From then on, FOO will be no different than
815 any other variable, and when maildrop runs an external command, the
816 contents of maildrop's variables will be exported as the
817 environment for the command.
818
819 Certain variables, like HOME and PATH, are always reset to fixed
820 defaults, for security reasons. Also, in delivery and embedded
821 modes, the environment is not imported at all (with the exception
822 of system locale environment variables), and maildrop starts with
823 only the fixed default variables.
824
825 The import statement initializes the specified variable with the
826 contents of the original environment variable when maildrop
827 started. For example:
828
829 echo "PATH is $PATH"
830 PATH="/bin"
831 echo "PATH is $PATH"
832 import PATH
833 echo "PATH is $PATH"
834 exit
835
836
837 This results in the following output:
838
839 PATH is /bin:/usr/bin:/usr/local/bin
840 PATH is /bin
841 PATH is /home/root/bin:/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/bin
842
843
844 This shows that when maildrop starts PATH is set to the fixed
845 default of /bin:/usr/bin:/usr/local/bin. However, the original
846 contents of the PATH environment variable we different, and the
847 import statement shows what it was.
848
849 include - execute filtering instructions from another file
850 include expression
851
852
853 The include statement reads a file, and executes filtering
854 instructions contained in that file. Note that the include
855 statement is processed when the current filter file is being
856 executed. When maildrop reads the initial filter file, any syntax
857 errors in the filtering instructions are immediately reported, and
858 maildrop will terminate with a return code of EX_TEMPFAIL. Any
859 errors in files specified by include statements are NOT reported,
860 because those files will not be read until the include statement is
861 itself executed.
862
863 If the specified file does not exist, or if there are any syntax
864 errors in the file, maildrop reports the error, and terminates with
865 a return code of EX_TEMPFAIL.
866
867 log, logfile - log message deliveries
868 logfile expression
869
870 log expression
871
872
873 Logging in maildrop is normally turned off. The logfile statement
874 specifies the file where maildrop will log how the message has been
875 disposed of. The parameter is then name of the file. If the file
876 exists maildrop appends to the file.
877
878 For each delivery (the to[8] and cc[12] statements, and default
879 deliveries) maildrop records the From: and the Subject: fields,
880 together with the current time, in the log file.
881
882 The log statement adds additional logging text to the log file. The
883 log statement works exactly like the echo statement, except that
884 the text is written to the logfile, instead of standard output.
885
886 system - execute a system command
887 system expression
888
889
890 expression specifies an external program that maildrop runs as a
891 subprocess. The subprocess's standard input gets connected to
892 /dev/null, and the subprocess inherits the standard output and
893 error from maildrop.
894
895 to - deliver message to a mailbox
896 to expression
897
898
899 The to statement delivers the message to a mailbox. expression
900 must evaluate to a valid mailbox. A valid mailbox is either a
901 mailbox file, a maildir, or an external program (which includes
902 forwarding to another address).
903
904 The to statement is the final delivery statement. maildrop
905 delivers message, then immediately terminates, with its return code
906 set to the EXITCODE variable. If there was an error while
907 delivering the message, maildrop terminates with the EX_TEMPFAIL
908 exit code. A properly-written mail transport agent should re-queue
909 the message, and re-attempt delivery at some later time.
910
911 An expression that begins with the "|" character specifies an
912 external program to run to handle the actual delivery. The SHELL
913 variable specifies the shell to execute the given command. The
914 message is provided to the command on standard input. maildrop's
915 exit code will be the process's exit code.
916
917 An expression that begins with an exclamation mark, "!" specifies a
918 whitespace-delimited list of E-mail addresses to forward the
919 message to. The program specified by the SENDMAIL variable is run
920 as an external program, with the list of E-mail addresses provided
921 as parameters to the program.
922
923 Otherwise, expression names the mailbox where maildrop delivers the
924 message. If expression is a directory, maildrop assumes that the
925 directory is a maildir directory. Otherwise, maildrop will deliver
926 the message to a file, formatted in traditional mailbox format.
927 maildrop will use either dot-locking, or flock()-locking when
928 delivering the message to the file.
929
930 while - repeatedly execute a block of statements
931 while (expression)
932 {
933 ...
934 }
935
936
937 The expression is repeatedly evaluated. Each time it evaluates to a
938 logical true[13], the statements inside the braces are executed.
939 When expression evaluates to a logical false, the while loop is
940 over. Take care to avoid infinite loops.
941
942 xfilter - filter message through another program
943 xfilter expression
944
945
946 expression specifies an external program that maildrop runs to
947 filter the current message. The current message will be piped to
948 the filter program as standard input. The output of the filter
949 program replaces the current message being delivered. The external
950 program must terminate with an exit code of 0. If the external
951 program does not terminate with an exit code of 0, or if it does
952 not read the message from the standard input, maildrop terminates
953 with an exit code of EX_TEMPFAIL.
954
955 || - logical or
956 expression1 || expression2
957
958
959
960 If expression1 evaluates to a logical true, the result of the || is
961 expression1, otherwise it's expression2, which is evaluated.
962
963 maildrop uses the following concept of true/false: an empty text
964 literal, or a text literal that consists of the single character
965 "0" is a logical false value. Anything else is a logical true
966 value.
967
968 && - logical and
969 expression1 && expression2
970
971
972
973 If expression1 evaluates to a logical false, the result of the &&
974 is expression1, otherwise it's expression2, which is evaluated.
975
976 maildrop uses the following concept of true/false: an empty text
977 literal, or a text literal that consists of the single character
978 "0" is a logical false value. Anything else is a logical true
979 value.
980
981 <, <=, >, >=, ==, != - numerical comparison
982 expression1 < expression2
983
984 expression1 <= expression2
985
986 expression1 > expression2
987
988 expression1 >= expression2
989
990 expression1 == expression2
991
992 expression1 != expression2
993
994
995
996 These operators compare their left hand side expression against
997 their right hand side. These operators compare the numerical values
998 of each side, as floating point numbers. If the numbers compare as
999 indicated, the result of the comparison is the text string "1",
1000 otherwise it is the text string 0.
1001
1002 Note
1003 Ccomparisons are not associative: "a < b < c" is an error. If
1004 it is absolutely necessary, use "(a < b) < c".
1005
1006 lt, le, gt, ge, eq, ne - text comparison
1007 expression1 lt expression2
1008
1009 expression1 le expression2
1010
1011 expression1 gt expression2
1012
1013 expression1 ge expression2
1014
1015 expression1 eq expression2
1016
1017 expression1 ne expression2
1018
1019
1020
1021 These operators compare their left hand side expression against
1022 their right hand side. These operators compare each side as text
1023 strings (alphabetically, although the text may include anything).
1024 If the text strings compare as indicated, the result of the
1025 comparison is the text string "1", otherwise it is the text string
1026 0.
1027
1028 Note
1029 Comparisons are not associative: "a lt b lt c" is an error. If
1030 it is absolutely necessary, use "(a lt b) lt c". (But why would
1031 you?).
1032
1033 | - bitwise or
1034 expression1 | expression2
1035
1036
1037 This is the bitwise or operator. Its result is a 32 bit integer,
1038 which is a bitwise-or combination of the left hand side and the
1039 right hand side.
1040
1041 & - bitwise and
1042 expression1 & expression2
1043
1044
1045 This is the bitwise and operator. Its result is a 32 bit integer,
1046 which is a bitwise-and combination of the left hand side and the
1047 right hand side.
1048
1049 +, -, *, / - numerical operations
1050 expression1 + expression2
1051
1052 expression1 - expression2
1053
1054 expression1 * expression2
1055
1056 expression1 / expression2
1057
1058
1059
1060 These are numerical, floating point, operators.
1061
1062 =~ /pattern/:options - pattern match against string
1063 expression =~ /pattern/:option
1064
1065
1066 The left hand side of the =~ operator can be any expression. The
1067 right hand side is always a pattern specification. The result of
1068 the operator is the weighted match of the pattern against
1069 expression (if the options do not specify weighted scoring, the
1070 result is simply 1 if the pattern was found, 0 if not).
1071
1072 See "Patterns[14]" for more information.
1073
1074 /pattern/:options - pattern match against message
1075 /pattern/:option
1076
1077
1078 The result of this operator is the weighted match of the pattern
1079 against the current message (if the options do not specify weighted
1080 scoring, the result is simply 1 if the pattern was found, 0 if
1081 not).
1082
1083 See "Patterns[14]" for more information.
1084
1085 !, ~ - logical/bitwise not operator.
1086 ! expression
1087
1088 ~ expression
1089
1090
1091 The result of the ! operator is a logical opposite of its right
1092 hand side expression. If the right hand side expression evaluated
1093 to a logical true, the result is a logical false. If it evaluated
1094 to a logical false, the result is a logical true.
1095
1096 maildrop uses the following concept of true/false: an empty text
1097 literal, or a text literal that consists of the single character
1098 "0" is a logical false value. Anything else is a logical true
1099 value.
1100
1101 The result of the ~ operator is a bitwise complement of its right
1102 hand side expression. The right hand side expression is evaluated
1103 as a 32 bit integer, and the result of this operator is a bitwise
1104 complement of the result.
1105
1106 escape(string) - escape special characters in a string.
1107 escape(expression)
1108
1109
1110 The escape function returns its sole argument with every occurrence
1111 of a special character prefixed by a backslash. A special character
1112 is any of the following characters:
1113
1114 |!$()[]\+*?.&;`'-~<>^{}"
1115
1116
1117 This can used when matching pattern sections[15], and then taking
1118 one section and matching it again. For example:
1119
1120 if ( /^From:\s*(.*)/ )
1121 {
1122 MATCH1=escape($MATCH1)
1123 if ( /^Subject:.*$MATCH1/ )
1124 {
1125 ...
1126 }
1127 }
1128
1129
1130 This example checks if the contents of the From: header can also be
1131 found in the Subject: header. If the escape function were not used,
1132 then any special characters in the From: header that are also used
1133 in regular expressions, such as * or +, would introduce
1134 unpredictable behavior, most likely a syntax error.
1135
1136 The reason why this list of special characters also includes
1137 characters not used in maildrop's regular expressions is to allow
1138 maildrop's variables to be used on the command line of a shell
1139 command executed by the xfilter command, backtick characters, or to
1140 or cc commands.
1141
1142 Although using data from an external data source is dangerous, and
1143 it may result in inadvertent exploits, using the escape function
1144 should hopefully result in fewer surprises.
1145
1146 gdbmopen, gdbmclose, gdbmfetch, gdbmstore - GDBM support in maildrop
1147 These functions provide support for GDBM database files. See
1148 maildropgdbm(5)[16] for more information.
1149
1150 Note
1151 The system administrator can disable GDBM support in maildrop,
1152 so these commands may not be available to you.
1153
1154 getaddr(string) - extract RFC 2822 addresses from a header.
1155 if ( /^From:\s*(.*)/ )
1156 {
1157 ADDR=getaddr($MATCH1)
1158 }
1159
1160
1161 This function is usually applied to a header that contains RFC
1162 2822[17] addresses. It extracts the actual addresses from the
1163 header, without any comments or extraneous punctuation. Each
1164 address is followed by a newline character. For example, if string
1165 contains:
1166
1167 joe@domain.com (Joe Brown), "Alex Smith" <alex@domain.com>, tom@domain.com
1168
1169
1170 The result of the getaddr function is the following string:
1171
1172 joe@domain.com<NL>alex@domain.com<NL>tom@domain.com<NL>
1173
1174
1175 Note
1176 Because getaddr() interprets RFC 2822[18] loosely, it is not
1177 necessary to strip off the "To:" or the "Cc:" header from the
1178 string, before feeding it to getaddr(). For example, the
1179 following snippet of code takes all addresses in the message,
1180 and concatenates them into a single string, separated by
1181 spaces:
1182
1183 ADDRLIST=""
1184 foreach /^(To|Cc): .*/
1185 {
1186 foreach (getaddr $MATCH) =~ /.+/
1187 {
1188 ADDRLIST="$ADDRLIST $MATCH"
1189 }
1190 }
1191
1192
1193 Note
1194 In certain rare situations, RFC 2822[18] allows spaces to be
1195 included in E-mail addresses, so this example is just
1196 educational.
1197
1198 hasaddr(string) - Search for an address.
1199 if ( hasaddr(string) )
1200 {
1201 ...
1202 }
1203
1204
1205 "string" is of the form user@domain. The hasaddr function returns 1
1206 if this address is included in any To:, Cc:,Resent-To:, or
1207 Resent-Cc:, header in the message, otherwise this function returns
1208 0.
1209
1210 This is more than just a simple text search. Each header is parsed
1211 according to RFC822. Addresses found in the header are extracted,
1212 ignoring all comments and names. The remaining addresses are
1213 checked, and if "string" is one of them, hasaddr returns 1,
1214 otherwise it returns 0.
1215
1216 The comparison is case-insensitive. This actually violates RFC822
1217 (and several others) a little bit, because the user part of the
1218 address may be (but is not required to be) case sensitive.
1219
1220 length (string) - length of a string
1221 if (length(string) > 80)
1222 {
1223 ...
1224 }
1225
1226
1227 The length function returns the number of characters in string.
1228
1229 lookup (expr, 'filename', 'options') - read file for patterns
1230 if (lookup(expr, file, "option"))
1231 {
1232 ...
1233 }
1234
1235
1236 expr is any expression. filename is a name of a file containing a
1237 list of patterns. Note that filename is relative to the current
1238 directory, which is the home directory of the user when maildrop
1239 runs in delivery mode, or embedded mode. maildrop then reads the
1240 file. Blank lines will be ignored, as well as any lines that begin
1241 with the # character (comments).
1242
1243 Leading whitespace (but not trailing whitespace, take care) is
1244 removed, and the remaining contents of each line are interpreted as
1245 a pattern which is matched against expr. As soon as the match is
1246 found, lookup returns "1". If no match is found after reading the
1247 entire file, lookup returns "0". For example:
1248
1249 if ( /^To:\s*(.*)/ && lookup( $MATCH1, "badto.dat" ))
1250 {
1251 exit
1252 }
1253
1254
1255 The file badto.dat contains the following two lines:
1256
1257 friend@public
1258 ^[^@]*$
1259
1260
1261 If a message has a To: header that contains the text
1262 "friend@public", or does not contain at least one @ character, then
1263 the message will be silently dropped on the floor ( maildrop will
1264 terminate without delivering the message anywhere).
1265
1266 options are the pattern matching options to use. The only supported
1267 option is "D" (the rest are meaningless, in this case).
1268
1269 Note
1270 Be careful with discarding messages like that. Pattern matching
1271 can be tricky, and a slight miscalculation can cause mail to be
1272 unintentionally discarded. It is much desirable to first
1273 deliver message to a separate folder or mailbox, and once the
1274 filter is verified to work correctly, change it so the messages
1275 are discarded completely.
1276
1277 substr(string,start [,count]) - return substring
1278 foo=substr($foo, 1, 10)
1279
1280
1281 The substr function extracts characters from string beginning with
1282 character #start. If count is specified, at most count characters
1283 starting at position start are kept, any excess is trimmed.
1284
1285 time - return current time
1286 foo=time
1287
1288
1289 The time function returns the current time, in seconds, since
1290 January 1, 1970. This function is useful when using GDBM files. See
1291 maildropex(7)[19] for an example of using the time function.
1292
1293 tolower(string) - Convert string to lowercase.
1294 foo=tolower(string)
1295
1296
1297 This function returns the string with all uppercase characters
1298 replaced by lowercase characters.
1299
1300 toupper(string) - Convert string to uppercase.
1301 foo=toupper(string)
1302
1303
1304 This function returns the string with all lowercase characters
1305 replaced by uppercase characters.
1306
1307 Statements
1308 The filter file is read by maildrop ($HOME/.mailfilter or another
1309 file), and it contains filtering statements, one per line. The
1310 filtering language used by maildrop has a loosely - defined grammatical
1311 structure.
1312
1313 Statements are listed one per line. Multiple statements may be listed
1314 on the same line by separating them with semicolons. To continue a long
1315 statement on the next line, terminate the line with a backslash
1316 character.
1317
1319 If getaddr() or hasaddr() functions are used on broken headers, the
1320 results are unpredictable.
1321
1322 hasaddr() is completely case insensitive. This actually violates a few
1323 RFCs, because the userid portion of the address could be
1324 case-sensitive, but it's not in too many cases, so there.
1325
1327 lockmail(1)[20], maildrop(1)[21], maildropgdbm(5)[16],
1328 maildirquota(8)[4], reformail(1)[22], egrep(1), sendmail(8).
1329
1331 Sam Varshavchik
1332 Author
1333
1335 1. Courier mail server
1336 http://www.courier-mta.org/
1337
1338 2. dot-courier(5)
1339 http://www.courier-mta.org/maildrop/dot-courier.html
1340
1341 3. value of the -M option
1342 http://www.courier-mta.org/maildrop/maildrop.html#moption
1343
1344 4. maildirquota(8)
1345 http://www.courier-mta.org/maildrop/maildirquota.html
1346
1347 5. system
1348 http://www.courier-mta.org/maildrop/#system
1349
1350 6. xfilter
1351 http://www.courier-mta.org/maildrop/#xfilter
1352
1353 7. PCRE
1354 http://www.pcre.org
1355
1356 8. See the to statement
1357 http://www.courier-mta.org/maildrop/#to
1358
1359 9. flock statement
1360 http://www.courier-mta.org/maildrop/#flock
1361
1362 10. embedded mode
1363 http://www.courier-mta.org/maildrop/maildrop.html#embedded
1364
1365 11. dotlock statement
1366 http://www.courier-mta.org/maildrop/#dotlock
1367
1368 12. cc
1369 http://www.courier-mta.org/maildrop/#cc
1370
1371 13. evaluates to a logical true
1372 http://www.courier-mta.org/maildrop/#if
1373
1374 14. Patterns
1375 http://www.courier-mta.org/maildrop/#patterns
1376
1377 15. matching pattern sections
1378 http://www.courier-mta.org/maildrop/#patmatch
1379
1380 16. maildropgdbm(5)
1381 http://www.courier-mta.org/maildrop/maildropgdbm.html
1382
1383 17. RFC 2822
1384 http://www.rfc-editor.org/rfc/rfc2822.txt
1385
1386 18. RFC 2822
1387 http://www.rfc-editor.org/rfc/rfc822.txt
1388
1389 19. maildropex(7)
1390 http://www.courier-mta.org/maildrop/maildropex.html
1391
1392 20. lockmail(1)
1393 http://www.courier-mta.org/maildrop/lockmail.html
1394
1395 21. maildrop(1)
1396 http://www.courier-mta.org/maildrop/maildrop.html
1397
1398 22. reformail(1)
1399 http://www.courier-mta.org/maildrop/reformail.html
1400
1401
1402
1403Courier Mail Server 07/24/2017 MAILDROPFILTER(7)