xref: /netbsd-src/external/ibm-public/postfix/dist/conf/header_checks (revision 7788a0781fe6ff2cce37368b4578a7ade0850cb1)
1# HEADER_CHECKS(5)                                              HEADER_CHECKS(5)
2#
3# NAME
4#        header_checks - Postfix built-in content inspection
5#
6# SYNOPSIS
7#        header_checks = pcre:/etc/postfix/header_checks
8#        mime_header_checks = pcre:/etc/postfix/mime_header_checks
9#        nested_header_checks = pcre:/etc/postfix/nested_header_checks
10#        body_checks = pcre:/etc/postfix/body_checks
11#
12#        milter_header_checks = pcre:/etc/postfix/milter_header_checks
13#
14#        smtp_header_checks = pcre:/etc/postfix/smtp_header_checks
15#        smtp_mime_header_checks = pcre:/etc/postfix/smtp_mime_header_checks
16#        smtp_nested_header_checks = pcre:/etc/postfix/smtp_nested_header_checks
17#        smtp_body_checks = pcre:/etc/postfix/smtp_body_checks
18#
19#        postmap -q "string" pcre:/etc/postfix/filename
20#        postmap -q - pcre:/etc/postfix/filename <inputfile
21#
22# DESCRIPTION
23#        This  document  describes access control on the content of
24#        message headers and message body lines; it is  implemented
25#        by  the  Postfix  cleanup(8) server before mail is queued.
26#        See access(5) for access control  on  remote  SMTP  client
27#        information.
28#
29#        Each  message  header  or  message  body  line is compared
30#        against a list of patterns.  When a  match  is  found  the
31#        corresponding action is executed, and the matching process
32#        is repeated for the next message header  or  message  body
33#        line.
34#
35#        Note: message headers are examined one logical header at a
36#        time, even when a message  header  spans  multiple  lines.
37#        Body lines are always examined one line at a time.
38#
39#        For  examples, see the EXAMPLES section at the end of this
40#        manual page.
41#
42#        Postfix header or body_checks are designed to stop a flood
43#        of  mail from worms or viruses; they do not decode attach-
44#        ments, and they do not unzip archives. See  the  documents
45#        referenced  below  in the README FILES section if you need
46#        more sophisticated content analysis.
47#
48# FILTERS WHILE RECEIVING MAIL
49#        Postfix implements the  following  four  built-in  content
50#        inspection classes while receiving mail:
51#
52#        header_checks (default: empty)
53#               These   are  applied  to  initial  message  headers
54#               (except for the headers  that  are  processed  with
55#               mime_header_checks).
56#
57#        mime_header_checks (default: $header_checks)
58#               These  are  applied to MIME related message headers
59#               only.
60#
61#               This feature is available in Postfix 2.0 and later.
62#
63#        nested_header_checks (default: $header_checks)
64#               These  are  applied  to message headers of attached
65#               email messages (except for  the  headers  that  are
66#               processed with mime_header_checks).
67#
68#               This feature is available in Postfix 2.0 and later.
69#
70#        body_checks
71#               These are applied to all other  content,  including
72#               multi-part message boundaries.
73#
74#               With Postfix versions before 2.0, all content after
75#               the initial message headers is treated as body con-
76#               tent.
77#
78# FILTERS AFTER RECEIVING MAIL
79#        Postfix  supports a subset of the built-in content inspec-
80#        tion classes after the message is received:
81#
82#        milter_header_checks (default: empty)
83#               These are applied to headers that  are  added  with
84#               Milter applications.
85#
86#               This feature is available in Postfix 2.7 and later.
87#
88# FILTERS WHILE DELIVERING MAIL
89#        Postfix supports all four content inspection classes while
90#        delivering mail via SMTP.
91#
92#        smtp_header_checks (default: empty)
93#
94#        smtp_mime_header_checks (default: empty)
95#
96#        smtp_nested_header_checks (default: empty)
97#
98#        smtp_body_checks (default: empty)
99#               These  features  are  available  in Postfix 2.5 and
100#               later.
101#
102# COMPATIBILITY
103#        With Postfix version 2.2 and earlier specify "postmap -fq"
104#        to query a table that contains case sensitive patterns. By
105#        default, regexp: and pcre: patterns are case  insensitive.
106#
107# TABLE FORMAT
108#        This  document  assumes  that header and body_checks rules
109#        are specified in the form of  Postfix  regular  expression
110#        lookup  tables.  Usually  the best performance is obtained
111#        with pcre (Perl Compatible Regular Expression) tables, but
112#        the  slower  regexp (POSIX regular expressions) support is
113#        more widely available.  Use the command "postconf  -m"  to
114#        find  out what lookup table types your Postfix system sup-
115#        ports.
116#
117#        The general format of Postfix regular expression tables is
118#        given  below.   For  a  discussion  of specific pattern or
119#        flags  syntax,  see  pcre_table(5)   or   regexp_table(5),
120#        respectively.
121#
122#        /pattern/flags action
123#               When  /pattern/  matches  the input string, execute
124#               the corresponding action. See below for a  list  of
125#               possible actions.
126#
127#        !/pattern/flags action
128#               When  /pattern/  does  not  match the input string,
129#               execute the corresponding action.
130#
131#        if /pattern/flags
132#
133#        endif  Match the input string against the patterns between
134#               if  and endif, if and only if the same input string
135#               also matches /pattern/. The if..endif can nest.
136#
137#               Note: do not prepend whitespace to patterns  inside
138#               if..endif.
139#
140#        if !/pattern/flags
141#
142#        endif  Match the input string against the patterns between
143#               if and endif, if and only if the same input  string
144#               does not match /pattern/. The if..endif can nest.
145#
146#        blank lines and comments
147#               Empty  lines and whitespace-only lines are ignored,
148#               as are lines whose first  non-whitespace  character
149#               is a `#'.
150#
151#        multi-line text
152#               A  pattern/action  line  starts with non-whitespace
153#               text. A line that starts with whitespace  continues
154#               a logical line.
155#
156# TABLE SEARCH ORDER
157#        For  each  line of message input, the patterns are applied
158#        in the order as specified in the table. When a pattern  is
159#        found  that  matches  the  input  line,  the corresponding
160#        action is  executed  and  then  the  next  input  line  is
161#        inspected.
162#
163# TEXT SUBSTITUTION
164#        Substitution  of  substrings  from  the matched expression
165#        into the action string is possible using the  conventional
166#        Perl  syntax  ($1,  $2,  etc.).   The macros in the result
167#        string may need to be written as  ${n}  or  $(n)  if  they
168#        aren't followed by whitespace.
169#
170#        Note:  since negated patterns (those preceded by !) return
171#        a result when the expression does not match, substitutions
172#        are not available for negated patterns.
173#
174# ACTIONS
175#        Action names are case insensitive. They are shown in upper
176#        case for consistency with other Postfix documentation.
177#
178#        DISCARD optional text...
179#               Claim successful delivery and silently discard  the
180#               message.   Log the optional text if specified, oth-
181#               erwise log a generic message.
182#
183#               Note:  this  action  disables  further  header   or
184#               body_checks  inspection  of the current message and
185#               affects all recipients.  To discard only one recip-
186#               ient without discarding the entire message, use the
187#               transport(5) table to direct mail to the discard(8)
188#               service.
189#
190#               This feature is available in Postfix 2.0 and later.
191#
192#               This feature is not supported with smtp header/body
193#               checks.
194#
195#        DUNNO  Pretend  that the input line did not match any pat-
196#               tern, and inspect the next input line. This  action
197#               can be used to shorten the table search.
198#
199#               For  backwards  compatibility reasons, Postfix also
200#               accepts OK but it is (and always has been)  treated
201#               as DUNNO.
202#
203#               This feature is available in Postfix 2.1 and later.
204#
205#        FILTER transport:destination
206#               After the message is queued, send the  entire  mes-
207#               sage through the specified external content filter.
208#               The transport name specifies the first field  of  a
209#               mail  delivery  agent  definition in master.cf; the
210#               syntax of the next-hop destination is described  in
211#               the  manual  page  of  the  corresponding  delivery
212#               agent.  More  information  about  external  content
213#               filters is in the Postfix FILTER_README file.
214#
215#               Note  1: do not use $number regular expression sub-
216#               stitutions for transport or destination unless  you
217#               know that the information has a trusted origin.
218#
219#               Note  2:  this  action  overrides  the main.cf con-
220#               tent_filter setting, and affects all recipients  of
221#               the  message.  In  the  case  that  multiple FILTER
222#               actions fire, only the last one is executed.
223#
224#               Note 3: the purpose of the  FILTER  command  is  to
225#               override  message routing.  To override the recipi-
226#               ent's transport but not the  next-hop  destination,
227#               specify  an  empty  filter destination (Postfix 2.7
228#               and later), or specify a transport:destination that
229#               delivers   through  a  different  Postfix  instance
230#               (Postfix 2.6 and earlier). Other options are  using
231#               the  recipient-dependent transport_maps or the sen-
232#               der-dependent   sender_dependent_default_transport-
233#               _maps features.
234#
235#               This feature is available in Postfix 2.0 and later.
236#
237#               This feature is not supported with smtp header/body
238#               checks.
239#
240#        HOLD optional text...
241#               Arrange  for  the  message to be placed on the hold
242#               queue, and inspect the next input line.   The  mes-
243#               sage  remains  on hold until someone either deletes
244#               it or releases it for delivery.  Log  the  optional
245#               text if specified, otherwise log a generic message.
246#
247#               Mail that is placed on hold can  be  examined  with
248#               the  postcat(1)  command,  and  can be destroyed or
249#               released with the postsuper(1) command.
250#
251#               Note: use "postsuper -r" to release mail  that  was
252#               kept  on  hold for a significant fraction of $maxi-
253#               mal_queue_lifetime  or  $bounce_queue_lifetime,  or
254#               longer.  Use "postsuper -H" only for mail that will
255#               not expire within a few delivery attempts.
256#
257#               Note: this action affects  all  recipients  of  the
258#               message.
259#
260#               This feature is available in Postfix 2.0 and later.
261#
262#               This feature is not supported with smtp header/body
263#               checks.
264#
265#        IGNORE Delete the current line from the input, and inspect
266#               the next input line.
267#
268#        INFO optional text...
269#               Log an "info:" record with the optional text... (or
270#               log  a  generic  text),  and inspect the next input
271#               line. This action is useful for routine logging  or
272#               for debugging.
273#
274#               This feature is available in Postfix 2.8 and later.
275#
276#        PREPEND text...
277#               Prepend one  line  with  the  specified  text,  and
278#               inspect the next input line.
279#
280#               Notes:
281#
282#               o      The  prepended  text is output on a separate
283#                      line,  immediately  before  the  input  that
284#                      triggered the PREPEND action.
285#
286#               o      The prepended text is not considered part of
287#                      the input  stream:  it  is  not  subject  to
288#                      header/body checks or address rewriting, and
289#                      it does not affect the way that Postfix adds
290#                      missing message headers.
291#
292#               o      When prepending text before a message header
293#                      line, the prepended text must begin  with  a
294#                      valid message header label.
295#
296#               o      This action cannot be used to prepend multi-
297#                      line text.
298#
299#               This feature is available in Postfix 2.1 and later.
300#
301#               This   feature   is   not   supported   with   mil-
302#               ter_header_checks.
303#
304#        REDIRECT user@domain
305#               Write a message redirection request  to  the  queue
306#               file,  and  inspect  the next input line. After the
307#               message is queued, it will be sent to the specified
308#               address instead of the intended recipient(s).
309#
310#               Note:  this action overrides the FILTER action, and
311#               affects all recipients of the message. If  multiple
312#               REDIRECT  actions  fire,  only the last one is exe-
313#               cuted.
314#
315#               This feature is available in Postfix 2.1 and later.
316#
317#               This feature is not supported with smtp header/body
318#               checks.
319#
320#        REPLACE text...
321#               Replace the current line with the  specified  text,
322#               and inspect the next input line.
323#
324#               This feature is available in Postfix 2.2 and later.
325#               The description below applies to Postfix 2.2.2  and
326#               later.
327#
328#               Notes:
329#
330#               o      When  replacing  a  message header line, the
331#                      replacement text must  begin  with  a  valid
332#                      header label.
333#
334#               o      The  replaced text remains part of the input
335#                      stream. Unlike the result from  the  PREPEND
336#                      action,  a  replaced  message  header may be
337#                      subject to address rewriting and may  affect
338#                      the  way  that  Postfix adds missing message
339#                      headers.
340#
341#        REJECT optional text...
342#               Reject the  entire  message.  Reply  with  optional
343#               text... when the optional text is specified, other-
344#               wise reply with a generic error message.
345#
346#               Note:  this  action  disables  further  header   or
347#               body_checks  inspection  of the current message and
348#               affects all recipients.
349#
350#               Postfix version 2.3 and later support enhanced sta-
351#               tus codes.  When no code is specified at the begin-
352#               ning of optional text..., Postfix inserts a default
353#               enhanced status code of "5.7.1".
354#
355#               This feature is not supported with smtp header/body
356#               checks.
357#
358#        WARN optional text...
359#               Log a "warning:" record with the  optional  text...
360#               (or log a generic text), and inspect the next input
361#               line. This action is useful for debugging  and  for
362#               testing  a  pattern  before  applying  more drastic
363#               actions.
364#
365# BUGS
366#        Empty lines never match, because some map types mis-behave
367#        when  given  a zero-length search string.  This limitation
368#        may be removed for regular expression tables in  a  future
369#        release.
370#
371#        Many  people  overlook  the main limitations of header and
372#        body_checks rules.
373#
374#        o      These rules operate on one logical  message  header
375#               or one body line at a time. A decision made for one
376#               line is not carried over to the next line.
377#
378#        o      If text in the message body is encoded  (RFC  2045)
379#               then the rules need to be specified for the encoded
380#               form.
381#
382#        o      Likewise, when message  headers  are  encoded  (RFC
383#               2047)  then  the rules need to be specified for the
384#               encoded form.
385#
386#        Message headers added by the cleanup(8) daemon itself  are
387#        excluded from inspection. Examples of such message headers
388#        are From:, To:, Message-ID:, Date:.
389#
390#        Message headers deleted by the cleanup(8) daemon  will  be
391#        examined before they are deleted. Examples are: Bcc:, Con-
392#        tent-Length:, Return-Path:.
393#
394# CONFIGURATION PARAMETERS
395#        body_checks
396#               Lookup tables with content filter rules for message
397#               body lines.  These filters see one physical line at
398#               a time, in chunks  of  at  most  $line_length_limit
399#               bytes.
400#
401#        body_checks_size_limit
402#               The  amount  of  content  per  message body segment
403#               (attachment) that is subjected to $body_checks fil-
404#               tering.
405#
406#        header_checks
407#
408#        mime_header_checks (default: $header_checks)
409#
410#        nested_header_checks (default: $header_checks)
411#               Lookup tables with content filter rules for message
412#               header lines: respectively, these  are  applied  to
413#               the  initial  message  headers  (not including MIME
414#               headers), to the MIME headers anywhere in the  mes-
415#               sage,  and  to the initial headers of attached mes-
416#               sages.
417#
418#               Note: these filters see one logical message  header
419#               at  a time, even when a message header spans multi-
420#               ple lines. Message headers  that  are  longer  than
421#               $header_size_limit characters are truncated.
422#
423#        disable_mime_input_processing
424#               While  receiving mail, give no special treatment to
425#               MIME related message headers; all  text  after  the
426#               initial message headers is considered to be part of
427#               the message body. This means that header_checks  is
428#               applied  to  all  the  initial message headers, and
429#               that body_checks is applied to the remainder of the
430#               message.
431#
432#               Note:  when  used  in this manner, body_checks will
433#               process a multi-line message header one line  at  a
434#               time.
435#
436# EXAMPLES
437#        Header  pattern  to  block  attachments with bad file name
438#        extensions.  For convenience, the PCRE /x flag  is  speci-
439#        fied,  so  that  there  is no need to collapse the pattern
440#        into  a  single  line  of  text.   The  purpose   of   the
441#        [[:xdigit:]] sub-expressions is to recognize Windows CLSID
442#        strings.
443#
444#        /etc/postfix/main.cf:
445#            header_checks = pcre:/etc/postfix/header_checks.pcre
446#
447#        /etc/postfix/header_checks.pcre:
448#            /^Content-(Disposition|Type).*name\s*=\s*"?(.*(\.|=2E)(
449#              ade|adp|asp|bas|bat|chm|cmd|com|cpl|crt|dll|exe|
450#              hlp|ht[at]|
451#              inf|ins|isp|jse?|lnk|md[betw]|ms[cipt]|nws|
452#              \{[[:xdigit:]]{8}(?:-[[:xdigit:]]{4}){3}-[[:xdigit:]]{12}\}|
453#              ops|pcd|pif|prf|reg|sc[frt]|sh[bsm]|swf|
454#              vb[esx]?|vxd|ws[cfh]))(\?=)?"?\s*(;|$)/x
455#                REJECT Attachment name "$2" may not end with ".$4"
456#
457#        Body pattern to stop a specific HTML browser vulnerability
458#        exploit.
459#
460#        /etc/postfix/main.cf:
461#            body_checks = regexp:/etc/postfix/body_checks
462#
463#        /etc/postfix/body_checks:
464#            /^<iframe src=(3D)?cid:.* height=(3D)?0 width=(3D)?0>$/
465#                REJECT IFRAME vulnerability exploit
466#
467# SEE ALSO
468#        cleanup(8), canonicalize and enqueue Postfix message
469#        pcre_table(5), format of PCRE lookup tables
470#        regexp_table(5), format of POSIX regular expression tables
471#        postconf(1), Postfix configuration utility
472#        postmap(1), Postfix lookup table management
473#        postsuper(1), Postfix janitor
474#        postcat(1), show Postfix queue file contents
475#        RFC 2045, base64 and quoted-printable encoding rules
476#        RFC 2047, message header encoding for non-ASCII text
477#
478# README FILES
479#        Use  "postconf  readme_directory" or "postconf html_direc-
480#        tory" to locate this information.
481#        DATABASE_README, Postfix lookup table overview
482#        CONTENT_INSPECTION_README, Postfix content inspection overview
483#        BUILTIN_FILTER_README, Postfix built-in content inspection
484#        BACKSCATTER_README, blocking returned forged mail
485#
486# LICENSE
487#        The Secure Mailer license must be  distributed  with  this
488#        software.
489#
490# AUTHOR(S)
491#        Wietse Venema
492#        IBM T.J. Watson Research
493#        P.O. Box 704
494#        Yorktown Heights, NY 10598, USA
495#
496#                                                               HEADER_CHECKS(5)
497