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

BUGS

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

SEE ALSO

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

AUTHOR

1333       Sam Varshavchik
1334           Author
1335

NOTES

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