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