summaryrefslogtreecommitdiffstats
path: root/html/SMTPD_PROXY_README.html
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-10 19:59:03 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-10 19:59:03 +0000
commita848231ae0f346dc7cc000973fbeb65b0894ee92 (patch)
tree44b60b367c86723cc78383ef247885d72b388afe /html/SMTPD_PROXY_README.html
parentInitial commit. (diff)
downloadpostfix-a848231ae0f346dc7cc000973fbeb65b0894ee92.tar.xz
postfix-a848231ae0f346dc7cc000973fbeb65b0894ee92.zip
Adding upstream version 3.8.5.upstream/3.8.5
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'html/SMTPD_PROXY_README.html')
-rw-r--r--html/SMTPD_PROXY_README.html438
1 files changed, 438 insertions, 0 deletions
diff --git a/html/SMTPD_PROXY_README.html b/html/SMTPD_PROXY_README.html
new file mode 100644
index 0000000..ee7dfbd
--- /dev/null
+++ b/html/SMTPD_PROXY_README.html
@@ -0,0 +1,438 @@
+<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+
+<html>
+
+<head>
+
+<title>Postfix Before-Queue Content Filter </title>
+
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
+
+</head>
+
+<body>
+
+<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix Before-Queue Content Filter </h1>
+
+<hr>
+
+<h2>WARNING </h2>
+
+<p> The before-queue content filtering feature described in this
+document limits the amount of mail that a site can handle. See the
+"<a href="#pros_cons">Pros and Cons</a>" section below for details.
+</p>
+
+<h2>The Postfix before-queue content filter feature</h2>
+
+<p> 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 <a href="MILTER_README.html">MILTER_README</a>,
+except that the latter uses a dedicated protocol instead of SMTP.
+
+<p> The before-queue content filter is meant to be used as follows: </p>
+
+<blockquote>
+
+<table>
+
+<tr>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> Internet </td>
+
+ <td align="center" valign="middle" width="5%"> <tt> -&gt; </tt> </td>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> <a href="smtpd.8.html">Postfix SMTP server</a>
+ </td>
+
+ <td align="center" valign="middle" width="5%"> <tt> -&gt; </tt> </td>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> <b>Before</b> <b>queue</b> <b>filter</b> </td>
+
+ <td align="center" valign="middle" width="5%"> <tt> -&gt; </tt> </td>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> <a href="smtpd.8.html">Postfix SMTP server</a>
+ </td>
+
+ <td align="center" valign="middle" width="5%"> <tt> -&gt; </tt> </td>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> <a href="cleanup.8.html">Postfix cleanup
+ server</a> </td>
+
+ <td align="center" valign="middle" width="5%"> <tt> -&gt; </tt> </td>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> Postfix queue </td>
+
+ <td align="center" valign="middle" width="5%"> <tt> -&lt; </tt> </td>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> <a href="smtp.8.html">smtp</a><br> <a
+ href="local.8.html">local</a><br> <a
+ href="virtual.8.html">virtual</a> </td>
+
+</tr>
+
+</table>
+
+</blockquote>
+
+<p> The before-queue content filter is not to be confused with the
+approach described in the <a href="FILTER_README.html">FILTER_README</a> document, where mail is
+filtered AFTER it is stored in the Postfix mail queue. </p>
+
+<p> This document describes the following topics: </p>
+
+<ul>
+
+<li><a href="#principles">Principles of operation</a>
+
+<li><a href="#pros_cons">Pros and cons of before-queue content filtering</a>
+
+<li><a href="#config">Configuring the Postfix SMTP pass-through
+proxy feature</a>
+
+<li><a href="#parameters">Configuration parameters</a>
+
+<li><a href="#protocol">How Postfix talks to the before-queue content
+filter</a>
+
+</ul>
+
+<h2><a name="principles">Principles of operation</a></h2>
+
+<p> As shown in the diagram above, the before-queue filter sits
+between two Postfix SMTP server processes. </p>
+
+<ul>
+
+<li> <p> The before-filter Postfix SMTP server accepts connections from the
+Internet and does the usual relay access control, SASL authentication,
+TLS negotiation,
+RBL lookups, rejecting non-existent sender or recipient addresses,
+etc. </p>
+
+<li> <p> The before-queue filter receives unfiltered mail content from
+Postfix and does one of the following: </p>
+
+<ol>
+
+ <li> <p> Re-inject the mail back into Postfix via SMTP, perhaps
+ after changing its content and/or destination. </p>
+
+ <li> <p> Discard or quarantine the mail. </p>
+
+ <li> <p> 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. </p>
+
+</ol>
+
+<li> <p>The after-filter Postfix SMTP server receives mail from the
+content filter. From then on Postfix processes the mail as usual. </p>
+
+</ul>
+
+<p> The before-queue content filter described here works just like
+the after-queue content filter described in the <a href="FILTER_README.html">FILTER_README</a>
+document. In many cases you can use the same software, within the
+limitations as discussed in the "<a href="#pros_cons">Pros and
+Cons</a>" section below. </p>
+
+<h2><a name="pros_cons">Pros and cons of before-queue content
+filtering</a></h2>
+
+<ul>
+
+<li> <p> 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. </p>
+
+<li> <p> Con: The <a href="smtpd.8.html">smtpd(8)</a> service before the <a href="postconf.5.html#smtpd_proxy_filter">smtpd_proxy_filter</a>
+cannot support features that involve header or body access, or that
+involve queue file manipulation (i.e., anything that involves
+processing by the <a href="cleanup.8.html">cleanup(8)</a> service). </p>
+
+<ul>
+
+<li> <p> No support for HOLD actions in Postfix smtpd <a href="access.5.html">access(5)</a>
+restrictions. </p>
+
+<li> <p> No support for <a href="postconf.5.html#smtpd_milters">smtpd_milters</a> features that involve message
+header or body content. </p>
+
+<li> <p> No support for <a href="postconf.5.html#receive_override_options">receive_override_options</a>.
+
+</ul>
+
+<p> Instead, specify those features with the <a href="smtpd.8.html">smtpd(8)</a> service behind
+the <a href="postconf.5.html#smtpd_proxy_filter">smtpd_proxy_filter</a>. In some cases, it may be possible to combine
+a before-filter PREPEND action that emits a unique pattern (for
+example containing the MTA domain name), with an after-filter
+<a href="postconf.5.html#header_checks">header_checks</a> action that does what you want, and with an
+<a href="postconf.5.html#smtp_header_checks">smtp_header_checks</a> IGNORE action that deletes the prepended header
+from transit mail. </p>
+
+<li> <p> 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. </p>
+
+<li> <p> 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. </p>
+
+<ul>
+
+<li> <p> 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). </p>
+
+<li> <p> 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). </p>
+
+</ul>
+
+</ul>
+
+<h2><a name="config">Configuring the Postfix SMTP pass-through
+proxy feature</a></h2>
+
+<p> 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. </p>
+
+<p> 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:
+<a href="https://web.archive.org/web/20151022025756/http://bent.latency.net/smtpprox/">https://web.archive.org/web/20151022025756/http://bent.latency.net/smtpprox/</a>
+or <a href="https://github.com/jnorell/smtpprox/">https://github.com/jnorell/smtpprox/</a> </p>
+
+<blockquote>
+
+<table border="0">
+
+<tr>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> Internet </td>
+
+ <td align="center" valign="middle" width="5%"> <tt> -&gt; </tt> </td>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> <a href="smtpd.8.html">Postfix SMTP server on
+ port 25</a> </td>
+
+ <td align="center" valign="middle" width="5%"> <tt> -&gt; </tt> </td>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> filter on localhost port 10025 </td>
+
+ <td align="center" valign="middle" width="5%"> <tt> -&gt; </tt> </td>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> <a href="smtpd.8.html">Postfix SMTP server on
+ localhost port 10026</a> </td>
+
+ <td align="center" valign="middle" width="5%"> <tt> -&gt; </tt> </td>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> <a href="cleanup.8.html">Postfix cleanup
+ server</a> </td>
+
+ <td align="center" valign="middle" width="5%"> <tt> -&gt; </tt> </td>
+
+ <td bgcolor="#f0f0ff" align="center" valign="middle"
+ width="10%"> Postfix <a href="QSHAPE_README.html#incoming_queue">incoming queue</a> </td>
+
+</tr>
+
+</table>
+
+</blockquote>
+
+<p> This is configured by editing the <a href="master.5.html">master.cf</a> file: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="master.5.html">master.cf</a>:
+ # =============================================================
+ # service type private unpriv chroot wakeup maxproc command
+ # (yes) (yes) (yes) (never) (100)
+ # =============================================================
+ #
+ # Before-filter SMTP server. Receive mail from the network and
+ # pass it to the content filter on localhost port 10025.
+ #
+ smtp inet n - n - 20 smtpd
+ -o <a href="postconf.5.html#smtpd_proxy_filter">smtpd_proxy_filter</a>=127.0.0.1:10025
+ -o <a href="postconf.5.html#smtpd_client_connection_count_limit">smtpd_client_connection_count_limit</a>=10
+ # Postfix 2.7 and later performance feature.
+ # -o <a href="postconf.5.html#smtpd_proxy_options">smtpd_proxy_options</a>=speed_adjust
+ #
+ # After-filter SMTP server. Receive mail from the content filter
+ # on localhost port 10026.
+ #
+ 127.0.0.1:10026 inet n - n - - smtpd
+ -o <a href="postconf.5.html#smtpd_authorized_xforward_hosts">smtpd_authorized_xforward_hosts</a>=127.0.0.0/8
+ -o <a href="postconf.5.html#smtpd_client_restrictions">smtpd_client_restrictions</a>=
+ -o <a href="postconf.5.html#smtpd_helo_restrictions">smtpd_helo_restrictions</a>=
+ -o <a href="postconf.5.html#smtpd_sender_restrictions">smtpd_sender_restrictions</a>=
+ # Postfix 2.10 and later: specify empty <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>.
+ -o <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>=
+ -o <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a>=<a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>,reject
+ -o <a href="postconf.5.html#smtpd_data_restrictions">smtpd_data_restrictions</a>=
+ -o <a href="postconf.5.html#mynetworks">mynetworks</a>=127.0.0.0/8
+ -o <a href="postconf.5.html#receive_override_options">receive_override_options</a>=<a href="postconf.5.html#no_unknown_recipient_checks">no_unknown_recipient_checks</a>
+</pre>
+</blockquote>
+
+<p> Note: do not specify spaces around the "=" or "," characters. </p>
+
+<p> The before-filter SMTP server entry is a modified version of the
+default Postfix SMTP server entry that is normally configured at
+the top of the <a href="master.5.html">master.cf</a> file: </p>
+
+<ul>
+
+ <li> <p> The number of SMTP sessions is reduced from the default
+ 100 to only 20. This prevents a burst of mail from running your
+ system into the ground with too many content filter processes. </p>
+
+ <li> <p> The "-o <a href="postconf.5.html#smtpd_client_connection_count_limit">smtpd_client_connection_count_limit</a>=10" prevents
+ one SMTP client from using up all 20 SMTP server processes.
+ This limit is not necessary if you receive all mail from a
+ trusted <a href="postconf.5.html#relayhost">relay host</a>. </p>
+
+ <p> Note: this setting is available in Postfix version 2.2 and
+ later. Earlier Postfix versions will ignore it. </p>
+
+ <li> <p> The "-o <a href="postconf.5.html#smtpd_proxy_filter">smtpd_proxy_filter</a>=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.
+
+ <li> <p> The "-o <a href="postconf.5.html#smtpd_proxy_options">smtpd_proxy_options</a>=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. </p>
+
+ <p> NOTE 1: When this option is turned on, a content filter must
+ not <i>selectively</i> reject recipients of a multi-recipient
+ message. Rejecting all recipients is OK, as is accepting all
+ recipients. </p>
+
+ <p> NOTE 2: This feature increases the minimum amount of free
+ queue space by $<a href="postconf.5.html#message_size_limit">message_size_limit</a>. The extra space is needed
+ to save the message to a temporary file. </p>
+
+ <li> <p> Postfix &ge; 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:<i>pathname</i>".
+ A relative pathname is interpreted relative to the Postfix queue
+ directory. </p>
+
+</ul>
+
+<p> The after-filter SMTP server is a new <a href="master.5.html">master.cf</a> entry: </p>
+
+<ul>
+
+ <li> <p> The "127.0.0.1:10026" makes the after-filter SMTP
+ server listen
+ on the localhost address only, without exposing it to the
+ network. NEVER expose the after-filter SMTP server to the
+ Internet :-) </p>
+
+ <li> <p> The "-o <a href="postconf.5.html#smtpd_authorized_xforward_hosts">smtpd_authorized_xforward_hosts</a>=127.0.0.0/8"
+ allows the after-filter SMTP server to receive remote SMTP
+ client information from the before-filter SMTP server, so that
+ the after-filter Postfix daemons log the remote SMTP client
+ information instead of logging localhost[127.0.0.1]. </p>
+
+ <li> <p> The other after-filter SMTP server settings avoid
+ duplication of work that is already done in the "before filter"
+ SMTP server. </p>
+
+</ul>
+
+<p> 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 the <a href="#parameters">"Configuration
+parameters"</a> section below) but doing so is pointless because you
+can't control when the remote SMTP client times out. </p>
+
+<h2><a name="parameters">Configuration parameters</a></h2>
+
+<p> Parameters that control proxying: </p>
+
+<ul>
+
+<li> <p> <a href="postconf.5.html#smtpd_proxy_filter">smtpd_proxy_filter</a> (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. </p>
+
+<li> <p> <a href="postconf.5.html#smtpd_proxy_timeout">smtpd_proxy_timeout</a> (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. </p>
+
+<li> <p> <a href="postconf.5.html#smtpd_proxy_ehlo">smtpd_proxy_ehlo</a> (default: $<a href="postconf.5.html#myhostname">myhostname</a>): The hostname to
+use when sending an EHLO command to the before-queue content filter.
+</p>
+
+</ul>
+
+<h2><a name="protocol">How Postfix talks to the before-queue content
+filter</a></h2>
+
+<p> 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. </p>
+
+<p> 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
+<a href="postconf.5.html#smtpd_discard_ehlo_keywords">smtpd_discard_ehlo_keywords</a> parameter. </p>
+
+<p> 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. </p>
+
+</body>
+
+</html>