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
40 variable whose name is FILE. Later, the contents of a variable are
41 accessed by using the $ symbol and the name for the variable. For
42 example:
43 to $FILE
45 This will deliver the current message to the mailbox file (or a maildir
47 directory) named "IN.junk".
48 maildrop initially creates variables from the environment variables of
50 the operating system, UNLESS maildrop runs in delivery mode. Each
51 operating system environment variable becomes a maildrop variable. When
52 running in delivery mode, maildrop does not import the environment for
53 security reasons, except for the environment variables that define the
54 process locale (LANG, LANGUAGE, and LC_*), which are still imported.
55 In all cases maildrop resets the following variables to their default
57 values: HOME, DEFAULT, SHELL, PATH, LOCKEXT, LOCKREFRESH, LOCKSLEEP,
58 LOCKTIMEOUT, MAILDIRQUOTA, SENDMAIL and LOGNAME.
59 There´s one exception to this rule which applies to the version of
61 maildrop that comes with the Courier mail server[1]. The following does
62 not apply to the standalone version of maildrop: when running in
63 delivery mode, if the -d flag was not used, or if it specifies the same
64 userid as the one that´s running maildrop: the following variables are
65 automatically imported from the environment: HOME, SHELL, LOGNAME and
66 MAILDIRQUOTA. These environment variables are initialized by the
67 Courier mail server prior to running maildrop. Additionally, the
68 initial value for the DEFAULT maildrop variable is imported from the
69 MAILDROPDEFAULT environment variable. This is because the Courier mail
70 server overloads the DEFAULT environment variable to store the
71 defaulted portion of the local mailbox address. See the
72 dot-courier(5)[2] man page in the Courier mail server distribution. You
73 can get the Courier mail server´s DEFAULT value by using the import
74 command. Note, however, that this will clobber the old contents of
75 DEFAULT, which is probably not what you want. The right way to do this
76 would be something like this:
77 SAVEDEFAULT=$DEFAULT
79 import DEFAULT
80 LOCALDEFAULT=$DEFAULT
81 DEFAULT=$SAVEDEFAULT
82 All internal variables are exported back as environment variables when
84 maildrop runs an external command. Changes to internal variables, made
85 by the filter file, are reflected in the exported environment.
86 Lexical structure
88 Most whitespace is generally ignored. The # character introduces a
89 comment running to the end of the line, which is also ignored. Unlike
90 other mail filters, maildrop parses the filter file before taking any
91 action with the message. If there are syntax errors in the file,
92 maildrop displays an error message, and returns EX_TEMPFAIL. That
93 should cause the mail message to remain in the queue, and, hopefully
94 allow the problem to be corrected, without bouncing any mail.
95 Note
97 In maildrop, the end of line is a lexical token. In order to
98 continue a long statement on the next line, terminate the line with
99 a backslash character.
100 Literal text
102 Literal text in the maildrop filtering language is surrounded by either
103 single or double quotes. In order to enter a single quote into a text
104 literal surrounded by single quotes, or a double quote into a literal
105 surrounded by double quotes, prefix it with a backslash character. Use
106 two backslash characters characters to enter one backslash character in
107 the text literal.
108 Note
110 A backslash followed by either a backslash, or a matching quote, is
111 the only situation where the backslash character is actually
112 removed, leaving only the following character in the actual text
113 literal. If a backslash character is followed by any other
114 character, the backslash is NOT removed.
115 Multiple text literals in a row are automatically concatenated, even if
117 they use different quotes. For example:
118 FOOBAR="Foo"´bar´
120 SAVEDEFAULT=$DEFAULT
121 import DEFAULT
122 LOCALDEFAULT=$DEFAULT
123 DEFAULT=$SAVEDEFAULT
124 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
135 followed by "/Mailbox". Variable names must begin with an uppercase
136 letter, a lowercase letter, or an underscore. Following that, all
137 letters, digits, and underscores are taken as a variable name, and its
138 contents replace the $ sign, and the variable name. It is possible to
139 access variables whose name includes other characters, by using braces
140 as follows:
141 MAILBOX="${HOME-WORD}/Mailbox"
143 Inserts the contents of the HOME-WORD variable. If the variable does
145 not exist, the empty text literal is used to replace the variable name.
146 It is not possible to access variables whose names include the }
147 character.
148 If the $ character is not followed by a left brace, letter, or an
150 underscore, the $ character remains unmolested in the text literal. A
151 backslash followed by the $ character results in a $ character in the
152 text literal, without doing any variable substitution.
153 Variable substitution is not done in text literals which are surrounded
155 by single quotes (apostrophes).
156 Command line arguments
158 maildrop initializes special variables: $1, $2, and so on, with
159 additional parameters specified on the maildrop command line. A filter
160 file may use those variables just like any other variables.
161 Predefined variables
163 The following variables are automatically defined by maildrop. The
164 default values for the following variables may be changed by the system
165 administrator. For security reasons, the values of the following
166 variables are always reset to their default values, and are never
167 imported from the environment:
168 DEFAULT
170 The default mailbox to deliver the message to. If the filter file
171 does not indicate a mailbox to deliver this message to, the message
172 is delivered to this mailbox. The default mailbox is defined by the
173 system administrator.
174 FROM
176 Message envelope sender. This is usually the same address as what
177 appears in the From: header, but may not be. This information may
178 or may not be available to maildrop on your system. The message
179 envelope sender is usually specified with the -f option to
180 maildrop. If the -f option is not given, maildrop looks for the
181 From_ line in the message. As the last resort, FROM defaults to the
182 userid which invoked maildrop. Note that FROM may be empty - the
183 message envelope sender is empty for bounce messages.
184 HOME
186 Home directory of the user running maildrop.
187 HOSTNAME
189 Network name of the machine running maildrop. Obtained from
190 gethostname(3).
191 LOCKEXT
193 Extension for dot-lock files (default: .lock).
194 LOCKREFRESH
196 Refresh interval, in seconds, for dot-locks (default: 15). When
197 maildrop dot-locks a mailbox, maildrop tries to refresh the lock
198 periodically in order to keep other programs from removing a stale
199 dot-lock. This is only required if a dot-lock exists for a
200 prolonged period of time, which should be discouraged anyway.
201 LOCKSLEEP
203 Number of seconds to wait to try again to create a dot-lock file,
204 if one already exists (default: 5).
205 LOCKTIMEOUT
207 Number of seconds to wait before removing a stale dot-lock file
208 (default: 60). If a dot-lock file still exists after LOCKTIMEOUT
209 seconds, maildrop assumes that the process holding the lock no
210 longer exists, and the dot-lock file can be safely removed. After
211 removing the dot-lock file, maildrop waits LOCKSLEEP seconds before
212 trying to create its own dot-lock file, in order to avoid a race
213 condition with another process which is also trying to remove the
214 same stale dot-lock, at the same time.
215 LOGNAME
217 Name of the user to who the message is being delivered.
218 MAILDROP_OLD_REGEXP
220 Revert to using the old legacy pattern matching engine. Versions of
221 maildrop prior to version 2.0 (included in the Courier mail server
222 0.51, and earlier), used a built-in pattern matching engine,
223 instead of using the PCRE library (see the “Patterns” section).
224 maildrop 1.x used a different syntax for patterns, which is no
225 longer described in this manual page. The old pattern matching
226 engine is still available, by setting MAILDROP_OLD_REGEXP to “1”.
227 Setting this variable will use the legacy pattern matching engine
228 for the rest of the maildrop recipe file.
229 The pattern matching engine will be removed completely in a future
231 version of maildrop. This setting provides for a transitional
232 period of converting old recipes. MAILDROP_OLD_REGEXP can be set
233 to “1” in the global maildroprc file, then reset to “0” in each
234 individual maildrop recipe file, after it gets converted to the new
235 syntax.
236 MAILFILTER
238 This is the name of the original filter file that was given to
239 maildrop on the command line. This is mostly usefull to -default
240 filter files, it allows them to obtain the value of the -M
241 option[3] specified on the command line.
242 PATH
244 Command execution path. maildrop resets PATH to the system default
245 (usually /bin:/usr/bin:/usr/local/bin).
246 SENDMAIL
248 The mail delivery agent. When maildrop is instructed to deliver the
249 message to a mailbox whose name begins with the ! character, this
250 is interpreted as a request to forward the message. The SENDMAIL
251 command is executed to forward the message.
252 SHELL
254 The login shell. The shell is used to execute all commands invoked
255 by maildrop.
256 VERBOSE
258 Current Debug level (default: 0). Setting VERBOSE to progressive
259 higher values, between 1 and 9, produces debugging output on
260 standard error. maildrop ignores the VERBOSE variable in delivery
261 mode (in order not to confuse the mail transport agent).
262 UMASK
264 The file creation mode mask, in octal. The default setting of 077
265 creates mailboxes that are readable and writable by the owner only.
266 Use 007 to create mailboxes that are readable/writable by both
267 owner and the group. Use 037 to create mailboxes that are readable
268 by both owner and group, but writable by owner only. Permissions on
269 existing mailboxes are not changed, this setting affects only new
270 mailboxes. When delivering to maildirs this setting sets the
271 permissions on new messages only. Access permissions on messages in
272 maildirs are also affected by the permissions on the maildir
273 directories.
274 Other special variables
276 The following variables are automatically used by maildrop when the
277 filter file is being processed:
278 EXITCODE
280 Return code for maildrop. When maildrop successfully delivers a
281 message, it terminates with this exit code, which defaults to 0.
282 When the to or the cc command is used to deliver the message to an
283 external process, via a pipe, maildrop will set this variable to
284 the exit code of the external process. Since maildrop immediately
285 terminates after completing the to command this means that
286 maildrop´s exit code will be the exit code of the external process.
287 If the to command does not deliver the message to a process you
288 must set EXITCODE before the to command, since maildrop terminates
289 immediately after finishing the delivery.
290 KEYWORDS
292 The KEYWORDS variable is used only when delivering a message to a
293 maildir, and implements the optional IMAP keyword extension as
294 implemented in the Courier IMAP server[1]. It may be optionally
295 initialized to contain a comma-separate list of keywords. The to,
296 or the cc command, delivers the message to the maildir normally,
297 but also associated the list of keywords in KEYWORDS with the newly
298 delivered message.
299 KEYWORDS must be set before the message is delivered to a maildir.
302 The contents of KEYWORDS are ignored, when delivering on an mbox
303 folder.
304 LINES
306 Number of lines in the current message. Note that this may be an
307 approximation. It may or may not take into account the -A option,
308 or any mbox "From_" lines. Use this as criteria for filtering,
309 nothing more.
310 MAILDIRQUOTA
312 Set this variable in order to manually enforce a maximum size on
313 ANY maildir where the message is delivered. This is an optional
314 feature that must be enabled by the system administrator, see
315 maildirquota(8)[4] for more information.
316 RETURNCODE
318 This variable is set when maildrop runs the xfilter[5] command, or
319 a command that´s specified within a pair of backtick characters (
320 command substitution ). The RETURNCODE variable will be set to the
321 exit code of the command, after it completes.
322 SIZE
324 Number of bytes in the message. This may or may not include the -A
325 option, and the mbox From_ line. Use this as a criteria for
326 filtering, nothing more.
327 Unquoted text
329 All text strings in filter files should be in single, or double quotes.
330 However, for convenience sake, quotes can be omitted under certain
331 circumstances.
332 Text that includes ONLY letters, digits, and the following characters:
334 _-.:/${}@ may appear without quotes. Note that this does not allow
335 spaces, or backslashes to be entered, however the text is still
336 variable-substituted, and the substituted text may contain other
337 characters.
338 Also, note that patterns (see below) begin with the slash character.
340 Normally, anything that begins with the slash is interpreted as a
341 pattern. However, text immediately after “VARIABLE=” is interpreted as
342 a string even if it begins with a slash. This is why something like:
343 MAILDIR=/var/mail
345 works as expected. Using quotes, though, is highly recommended. You
347 must use quotes to set a variable to a lone slash, because an unquoted
348 slash is interpreted as a division sign.
349 Long double or singly-quoted text can be broken across multiple lines
351 by ending the line with a lone backslash character, like this:
352 TEXT="This is a long \
354 text string"
355 The backslash, the newline, and all leading whitespace on the next line
357 is removed, resulting in "This is a long text string".
358 Command substitution
360 Text enclosed in back-tick characters is interpreted as a shell
361 command. The shell command is executed as a child process by maildrop.
362 Its output is used in place of the command. For example:
363 DIR=`ls`
365 places the names of the files in the current directory into the DIR
367 variable.
368 The output of the command will have all newline characters replaced by
370 spaces, and leading and trailing spaces will be stripped (multiple
371 spaces are not removed, though). Also, the contents of the message
372 being delivered is made available to the command on standard input.
373 Patterns
375 The pattern syntax in maildrop is similar to the grep command´s syntax,
376 with some minor differences. A pattern takes the following form in the
377 filter file:
378 /pattern/:options
380 pattern specifies the text to look for in the message. pattern must
382 not begin with a space, otherwise the leading slash will then be
383 interpreted as a division sign. If you must search for text that starts
384 with a space, use something like "/[ ] ... /".
385 The general syntax of maildrop´s patterns is described in the
387 pcrepattern(3) manual page, with certain exceptions noted below.
388 maildrop uses the PCRE[6] library to implement pattern matching. Not
389 all features in PCRE are available in maildrop, and the “options” part,
390 which follows the pattern specification, changes the pattern matching
391 further. Consult the pcrepattern(3) manual page for more information,
392 but note the following exceptions:
393 · UTF-8 string matching is not presently supported.
395 · Internal options settings are not supported (but see the “D”
397 maildrop option, below). Do not include option settings in the
398 pattern, doing so will lead to undefined results.
399 · Named subpatterns are not implemented. Numbered subpatterns are
401 implemented, see “Pattern Match Results”, below.
402 Pattern options
404 Following /pattern/, there may be an optional colon, followed by one.
405 or more options. The following options may be specified in any order:
406 h
408 Match this pattern against the message header.
409 b
411 Match this pattern against the message body.
412 D
414 This is a case sensitive match. Normally the patterns match either
415 uppercase or lowercase text. /john/ will match "John", "john", or
416 "JOHN". Specify the D option for a case-sensitive search: lowercase
417 letters in the pattern must match lowercase letters in the message;
418 ditto for uppercase.
419 If neither ´h´ or ´b´ is specified, the pattern is matched against the
421 header only. Specifying the ´b´ option causes the pattern to be matched
422 against the message body. Specifying both causes the pattern to be
423 matched against the entire message.
424 Normally, each line in the message gets matched against the pattern
426 individually. When applying patterns to a header, multi-line headers
427 (headers split on several lines by beginning each continuation line
428 with whitespace) are silently combined into a single line, before the
429 pattern is applied.
430 Weighted scoring
432 Patterns are evaluated by maildrop as any other numerical expression.
433 If a pattern is found, maildrop´s filter interprets the results of the
434 pattern match as number 1, or true, for filtering purposes. If a
435 pattern is not found the results of the pattern search is zero. Once a
436 pattern is found, the search stops. Second, and subsequent occurrences
437 of the same pattern are NOT searched for.
438 maildrop can also do weighted scoring. In weighted scoring, multiple
440 occurrences of the same pattern are used to calculate a numerical
441 score.
442 To use a weighted search, specify the pattern as follows:
444 /pattern/:options,xxx,yyy
446 where xxx and yyy are two numbers. yyy is optional -- it will default
448 to 1, if missing.
449 The first occurrence of the pattern is evaluated as xxx. The second
451 occurrence of the pattern is evaluated as xxx*yyy, the third as
452 xxx*yyy*yyy, etc... All occurrences of the pattern are added up to
453 calculate the final score.
454 Note
456 maildrop does not recognize multiple occurrences of the same
457 pattern in the same line. Multiple occurences of the same pattern
458 in one line count as one occurence.
459 Pattern Match Results
461 After a pattern is successfully matched, the actual text that is
462 matched is placed in the MATCH variable. For example:
463 /^From:.*/
465 matches a line of the form:
467 From: postmaster@localhost .PP Here the variable MATCH will be
469 set to "From: postmaster@localhost", which can be used in subsequent
470 statements.
471 If the pattern contains subpatterns, the portions of the text that
473 match the first subpattern is placed in the MATCH1 variable. The second
474 subpattern, if any, is placed in MATCH2, and so on:
475 /^From:\s+(.*)@(.*)/
477 matched against the same line will set MATCH to “From:
479 postmaster@localhost”, MATCH1 to “postmaster”, and MATCH2 to
480 “localhost”. Of course, in real world the “From:” header is usually
481 much more complicated, and can´t be handled that easily. This is just
482 an illustrative example.
483 Note
485 Subpatterns are not processed in the foreach statement.
486 Conversion of maildrop 1.x patterns to 2.0
488 Although the new PCRE-based pattern matching code in maildrop is
489 completely different from the built-in pattern matching code in
490 maildrop 1.x, very few changes will be required to convert recipes to
491 the new syntax. The only major differences are:
492 · The subexpression format has changed. Any pattern that uses
494 subexpression needs to be converted. Additionally, references to
495 MATCH2 must be replaced with MATCH1, MATCH3 to MATCH2, and so on.
496 References to plain old MATCH will remain the same.
497 · The “w” pattern option is no longer possible, with PCRE. The very
499 few recipes that use this option, if any actually exist, will have
500 to be rewritten in some other fashion.
501 Expressions
503 Although maildrop evaluates expressions numerically, results of
504 expressions are stored as text literals. When necessary, text literals
505 are converted to numbers, then the results of a mathematical operation
506 is converted back into a text literal.
507 Operators
509 The following operators carry their usual meaning, and are listed
510 in order from lowest precedence, to the highest:
511 ||
514 &&
515 < <= > >= == != lt le gt ge eq ne
516 |
517 &
518 + -
519 * /
520 =~ /pattern/
521 /pattern/ ! ~ function()
522 Variable assignment
525 VARIABLE=expression
526 Assigns the result of the expression to VARIABLE (note no leading $
528 in front of variable).
529 Note
531 If VARIABLE is NOT surrounded by quotes, then it may contain
532 only letters, numbers, underscores, dashes, and a selected few
533 other characters. In order to initialize a variable whose name
534 contains non-standard punctuation marks, surround the name of
535 the variable with quotes.
536 cc - deliver a copy of the message
538 cc expression
539 The cc statement is very similar to the to statement, except that
541 after delivering the message maildrop continues to process the
542 filter file, unlike the to statement which immediately terminates
543 maildrop after the delivery is complete. Essentially, the message
544 is carbon copied to the given mailbox, and may be delivered again
545 to another mailbox by another cc or to statement.
546 See the to statement[7] for more details. When cc is used to
548 deliver a message to a process maildrop will set the EXITCODE
549 variable to the process´s exit code.
550 dotlock - create a manual dot-lock
552 dotlock expression {
553 ...
555 }
557 maildrop automatically creates a lock when a message is delivered
559 to a mailbox. Depending upon your system configuration, maildrop
560 will use either dot-locks, or the flock() system call.
561 The dotlock statement creates an explicit dot-lock file. Use the
563 flock statement[8] to create an explicit flock() lock.
564 The expression is a filename that should be used as a lock file.
566 maildrop creates the indicated dot-lock, executes the filtering
567 instructions contained within the { ... } block, and removes the
568 lock. The expression must be the name of the dot-lock file itself,
569 NOT the name of the mailbox file you want to lock.
570 Note
572 With manual locking, it is possible to deadlock multiple
573 maildrop processes (or any other processes that try to claim
574 the same locks).
575 No deadlock detection is possible with dot-locks, and since
577 maildrop automatically refreshes all of its dot-locks
578 regularly, they will never go stale. You´ll have maildrop
579 processes hanging in limbo, until their watchdog timers go off,
580 aborting the mail delivery.
581 echo - output diagnostic information
583 echo expression
584 maildrop will print the given text. This is usually used when
586 maildrop runs in embedded mode, but can be used for debugging
587 purposes. Normally, a newline is printed after the text. If text is
588 terminated with a \c, no newline will be printed.
589 exception - trap fatal errors
591 exception {
592 ...
594 }
596 The exception statement traps errors that would normally cause
598 maildrop to terminate. If a fatal error is encountered anywhere
599 within the block of statements enclosed by the exception clause,
600 execution will resume immediately following the exception clause.
601 exit - terminate filtering unconditionally
603 exit
604 The exit statement immediately terminates filtering. maildrop´s
606 return code is set to the value of the EXITCODE variable. Normally,
607 maildrop terminates immediately after successfully delivering the
608 message[7] to a mailbox. The exit statement causes maildrop to
609 terminate without delivering the message anywhere.
610 The exit statement is usually used when maildrop runs in embedded
612 mode[9], when message delivery instructions are not allowed.
613 flock - create an manual flock() lock
615 flock expression {
616 ...
618 }
620 maildrop automatically creates a lock when a message is delivered
622 to a mailbox. Depending upon your system configuration, maildrop
623 will use either dot-locks, or the flock() system call.
624 The flock statement creates a manual flock() lock. Use the dotlock
626 statement[10] to create a manual dot-lock file.
627 The expression is the name of the file that should be locked.
629 maildrop creates the lock on the indicated file, executes the
630 filtering instructions contained within the { ... } block, and
631 removes the lock.
632 Note
634 With manual locking, it is possible to deadlock multiple
635 maildrop processes (or any other processes that try to claim
636 the same locks). The operating system will automatically break
637 flock() deadlocks. When that happens, one of the maildrop
638 processes will terminate immediately. Use the exception
639 statement in order to trap this exception condition, and
640 execute an alternative set of filtering instructions.
641 foreach - iterate over text sections matched by a pattern
643 foreach /pattern/:options
644 {
645 ...
646 }
647 foreach (expression) =~ /pattern/:options
649 {
650 ...
651 }
652 The foreach statement executes a block of statements for each
654 occurrence of the given pattern in the given message, or
655 expression. On every iteration MATCH variable will be set to the
656 matched string. All the usual options may be applied to the pattern
657 match, EXCEPT the following:
658 ,xxx,yyy
660 Weighted scoring is meaningless, in this context.
661 ( ... )
663 Subpatterns are not processed. Only the MATCH variable will be
664 set for each found pattern.
665 if - conditional execution
667 if (expression)
668 {
669 ...
670 }
671 else
672 {
673 ...
674 }
675 Conditional execution. If expression evaluates to a logical true
677 (note - parenthesis are required) then the first set of statements
678 is executed. The else keyword, and the subsequent statements, are
679 optional. If present, and the expression evaluates to a logical
680 false, the else part is executed.
681 maildrop evaluates all expression as text strings. In the context
683 of a logical expression, an empty string, or the number 0
684 constitutes a logical false value, anything else is a logical true
685 value.
686 If the if part, or the else part consists of only one statement,
688 the braces may be omitted.
689 Note
691 The grammar of this if statement is stricter than usual. If you
692 get baffling syntax errors from maildrop, make sure that the
693 braces, and the if statement, appear on separate lines.
694 Specifically: the closing parenthesis, the closing braces, and
695 the else statement, must be at the end of the line (comments
696 are allowed), and there may not be any blank lines in between
697 (not even ones containing comments only).
698 import - access original environment variable
700 import variable
701 When maildrop starts, it normally imports the contents of the
703 environment variables, and assigns them to internal maildrop
704 variables. For example, if there was an environment variable FOO,
705 the internal maildrop variable FOO will have the contents of the
706 environment variable. From then on, FOO will be no different than
707 any other variable, and when maildrop runs an external command, the
708 contents of maildrop´s variables will be exported as the
709 environment for the command.
710 Certain variables, like HOME and PATH, are always reset to fixed
712 defaults, for security reasons. Also, in delivery and embedded
713 modes, the environment is not imported at all (with the exception
714 of system locale environment variables), and maildrop starts with
715 only the fixed default variables.
716 The import statement initializes the specified variable with the
718 contents of the original environment variable when maildrop
719 started. For example:
720 echo "PATH is $PATH"
722 PATH="/bin"
723 echo "PATH is $PATH"
724 import PATH
725 echo "PATH is $PATH"
726 exit
727 This results in the following output:
729 PATH is /bin:/usr/bin:/usr/local/bin
731 PATH is /bin
732 PATH is /home/root/bin:/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/bin
733 This shows that when maildrop starts PATH is set to the fixed
735 default of /bin:/usr/bin:/usr/local/bin. However, the original
736 contents of the PATH environment variable we different, and the
737 import statement shows what it was.
738 include - execute filtering instructions from another file
740 include expression
741 The include statement reads a file, and executes filtering
743 instructions contained in that file. Note that the include
744 statement is processed when the current filter file is being
745 executed. When maildrop reads the initial filter file, any syntax
746 errors in the filtering instructions are immediately reported, and
747 maildrop will terminate with a return code of EX_TEMPFAIL. Any
748 errors in files specified by include statements are NOT reported,
749 because those files will not be read until the include statement is
750 itself executed.
751 If the specified file does not exist, or if there are any syntax
753 errors in the file, maildrop reports the error, and terminates with
754 a return code of EX_TEMPFAIL.
755 log, logfile - log message deliveries
757 logfile expression
758 log expression
760 Logging in maildrop is normally turned off. The logfile statement
762 specifies the file where maildrop will log how the message has been
763 disposed of. The parameter is then name of the file. If the file
764 exists maildrop appends to the file.
765 For each delivery (the to[7] and cc[11] statements, and default
767 deliveries) maildrop records the From: and the Subject: fields,
768 together with the current time, in the log file.
769 The log statement adds additional logging text to the log file. The
771 log statement works exactly like the echo statement, except that
772 the text is written to the logfile, instead of standard output.
773 to - deliver message to a mailbox
775 to expression
776 The to statement delivers the message to a mailbox. expression
778 must evaluate to a valid mailbox. A valid mailbox is either a
779 mailbox file, a maildir, or an external program (which includes
780 forwarding to another address).
781 The to statement is the final delivery statement. maildrop
783 delivers message, then immediately terminates, with its return code
784 set to the EXITCODE variable. If there was an error while
785 delivering the message, maildrop terminates with the EX_TEMPFAIL
786 exit code. A properly-written mail transport agent should re-queue
787 the message, and re-attempt delivery at some later time.
788 An expression that begins with the "|" character specifies an
790 external program to run to handle the actual delivery. The SHELL
791 variable specifies the shell to execute the given command. The
792 message is provided to the command on standard input. maildrop´s
793 exit code will be the process´s exit code.
794 An expression that begins with an exclamation mark, "!" specifies a
796 whitespace-delimited list of E-mail addresses to forward the
797 message to. The program specified by the SENDMAIL variable is run
798 as an external program, with the list of E-mail addresses provided
799 as parameters to the program.
800 Otherwise, expression names the mailbox where maildrop delivers the
802 message. If expression is a directory, maildrop assumes that the
803 directory is a maildir directory. Otherwise, maildrop will deliver
804 the message to a file, formatted in traditional mailbox format.
805 maildrop will use either dot-locking, or flock()-locking when
806 delivering the message to the file.
807 while - repeatedly execute a block of statements
809 while (expression)
810 {
811 ...
812 }
813 The expression is repeatedly evaluated. Each time it evaluates to a
815 logical true[12], the statements inside the braces are executed.
816 When expression evaluates to a logical false, the while loop is
817 over. Take care to avoid infinite loops.
818 xfilter - filter message through another program
820 xfilter expression
821 expression specifies an external program that maildrop runs to
823 filter the current message. The current message will be piped to
824 the filter program as standard input. The output of the filter
825 program replaces the current message being delivered. The external
826 program must terminate with an exit code of 0. If the external
827 program does not terminate with an exit code of 0, or if it does
828 not read the message from the standard input, maildrop terminates
829 with an exit code of EX_TEMPFAIL.
830 || - logical or
832 expression1 || expression2
833 If expression1 evaluates to a logical true, the result of the || is
836 expression1, otherwise it´s expression2, which is evaluated.
837 maildrop uses the following concept of true/false: an empty text
839 literal, or a text literal that consists of the single character
840 "0" is a logical false value. Anything else is a logical true
841 value.
842 && - logical and
844 expression1 && expression2
845 If expression1 evaluates to a logical false, the result of the &&
848 is expression1, otherwise it´s expression2, which is evaluated.
849 maildrop uses the following concept of true/false: an empty text
851 literal, or a text literal that consists of the single character
852 "0" is a logical false value. Anything else is a logical true
853 value.
854 <, <=, >, >=, ==, != - numerical comparison
856 expression1 < expression2
857 expression1 <= expression2
859 expression1 > expression2
861 expression1 >= expression2
863 expression1 == expression2
865 expression1 != expression2
867 These operators compare their left hand side expression against
870 their right hand side. These operators compare the numerical values
871 of each side, as floating point numbers. If the numbers compare as
872 indicated, the result of the comparison is the text string "1",
873 otherwise it is the text string 0.
874 Note
876 Ccomparisons are not associative: "a < b < c" is an error. If
877 it is absolutely necessary, use "(a < b) < c".
878 lt, le, gt, ge, eq, ne - text comparison
880 expression1 lt expression2
881 expression1 le expression2
883 expression1 gt expression2
885 expression1 ge expression2
887 expression1 eq expression2
889 expression1 ne expression2
891 These operators compare their left hand side expression against
894 their right hand side. These operators compare each side as text
895 strings (alphabetically, although the text may include anything).
896 If the text strings compare as indicated, the result of the
897 comparison is the text string "1", otherwise it is the text string
898 0.
899 Note
901 Comparisons are not associative: "a lt b lt c" is an error. If
902 it is absolutely necessary, use "(a lt b) lt c". (But why would
903 you?).
904 | - bitwise or
906 expression1 | expression2
907 This is the bitwise or operator. Its result is a 32 bit integer,
909 which is a bitwise-or combination of the left hand side and the
910 right hand side.
911 & - bitwise and
913 expression1 & expression2
914 This is the bitwise and operator. Its result is a 32 bit integer,
916 which is a bitwise-and combination of the left hand side and the
917 right hand side.
918 +, -, *, / - numerical operations
920 expression1 + expression2
921 expression1 - expression2
923 expression1 * expression2
925 expression1 / expression2
927 These are numerical, floating point, operators.
930 =~ /pattern/:options - pattern match against string
932 expression =~ /pattern/:option
933 The left hand side of the =~ operator can be any expression. The
935 right hand side is always a pattern specification. The result of
936 the operator is the weighted match of the pattern against
937 expression (if the options do not specify weighted scoring, the
938 result is simply 1 if the pattern was found, 0 if not).
939 See "Patterns[13]" for more information.
941 /pattern/:options - pattern match against message
943 /pattern/:option
944 The result of this operator is the weighted match of the pattern
946 against the current message (if the options do not specify weighted
947 scoring, the result is simply 1 if the pattern was found, 0 if
948 not).
949 See "Patterns[13]" for more information.
951 !, ~ - logical/bitwise not operator.
953 ! expression
954 ~ expression
956 The result of the ! operator is a logical opposite of its right
958 hand side expression. If the right hand side expression evaluated
959 to a logical true, the result is a logical false. If it evaluated
960 to a logical false, the result is a logical true.
961 maildrop uses the following concept of true/false: an empty text
963 literal, or a text literal that consists of the single character
964 "0" is a logical false value. Anything else is a logical true
965 value.
966 The result of the ~ operator is a bitwise complement of its right
968 hand side expression. The right hand side expression is evaluated
969 as a 32 bit integer, and the result of this operator is a bitwise
970 complement of the result.
971 escape(string) - escape special characters in a string.
973 escape(expression)
974 The escape function returns its sole argument with every occurrence
976 of a special character prefixed by a backslash. A special character
977 is any of the following characters:
978 |!$()[]\+*?.&;`´-~<>^{}"
980 This can used when matching pattern sections[14], and then taking
982 one section and matching it again. For example:
983 if ( /^From:\s*(.*)/ )
985 {
986 MATCH1=escape($MATCH1)
987 if ( /^Subject:.*$MATCH1/ )
988 {
989 ...
990 }
991 }
992 This example checks if the contents of the From: header can also be
994 found in the Subject: header. If the escape function were not used,
995 then any special characters in the From: header that are also used
996 in regular expressions, such as * or +, would introduce
997 unpredictable behavior, most likely a syntax error.
998 The reason why this list of special characters also includes
1000 characters not used in maildrop´s regular expressions is to allow
1001 maildrop´s variables to be used on the command line of a shell
1002 command executed by the xfilter command, backtick characters, or to
1003 or cc commands.
1004 Although using data from an external data source is dangerous, and
1006 it may result in inadvertent exploits, using the escape function
1007 should hopefully result in fewer surprises.
1008 gdbmopen, gdbmclose, gdbmfetch, gdbmstore - GDBM support in maildrop
1010 These functions provide support for GDBM database files. See
1011 maildropgdbm(5)[15] for more information.
1012 Note
1014 The system administrator can disable GDBM support in maildrop,
1015 so these commands may not be available to you.
1016 getaddr(string) - extract RFC 2822 addresses from a header.
1018 if ( /^From:\s*(.*)/ )
1019 {
1020 ADDR=getaddr($MATCH1)
1021 }
1022 This function is usually applied to a header that contains RFC
1024 2822[16] addresses. It extracts the actual addresses from the
1025 header, without any comments or extraneous punctuation. Each
1026 address is followed by a newline character. For example, if string
1027 contains:
1028 joe@domain.com (Joe Brown), "Alex Smith" <alex@domain.com>, tom@domain.com
1030 The result of the getaddr function is the following string:
1032 joe@domain.com<NL>alex@domain.com<NL>tom@domain.com<NL>
1034 Note
1036 Because getaddr() interprets RFC 2822[17] loosely, it is not
1037 necessary to strip off the "To:" or the "Cc:" header from the
1038 string, before feeding it to getaddr(). For example, the
1039 following snippet of code takes all addresses in the message,
1040 and concatenates them into a single string, separated by
1041 spaces:
1042 ADDRLIST=""
1044 foreach /^(To|Cc): .*/
1045 {
1046 foreach (getaddr $MATCH) =~ /.+/
1047 {
1048 ADDRLIST="$ADDRLIST $MATCH"
1049 }
1050 }
1051 Note
1053 In certain rare situations, RFC 2822[17] allows spaces to be
1054 included in E-mail addresses, so this example is just
1055 educational.
1056 hasaddr(string) - Search for an address.
1058 if ( hasaddr(string) )
1059 {
1060 ...
1061 }
1062 "string" is of the form user@domain. The hasaddr function returns 1
1064 if this address is included in any To:, Cc:,Resent-To:, or
1065 Resent-Cc:, header in the message, otherwise this function returns
1066 0.
1067 This is more than just a simple text search. Each header is parsed
1069 according to RFC822. Addresses found in the header are extracted,
1070 ignoring all comments and names. The remaining addresses are
1071 checked, and if "string" is one of them, hasaddr returns 1,
1072 otherwise it returns 0.
1073 The comparison is case-insensitive. This actually violates RFC822
1075 (and several others) a little bit, because the user part of the
1076 address may be (but is not required to be) case sensitive.
1077 length (string) - length of a string
1079 if (length(string) > 80)
1080 {
1081 ...
1082 }
1083 The length function returns the number of characters in string.
1085 lookup (expr, 'filename', 'options') - read file for patterns
1087 if (lookup(expr, file, "option"))
1088 {
1089 ...
1090 }
1091 expr is any expression. filename is a name of a file containing a
1093 list of patterns. Note that filename is relative to the current
1094 directory, which is the home directory of the user when maildrop
1095 runs in delivery mode, or embedded mode. maildrop then reads the
1096 file. Blank lines will be ignored, as well as any lines that begin
1097 with the # character (comments).
1098 Leading whitespace (but not trailing whitespace, take care) is
1100 removed, and the remaining contents of each line are interpreted as
1101 a pattern which is matched against expr. As soon as the match is
1102 found, lookup returns "1". If no match is found after reading the
1103 entire file, lookup returns "0". For example:
1104 if ( /^To:\s*(.*)/ && lookup( $MATCH1, "badto.dat" ))
1106 {
1107 exit
1108 }
1109 The file badto.dat contains the following two lines:
1111 friend@public
1113 ^[^@]*$
1114 If a message has a To: header that contains the text
1116 "friend@public", or does not contain at least one @ character, then
1117 the message will be silently dropped on the floor ( maildrop will
1118 terminate without delivering the message anywhere).
1119 options are the pattern matching options to use. The only supported
1121 option is "D" (the rest are meaningless, in this case).
1122 Note
1124 Be careful with discarding messages like that. Pattern matching
1125 can be tricky, and a slight miscalculation can cause mail to be
1126 unintentionally discarded. It is much desirable to first
1127 deliver message to a separate folder or mailbox, and once the
1128 filter is verified to work correctly, change it so the messages
1129 are discarded completely.
1130 substr(string,start [,count]) - return substring
1132 foo=substr($foo, 1, 10)
1133 The substr function takes start number of characters from string.
1135 If count is specified, at most count characters starting at
1136 position start are kept, any excess is trimmed.
1137 time - return current time
1139 foo=time
1140 The time function returns the current time, in seconds, since
1142 January 1, 1970. This function is useful when using GDBM files. See
1143 maildropex(7)[18] for an example of using the time function.
1144 tolower(string) - Convert string to lowercase.
1146 foo=tolower(string)
1147 This function returns the string with all uppercase characters
1149 replaced by lowercase characters.
1150 toupper(string) - Convert string to uppercase.
1152 foo=toupper(string)
1153 This function returns the string with all lowercase characters
1155 replaced by uppercase characters.
1156 Statements
1158 The filter file is read by maildrop ($HOME/.mailfilter or another
1159 file), and it contains filtering statements, one per line. The
1160 filtering language used by maildrop has a loosely - defined grammatical
1161 structure.
1162 Statements are listed one per line. Multiple statements may be listed
1164 on the same line by separating them with semicolons. To continue a long
1165 statement on the next line, terminate the line with a backslash
1166 character.
1167
1169 If getaddr() or hasaddr() functions are used on broken headers, the
1170 results are unpredictable.
1171 hasaddr() is completely case insensitive. This actually violates a few
1173 RFCs, because the userid portion of the address could be
1174 case-sensitive, but it´s not in too many cases, so there.
1175
1177 lockmail(1)[19], maildrop(1)[20], maildropgdbm(5)[15],
1178 maildirquota(8)[4], reformail(1)[21], egrep(1), sendmail(8).
1179
1181 1. Courier mail server
1182 http://www.courier-mta.org/
1183 2. dot-courier(5)
1185 [set $man.base.url.for.relative.links]/dot-courier.html
1186 3. value of the -M option
1188 [set $man.base.url.for.relative.links]/maildrop.html#moption
1189 4. maildirquota(8)
1191 [set $man.base.url.for.relative.links]/maildirquota.html
1192 5. xfilter
1194 [set $man.base.url.for.relative.links]/#xfilter
1195 6. PCRE
1197 http://www.pcre.org
1198 7. See the to statement
1200 [set $man.base.url.for.relative.links]/#to
1201 8. flock statement
1203 [set $man.base.url.for.relative.links]/#flock
1204 9. embedded mode
1206 [set $man.base.url.for.relative.links]/maildrop.html#embedded
1207 10. dotlock statement
1209 [set $man.base.url.for.relative.links]/#dotlock
1210 11. cc
1212 [set $man.base.url.for.relative.links]/#cc
1213 12. evaluates to a logical true
1215 [set $man.base.url.for.relative.links]/#if
1216 13. Patterns
1218 [set $man.base.url.for.relative.links]/#patterns
1219 14. matching pattern sections
1221 [set $man.base.url.for.relative.links]/#patmatch
1222 15. maildropgdbm(5)
1224 [set $man.base.url.for.relative.links]/maildropgdbm.html
1225 16. RFC 2822
1227 http://www.rfc-editor.org/rfc/rfc2822.txt
1228 17. RFC 2822
1230 http://www.rfc-editor.org/rfc/rfc822.txt
1231 18. maildropex(7)
1233 [set $man.base.url.for.relative.links]/maildropex.html
1234 19. lockmail(1)
1236 [set $man.base.url.for.relative.links]/lockmail.html
1237 20. maildrop(1)
1239 [set $man.base.url.for.relative.links]/maildrop.html
1240 21. reformail(1)
1242 [set $man.base.url.for.relative.links]/reformail.html
1243Double Precision, Inc. 02/19/2010 MAILDROPFILTER(7)