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