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
14 This manual page describes the language used by maildrop to filter
15 E-mail messages. The mail filtering instructions are read from a file.
16 The language is loosely structured, it is based on pattern matching.
17 The language has a distinct lexical and syntactical structure, very
18 similar to Perl's, but it is important to note that it is not Perl, and
19 is very different from Perl, in certain cases.
20 If the filtering instructions do not exist, maildrop delivers the
22 message to the default mailbox without doing any additional processing,
23 making it indistinguishable from the usual mail delivery agent.
24 It is important to note that maildrop reads and parses the filter file
26 before doing anything. If there are any errors maildrop prints an error
27 message, and terminates with the exit code set to EX_TEMPFAIL. A
28 compliant mail transport agent should re-queue the message for a later
29 delivery attempt. Hopefully, most simple syntax errors will not cause
30 mail to be bounced back if the error is caught and fixed quickly.
31 Environment
33 maildrop uses variables to access and manipulate messages. Variables
34 are arbitrary text accessed by referring to the name of the variable,
35 such as HOME, or DEFAULT. Text is placed into a variable by using an
36 assignment statement, such as:
37 FILE="IN.junk"
39 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 This will deliver the current message to the mailbox file (or a maildir
46 directory) named "IN.junk".
47 maildrop initially creates variables from the environment variables of
49 the operating system, UNLESS maildrop runs in delivery mode. Each
50 operating system environment variable becomes a maildrop variable. When
51 running in delivery mode, maildrop does not import the environment for
52 security reasons. In all cases maildrop resets the following variables
53 to their default values: HOME, DEFAULT, SHELL, PATH, LOCKEXT,
54 LOCKREFRESH, LOCKSLEEP, LOCKTIMEOUT, MAILDIRQUOTA, SENDMAIL and
55 LOGNAME.
56 There's one exception to this rule which applies to the version of
58 maildrop that comes with the Courier Mail Server[1]. The following does
59 not apply to the standalone version of maildrop: when running in
60 delivery mode, if the -d flag was not used, or if it specifies the same
61 userid as the one that's running maildrop, the following variables are
62 automatically imported from the environment: HOME, SHELL, LOGNAME and
63 MAILDIRQUOTA. These environment variables are initialized by Courier
64 prior to running maildrop. Additionally, the initial value for the
65 DEFAULT maildrop variable is imported from the MAILDROPDEFAULT
66 environment variable. This is because Courier overloads the DEFAULT
67 environment variable to store the defaulted portion of the local
68 mailbox address. See the dot-courier(5)[2] man page in the Courier
69 distribution. You can grab Courier's DEFAULT value by using the import
70 command. Note, however, that this will clobber the old contents of
71 DEFAULT, which is probably not what you want. The right way to do this
72 would be something like this:
73 SAVEDEFAULT=$DEFAULT
75 import DEFAULT
76 LOCALDEFAULT=$DEFAULT
77 DEFAULT=$SAVEDEFAULT
78 All internal variables are exported back as environment variables when
80 maildrop runs an external command. Changes to internal variables, made
81 by the filter file, are reflected in the exported environment.
82 Lexical structure
84 Most whitespace is generally ignored. The # character introduces a
85 comment running to the end of the line, which is also ignored. Unlike
86 other mail filters, maildrop parses the filter file before taking any
87 action with the message. If there are syntax errors in the file,
88 maildrop displays an error message, and returns EX_TEMPFAIL. That
89 should cause the mail message to remain in the queue, and, hopefully
90 allow the problem to be corrected, without bouncing any mail.
91 Note
93 In maildrop, the end of line is a lexical token. In order to continue a
94 long statement on the next line, terminate the line with a backslash
95 character.
96 Literal text
98 Literal text in the maildrop filtering language is surrounded by either
99 single or double quotes. In order to enter a single quote into a text
100 literal surrounded by single quotes, or a double quote into a literal
101 surrounded by double quotes, prefix it with a backslash character. Use
102 two backslash characters characters to enter one backslash character in
103 the text literal.
104 Note
106 A backslash followed by either a backslash, or a matching quote, is the
107 only situation where the backslash character is actually removed,
108 leaving only the following character in the actual text literal. If a
109 backslash character is followed by any other character, the backslash
110 is NOT removed.
111 Multiple text literals in a row are automatically concatenated, even if
113 they use different quotes. For example:
114 FOOBAR="Foo"'bar'
116 SAVEDEFAULT=$DEFAULT
117 import DEFAULT
118 LOCALDEFAULT=$DEFAULT
119 DEFAULT=$SAVEDEFAULT
120 This sets the variable FOOBAR to the text "Foobar".
122 Variable substitution
124 Variable substitution is performed on text literals that's surrounded
125 by double quotation marks. The "$" character, followed by a variable
126 name, is replaced by that variable's contents.
127 MAILBOX="$HOME/Mailbox"
129 This sets the variable MAILBOX to the contents of the variable HOME
131 followed by "/Mailbox". Variable names must begin with an uppercase
132 letter, a lowercase letter, or an underscore. Following that, all
133 letters, digits, and underscores are taken as a variable name, and its
134 contents replace the $ sign, and the variable name. It is possible to
135 access variables whose name includes other characters, by using braces
136 as follows:
137 MAILBOX="${HOME-WORD}/Mailbox"
139 Inserts the contents of the HOME-WORD variable. If the variable does
141 not exist, the empty text literal is used to replace the variable name.
142 It is not possible to access variables whose names include the }
143 character.
144 If the $ character is not followed by a left brace, letter, or an
146 underscore, the $ character remains unmolested in the text literal. A
147 backslash followed by the $ character results in a $ character in the
148 text literal, without doing any variable substitution.
149 Variable substitution is not done in text literals which are surrounded
151 by single quotes (apostrophes).
152 Command line arguments
154 maildrop initializes special variables: $1, $2, and so on, with
155 additional parameters specified on the maildrop command line. A filter
156 file may use those variables just like any other variables.
157 Predefined variables
159 The following variables are automatically defined by maildrop. The
160 default values for the following variables may be changed by the system
161 administrator. For security reasons, the values of the following
162 variables are always reset to their default values, and are never
163 imported from the environment:
164 DEFAULT
166 The default mailbox to deliver the message to. If the filter file
167 does not indicate a mailbox to deliver this message to, the message
168 is delivered to this mailbox. The default mailbox is defined by the
169 system administrator.
170 FROM
172 Message envelope sender. This is usually the same address as what
173 appears in the From: header, but may not be. This information may
174 or may not be available to maildrop on your system. The message
175 envelope sender is usually specified with the -f option to
176 maildrop. If the -f option is not given, maildrop looks for the
177 From_ line in the message. As the last resort, FROM defaults to the
178 userid which invoked maildrop. Note that FROM may be empty - the
179 message envelope sender is empty for bounce messages.
180 HOME
182 Home directory of the user running maildrop.
183 HOSTNAME
185 Network name of the machine running maildrop. Obtained from
186 gethostname(3).
187 LOCKEXT
189 Extension for dot-lock files (default: .lock).
190 LOCKREFRESH
192 Refresh interval, in seconds, for dot-locks (default: 15). When
193 maildrop dot-locks a mailbox, maildrop tries to refresh the lock
194 periodically in order to keep other programs from removing a stale
195 dot-lock. This is only required if a dot-lock exists for a
196 prolonged period of time, which should be discouraged anyway.
197 LOCKSLEEP
199 Number of seconds to wait to try again to create a dot-lock file,
200 if one already exists (default: 5).
201 LOCKTIMEOUT
203 Number of seconds to wait before removing a stale dot-lock file
204 (default: 60). If a dot-lock file still exists after LOCKTIMEOUT
205 seconds, maildrop assumes that the process holding the lock no
206 longer exists, and the dot-lock file can be safely removed. After
207 removing the dot-lock file, maildrop waits LOCKSLEEP seconds before
208 trying to create its own dot-lock file, in order to avoid a race
209 condition with another process which is also trying to remove the
210 same stale dot-lock, at the same time.
211 LOGNAME
213 Name of the user to who the message is being delivered.
214 MAILDROP_OLD_REGEXP
216 Revert to using the old legacy pattern matching engine. Versions of
217 maildrop prior to version 2.0 (included in the Courier Mail Server
218 0.51, and earlier), used a built-in pattern matching engine,
219 instead of using the PCRE library (see the “Patterns” section).
220 maildrop 1.x used a different syntax for patterns, which is no
221 longer described in this manual page. The old pattern matching
222 engine is still available, by setting MAILDROP_OLD_REGEXP to “1”.
223 Setting this variable will use the legacy pattern matching engine
224 for the rest of the maildrop recipe file.
225 The pattern matching engine will be removed completely in a future
227 version of maildrop. This setting provides for a transitional
228 period of converting old recipes. MAILDROP_OLD_REGEXP can be set
229 to “1” in the global maildroprc file, then reset to “0” in each
230 individual maildrop recipe file, after it gets converted to the new
231 syntax.
232 MAILFILTER
234 This is the name of the original filter file that was given to
235 maildrop on the command line. This is mostly usefull to -default
236 filter files, it allows them to obtain the value of the -M
237 option[3] specified on the command line.
238 PATH
240 Command execution path. maildrop resets PATH to the system default
241 (usually /bin:/usr/bin:/usr/local/bin).
242 SENDMAIL
244 The mail delivery agent. When maildrop is instructed to deliver the
245 message to a mailbox whose name begins with the ! character, this
246 is interpreted as a request to forward the message. The SENDMAIL
247 command is executed to forward the message.
248 SHELL
250 The login shell. The shell is used to execute all commands invoked
251 by maildrop.
252 VERBOSE
254 Current Debug level (default: 0). Setting VERBOSE to progressive
255 higher values, between 1 and 9, produces debugging output on
256 standard error. maildrop ignores the VERBOSE variable in delivery
257 mode (in order not to confuse the mail transport agent).
258 UMASK
260 The file creation mode mask, in octal. The default setting of 077
261 creates mailboxes that are readable and writable by the owner only.
262 Use 007 to create mailboxes that are readable/writable by both
263 owner and the group. Use 037 to create mailboxes that are readable
264 by both owner and group, but writable by owner only. Permissions on
265 existing mailboxes are not changed, this setting affects only new
266 mailboxes. When delivering to maildirs this setting sets the
267 permissions on new messages only. Access permissions on messages in
268 maildirs are also affected by the permissions on the maildir
269 directories.
270 Other special variables
272 The following variables are automatically used by maildrop when the
273 filter file is being processed:
274 EXITCODE
276 Return code for maildrop. When maildrop successfully delivers a
277 message, it terminates with this exit code, which defaults to 0.
278 When the to or the cc command is used to deliver the message to an
279 external process, via a pipe, maildrop will set this variable to
280 the exit code of the external process. Since maildrop immediately
281 terminates after completing the to command this means that
282 maildrop's exit code will be the exit code of the external process.
283 If the to command does not deliver the message to a process you
284 must set EXITCODE before the to command, since maildrop terminates
285 immediately after finishing the delivery.
286 KEYWORDS
288 The KEYWORDS variable is used only when delivering a message to a
289 maildir, and implements the optional IMAP keyword extension as
290 implemented in the Courier-IMAP[1]. It may be optionally
291 initialized to contain a comma-separate list of keywords. The to,
292 or the cc command, delivers the message to the maildir normally,
293 but also associated the list of keywords in KEYWORDS with the newly
294 delivered message.
295 KEYWORDS must be set before the message is delivered to a maildir.
298 The contents of KEYWORDS are ignored, when delivering on an mbox
299 folder.
300 LINES
302 Number of lines in the current message. Note that this may be an
303 approximation. It may or may not take into account the -A option,
304 or any mbox "From_" lines. Use this as criteria for filtering,
305 nothing more.
306 MAILDIRQUOTA
308 Set this variable in order to manually enforce a maximum size on
309 ANY maildir where the message is delivered. This is an optional
310 feature that must be enabled by the system administrator, see
311 maildirquota(8)[4] for more information.
312 RETURNCODE
314 This variable is set when maildrop runs the xfilter[5] command, or
315 a command that's specified within a pair of backtick characters (
316 command substitution ). The RETURNCODE variable will be set to the
317 exit code of the command, after it completes.
318 SIZE
320 Number of bytes in the message. This may or may not include the -A
321 option, and the mbox From_ line. Use this as a criteria for
322 filtering, nothing more.
323 Unquoted text
325 All text strings in filter files should be in single, or double quotes.
326 However, for convenience sake, quotes can be omitted under certain
327 circumstances.
328 Text that includes ONLY letters, digits, and the following characters:
330 _-.:/${}@ may appear without quotes. Note that this does not allow
331 spaces, or backslashes to be entered, however the text is still
332 variable-substituted, and the substituted text may contain other
333 characters.
334 Also, note that patterns (see below) begin with the slash character.
336 Normally, anything that begins with the slash is interpreted as a
337 pattern. However, text immediately after “VARIABLE=” is interpreted as
338 a string even if it begins with a slash. This is why something like:
339 works as expected. Using quotes, though, is highly recommended. You
340 must use quotes to set a variable to a lone slash, because an unquoted
341 slash is interpreted as a division sign.
342 Long double or singly-quoted text can be broken across multiple lines
344 by ending the line with a lone backslash character, like this:
345 The backslash, the newline, and all leading whitespace on the next line
346 is removed, resulting in "This is a long text string".
347 Command substitution
349 Text enclosed in back-tick characters is interpreted as a shell
350 command. The shell command is executed as a child process by maildrop.
351 Its output is used in place of the command. For example:
352 places the names of the files in the current directory into the DIR
353 variable.
354 The output of the command will have all newline characters replaced by
356 spaces, and leading and trailing spaces will be stripped (multiple
357 spaces are not removed, though). Also, the contents of the message
358 being delivered is made available to the command on standard input.
359 Patterns
361 The pattern syntax in maildrop is similar to the grep command's syntax,
362 with some minor differences. A pattern takes the following form in the
363 filter file:
364 pattern specifies the text to look for in the message. pattern must
366 not begin with a space, otherwise the leading slash will then be
367 interpreted as a division sign. If you must search for text that starts
368 with a space, use something like "/[ ] ... /".
369 The general syntax of maildrop's patterns is described in the
371 pcrepattern(3) manual page, with certain exceptions noted below.
372 maildrop uses the PCRE[6] library to implement pattern matching. Not
373 all features in PCRE are available in maildrop, and the “options” part,
374 which follows the pattern specification, changes the pattern matching
375 further. Consult the pcrepattern(3) manual page for more information,
376 but note the following exceptions:
377 · UTF-8 string matching is not presently supported.
378 · Internal options settings are not supported (but see the “D”
379 maildrop option, below). Do not include option settings in the
380 pattern, doing so will lead to undefined results.
381 · Named subpatterns are not implemented. Numbered subpatterns are
382 implemented, see “Pattern Match Results”, below.
383 Pattern options
385 Following /pattern/, there may be an optional colon, followed by one.
386 or more options. The following options may be specified in any order:
387 h
389 Match this pattern against the message header.
390 b
392 Match this pattern against the message body.
393 D
395 This is a case sensitive match. Normally the patterns match either
396 uppercase or lowercase text. /john/ will match "John", "john", or
397 "JOHN". Specify the D option for a case-sensitive search: lowercase
398 letters in the pattern must match lowercase letters in the message;
399 ditto for uppercase.
400 If neither 'h' or 'b' is specified, the pattern is matched against the
402 header only. Specifying the 'b' option causes the pattern to be matched
403 against the message body. Specifying both causes the pattern to be
404 matched against the entire message.
405 Normally, each line in the message gets matched against the pattern
407 individually. When applying patterns to a header, multi-line headers
408 (headers split on several lines by beginning each continuation line
409 with whitespace) are silently combined into a single line, before the
410 pattern is applied.
411 Weighted scoring
413 Patterns are evaluated by maildrop as any other numerical expression.
414 If a pattern is found, maildrop's filter interprets the results of the
415 pattern match as number 1, or true, for filtering purposes. If a
416 pattern is not found the results of the pattern search is zero. Once a
417 pattern is found, the search stops. Second, and subsequent occurrences
418 of the same pattern are NOT searched for.
419 maildrop can also do weighted scoring. In weighted scoring, multiple
421 occurrences of the same pattern are used to calculate a numerical
422 score.
423 To use a weighted search, specify the pattern as follows:
425 where xxx and yyy are two numbers. yyy is optional -- it will default
426 to 1, if missing.
427 The first occurrence of the pattern is evaluated as xxx. The second
429 occurrence of the pattern is evaluated as xxx*yyy, the third as
430 xxx*yyy*yyy, etc... All occurrences of the pattern are added up to
431 calculate the final score.
432 Note
434 maildrop does not recognize multiple occurrences of the same pattern in
435 the same line. Multiple occurences of the same pattern in one line
436 count as one occurence.
437 Pattern Match Results
439 After a pattern is successfully matched, the actual text that is
440 matched is placed in the MATCH variable. For example:
441 matches a line of the form:
442 Here the variable MATCH will be set to "From: postmaster@localhost",
444 which can be used in subsequent statements.
445 If the pattern contains subpatterns, the portions of the text that
447 match the first subpattern is placed in the MATCH1 variable. The second
448 subpattern, if any, is placed in MATCH2, and so on:
449 matched against the same line will set MATCH to “From:
450 postmaster@localhost”, MATCH1 to “postmaster”, and MATCH2 to
451 “localhost”. Of course, in real world the “From:” header is usually
452 much more complicated, and can't be handled that easily. This is just
453 an illustrative example.
454 Note
456 Subpatterns are not processed in the foreach statement.
457 Conversion of maildrop 1.x patterns to 2.0
459 Although the new PCRE-based pattern matching code in maildrop is
460 completely different from the built-in pattern matching code in
461 maildrop 1.x, very few changes will be required to convert recipes to
462 the new syntax. The only major differences are:
463 · The subexpression format has changed. Any pattern that uses
464 subexpression needs to be converted. Additionally, references to
465 MATCH2 must be replaced with MATCH1, MATCH3 to MATCH2, and so on.
466 References to plain old MATCH will remain the same.
467 · The “w” pattern option is no longer possible, with PCRE. The very
468 few recipes that use this option, if any actually exist, will have
469 to be rewritten in some other fashion.
470 Expressions
472 Although maildrop evaluates expressions numerically, results of
473 expressions are stored as text literals. When necessary, text literals
474 are converted to numbers, then the results of a mathematical operation
475 is converted back into a text literal.
476 Operators
478 The following operators carry their usual meaning, and are
479 listed in order from lowest precedence, to the highest:
480 ||
483 &&
484 < <= > >= == != lt le gt ge eq ne
485 |
486 &
487 + -
488 * /
489 =~ /pattern/
490 /pattern/ ! ~ function()
491 Variable assignment
494 VARIABLE=expression
495 Assigns the result of the expression to VARIABLE (note no
497 leading $ in front of variable).
498 Note
500 If VARIABLE is NOT surrounded by quotes, then it may contain
501 only letters, numbers, underscores, dashes, and a selected few
502 other characters. In order to initialize a variable whose name
503 contains non-standard punctuation marks, surround the name of
504 the variable with quotes.
505 cc - deliver a copy of the message
507 cc expression
508 The cc statement is very similar to the to statement, except
510 that after delivering the message maildrop continues to process
511 the filter file, unlike the to statement which immediately
512 terminates maildrop after the delivery is complete. Essentially,
513 the message is carbon copied to the given mailbox, and may be
514 delivered again to another mailbox by another cc or to
515 statement.
516 See the to statement[7] for more details. When cc is used to
518 deliver a message to a process maildrop will set the EXITCODE
519 variable to the process's exit code.
520 dotlock - create a manual dot-lock
522 dotlock expression {
523 ...
525 }
527 maildrop automatically creates a lock when a message is
529 delivered to a mailbox. Depending upon your system
530 configuration, maildrop will use either dot-locks, or the
531 flock() system call.
532 The dotlock statement creates an explicit dot-lock file. Use the
534 flock statement[8] to create an explicit flock() lock.
535 The expression is a filename that should be used as a lock file.
537 maildrop creates the indicated dot-lock, executes the filtering
538 instructions contained within the { ... } block, and removes the
539 lock. The expression must be the name of the dot-lock file
540 itself, NOT the name of the mailbox file you want to lock.
541 Note
543 With manual locking, it is possible to deadlock multiple
544 maildrop processes (or any other processes that try to claim the
545 same locks).
546 No deadlock detection is possible with dot-locks, and since
548 maildrop automatically refreshes all of its dot-locks regularly,
549 they will never go stale. You'll have maildrop processes hanging
550 in limbo, until their watchdog timers go off, aborting the mail
551 delivery.
552 echo - output diagnostic information
554 echo expression
555 maildrop will print the given text. This is usually used when
557 maildrop runs in embedded mode, but can be used for debugging
558 purposes. Normally, a newline is printed after the text. If text
559 is terminated with a \c, no newline will be printed.
560 exception - trap fatal errors
562 exception {
563 ...
565 }
567 The exception statement traps errors that would normally cause
569 maildrop to terminate. If a fatal error is encountered anywhere
570 within the block of statements enclosed by the exception clause,
571 execution will resume immediately following the exception
572 clause.
573 exit - terminate filtering unconditionally
575 exit
576 The exit statement immediately terminates filtering. maildrop's
578 return code is set to the value of the EXITCODE variable.
579 Normally, maildrop terminates immediately after successfully
580 delivering the message[7] to a mailbox. The exit statement
581 causes maildrop to terminate without delivering the message
582 anywhere.
583 The exit statement is usually used when maildrop runs in
585 embedded mode[9], when message delivery instructions are not
586 allowed.
587 flock - create an manual flock() lock
589 flock expression {
590 ...
592 }
594 maildrop automatically creates a lock when a message is
596 delivered to a mailbox. Depending upon your system
597 configuration, maildrop will use either dot-locks, or the
598 flock() system call.
599 The flock statement creates a manual flock() lock. Use the
601 dotlock statement[10] to create a manual dot-lock file.
602 The expression is the name of the file that should be locked.
604 maildrop creates the lock on the indicated file, executes the
605 filtering instructions contained within the { ... } block, and
606 removes the lock.
607 Note
609 With manual locking, it is possible to deadlock multiple
610 maildrop processes (or any other processes that try to claim the
611 same locks). The operating system will automatically break
612 flock() deadlocks. When that happens, one of the maildrop
613 processes will terminate immediately. Use the exception
614 statement in order to trap this exception condition, and execute
615 an alternative set of filtering instructions.
616 foreach - iterate over text sections matched by a pattern
618 foreach /pattern/:options
619 {
620 ...
621 }
622 foreach (expression) =~ /pattern/:options
624 {
625 ...
626 }
627 The foreach statement executes a block of statements for each
629 occurrence of the given pattern in the given message, or
630 expression. On every iteration MATCH variable will be set to the
631 matched string. All the usual options may be applied to the
632 pattern match, EXCEPT the following:
633 ,xxx,yyy
635 Weighted scoring is meaningless, in this context.
636 ( ... )
638 Subpatterns are not processed. Only the MATCH variable will
639 be set for each found pattern.
640 if - conditional execution
642 if (expression)
643 {
644 ...
645 }
646 else
647 {
648 ...
649 }
650 Conditional execution. If expression evaluates to a logical true
652 (note - parenthesis are required) then the first set of
653 statements is executed. The else keyword, and the subsequent
654 statements, are optional. If present, and the expression
655 evaluates to a logical false, the else part is executed.
656 maildrop evaluates all expression as text strings. In the
658 context of a logical expression, an empty string, or the number
659 0 constitutes a logical false value, anything else is a logical
660 true value.
661 If the if part, or the else part consists of only one statement,
663 the braces may be omitted.
664 Note
666 The grammar of this if statement is stricter than usual. If you
667 get baffling syntax errors from maildrop, make sure that the
668 braces, and the if statement, appear on separate lines.
669 Specifically: the closing parenthesis, the closing braces, and
670 the else statement, must be at the end of the line (comments are
671 allowed), and there may not be any blank lines in between (not
672 even ones containing comments only).
673 import - access original environment variable
675 import variable
676 When maildrop starts, it normally imports the contents of the
678 environment variables, and assigns them to internal maildrop
679 variables. For example, if there was an environment variable
680 FOO, the internal maildrop variable FOO will have the contents
681 of the environment variable. From then on, FOO will be no
682 different than any other variable, and when maildrop runs an
683 external command, the contents of maildrop's variables will be
684 exported as the environment for the command.
685 Certain variables, like HOME and PATH, are always reset to fixed
687 defaults, for security reasons. Also, in delivery and embedded
688 modes, the environment is not imported at all, and maildrop
689 starts with only the fixed default variables.
690 The import statement initializes the specified variable with the
692 contents of the original environment variable when maildrop
693 started. For example:
694 This results in the following output:
696 This shows that when maildrop starts PATH is set to the fixed
698 default of /bin:/usr/bin:/usr/local/bin. However, the original
699 contents of the PATH environment variable we different, and the
700 import statement shows what it was.
701 include - execute filtering instructions from another file
703 include expression
704 The include statement reads a file, and executes filtering
706 instructions contained in that file. Note that the include
707 statement is processed when the current filter file is being
708 executed. When maildrop reads the initial filter file, any
709 syntax errors in the filtering instructions are immediately
710 reported, and maildrop will terminate with a return code of
711 EX_TEMPFAIL. Any errors in files specified by include statements
712 are NOT reported, because those files will not be read until the
713 include statement is itself executed.
714 If the specified file does not exist, or if there are any syntax
716 errors in the file, maildrop reports the error, and terminates
717 with a return code of EX_TEMPFAIL.
718 log, logfile - log message deliveries
720 logfile expression
721 log expression
723 Logging in maildrop is normally turned off. The logfile
725 statement specifies the file where maildrop will log how the
726 message has been disposed of. The parameter is then name of the
727 file. If the file exists maildrop appends to the file.
728 For each delivery (the to[7] and cc[11] statements, and default
730 deliveries) maildrop records the From: and the Subject: fields,
731 together with the current time, in the log file.
732 The log statement adds additional logging text to the log file.
734 The log statement works exactly like the echo statement, except
735 that the text is written to the logfile, instead of standard
736 output.
737 to - deliver message to a mailbox
739 to expression
740 The to statement delivers the message to a mailbox. expression
742 must evaluate to a valid mailbox. A valid mailbox is either a
743 mailbox file, a maildir, or an external program (which includes
744 forwarding to another address).
745 The to statement is the final delivery statement. maildrop
747 delivers message, then immediately terminates, with its return
748 code set to the EXITCODE variable. If there was an error while
749 delivering the message, maildrop terminates with the EX_TEMPFAIL
750 exit code. A properly-written mail transport agent should
751 re-queue the message, and re-attempt delivery at some later
752 time.
753 An expression that begins with the "|" character specifies an
755 external program to run to handle the actual delivery. The SHELL
756 variable specifies the shell to execute the given command. The
757 message is provided to the command on standard input.
758 maildrop's exit code will be the process's exit code.
759 An expression that begins with an exclamation mark, "!"
761 specifies a whitespace-delimited list of E-mail addresses to
762 forward the message to. The program specified by the SENDMAIL
763 variable is run as an external program, with the list of E-mail
764 addresses provided as parameters to the program.
765 Otherwise, expression names the mailbox where maildrop delivers
767 the message. If expression is a directory, maildrop assumes that
768 the directory is a maildir directory. Otherwise, maildrop will
769 deliver the message to a file, formatted in traditional mailbox
770 format. maildrop will use either dot-locking, or
771 flock()-locking when delivering the message to the file.
772 while - repeatedly execute a block of statements
774 while (expression)
775 {
776 ...
777 }
778 The expression is repeatedly evaluated. Each time it evaluates
780 to a logical true[12], the statements inside the braces are
781 executed. When expression evaluates to a logical false, the
782 while loop is over. Take care to avoid infinite loops.
783 xfilter - filter message through another program
785 xfilter expression
786 expression specifies an external program that maildrop runs to
788 filter the current message. The current message will be piped to
789 the filter program as standard input. The output of the filter
790 program replaces the current message being delivered. The
791 external program must terminate with an exit code of 0. If the
792 external program does not terminate with an exit code of 0, or
793 if it does not read the message from the standard input,
794 maildrop terminates with an exit code of EX_TEMPFAIL.
795 || - logical or
797 expression1 || expression2
798 If expression1 evaluates to a logical true, the result of the ||
801 is expression1, otherwise it's expression2, which is evaluated.
802 maildrop uses the following concept of true/false: an empty text
804 literal, or a text literal that consists of the single character
805 "0" is a logical false value. Anything else is a logical true
806 value.
807 && - logical and
809 expression1 && expression2
810 If expression1 evaluates to a logical false, the result of the
813 && is expression1, otherwise it's expression2, which is
814 evaluated.
815 maildrop uses the following concept of true/false: an empty text
817 literal, or a text literal that consists of the single character
818 "0" is a logical false value. Anything else is a logical true
819 value.
820 <, <=, >, >=, ==, != - numerical comparison
822 expression1 < expression2
823 expression1 <= expression2
825 expression1 > expression2
827 expression1 >= expression2
829 expression1 == expression2
831 expression1 != expression2
833 These operators compare their left hand side expression against
836 their right hand side. These operators compare the numerical
837 values of each side, as floating point numbers. If the numbers
838 compare as indicated, the result of the comparison is the text
839 string "1", otherwise it is the text string 0.
840 Note
842 Ccomparisons are not associative: "a < b < c" is an error. If it
843 is absolutely necessary, use "(a < b) < c".
844 lt, le, gt, ge, eq, ne - text comparison
846 expression1 lt expression2
847 expression1 le expression2
849 expression1 gt expression2
851 expression1 ge expression2
853 expression1 eq expression2
855 expression1 ne expression2
857 These operators compare their left hand side expression against
860 their right hand side. These operators compare each side as text
861 strings (alphabetically, although the text may include
862 anything). If the text strings compare as indicated, the result
863 of the comparison is the text string "1", otherwise it is the
864 text string 0.
865 Note
867 Comparisons are not associative: "a lt b lt c" is an error. If
868 it is absolutely necessary, use "(a lt b) lt c". (But why would
869 you?).
870 | - bitwise or
872 expression1 | expression2
873 This is the bitwise or operator. Its result is a 32 bit integer,
875 which is a bitwise-or combination of the left hand side and the
876 right hand side.
877 & - bitwise and
879 expression1 & expression2
880 This is the bitwise and operator. Its result is a 32 bit
882 integer, which is a bitwise-and combination of the left hand
883 side and the right hand side.
884 +, -, *, / - numerical operations
886 expression1 + expression2
887 expression1 - expression2
889 expression1 * expression2
891 expression1 / expression2
893 These are numerical, floating point, operators.
896 =~ /pattern/:options - pattern match against string
898 expression =~ /pattern/:option
899 The left hand side of the =~ operator can be any expression. The
901 right hand side is always a pattern specification. The result of
902 the operator is the weighted match of the pattern against
903 expression (if the options do not specify weighted scoring, the
904 result is simply 1 if the pattern was found, 0 if not).
905 See "Patterns[13]" for more information.
907 /pattern/:options - pattern match against message
909 expression =~ /pattern/:option
910 The result of this operator is the weighted match of the pattern
912 against the current message (if the options do not specify
913 weighted scoring, the result is simply 1 if the pattern was
914 found, 0 if not).
915 See "Patterns[13]" for more information.
917 !, ~ - logical/bitwise not operator.
919 ! expression
920 ~ expression
922 The result of the ! operator is a logical opposite of its right
924 hand side expression. If the right hand side expression
925 evaluated to a logical true, the result is a logical false. If
926 it evaluated to a logical false, the result is a logical true.
927 maildrop uses the following concept of true/false: an empty text
929 literal, or a text literal that consists of the single character
930 "0" is a logical false value. Anything else is a logical true
931 value.
932 The result of the ~ operator is a bitwise complement of its
934 right hand side expression. The right hand side expression is
935 evaluated as a 32 bit integer, and the result of this operator
936 is a bitwise complement of the result.
937 escape(string) - escape special characters in a string.
939 escape(expression)
940 The escape function returns its sole argument with every
942 occurrence of a special character prefixed by a backslash. A
943 special character is any of the following characters:
944 This can used when matching pattern sections[14], and then
946 taking one section and matching it again. For example:
947 This example checks if the contents of the From: header can also
949 be found in the Subject: header. If the escape function were not
950 used, then any special characters in the From: header that are
951 also used in regular expressions, such as * or +, would
952 introduce unpredictable behavior, most likely a syntax error.
953 The reason why this list of special characters also includes
955 characters not used in maildrop's regular expressions is to
956 allow maildrop's variables to be used on the command line of a
957 shell command executed by the xfilter command, backtick
958 characters, or to or cc commands.
959 Although using data from an external data source is dangerous,
961 and it may result in inadvertent exploits, using the escape
962 function should hopefully result in fewer surprises.
963 gdbmopen, gdbmclose, gdbmfetch, gdbmstore - GDBM support in maildrop
965 These functions provide support for GDBM database files. See
966 maildropgdbm(5)[15] for more information.
967 Note
969 The system administrator can disable GDBM support in maildrop,
970 so these commands may not be available to you.
971 getaddr(string) - extract RFC 2822 addresses from a header.
973 if ( /^From:\s*(.*)/ )
974 {
975 ADDR=getaddr($MATCH1)
976 }
977 This function is usually applied to a header that contains RFC
979 2822[16] addresses. It extracts the actual addresses from the
980 header, without any comments or extraneous punctuation. Each
981 address is followed by a newline character. For example, if
982 string contains:
983 The result of the getaddr function is the following string:
984 Note
986 Because getaddr() interprets RFC 2822[17] loosely, it is not
987 necessary to strip off the "To:" or the "Cc:" header from the
988 string, before feeding it to getaddr(). For example, the
989 following snippet of code takes all addresses in the message,
990 and concatenates them into a single string, separated by spaces:
991 Note
993 In certain rare situations, RFC 2822[17] allows spaces to be
994 included in E-mail addresses, so this example is just
995 educational.
996 hasaddr(string) - Search for an address.
998 if ( hasaddr(string) )
999 {
1000 ...
1001 }
1002 "string" is of the form user@domain. The hasaddr function
1004 returns 1 if this address is included in any To:,
1005 Cc:,Resent-To:, or Resent-Cc:, header in the message, otherwise
1006 this function returns 0.
1007 This is more than just a simple text search. Each header is
1009 parsed according to RFC822. Addresses found in the header are
1010 extracted, ignoring all comments and names. The remaining
1011 addresses are checked, and if "string" is one of them, hasaddr
1012 returns 1, otherwise it returns 0.
1013 The comparison is case-insensitive. This actually violates
1015 RFC822 (and several others) a little bit, because the user part
1016 of the address may be (but is not required to be) case
1017 sensitive.
1018 length (string) - length of a string
1020 if (length(string) > 80)
1021 {
1022 ...
1023 }
1024 The length function returns the number of characters in string.
1026 lookup (expr, 'filename', 'options') - read file for patterns
1028 if (lookup(expr, file, "option"))
1029 {
1030 ...
1031 }
1032 expr is any expression. filename is a name of a file containing
1034 a list of patterns. Note that filename is relative to the
1035 current directory, which is the home directory of the user when
1036 maildrop runs in delivery mode, or embedded mode. maildrop then
1037 reads the file. Blank lines will be ignored, as well as any
1038 lines that begin with the # character (comments).
1039 Leading whitespace (but not trailing whitespace, take care) is
1041 removed, and the remaining contents of each line are interpreted
1042 as a pattern which is matched against expr. As soon as the match
1043 is found, lookup returns "1". If no match is found after reading
1044 the entire file, lookup returns "0". For example:
1045 The file badto.dat contains the following two lines:
1047 If a message has a To: header that contains the text
1049 "friend@public", or does not contain at least one @ character,
1050 then the message will be silently dropped on the floor (
1051 maildrop will terminate without delivering the message
1052 anywhere).
1053 options are the pattern matching options to use. The only
1055 supported option is "D" (the rest are meaningless, in this
1056 case).
1057 Note
1059 Be careful with discarding messages like that. Pattern matching
1060 can be tricky, and a slight miscalculation can cause mail to be
1061 unintentionally discarded. It is much desirable to first deliver
1062 message to a separate folder or mailbox, and once the filter is
1063 verified to work correctly, change it so the messages are
1064 discarded completely.
1065 substr(string,start [,count]) - return substring
1067 foo=substr($foo, 1, 10)
1068 The substr function takes start number of characters from
1070 string. If count is specified, at most count characters starting
1071 at position start are kept, any excess is trimmed.
1072 time - return current time
1074 foo=time
1075 The time function returns the current time, in seconds, since
1077 January 1, 1970. This function is useful when using GDBM files.
1078 See maildropex(7)[18] for an example of using the time function.
1079 tolower(string) - Convert string to lowercase.
1081 foo=tolower(string)
1082 This function returns the string with all uppercase characters
1084 replaced by lowercase characters.
1085 toupper(string) - Convert string to uppercase.
1087 foo=toupper(string)
1088 This function returns the string with all lowercase characters
1090 replaced by uppercase characters.
1091 Statements
1093 The filter file is read by maildrop ($HOME/.mailfilter or another
1094 file), and it contains filtering statements, one per line. The
1095 filtering language used by maildrop has a loosely - defined grammatical
1096 structure.
1097 Statements are listed one per line. Multiple statements may be listed
1099 on the same line by separating them with semicolons. To continue a long
1100 statement on the next line, terminate the line with a backslash
1101 character.
1102
1104 If getaddr() or hasaddr() functions are used on broken headers, the
1105 results are unpredictable.
1106 hasaddr() is completely case insensitive. This actually violates a few
1108 RFCs, because the userid portion of the address could be
1109 case-sensitive, but it's not in too many cases, so there.
1110
1112 lockmail(1)[19], maildrop(1)[20], maildropgdbm(5)[15],
1113 maildirquota(8)[4], reformail(1)[21], egrep(1), sendmail(8).
1114
1116 1. Courier Mail Server
1117 http://www.courier-mta.org/
1118 2. dot-courier(5)
1120 dot-courier.html
1121 3. value of the -M option
1123 maildrop.html#moption
1124 4. maildirquota(8)
1126 maildirquota.html
1127 5. xfilter
1129 #xfilter
1130 6. PCRE
1132 http://www.pcre.org
1133 7. See the to statement
1135 #to
1136 8. flock statement
1138 #flock
1139 9. embedded mode
1141 maildrop.html#embedded
1142 10. dotlock statement
1144 #dotlock
1145 11. cc
1147 #cc
1148 12. evaluates to a logical true
1150 #if
1151 13. Patterns
1153 #patterns
1154 14. matching pattern sections
1156 #patmatch
1157 15. maildropgdbm(5)
1159 maildropgdbm.html
1160 16. RFC 2822
1162 http://www.rfc-editor.org/rfc/rfc2822.txt
1163 17. RFC 2822
1165 http://www.rfc-editor.org/rfc/rfc822.txt
1166 18. maildropex(7)
1168 maildropex.html
1169 19. lockmail(1)
1171 lockmail.html
1172 20. maildrop(1)
1174 maildrop.html
1175 21. reformail(1)
1177 reformail.html
1178Double Precision, Inc. 04/22/2007 MAILDROPFILTER(7)