Postfix Before-Queue Content Filter

WARNING

The before-queue content filtering feature described in this
document limits the amount of mail that a site can handle. See the
"Pros and Cons" section below for details.

The Postfix before-queue content filter feature

As of version 2.1, the Postfix SMTP server can forward all
incoming mail to a content filtering proxy server that inspects all
mail BEFORE it is stored in the Postfix mail queue. It is roughly
equivalent in capabilities to the approach described in MILTER_README,
except that the latter uses a dedicated protocol instead of SMTP.

The before-queue filter receives unfiltered mail content from
Postfix and does one of the following:

Re-inject the mail back into Postfix via SMTP, perhaps
after changing its content and/or destination.

Discard or quarantine the mail.

Reject the mail by sending a suitable SMTP status code
back to Postfix. Postfix passes the status back to the remote
SMTP client. This way, Postfix does not have to send a bounce
message.

The after-filter Postfix SMTP server receives mail from the
content filter. From then on Postfix processes the mail as usual.

The before-queue content filter described here works just like
the after-queue content filter described in the FILTER_README
document. In many cases you can use the same software, within the
limitations as discussed in the "Pros and
Cons" section below.

Pro: Postfix can reject mail before the incoming SMTP mail
transfer completes, so that Postfix does not have to send rejected
mail back to the sender (which is usually forged anyway). Mail
that is not accepted remains the responsibility of the remote SMTP
client.

Con: The remote SMTP client expects an SMTP reply within
a deadline. As the system load increases, fewer and fewer CPU
cycles remain available to answer within the deadline, and eventually
you either have to stop accepting mail or you have to stop filtering
mail. It is for this reason that the before-queue content filter
limits the amount of mail that a site can handle.

Con: Content filtering software can use lots of memory
resources. You have to reduce the number of simultaneous content
filter processes so that a burst of mail will not drive your system
into the ground.

With Postfix versions 2.7 and later, SMTP clients will
experience an increase in the delay between the time the client
sends "end-of-message" and the time the Postfix SMTP server replies
(here, the number of before-filter SMTP server processes can be
larger than the number of filter processes).

With Postfix versions before 2.7, SMTP clients will
experience an increase in the delay before they can receive service
(here, the number of before-filter SMTP server processes is always
equal to the number of filter processes).

In the following example, the before-filter Postfix SMTP server
gives mail to a content filter that listens on localhost port 10025.
The after-filter Postfix SMTP server receives mail from the content
filter via localhost port 10026. From then on mail is processed as
usual.

The content filter itself is not described here. You can use
any filter that is SMTP enabled. For non-SMTP capable content
filtering software, Bennett Todd's SMTP proxy implements a nice
Perl-based framework. See: http://bent.latency.net/smtpprox/ or
https://github.com/jnorell/smtpprox.

Note: this setting is available in Postfix version 2.2 and
later. Earlier Postfix versions will ignore it.

The "-o smtpd_proxy_filter=127.0.0.1:10025" tells the
before-filter SMTP server that it should give incoming mail to
the content filter that listens on localhost TCP port 10025.

The "-o smtpd_proxy_options=speed_adjust" tells the
before-filter SMTP server that it should receive an entire email
message before it connects to a content filter. This reduces
the number of simultaneous filter processes.

NOTE 1: When this option is turned on, a content filter must
not selectively reject recipients of a multi-recipient
message. Rejecting all recipients is OK, as is accepting all
recipients.

NOTE 2: This feature increases the minimum amount of free
queue space by $message_size_limit. The extra space is needed
to save the message to a temporary file.

Postfix ≥ 2.3 supports both TCP and UNIX-domain filters.
The above filter could be specified as "inet:127.0.0.1:10025".
To specify a UNIX-domain filter, specify "unix:pathname".
A relative pathname is interpreted relative to the Postfix queue
directory.

The other after-filter SMTP server settings avoid
duplication of work that is already done in the "before filter"
SMTP server.

By default, the filter has 100 seconds to do its work. If it
takes longer then Postfix gives up and reports an error to the
remote SMTP client. You can increase this time limit (see configuration
parameter section below) but doing so is pointless because you
can't control when the remote SMTP client times out.

smtpd_proxy_filter (syntax: host:port): The host and TCP
port of the before-queue content filter. When no host or host:
is specified here, localhost is assumed.

smtpd_proxy_timeout (default: 100s): Timeout for connecting
to the before-queue content filter and for sending and receiving
commands and data. All proxy errors are logged to the maillog
file. For privacy reasons, all the remote SMTP client sees is "451
Error: queue file write error". It would not be right to disclose
internal details to strangers.

The before-filter Postfix SMTP server connects to the content
filter, delivers one message, and disconnects. While sending mail
into the content filter, Postfix speaks ESMTP but uses no command
pipelining. Postfix generates its own EHLO, XFORWARD (for logging
the remote client IP address instead of localhost[127.0.0.1]), DATA
and QUIT commands, and forwards unmodified copies of all the MAIL
FROM and RCPT TO commands that the before-filter Postfix SMTP server
didn't reject itself.
Postfix sends no other SMTP commands.

The content filter should accept the same MAIL FROM and RCPT
TO command syntax as the before-filter Postfix SMTP server, and
should forward the commands without modification to the after-filter
SMTP server. If the content filter or after-filter SMTP server
does not support all the ESMTP features that the before-filter
Postfix SMTP server supports, then the missing features must be
turned off in the before-filter Postfix SMTP server with the
smtpd_discard_ehlo_keywords parameter.

When the filter rejects content, it should send a negative SMTP
response back to the before-filter Postfix SMTP server, and it
should abort the connection with the after-filter Postfix SMTP
server without completing the SMTP conversation with the after-filter
Postfix SMTP server.