xref: /src/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
#--