Expand PMF_FN_* macros.

[netbsd-mini2440.git] / external / ibm-public / postfix / dist / proto / header_checks

#++
# NAME
#       header_checks 5
# SUMMARY
#       Postfix built-in content inspection
# SYNOPSIS
# .nf
#       \fBheader_checks = pcre:/etc/postfix/header_checks\fR
#       \fBmime_header_checks = pcre:/etc/postfix/mime_header_checks\fR
#       \fBnested_header_checks = pcre:/etc/postfix/nested_header_checks\fR
#       \fBbody_checks = pcre:/etc/postfix/body_checks\fR
# .sp
#       \fBpostmap -q "\fIstring\fB" pcre:/etc/postfix/\fIfilename\fR
#       \fBpostmap -q - pcre:/etc/postfix/\fIfilename\fR <\fIinputfile\fR
# .fi
# DESCRIPTION
#       This document describes access control on the content of
#       message headers and message body lines; it is implemented
#       by the Postfix \fBcleanup\fR(8) server before mail is queued.
#       See \fBaccess\fR(5) for access control on remote SMTP client
#       information.
#
#       Each message header or message body line is compared against
#       a list of patterns.
#       When a match is found the corresponding action is executed, and
#       the matching process is repeated for the next message header or
#       message body line.
#
#       For examples, see the EXAMPLES section at the end of this
#       manual page.
#
#       Postfix header or body_checks are designed to stop a flood of mail
#       from worms or viruses; they do not decode attachments, and they do
#       not unzip archives. See the documents referenced below in the README
#       FILES section if you need more sophisticated content analysis.
#
#       Postfix supports four built-in content inspection classes:
# .IP \fBheader_checks\fR
#       These are applied to initial message headers (except for
#       the headers that are processed with \fBmime_header_checks\fR).
# .IP "\fBmime_header_checks\fR (default: \fB$header_checks\fR)"
#       These are applied to MIME related message headers only.
# .sp
#       This feature is available in Postfix 2.0 and later.
# .IP "\fBnested_header_checks\fR (default: \fB$header_checks\fR)"
#       These are applied to message headers of attached email
#       messages (except for the headers that are processed with
#       \fBmime_header_checks\fR).
# .sp
#       This feature is available in Postfix 2.0 and later.
# .IP \fBbody_checks\fR
#       These are applied to all other content, including multi-part
#       message boundaries.
# .sp
#       With Postfix versions before 2.0, all content after the initial
#       message headers is treated as body content.
# .PP
#       Note: message headers are examined one logical header at a time,
#       even when a message header spans multiple lines. Body lines are
#       always examined one line at a time.
# COMPATIBILITY
# .ad
# .fi
#       With Postfix version 2.2 and earlier specify "\fBpostmap
#       -fq\fR" to query a table that contains case sensitive
#       patterns. By default, regexp: and pcre: patterns are case
#       insensitive.
# TABLE FORMAT
# .ad
# .fi
#       This document assumes that header and body_checks rules are specified
#       in the form of Postfix regular expression lookup tables. Usually the
#       best performance is obtained with \fBpcre\fR (Perl Compatible Regular
#       Expression) tables, but the slower \fBregexp\fR (POSIX regular
#       expressions) support is more widely available.
#       Use the command "\fBpostconf -m\fR" to find out what lookup table
#       types your Postfix system supports.
#
#       The general format of Postfix regular expression tables is
#       given below.
#       For a discussion of specific pattern or flags syntax,
#       see \fBpcre_table\fR(5) or \fBregexp_table\fR(5), respectively.
# .IP "\fB/\fIpattern\fB/\fIflags action\fR"
#       When /\fIpattern\fR/ matches the input string, execute
#       the corresponding \fIaction\fR. See below for a list
#       of possible actions.
# .IP "\fB!/\fIpattern\fB/\fIflags action\fR"
#       When /\fIpattern\fR/ does \fBnot\fR match the input string,
#       execute the corresponding \fIaction\fR.
# .IP "\fBif /\fIpattern\fB/\fIflags\fR"
# .IP "\fBendif\fR"
#       Match the input string against the patterns between \fBif\fR
#       and \fBendif\fR, if and only if the same input string also
#       matches /\fIpattern\fR/. The \fBif\fR..\fBendif\fR can nest.
# .sp
#       Note: do not prepend whitespace to patterns inside
#       \fBif\fR..\fBendif\fR.
# .IP "\fBif !/\fIpattern\fB/\fIflags\fR"
# .IP "\fBendif\fR"
#       Match the input string against the patterns between \fBif\fR
#       and \fBendif\fR, if and only if the same input string does
#       \fBnot\fR match /\fIpattern\fR/. The \fBif\fR..\fBendif\fR
#       can nest.
# .IP "blank lines and comments"
#       Empty lines and whitespace-only lines are ignored, as
#       are lines whose first non-whitespace character is a `#'.
# .IP "multi-line text"
#       A pattern/action line starts with non-whitespace text. A line that
#       starts with whitespace continues a logical line.
# TABLE SEARCH ORDER
# .ad
# .fi
#       For each line of message input, the patterns are applied in the
#       order as specified in the table. When a pattern is found that matches
#       the input line, the corresponding action is executed and then the
#       next input line is inspected.
# TEXT SUBSTITUTION
# .ad
# .fi
#       Substitution of substrings from the matched expression into the
#       \fIaction\fR
#       string is possible using the conventional Perl syntax
#       (\fB$1\fR, \fB$2\fR, etc.).
#       The macros in the result string may need to be written as \fB${n}\fR
#       or \fB$(n)\fR if they aren't followed by whitespace.
#
#       Note: since negated patterns (those preceded by \fB!\fR) return a
#       result when the expression does not match, substitutions are not
#       available for negated patterns.
# ACTIONS
# .ad
# .fi
#       Action names are case insensitive. They are shown in upper case
#       for consistency with other Postfix documentation.
# \" .IP "\fBDELAY \fItime\fR"
# \"    Place the message into the deferred queue, and delay the
# \"    initial delivery attempt by \fItime\fR. The time value may
# \"    be followed by a one-character suffix that specifies the
# \"    time unit: s (seconds), m (minutes), h (hours), d (days),
# \"    w (weeks).  The default time unit is s (seconds).
# \" .sp
# \"    Limitations:
# \" .RS
# \" .IP \(bu
# \"    This action affects all the recipients of the message.
# \" .IP \(bu
# \"    The delay value has no effect with remote file systems that
# \"    don't correctly emulate UNIX local file system semantics.
# \"    In that case, the delay will be half of $queue_run_delay
# \"    on average.
# \" .IP \(bu
# \"    Mail will still be delivered with "sendmail -q", "postfix
# \"    flush" or "postqueue -f".
# \" .IP \(bu
# \"    Delayed mail increases the amount of disk I/O during deferred
# \"    queue scans. When large amounts of mail are queued for
# \"    delayed delivery it may be preferable to use the HOLD feature
# \"    instead.
# \" .RE
# \" .IP
# \"    This feature is available in Postfix 2.3 and later.
# .IP "\fBDISCARD \fIoptional text...\fR"
#       Claim successful delivery and silently discard the message.
#       Log the optional text if specified, otherwise log a generic
#       message.
# .sp
#       Note: this action disables further header or body_checks inspection
#       of the current message and affects all recipients.
#       To discard only one recipient without discarding the entire message,
#       use the transport(5) table to direct mail to the discard(8) service.
# .sp
#       This feature is available in Postfix 2.0 and later.
# .IP \fBDUNNO\fR
#       Pretend that the input line did not match any pattern, and inspect the
#       next input line. This action can be used to shorten the table search.
# .sp
#       For backwards compatibility reasons, Postfix also accepts
#       \fBOK\fR but it is (and always has been) treated as \fBDUNNO\fR.
# .sp
#       This feature is available in Postfix 2.1 and later.
# .IP "\fBFILTER \fItransport:destination\fR"
#       Write a content filter request to the queue file, and
#       inspect the next input line.
#       After the complete message is received it will be sent through
#       the specified external content filter.  More information about
#       external content filters is in the Postfix FILTER_README file.
# .sp
#       Note: this action overrides the \fBcontent_filter\fR setting,
#       and affects all recipients of the message. In the case that multiple
#       \fBFILTER\fR actions fire, only the last one is executed.
# .sp
#       This feature is available in Postfix 2.0 and later.
# .IP "\fBHOLD \fIoptional text...\fR"
#       Arrange for the message to be placed on the \fBhold\fR queue,
#       and inspect the next input line.  The message remains on \fBhold\fR
#       until someone either deletes it or releases it for delivery.
#       Log the optional text if specified, otherwise log a generic
#       message.
#
#       Mail that is placed on hold can be examined with the
#       \fBpostcat\fR(1) command, and can be destroyed or released with
#       the \fBpostsuper\fR(1) command.
# .sp
#       Note: use "\fBpostsuper -r\fR" to release mail that was kept on
#       hold for a significant fraction of \fB$maximal_queue_lifetime\fR
#       or \fB$bounce_queue_lifetime\fR, or longer. Use "\fBpostsuper -H\fR"
#       only for mail that will not expire within a few delivery attempts.
# .sp
#       Note: this action affects all recipients of the message.
# .sp
#       This feature is available in Postfix 2.0 and later.
# .IP \fBIGNORE\fR
#       Delete the current line from the input, and inspect
#       the next input line.
# .IP "\fBPREPEND \fItext...\fR"
#       Prepend one line with the specified text, and inspect the next
#       input line.
# .sp
#       Notes: 
# .RS
# .IP \(bu
#       The prepended text is output on a separate line, immediately
#       before the input that triggered the \fBPREPEND\fR action.
# .IP \(bu
#       The prepended text is not considered part of the input
#       stream: it is not subject to header/body checks or address
#       rewriting, and it does not affect the way that Postfix adds
#       missing message headers.
# .IP \(bu
#       When prepending text before a message header line, the prepended
#       text must begin with a valid message header label.
# .IP \(bu
#       This action cannot be used to prepend multi-line text.
# .RE
# .IP
#       This feature is available in Postfix 2.1 and later.
# .IP "\fBREDIRECT \fIuser@domain\fR"
#       Write a message redirection request to the queue file, and
#       inspect the next input line. After the message is queued,
#       it will be sent to the specified address instead of the
#       intended recipient(s).
# .sp
#       Note: this action overrides the \fBFILTER\fR action, and affects
#       all recipients of the message. If multiple \fBREDIRECT\fR actions
#       fire, only the last one is executed.
# .sp
#       This feature is available in Postfix 2.1 and later.
# .IP "\fBREPLACE \fItext...\fR"
#       Replace the current line with the specified text, and inspect the next
#       input line.
# .sp
#       This feature is available in Postfix 2.2 and later. The
#       description below applies to Postfix 2.2.2 and later.
# .sp
#       Notes: 
# .RS
# .IP \(bu
#       When replacing a message header line, the replacement text
#       must begin with a valid header label.
# .IP \(bu
#       The replaced text remains part of the input stream. Unlike
#       the result from the \fBPREPEND\fR action, a replaced message
#       header may be subject to address rewriting and may affect
#       the way that Postfix adds missing message headers.
# .RE
# .IP "\fBREJECT \fIoptional text...\fR
#       Reject the entire message. Reply with \fIoptional text...\fR when
#       the optional text is specified, otherwise reply with a generic error
#       message.
# .sp
#       Note: this action disables further header or body_checks inspection
#       of the current message and affects all recipients.
# .sp
#       Postfix version 2.3 and later support enhanced status codes.
#       When no code is specified at the beginning of \fIoptional
#       text...\fR, Postfix inserts a default enhanced status code of
#       "5.7.1".
# .IP "\fBWARN \fIoptional text...\fR
#       Log a warning with the \fIoptional text...\fR (or log a
#       generic message), and inspect the next input line. This
#       action is useful for debugging and for testing a pattern
#       before applying more drastic actions.
# BUGS
#       Empty lines never match, because some map types mis-behave
#       when given a zero-length search string.  This limitation may
#       be removed for regular expression tables in a future release.
#
#       Many people overlook the main limitations of header and body_checks
#       rules.
# .IP \(bu
#       These rules operate on one logical message header or one body
#       line at a time. A decision made for one line is not carried over
#       to the next line.
# .IP \(bu
#       If text in the message body is encoded
#       (RFC 2045) then the rules need to be specified for the encoded
#       form.
# .IP \(bu
#       Likewise, when message headers are encoded (RFC
#       2047) then the rules need to be specified for the encoded
#       form.
# .PP
#       Message headers added by the \fBcleanup\fR(8) daemon itself
#       are excluded from inspection. Examples of such message headers
#       are \fBFrom:\fR, \fBTo:\fR, \fBMessage-ID:\fR, \fBDate:\fR.
#
#       Message headers deleted by the \fBcleanup\fR(8) daemon will
#       be examined before they are deleted. Examples are: \fBBcc:\fr,
#       \fBContent-Length:\fR, \fBReturn-Path:\fR.
# CONFIGURATION PARAMETERS
# .ad
# .fi
# .IP \fBbody_checks\fR
#       Lookup tables with content filter rules for message body lines.
#       These filters see one physical line at a time, in chunks of
#       at most \fB$line_length_limit\fR bytes.
# .IP \fBbody_checks_size_limit\fP
#       The amount of content per message body segment (attachment) that is
#       subjected to \fB$body_checks\fR filtering.
# .IP \fBheader_checks\fR
# .IP "\fBmime_header_checks\fR (default: \fB$header_checks\fR)"
# .IP "\fBnested_header_checks\fR (default: \fB$header_checks\fR)"
#       Lookup tables with content filter rules for message header lines:
#       respectively, these are applied to the initial message headers
#       (not including MIME headers), to the MIME headers anywhere in
#       the message, and to the initial headers of attached messages.
# .sp
#       Note: these filters see one logical message header at a time, even
#       when a message header spans multiple lines. Message headers that
#       are longer than \fB$header_size_limit\fR characters are truncated.
# .IP \fBdisable_mime_input_processing\fR
#       While receiving mail, give no special treatment to MIME related
#       message headers; all text after the initial message headers is
#       considered to be part of the message body. This means that
#       \fBheader_checks\fR is applied to all the initial message headers,
#       and that \fBbody_checks\fR is applied to the remainder of the
#       message.
# .sp
#       Note: when used in this manner, \fBbody_checks\fR will process
#       a multi-line message header one line at a time.
# EXAMPLES
# .ad
# .fi
#       Header pattern to block attachments with bad file name
#       extensions.  For convenience, the PCRE /x flag is specified,
#       so that there is no need to collapse the pattern into a
#       single line of text.  The purpose of the [[:xdigit:]]
#       sub-expressions is to recognize Windows CLSID strings.
#
# .na
# .nf
#       /etc/postfix/main.cf:
#           header_checks = pcre:/etc/postfix/header_checks.pcre
#
#       /etc/postfix/header_checks.pcre:
#           /^Content-(Disposition|Type).*name\es*=\es*"?(.*(\e.|=2E)(
#             ade|adp|asp|bas|bat|chm|cmd|com|cpl|crt|dll|exe|
#             hlp|ht[at]|
#             inf|ins|isp|jse?|lnk|md[betw]|ms[cipt]|nws|
#             \e{[[:xdigit:]]{8}(?:-[[:xdigit:]]{4}){3}-[[:xdigit:]]{12}\e}|
#             ops|pcd|pif|prf|reg|sc[frt]|sh[bsm]|swf|
#             vb[esx]?|vxd|ws[cfh]))(\e?=)?"?\es*(;|$)/x
#               REJECT Attachment name "$2" may not end with ".$4"
# .ad
# .fi
#
#       Body pattern to stop a specific HTML browser vulnerability exploit.
#
# .na
# .nf
#       /etc/postfix/main.cf:
#           body_checks = regexp:/etc/postfix/body_checks
#
#       /etc/postfix/body_checks:
#           /^<iframe src=(3D)?cid:.* height=(3D)?0 width=(3D)?0>$/
#               REJECT IFRAME vulnerability exploit
# SEE ALSO
#       cleanup(8), canonicalize and enqueue Postfix message
#       pcre_table(5), format of PCRE lookup tables
#       regexp_table(5), format of POSIX regular expression tables
#       postconf(1), Postfix configuration utility
#       postmap(1), Postfix lookup table management
#       postsuper(1), Postfix janitor
#       postcat(1), show Postfix queue file contents
#       RFC 2045, base64 and quoted-printable encoding rules
#       RFC 2047, message header encoding for non-ASCII text
# README FILES
# .ad
# .fi
#       Use "\fBpostconf readme_directory\fR" or
#       "\fBpostconf html_directory\fR" to locate this information.
# .na
# .nf
#       DATABASE_README, Postfix lookup table overview
#       CONTENT_INSPECTION_README, Postfix content inspection overview
#       BUILTIN_FILTER_README, Postfix built-in content inspection
#       BACKSCATTER_README, blocking returned forged mail
# LICENSE
# .ad
# .fi
#       The Secure Mailer license must be distributed with this software.
# AUTHOR(S)
#       Wietse Venema
#       IBM T.J. Watson Research
#       P.O. Box 704
#       Yorktown Heights, NY 10598, USA
#--