1MAILDROPFILTER(7)           Double Precision, Inc.           MAILDROPFILTER(7)
2
3
4

NAME

6       maildropfilter - maildrop's filtering language
7

SYNOPSIS

9       /etc/maildroprc, $HOME/.mailfilter, $HOME/.mailfilters/*, and
10       friends...
11

DESCRIPTION

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

BUGS

1319       If getaddr() or hasaddr() functions are used on broken headers, the
1320       results are unpredictable.
1321
1322       hasaddr() is completely case insensitive. This actually violates a few
1323       RFCs, because the userid portion of the address could be
1324       case-sensitive, but it's not in too many cases, so there.
1325

SEE ALSO

1327       lockmail(1)[20], maildrop(1)[21], maildropgdbm(5)[16],
1328       maildirquota(8)[4], reformail(1)[22], egrep(1), sendmail(8).
1329

AUTHOR

1331       Sam Varshavchik
1332           Author
1333

NOTES

1335        1. Courier mail server
1336           http://www.courier-mta.org/
1337
1338        2. dot-courier(5)
1339           http://www.courier-mta.org/maildrop/dot-courier.html
1340
1341        3. value of the -M option
1342           http://www.courier-mta.org/maildrop/maildrop.html#moption
1343
1344        4. maildirquota(8)
1345           http://www.courier-mta.org/maildrop/maildirquota.html
1346
1347        5. system
1348           http://www.courier-mta.org/maildrop/#system
1349
1350        6. xfilter
1351           http://www.courier-mta.org/maildrop/#xfilter
1352
1353        7. PCRE
1354           http://www.pcre.org
1355
1356        8. See the to statement
1357           http://www.courier-mta.org/maildrop/#to
1358
1359        9. flock statement
1360           http://www.courier-mta.org/maildrop/#flock
1361
1362       10. embedded mode
1363           http://www.courier-mta.org/maildrop/maildrop.html#embedded
1364
1365       11. dotlock statement
1366           http://www.courier-mta.org/maildrop/#dotlock
1367
1368       12. cc
1369           http://www.courier-mta.org/maildrop/#cc
1370
1371       13. evaluates to a logical true
1372           http://www.courier-mta.org/maildrop/#if
1373
1374       14. Patterns
1375           http://www.courier-mta.org/maildrop/#patterns
1376
1377       15. matching pattern sections
1378           http://www.courier-mta.org/maildrop/#patmatch
1379
1380       16. maildropgdbm(5)
1381           http://www.courier-mta.org/maildrop/maildropgdbm.html
1382
1383       17. RFC 2822
1384           http://www.rfc-editor.org/rfc/rfc2822.txt
1385
1386       18. RFC 2822
1387           http://www.rfc-editor.org/rfc/rfc822.txt
1388
1389       19. maildropex(7)
1390           http://www.courier-mta.org/maildrop/maildropex.html
1391
1392       20. lockmail(1)
1393           http://www.courier-mta.org/maildrop/lockmail.html
1394
1395       21. maildrop(1)
1396           http://www.courier-mta.org/maildrop/maildrop.html
1397
1398       22. reformail(1)
1399           http://www.courier-mta.org/maildrop/reformail.html
1400
1401
1402
1403Courier Mail Server               07/24/2017                 MAILDROPFILTER(7)
Impressum