SMTPD_PROXY_README.html revision 1.1
1 1.1 tron <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 1.1 tron "http://www.w3.org/TR/html4/loose.dtd"> 3 1.1 tron 4 1.1 tron <html> 5 1.1 tron 6 1.1 tron <head> 7 1.1 tron 8 1.1 tron <title>Postfix Before-Queue Content Filter </title> 9 1.1 tron 10 1.1 tron <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 11 1.1 tron 12 1.1 tron </head> 13 1.1 tron 14 1.1 tron <body> 15 1.1 tron 16 1.1 tron <h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix Before-Queue Content Filter </h1> 17 1.1 tron 18 1.1 tron <hr> 19 1.1 tron 20 1.1 tron <h2>WARNING </h2> 21 1.1 tron 22 1.1 tron <p> The before-queue content filtering feature described in 23 1.1 tron this document is suitable only for low-traffic sites. See the "<a 24 1.1 tron href="#pros_cons">Pros and Cons</a>" section below for details. 25 1.1 tron </p> 26 1.1 tron 27 1.1 tron <h2>The Postfix before-queue content filter feature</h2> 28 1.1 tron 29 1.1 tron <p> As of version 2.1, the Postfix SMTP server can forward all 30 1.1 tron incoming mail to a content filtering proxy server that inspects all 31 1.1 tron mail BEFORE it is stored in the Postfix mail queue. It is roughly 32 1.1 tron equivalent in capabilities to the approach described in MILTER_README, 33 1.1 tron except that the latter uses a dedicated protocol instead of SMTP. 34 1.1 tron 35 1.1 tron <p> The before-queue content filter is meant to be used as follows: </p> 36 1.1 tron 37 1.1 tron <blockquote> 38 1.1 tron 39 1.1 tron <table> 40 1.1 tron 41 1.1 tron <tr> 42 1.1 tron 43 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 44 1.1 tron width="10%"> Internet </td> 45 1.1 tron 46 1.1 tron <td align="center" valign="middle" width="5%"> <tt> -> </tt> </td> 47 1.1 tron 48 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 49 1.1 tron width="10%"> <a href="smtpd.8.html">Postfix SMTP server</a> 50 1.1 tron </td> 51 1.1 tron 52 1.1 tron <td align="center" valign="middle" width="5%"> <tt> -> </tt> </td> 53 1.1 tron 54 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 55 1.1 tron width="10%"> <b>Before</b> <b>queue</b> <b>filter</b> </td> 56 1.1 tron 57 1.1 tron <td align="center" valign="middle" width="5%"> <tt> -> </tt> </td> 58 1.1 tron 59 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 60 1.1 tron width="10%"> <a href="smtpd.8.html">Postfix SMTP server</a> 61 1.1 tron </td> 62 1.1 tron 63 1.1 tron <td align="center" valign="middle" width="5%"> <tt> -> </tt> </td> 64 1.1 tron 65 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 66 1.1 tron width="10%"> <a href="cleanup.8.html">Postfix cleanup 67 1.1 tron server</a> </td> 68 1.1 tron 69 1.1 tron <td align="center" valign="middle" width="5%"> <tt> -> </tt> </td> 70 1.1 tron 71 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 72 1.1 tron width="10%"> Postfix queue </td> 73 1.1 tron 74 1.1 tron <td align="center" valign="middle" width="5%"> <tt> -< </tt> </td> 75 1.1 tron 76 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 77 1.1 tron width="10%"> <a href="smtp.8.html">smtp</a><br> <a 78 1.1 tron href="local.8.html">local</a><br> <a 79 1.1 tron href="virtual.8.html">virtual</a> </td> 80 1.1 tron 81 1.1 tron </tr> 82 1.1 tron 83 1.1 tron </table> 84 1.1 tron 85 1.1 tron </blockquote> 86 1.1 tron 87 1.1 tron <p> The before-queue content filter is not to be confused with the 88 1.1 tron approach described in the FILTER_README document, where mail is 89 1.1 tron filtered AFTER it is stored in the Postfix mail queue. </p> 90 1.1 tron 91 1.1 tron <p> This document describes the following topics: </p> 92 1.1 tron 93 1.1 tron <ul> 94 1.1 tron 95 1.1 tron <li><a href="#principles">Principles of operation</a> 96 1.1 tron 97 1.1 tron <li><a href="#pros_cons">Pros and cons of before-queue content filtering</a> 98 1.1 tron 99 1.1 tron <li><a href="#config">Configuring the Postfix SMTP pass-through 100 1.1 tron proxy feature</a> 101 1.1 tron 102 1.1 tron <li><a href="#parameters">Configuration parameters</a> 103 1.1 tron 104 1.1 tron <li><a href="#protocol">How Postfix talks to the before-queue content 105 1.1 tron filter</a> 106 1.1 tron 107 1.1 tron </ul> 108 1.1 tron 109 1.1 tron <h2><a name="principles">Principles of operation</a></h2> 110 1.1 tron 111 1.1 tron <p> The before-filter Postfix SMTP server accepts connections from the 112 1.1 tron Internet and does the usual relay access control, SASL authentication, 113 1.1 tron TLS negotiation, 114 1.1 tron RBL lookups, rejecting non-existent sender or recipient addresses, 115 1.1 tron etc. The before-queue filter receives unfiltered mail content from 116 1.1 tron Postfix and does one of the following: </p> 117 1.1 tron 118 1.1 tron <ol> 119 1.1 tron 120 1.1 tron <li> <p> Re-inject the mail back into Postfix via SMTP, perhaps 121 1.1 tron after changing its content and/or destination. </p> 122 1.1 tron 123 1.1 tron <li> <p> Discard or quarantine the mail. </p> 124 1.1 tron 125 1.1 tron <li> <p> Reject the mail by sending a suitable SMTP status code 126 1.1 tron back to Postfix. Postfix passes the status back to the remote 127 1.1 tron SMTP client. This way, Postfix does not have to send a bounce 128 1.1 tron message. </p> 129 1.1 tron 130 1.1 tron </ol> 131 1.1 tron 132 1.1 tron <p>The after-filter Postfix SMTP server receives mail from the 133 1.1 tron content filter. From then on Postfix processes the mail as usual. </p> 134 1.1 tron 135 1.1 tron <p> The before-queue content filter described here works just like 136 1.1 tron the after-queue content filter described in the FILTER_README 137 1.1 tron document. In many cases you can use the same software, within the 138 1.1 tron limitations as discussed in the "<a href="#pros_cons">Pros and 139 1.1 tron Cons</a>" section below. </p> 140 1.1 tron 141 1.1 tron <h2><a name="pros_cons">Pros and cons of before-queue content 142 1.1 tron filtering</a></h2> 143 1.1 tron 144 1.1 tron <ul> 145 1.1 tron 146 1.1 tron <li> <p> Pro: Postfix can reject mail before the incoming SMTP mail 147 1.1 tron transfer completes, so that Postfix does not have to send rejected 148 1.1 tron mail back to the sender (which is usually forged anyway). Mail 149 1.1 tron that is not accepted remains the responsibility of the remote SMTP 150 1.1 tron client. </p> 151 1.1 tron 152 1.1 tron <li> <p> Con: The remote SMTP client expects an SMTP reply within 153 1.1 tron a deadline. As the system load increases, fewer and fewer CPU 154 1.1 tron cycles remain available to answer within the deadline, and eventually 155 1.1 tron you either have to stop accepting mail or you have to stop filtering 156 1.1 tron mail. It is for this reason that the before-queue content filter 157 1.1 tron can be used only on low-traffic sites. </p> 158 1.1 tron 159 1.1 tron <li> <p> Con: Content filtering software can use lots of memory 160 1.1 tron resources. In order to not run out of memory you have to reduce 161 1.1 tron the number of before-filter SMTP server processes so that a burst 162 1.1 tron of mail will not drive your system into the ground with too many 163 1.1 tron content filter processes. This, in turn, means that SMTP clients 164 1.1 tron have to wait for a long time before they receive service. </p> 165 1.1 tron 166 1.1 tron </ul> 167 1.1 tron 168 1.1 tron <h2><a name="config">Configuring the Postfix SMTP pass-through 169 1.1 tron proxy feature</a></h2> 170 1.1 tron 171 1.1 tron <p> In the following example, the before-filter Postfix SMTP server 172 1.1 tron gives mail to a content filter that listens on localhost port 10025. 173 1.1 tron The after-filter Postfix SMTP server receives mail from the content 174 1.1 tron filter via localhost port 10026. From then on mail is processed as 175 1.1 tron usual. </p> 176 1.1 tron 177 1.1 tron <p> The content filter itself is not described here. You can use 178 1.1 tron any filter that is SMTP enabled. For non-SMTP capable content 179 1.1 tron filtering software, Bennett Todd's SMTP proxy implements a nice 180 1.1 tron PERL/SMTP content filtering framework. See: 181 1.1 tron http://bent.latency.net/smtpprox/. </p> 182 1.1 tron 183 1.1 tron <blockquote> 184 1.1 tron 185 1.1 tron <table border="0"> 186 1.1 tron 187 1.1 tron <tr> 188 1.1 tron 189 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 190 1.1 tron width="10%"> Internet </td> 191 1.1 tron 192 1.1 tron <td align="center" valign="middle" width="5%"> <tt> -> </tt> </td> 193 1.1 tron 194 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 195 1.1 tron width="10%"> <a href="smtpd.8.html">Postfix SMTP server on 196 1.1 tron port 25</a> </td> 197 1.1 tron 198 1.1 tron <td align="center" valign="middle" width="5%"> <tt> -> </tt> </td> 199 1.1 tron 200 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 201 1.1 tron width="10%"> filter on localhost port 10025 </td> 202 1.1 tron 203 1.1 tron <td align="center" valign="middle" width="5%"> <tt> -> </tt> </td> 204 1.1 tron 205 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 206 1.1 tron width="10%"> <a href="smtpd.8.html">Postfix SMTP server on 207 1.1 tron localhost port 10026</a> </td> 208 1.1 tron 209 1.1 tron <td align="center" valign="middle" width="5%"> <tt> -> </tt> </td> 210 1.1 tron 211 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 212 1.1 tron width="10%"> <a href="cleanup.8.html">Postfix cleanup 213 1.1 tron server</a> </td> 214 1.1 tron 215 1.1 tron <td align="center" valign="middle" width="5%"> <tt> -> </tt> </td> 216 1.1 tron 217 1.1 tron <td bgcolor="#f0f0ff" align="center" valign="middle" 218 1.1 tron width="10%"> Postfix incoming queue </td> 219 1.1 tron 220 1.1 tron </tr> 221 1.1 tron 222 1.1 tron </table> 223 1.1 tron 224 1.1 tron </blockquote> 225 1.1 tron 226 1.1 tron <p> This is configured by editing the master.cf file: </p> 227 1.1 tron 228 1.1 tron <blockquote> 229 1.1 tron <pre> 230 1.1 tron /etc/postfix/master.cf: 231 1.1 tron # ============================================================= 232 1.1 tron # service type private unpriv chroot wakeup maxproc command 233 1.1 tron # (yes) (yes) (yes) (never) (100) 234 1.1 tron # ============================================================= 235 1.1 tron # 236 1.1 tron # Before-filter SMTP server. Receive mail from the network and 237 1.1 tron # pass it to the content filter on localhost port 10025. 238 1.1 tron # 239 1.1 tron smtp inet n - n - 20 smtpd 240 1.1 tron -o smtpd_proxy_filter=127.0.0.1:10025 241 1.1 tron -o smtpd_client_connection_count_limit=10 242 1.1 tron # 243 1.1 tron # After-filter SMTP server. Receive mail from the content filter 244 1.1 tron # on localhost port 10026. 245 1.1 tron # 246 1.1 tron 127.0.0.1:10026 inet n - n - - smtpd 247 1.1 tron -o smtpd_authorized_xforward_hosts=127.0.0.0/8 248 1.1 tron -o smtpd_client_restrictions= 249 1.1 tron -o smtpd_helo_restrictions= 250 1.1 tron -o smtpd_sender_restrictions= 251 1.1 tron -o smtpd_recipient_restrictions=permit_mynetworks,reject 252 1.1 tron -o smtpd_data_restrictions= 253 1.1 tron -o mynetworks=127.0.0.0/8 254 1.1 tron -o receive_override_options=no_unknown_recipient_checks 255 1.1 tron </pre> 256 1.1 tron </blockquote> 257 1.1 tron 258 1.1 tron <p> Note: do not specify spaces around the "=" or "," characters. </p> 259 1.1 tron 260 1.1 tron <p> The before-filter SMTP server entry is a modified version of the 261 1.1 tron default Postfix SMTP server entry that is normally configured at 262 1.1 tron the top of the master.cf file: </p> 263 1.1 tron 264 1.1 tron <ul> 265 1.1 tron 266 1.1 tron <li> <p> The number of SMTP sessions is reduced from the default 267 1.1 tron 100 to only 20. This prevents a burst of mail from running your 268 1.1 tron system into the ground with too many content filter processes. </p> 269 1.1 tron 270 1.1 tron <li> <p> The "-o smtpd_client_connection_count_limit=10" prevents 271 1.1 tron one SMTP client from using up all 20 SMTP server processes. 272 1.1 tron This limit is not necessary if you receive all mail from a 273 1.1 tron trusted relay host. </p> 274 1.1 tron 275 1.1 tron <p> Note: this setting is available in Postfix version 2.2 and 276 1.1 tron later. Earlier Postfix versions will ignore it. </p> 277 1.1 tron 278 1.1 tron <li> <p> The "-o smtpd_proxy_filter=127.0.0.1:10025" tells the 279 1.1 tron before filter SMTP server that it should give incoming mail to 280 1.1 tron the content filter that listens on localhost TCP port 10025. 281 1.1 tron 282 1.1 tron <li> <p> Postfix 2.3 supports both TCP and UNIX-domain filters. 283 1.1 tron The above filter could be specified as "inet:127.0.0.1:10025". 284 1.1 tron To specify a UNIX-domain filter, specify "unix:<i>pathname</i>". 285 1.1 tron A relative pathname is interpreted relative to the Postfix queue 286 1.1 tron directory. </p> 287 1.1 tron 288 1.1 tron </ul> 289 1.1 tron 290 1.1 tron <p> The after-filter SMTP server is a new master.cf entry: </p> 291 1.1 tron 292 1.1 tron <ul> 293 1.1 tron 294 1.1 tron <li> <p> The "127.0.0.1:10026" makes the after-filter SMTP 295 1.1 tron server listen 296 1.1 tron on the localhost address only, without exposing it to the 297 1.1 tron network. NEVER expose the after-filter SMTP server to the 298 1.1 tron Internet :-) </p> 299 1.1 tron 300 1.1 tron <li> <p> The "-o smtpd_authorized_xforward_hosts=127.0.0.0/8" 301 1.1 tron allows the after-filter SMTP server to receive remote SMTP 302 1.1 tron client information from the before filter SMTP server, so that 303 1.1 tron the after-filter Postfix daemons log the remote SMTP client 304 1.1 tron information instead of logging localhost[127.0.0.1]. </p> 305 1.1 tron 306 1.1 tron <li> <p> The other after-filter SMTP server settings avoid 307 1.1 tron duplication of work that is already done in the "before filter" 308 1.1 tron SMTP server. </p> 309 1.1 tron 310 1.1 tron </ul> 311 1.1 tron 312 1.1 tron <p> By default, the filter has 100 seconds to do its work. If it 313 1.1 tron takes longer then Postfix gives up and reports an error to the 314 1.1 tron remote SMTP client. You can increase this time limit (see configuration 315 1.1 tron parameter section below) but doing so is pointless because you 316 1.1 tron can't control when the remote SMTP client times out. </p> 317 1.1 tron 318 1.1 tron <h2><a name="parameters">Configuration parameters</a></h2> 319 1.1 tron 320 1.1 tron <p> Parameters that control proxying: </p> 321 1.1 tron 322 1.1 tron <ul> 323 1.1 tron 324 1.1 tron <li> <p> smtpd_proxy_filter (syntax: host:port): The host and TCP 325 1.1 tron port of the before-queue content filter. When no host or host: 326 1.1 tron is specified here, localhost is assumed. </p> 327 1.1 tron 328 1.1 tron <li> <p> smtpd_proxy_timeout (default: 100s): Timeout for connecting 329 1.1 tron to the before-queue content filter and for sending and receiving 330 1.1 tron commands and data. All proxy errors are logged to the maillog 331 1.1 tron file. For privacy reasons, all the remote SMTP client sees is "451 332 1.1 tron Error: queue file write error". It would not be right to disclose 333 1.1 tron internal details to strangers. </p> 334 1.1 tron 335 1.1 tron <li> <p> smtpd_proxy_ehlo (default: $myhostname): The hostname to 336 1.1 tron use when sending an EHLO command to the before-queue content filter. 337 1.1 tron </p> 338 1.1 tron 339 1.1 tron </ul> 340 1.1 tron 341 1.1 tron <h2><a name="protocol">How Postfix talks to the before-queue content 342 1.1 tron filter</a></h2> 343 1.1 tron 344 1.1 tron <p> The before-filter Postfix SMTP server connects to the content 345 1.1 tron filter, delivers one message, and disconnects. While sending mail 346 1.1 tron into the content filter, Postfix speaks ESMTP but uses no command 347 1.1 tron pipelining. Postfix generates its own EHLO, XFORWARD (for logging 348 1.1 tron the remote client IP address instead of localhost[127.0.0.1]), DATA 349 1.1 tron and QUIT commands, and forwards unmodified copies of all the MAIL 350 1.1 tron FROM and RCPT TO commands that the before-filter Postfix SMTP server 351 1.1 tron didn't reject itself. 352 1.1 tron Postfix sends no other SMTP commands. </p> 353 1.1 tron 354 1.1 tron <p> The content filter should accept the same MAIL FROM and RCPT 355 1.1 tron TO command syntax as the before-filter Postfix SMTP server, and 356 1.1 tron should forward the commands without modification to the after-filter 357 1.1 tron SMTP server. If the content filter or after-filter SMTP server 358 1.1 tron does not support all the ESMTP features that the before-filter 359 1.1 tron Postfix SMTP server supports, then the missing features must be 360 1.1 tron turned off in the before-filter Postfix SMTP server with the 361 1.1 tron smtpd_discard_ehlo_keywords parameter. </p> 362 1.1 tron 363 1.1 tron <p> When the filter rejects content, it should send a negative SMTP 364 1.1 tron response back to the before-filter Postfix SMTP server, and it 365 1.1 tron should abort the connection with the after-filter Postfix SMTP 366 1.1 tron server without completing the SMTP conversation with the after-filter 367 1.1 tron Postfix SMTP server. </p> 368 1.1 tron 369 1.1 tron </body> 370 1.1 tron 371 1.1 tron </html> 372
Indexes created Sat Jun 27 00:24:51 UTC 2026