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 section called
226 “Patterns”). maildrop 1.x used a different syntax for patterns,
227 which is no longer described in this manual page. The old pattern
228 matching engine is still available, by setting MAILDROP_OLD_REGEXP
229 to “1”. Setting this variable will use the legacy pattern matching
230 engine 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 the section called “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 Note
541 The contents of all MATCH variables use UTF-8 encoding. As
542 explained in the section called “Patterns” the message gets
543 transcoded into a canonical UTF-8 format, replacing MIME-encoded
544 headers with their UTF-8 equivalent. Consequently, MATCH variables
545 that represent matched text are in UTF-8. For example:
546 if (/^Subject: *(.*)/)
548 This sets MATCH to what's in the “Subject” header, which could
550 possibly use MIME-encoding, for example: “Subject:
551 =?UTF-8?B?SMOzbGEh?=”. The resulting MATCH shows “Hóla!”.
552 Conversion of maildrop 1.x patterns to 2.0
554 Although the new PCRE-based pattern matching code in maildrop is
555 completely different from the built-in pattern matching code in
556 maildrop 1.x, very few changes will be required to convert recipes to
557 the new syntax. The only major differences are:
558 • The subexpression format has changed. Any pattern that uses
560 subexpression needs to be converted. Additionally, references to
561 MATCH2 must be replaced with MATCH1, MATCH3 to MATCH2, and so on.
562 References to plain old MATCH will remain the same.
563 • The “w” pattern option is no longer possible, with PCRE. The very
565 few recipes that use this option, if any actually exist, will have
566 to be rewritten in some other fashion.
567 Expressions
569 Although maildrop evaluates expressions numerically, results of
570 expressions are stored as text literals. When necessary, text literals
571 are converted to numbers, then the results of a mathematical operation
572 is converted back into a text literal.
573 Operators
575 The following operators carry their usual meaning, and are listed
576 in order from lowest precedence, to the highest:
577 ||
580 &&
581 < <= > >= == != lt le gt ge eq ne
582 |
583 &
584 + -
585 * /
586 =~ /pattern/
587 /pattern/ ! ~ function()
588 Variable assignment
591 VARIABLE=expression
592 Assigns the result of the expression to VARIABLE (note no leading $
595 in front of variable).
596 Note
598 If VARIABLE is NOT surrounded by quotes, then it may contain
599 only letters, numbers, underscores, dashes, and a selected few
600 other characters. In order to initialize a variable whose name
601 contains non-standard punctuation marks, surround the name of
602 the variable with quotes.
603 cc - deliver a copy of the message
605 cc expression
606 The cc statement is very similar to the to statement, except that
609 after delivering the message maildrop continues to process the
610 filter file, unlike the to statement which immediately terminates
611 maildrop after the delivery is complete. Essentially, the message
612 is carbon copied to the given mailbox, and may be delivered again
613 to another mailbox by another cc or to statement.
614 See the to statement[8] for more details. When cc is used to
616 deliver a message to a process maildrop will set the EXITCODE
617 variable to the process's exit code.
618 dotlock - create a manual dot-lock
620 dotlock expression {
621 ...
623 }
625 maildrop automatically creates a lock when a message is delivered
628 to a mailbox. Depending upon your system configuration, maildrop
629 will use either dot-locks, or the flock() system call.
630 The dotlock statement creates an explicit dot-lock file. Use the
632 flock statement[9] to create an explicit flock() lock.
633 The expression is a filename that should be used as a lock file.
635 maildrop creates the indicated dot-lock, executes the filtering
636 instructions contained within the { ... } block, and removes the
637 lock. The expression must be the name of the dot-lock file itself,
638 NOT the name of the mailbox file you want to lock.
639 Note
641 With manual locking, it is possible to deadlock multiple
642 maildrop processes (or any other processes that try to claim
643 the same locks).
644 No deadlock detection is possible with dot-locks, and since
646 maildrop automatically refreshes all of its dot-locks
647 regularly, they will never go stale. You'll have maildrop
648 processes hanging in limbo, until their watchdog timers go off,
649 aborting the mail delivery.
650 echo - output diagnostic information
652 echo expression
653 maildrop will print the given text. This is usually used when
656 maildrop runs in embedded mode, but can be used for debugging
657 purposes. Normally, a newline is printed after the text. If text is
658 terminated with a \c, no newline will be printed.
659 exception - trap fatal errors
661 exception {
662 ...
664 }
666 The exception statement traps errors that would normally cause
669 maildrop to terminate. If a fatal error is encountered anywhere
670 within the block of statements enclosed by the exception clause,
671 execution will resume immediately following the exception clause.
672 exit - terminate filtering unconditionally
674 exit
675 The exit statement immediately terminates filtering. maildrop's
678 return code is set to the value of the EXITCODE variable. Normally,
679 maildrop terminates immediately after successfully delivering the
680 message[8] to a mailbox. The exit statement causes maildrop to
681 terminate without delivering the message anywhere.
682 The exit statement is usually used when maildrop runs in embedded
684 mode[10], when message delivery instructions are not allowed.
685 flock - create an manual flock() lock
687 flock expression {
688 ...
690 }
692 maildrop automatically creates a lock when a message is delivered
695 to a mailbox. Depending upon your system configuration, maildrop
696 will use either dot-locks, or the flock() system call.
697 The flock statement creates a manual flock() lock. Use the dotlock
699 statement[11] to create a manual dot-lock file.
700 The expression is the name of the file that should be locked.
702 maildrop creates the lock on the indicated file, executes the
703 filtering instructions contained within the { ... } block, and
704 removes the lock.
705 Note
707 With manual locking, it is possible to deadlock multiple
708 maildrop processes (or any other processes that try to claim
709 the same locks). The operating system will automatically break
710 flock() deadlocks. When that happens, one of the maildrop
711 processes will terminate immediately. Use the exception
712 statement in order to trap this exception condition, and
713 execute an alternative set of filtering instructions.
714 foreach - iterate over text sections matched by a pattern
716 foreach /pattern/:options
717 {
718 ...
719 }
720 foreach (expression) =~ /pattern/:options
722 {
723 ...
724 }
725 The foreach statement executes a block of statements for each
728 occurrence of the given pattern in the given message, or
729 expression. On every iteration MATCH variable will be set to the
730 matched string. All the usual options may be applied to the pattern
731 match, EXCEPT the following:
732 ,xxx,yyy
734 Weighted scoring is meaningless, in this context.
735 ( ... )
737 Subpatterns are not processed. Only the MATCH variable will be
738 set for each found pattern.
739 if - conditional execution
741 if (expression)
742 {
743 ...
744 }
745 else
746 {
747 ...
748 }
749 Conditional execution. If expression evaluates to a logical true
752 (note - parenthesis are required) then the first set of statements
753 is executed. The else keyword, and the subsequent statements, are
754 optional. If present, and the expression evaluates to a logical
755 false, the else part is executed.
756 maildrop evaluates all expression as text strings. In the context
758 of a logical expression, an empty string, or the number 0
759 constitutes a logical false value, anything else is a logical true
760 value.
761 If the if part, or the else part consists of only one statement,
763 the braces may be omitted.
764 Note
766 The grammar of this if statement is stricter than usual. If you
767 get baffling syntax errors from maildrop, make sure that the
768 braces, and the if statement, appear on separate lines.
769 Specifically: the closing parenthesis, the closing braces, and
770 the else statement, must be at the end of the line (comments
771 are allowed), and there may not be any blank lines in between
772 (not even ones containing comments only).
773 If the else part contains a single if, and nothing else, this may
775 be combined into an elsif:
776 if (expression)
778 {
779 ...
780 }
781 elsif (expression)
782 {
783 ...
784 }
785 The above example is logically identical to:
788 if (expression)
790 {
791 ...
792 }
793 else
794 {
795 if (expression)
796 {
797 ...
798 }
799 }
800 Consecutive elsif sequences are allowed:
803 if (expression)
805 {
806 ...
807 }
808 elsif (expression)
809 {
810 ...
811 }
812 elsif (expression)
813 {
814 ...
815 }
816 Consecutive occurences of elsif commands eliminate a significant
819 amount of indentation, and the resulting code is more readable.
820 import - access original environment variable
822 import variable
823 When maildrop starts, it normally imports the contents of the
826 environment variables, and assigns them to internal maildrop
827 variables. For example, if there was an environment variable FOO,
828 the internal maildrop variable FOO will have the contents of the
829 environment variable. From then on, FOO will be no different than
830 any other variable, and when maildrop runs an external command, the
831 contents of maildrop's variables will be exported as the
832 environment for the command.
833 Certain variables, like HOME and PATH, are always reset to fixed
835 defaults, for security reasons. Also, in delivery and embedded
836 modes, the environment is not imported at all (with the exception
837 of system locale environment variables), and maildrop starts with
838 only the fixed default variables.
839 The import statement initializes the specified variable with the
841 contents of the original environment variable when maildrop
842 started. For example:
843 echo "PATH is $PATH"
845 PATH="/bin"
846 echo "PATH is $PATH"
847 import PATH
848 echo "PATH is $PATH"
849 exit
850 This results in the following output:
853 PATH is /bin:/usr/bin:/usr/local/bin
855 PATH is /bin
856 PATH is /home/root/bin:/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/bin
857 This shows that when maildrop starts PATH is set to the fixed
860 default of /bin:/usr/bin:/usr/local/bin. However, the original
861 contents of the PATH environment variable we different, and the
862 import statement shows what it was.
863 include - execute filtering instructions from another file
865 include expression
866 The include statement reads a file, and executes filtering
869 instructions contained in that file. Note that the include
870 statement is processed when the current filter file is being
871 executed. When maildrop reads the initial filter file, any syntax
872 errors in the filtering instructions are immediately reported, and
873 maildrop will terminate with a return code of EX_TEMPFAIL. Any
874 errors in files specified by include statements are NOT reported,
875 because those files will not be read until the include statement is
876 itself executed.
877 If the specified file does not exist, or if there are any syntax
879 errors in the file, maildrop reports the error, and terminates with
880 a return code of EX_TEMPFAIL.
881 log, logfile - log message deliveries
883 logfile expression
884 log expression
886 Logging in maildrop is normally turned off. The logfile statement
889 specifies the file where maildrop will log how the message has been
890 disposed of. The parameter is then name of the file. If the file
891 exists maildrop appends to the file.
892 For each delivery (the to[8] and cc[12] statements, and default
894 deliveries) maildrop records the From: and the Subject: fields,
895 together with the current time, in the log file.
896 The log statement adds additional logging text to the log file. The
898 log statement works exactly like the echo statement, except that
899 the text is written to the logfile, instead of standard output.
900 system - execute a system command
902 system expression
903 expression specifies an external program that maildrop runs as a
906 subprocess. The subprocess's standard input gets connected to
907 /dev/null, and the subprocess inherits the standard output and
908 error from maildrop.
909 to - deliver message to a mailbox
911 to expression
912 The to statement delivers the message to a mailbox. expression
915 must evaluate to a valid mailbox. A valid mailbox is either a
916 mailbox file, a maildir, or an external program (which includes
917 forwarding to another address).
918 The to statement is the final delivery statement. maildrop
920 delivers message, then immediately terminates, with its return code
921 set to the EXITCODE variable. If there was an error while
922 delivering the message, maildrop terminates with the EX_TEMPFAIL
923 exit code. A properly-written mail transport agent should re-queue
924 the message, and re-attempt delivery at some later time.
925 An expression that begins with the "|" character specifies an
927 external program to run to handle the actual delivery. The SHELL
928 variable specifies the shell to execute the given command. The
929 message is provided to the command on standard input. maildrop's
930 exit code will be the process's exit code.
931 An expression that begins with an exclamation mark, "!" specifies a
933 whitespace-delimited list of E-mail addresses to forward the
934 message to. The program specified by the SENDMAIL variable is run
935 as an external program, with the list of E-mail addresses provided
936 as parameters to the program.
937 Otherwise, expression names the mailbox where maildrop delivers the
939 message. If expression is a directory, maildrop assumes that the
940 directory is a maildir directory. Otherwise, maildrop will deliver
941 the message to a file, formatted in traditional mailbox format.
942 maildrop will use either dot-locking, or flock()-locking when
943 delivering the message to the file.
944 while - repeatedly execute a block of statements
946 while (expression)
947 {
948 ...
949 }
950 The expression is repeatedly evaluated. Each time it evaluates to a
953 logical true[13], the statements inside the braces are executed.
954 When expression evaluates to a logical false, the while loop is
955 over. Take care to avoid infinite loops.
956 xfilter - filter message through another program
958 xfilter expression
959 expression specifies an external program that maildrop runs to
962 filter the current message. The current message will be piped to
963 the filter program as standard input. The output of the filter
964 program replaces the current message being delivered. The external
965 program must terminate with an exit code of 0. If the external
966 program does not terminate with an exit code of 0, or if it does
967 not read the message from the standard input, maildrop terminates
968 with an exit code of EX_TEMPFAIL.
969 || - logical or
971 expression1 || expression2
972 If expression1 evaluates to a logical true, the result of the || is
976 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 && - logical and
984 expression1 && expression2
985 If expression1 evaluates to a logical false, the result of the &&
989 is expression1, otherwise it's expression2, which is evaluated.
990 maildrop uses the following concept of true/false: an empty text
992 literal, or a text literal that consists of the single character
993 "0" is a logical false value. Anything else is a logical true
994 value.
995 <, <=, >, >=, ==, != - numerical comparison
997 expression1 < expression2
998 expression1 <= expression2
1000 expression1 > expression2
1002 expression1 >= expression2
1004 expression1 == expression2
1006 expression1 != expression2
1008 These operators compare their left hand side expression against
1012 their right hand side. These operators compare the numerical values
1013 of each side, as floating point numbers. If the numbers compare as
1014 indicated, the result of the comparison is the text string "1",
1015 otherwise it is the text string 0.
1016 Note
1018 Ccomparisons are not associative: "a < b < c" is an error. If
1019 it is absolutely necessary, use "(a < b) < c".
1020 lt, le, gt, ge, eq, ne - text comparison
1022 expression1 lt expression2
1023 expression1 le expression2
1025 expression1 gt expression2
1027 expression1 ge expression2
1029 expression1 eq expression2
1031 expression1 ne expression2
1033 These operators compare their left hand side expression against
1037 their right hand side. These operators compare each side as text
1038 strings (alphabetically, although the text may include anything).
1039 If the text strings compare as indicated, the result of the
1040 comparison is the text string "1", otherwise it is the text string
1041 0.
1042 Note
1044 Comparisons are not associative: "a lt b lt c" is an error. If
1045 it is absolutely necessary, use "(a lt b) lt c". (But why would
1046 you?).
1047 | - bitwise or
1049 expression1 | expression2
1050 This is the bitwise or operator. Its result is a 32 bit integer,
1053 which is a bitwise-or combination of the left hand side and the
1054 right hand side.
1055 & - bitwise and
1057 expression1 & expression2
1058 This is the bitwise and operator. Its result is a 32 bit integer,
1061 which is a bitwise-and combination of the left hand side and the
1062 right hand side.
1063 +, -, *, / - numerical operations
1065 expression1 + expression2
1066 expression1 - expression2
1068 expression1 * expression2
1070 expression1 / expression2
1072 These are numerical, floating point, operators.
1076 =~ /pattern/:options - pattern match against string
1078 expression =~ /pattern/:option
1079 The left hand side of the =~ operator can be any expression. The
1082 right hand side is always a pattern specification. The result of
1083 the operator is the weighted match of the pattern against
1084 expression (if the options do not specify weighted scoring, the
1085 result is simply 1 if the pattern was found, 0 if not).
1086 See "Patterns[14]" for more information.
1088 /pattern/:options - pattern match against message
1090 /pattern/:option
1091 The result of this operator is the weighted match of the pattern
1094 against the current message (if the options do not specify weighted
1095 scoring, the result is simply 1 if the pattern was found, 0 if
1096 not).
1097 See "Patterns[14]" for more information.
1099 !, ~ - logical/bitwise not operator.
1101 ! expression
1102 ~ expression
1104 The result of the ! operator is a logical opposite of its right
1107 hand side expression. If the right hand side expression evaluated
1108 to a logical true, the result is a logical false. If it evaluated
1109 to a logical false, the result is a logical true.
1110 maildrop uses the following concept of true/false: an empty text
1112 literal, or a text literal that consists of the single character
1113 "0" is a logical false value. Anything else is a logical true
1114 value.
1115 The result of the ~ operator is a bitwise complement of its right
1117 hand side expression. The right hand side expression is evaluated
1118 as a 32 bit integer, and the result of this operator is a bitwise
1119 complement of the result.
1120 escape(string) - escape special characters in a string.
1122 escape(expression)
1123 The escape function returns its sole argument with every occurrence
1126 of a special character prefixed by a backslash. A special character
1127 is any of the following characters:
1128 |!$()[]\+*?.&;`'-~<>^{}"
1130 This can used when matching pattern sections[15], and then taking
1133 one section and matching it again. For example:
1134 if ( /^From:\s*(.*)/ )
1136 {
1137 MATCH1=escape($MATCH1)
1138 if ( /^Subject:.*$MATCH1/ )
1139 {
1140 ...
1141 }
1142 }
1143 This example checks if the contents of the From: header can also be
1146 found in the Subject: header. If the escape function were not used,
1147 then any special characters in the From: header that are also used
1148 in regular expressions, such as * or +, would introduce
1149 unpredictable behavior, most likely a syntax error.
1150 The reason why this list of special characters also includes
1152 characters not used in maildrop's regular expressions is to allow
1153 maildrop's variables to be used on the command line of a shell
1154 command executed by the xfilter command, backtick characters, or to
1155 or cc commands.
1156 Although using data from an external data source is dangerous, and
1158 it may result in inadvertent exploits, using the escape function
1159 should hopefully result in fewer surprises.
1160 gdbmopen, gdbmclose, gdbmfetch, gdbmstore - GDBM support in maildrop
1162 These functions provide support for GDBM database files. See
1163 maildropgdbm(5)[16] for more information.
1164 Note
1166 The system administrator can disable GDBM support in maildrop,
1167 so these commands may not be available to you.
1168 getaddr(string) - extract RFC 2822 addresses from a header.
1170 if ( /^From:\s*(.*)/ )
1171 {
1172 ADDR=getaddr($MATCH1)
1173 }
1174 This function is usually applied to a header that contains RFC
1177 2822[17] addresses. It extracts the actual addresses from the
1178 header, without any comments or extraneous punctuation. Each
1179 address is followed by a newline character. For example, if string
1180 contains:
1181 joe@domain.com (Joe Brown), "Alex Smith" <alex@domain.com>, tom@domain.com
1183 The result of the getaddr function is the following string:
1186 joe@domain.com<NL>alex@domain.com<NL>tom@domain.com<NL>
1188 Note
1191 Because getaddr() interprets RFC 2822[18] loosely, it is not
1192 necessary to strip off the "To:" or the "Cc:" header from the
1193 string, before feeding it to getaddr(). For example, the
1194 following snippet of code takes all addresses in the message,
1195 and concatenates them into a single string, separated by
1196 spaces:
1197 ADDRLIST=""
1199 foreach /^(To|Cc): .*/
1200 {
1201 foreach (getaddr $MATCH) =~ /.+/
1202 {
1203 ADDRLIST="$ADDRLIST $MATCH"
1204 }
1205 }
1206 Note
1209 In certain rare situations, RFC 2822[18] allows spaces to be
1210 included in E-mail addresses, so this example is just
1211 educational.
1212 hasaddr(string) - Search for an address.
1214 if ( hasaddr(string) )
1215 {
1216 ...
1217 }
1218 "string" is of the form user@domain. The hasaddr function returns 1
1221 if this address is included in any To:, Cc:,Resent-To:, or
1222 Resent-Cc:, header in the message, otherwise this function returns
1223 0.
1224 This is more than just a simple text search. Each header is parsed
1226 according to RFC822. Addresses found in the header are extracted,
1227 ignoring all comments and names. The remaining addresses are
1228 checked, and if "string" is one of them, hasaddr returns 1,
1229 otherwise it returns 0.
1230 The comparison is case-insensitive. This actually violates RFC822
1232 (and several others) a little bit, because the user part of the
1233 address may be (but is not required to be) case sensitive.
1234 length (string) - length of a string
1236 if (length(string) > 80)
1237 {
1238 ...
1239 }
1240 The length function returns the number of characters in string.
1243 lookup (expr, 'filename', 'options') - read file for patterns
1245 if (lookup(expr, file, "option"))
1246 {
1247 ...
1248 }
1249 expr is any expression. filename is a name of a file containing a
1252 list of patterns. Note that filename is relative to the current
1253 directory, which is the home directory of the user when maildrop
1254 runs in delivery mode, or embedded mode. maildrop then reads the
1255 file. Blank lines will be ignored, as well as any lines that begin
1256 with the # character (comments).
1257 Leading whitespace (but not trailing whitespace, take care) is
1259 removed, and the remaining contents of each line are interpreted as
1260 a pattern which is matched against expr. As soon as the match is
1261 found, lookup returns "1". If no match is found after reading the
1262 entire file, lookup returns "0". For example:
1263 if ( /^To:\s*(.*)/ && lookup( $MATCH1, "badto.dat" ))
1265 {
1266 exit
1267 }
1268 The file badto.dat contains the following two lines:
1271 friend@public
1273 ^[^@]*$
1274 If a message has a To: header that contains the text
1277 "friend@public", or does not contain at least one @ character, then
1278 the message will be silently dropped on the floor ( maildrop will
1279 terminate without delivering the message anywhere).
1280 options are the pattern matching options to use. The only supported
1282 option is "D" (the rest are meaningless, in this case).
1283 Note
1285 Be careful with discarding messages like that. Pattern matching
1286 can be tricky, and a slight miscalculation can cause mail to be
1287 unintentionally discarded. It is much desirable to first
1288 deliver message to a separate folder or mailbox, and once the
1289 filter is verified to work correctly, change it so the messages
1290 are discarded completely.
1291 substr(string,start [,count]) - return substring
1293 foo=substr($foo, 1, 10)
1294 The substr function extracts characters from string beginning with
1297 character #start. If count is specified, at most count characters
1298 starting at position start are kept, any excess is trimmed.
1299 time - return current time
1301 foo=time
1302 The time function returns the current time, in seconds, since
1305 January 1, 1970. This function is useful when using GDBM files. See
1306 maildropex(7)[19] for an example of using the time function.
1307 tolower(string) - Convert string to lowercase.
1309 foo=tolower(string)
1310 This function returns the string with all uppercase characters
1313 replaced by lowercase characters.
1314 toupper(string) - Convert string to uppercase.
1316 foo=toupper(string)
1317 This function returns the string with all lowercase characters
1320 replaced by uppercase characters.
1321 Statements
1323 The filter file is read by maildrop ($HOME/.mailfilter or another
1324 file), and it contains filtering statements, one per line. The
1325 filtering language used by maildrop has a loosely - defined grammatical
1326 structure.
1327 Statements are listed one per line. Multiple statements may be listed
1329 on the same line by separating them with semicolons. To continue a long
1330 statement on the next line, terminate the line with a backslash
1331 character.
1332
1334 If getaddr() or hasaddr() functions are used on broken headers, the
1335 results are unpredictable.
1336 hasaddr() is completely case insensitive. This actually violates a few
1338 RFCs, because the userid portion of the address could be
1339 case-sensitive, but it's not in too many cases, so there.
1340
1342 lockmail(1)[20], maildrop(1)[21], maildropgdbm(5)[16],
1343 maildirquota(8)[4], reformail(1)[22], egrep(1), sendmail(8).
1344
1346 Sam Varshavchik
1347 Author
1348
1350 1. Courier mail server
1351 http://www.courier-mta.org/
1352 2. dot-courier(5)
1354 http://www.courier-mta.org/maildrop/dot-courier.html
1355 3. value of the -M option
1357 http://www.courier-mta.org/maildrop/maildrop.html#moption
1358 4. maildirquota(8)
1360 http://www.courier-mta.org/maildrop/maildirquota.html
1361 5. system
1363 http://www.courier-mta.org/maildrop/#system
1364 6. xfilter
1366 http://www.courier-mta.org/maildrop/#xfilter
1367 7. PCRE
1369 http://www.pcre.org
1370 8. See the to statement
1372 http://www.courier-mta.org/maildrop/#to
1373 9. flock statement
1375 http://www.courier-mta.org/maildrop/#flock
1376 10. embedded mode
1378 http://www.courier-mta.org/maildrop/maildrop.html#embedded
1379 11. dotlock statement
1381 http://www.courier-mta.org/maildrop/#dotlock
1382 12. cc
1384 http://www.courier-mta.org/maildrop/#cc
1385 13. evaluates to a logical true
1387 http://www.courier-mta.org/maildrop/#if
1388 14. Patterns
1390 http://www.courier-mta.org/maildrop/#patterns
1391 15. matching pattern sections
1393 http://www.courier-mta.org/maildrop/#patmatch
1394 16. maildropgdbm(5)
1396 http://www.courier-mta.org/maildrop/maildropgdbm.html
1397 17. RFC 2822
1399 http://www.rfc-editor.org/rfc/rfc2822.txt
1400 18. RFC 2822
1402 http://www.rfc-editor.org/rfc/rfc822.txt
1403 19. maildropex(7)
1405 http://www.courier-mta.org/maildrop/maildropex.html
1406 20. lockmail(1)
1408 http://www.courier-mta.org/maildrop/lockmail.html
1409 21. maildrop(1)
1411 http://www.courier-mta.org/maildrop/maildrop.html
1412 22. reformail(1)
1414 http://www.courier-mta.org/maildrop/reformail.html
1415Courier Mail Server 11/12/2022 MAILDROPFILTER(7)