1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3 4<head> 5 6<title>Postfix Postscreen Howto (Postfix 2.8 - 3.5)</title> 7 8<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 9<link rel='stylesheet' type='text/css' href='postfix-doc.css'> 10 11</head> 12 13<body> 14 15<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix Postscreen Howto (Postfix 2.8 - 3.5)</h1> 16 17<hr> 18 19<h2> <a name="intro">Introduction</a> </h2> 20 21<p> This document describes features that are available in Postfix 222.8 - 3.5. </p> 23 24<p> The Postfix postscreen(8) daemon provides additional protection 25against mail server overload. One postscreen(8) process handles 26multiple inbound SMTP connections, and decides which clients may 27talk to a Postfix SMTP server process. By keeping spambots away, 28postscreen(8) leaves more SMTP server processes available for 29legitimate clients, and delays the onset of <a 30href="STRESS_README.html">server overload</a> conditions. </p> 31 32<p> postscreen(8) should not be used on SMTP ports that receive 33mail from end-user clients (MUAs). In a typical deployment, 34postscreen(8) handles the MX service on TCP port 25, while MUA 35clients submit mail via the submission service on TCP port 587 which 36requires client authentication. Alternatively, a site could set up 37a dedicated, non-postscreen, "port 25" server that provides submission 38service and client authentication, but no MX service. </p> 39 40<p> postscreen(8) maintains a temporary allowlist for clients that 41pass its tests; by allowing allowlisted clients to skip tests, 42postscreen(8) minimizes its impact on legitimate email traffic. 43</p> 44 45<p> postscreen(8) is part of a multi-layer defense. <p> 46 47<ul> 48 49<li> <p> As the first layer, postscreen(8) blocks connections from 50zombies and other spambots that are responsible for about 90% of 51all spam. It is implemented as a single process to make this defense 52as inexpensive as possible. </p> 53 54<li> <p> The second layer implements more complex SMTP-level access 55checks with <a href="SMTPD_ACCESS_README.html">Postfix SMTP servers</a>, 56<a href="SMTPD_POLICY_README.html">policy daemons</a>, and 57<a href="MILTER_README.html">Milter applications</a>. </p> 58 59<li> <p> The third layer performs light-weight content inspection 60with the Postfix built-in header_checks and body_checks. This can 61block unacceptable attachments such as executable programs, and 62worms or viruses with easy-to-recognize signatures. </p> 63 64<li> <p> The fourth layer provides heavy-weight content inspection 65with external content filters. Typical examples are <a 66href="http://www.ijs.si/software/amavisd/">Amavisd-new</a>, <a 67href="http://spamassassin.apache.org/">SpamAssassin</a>, and <a 68href="MILTER_README.html">Milter applications</a>. </p> 69 70</ul> 71 72<p> Each layer reduces the spam volume. The general strategy is to 73use the less expensive defenses first, and to use the more expensive 74defenses only for the spam that remains. </p> 75 76<p> Topics in this document: </p> 77 78<ul> 79 80<li> <a href="#intro">Introduction</a> 81 82<li> <a href="#basic">The basic idea behind postscreen(8)</a> 83 84<li> <a href="#general"> General operation </a> 85 86<li> <a href="#quick">Quick tests before everything else</a> 87 88<li> <a href="#before_220"> Tests before the 220 SMTP server greeting </a> 89 90<li> <a href="#after_220">Tests after the 220 SMTP server greeting</a> 91 92<li> <a href="#other_error">Other errors</a> 93 94<li> <a href="#victory">When all tests succeed</a> 95 96<li> <a href="#config"> Configuring the postscreen(8) service</a> 97 98<li> <a href="#historical"> Historical notes and credits </a> 99 100</ul> 101 102<h2> <a name="basic">The basic idea behind postscreen(8)</a> </h2> 103 104<p> Most email is spam, and most spam is sent out by zombies (malware 105on compromised end-user computers). Wietse expects that the zombie 106problem will get worse before things improve, if ever. Without a 107tool like postscreen(8) that keeps the zombies away, Postfix would be 108spending most of its resources not receiving email. </p> 109 110<p> The main challenge for postscreen(8) is to make an is-a-zombie 111decision based on a single measurement. This is necessary because 112many zombies try to fly under the radar and avoid spamming the same 113site repeatedly. Once postscreen(8) decides that a client is 114not-a-zombie, it allowlists the client temporarily to avoid further 115delays for legitimate mail. </p> 116 117<p> Zombies have challenges too: they have only a limited amount 118of time to deliver spam before their IP address becomes denylisted. 119To speed up spam deliveries, zombies make compromises in their SMTP 120protocol implementation. For example, they speak before their turn, 121or they ignore responses from SMTP servers and continue sending 122mail even when the server tells them to go away. </p> 123 124<p> postscreen(8) uses a variety of measurements to recognize 125zombies. First, postscreen(8) determines if the remote SMTP client 126IP address is denylisted. Second, postscreen(8) looks for protocol 127compromises that are made to speed up delivery. These are good 128indicators for making is-a-zombie decisions based on single 129measurements. </p> 130 131<p> postscreen(8) does not inspect message content. Message content 132can vary from one delivery to the next, especially with clients 133that (also) send legitimate email. Content is not a good indicator 134for making is-a-zombie decisions based on single measurements, 135and that is the problem that postscreen(8) is focused on. </p> 136 137<h2> <a name="general"> General operation </a> </h2> 138 139<p> For each connection from an SMTP client, postscreen(8) performs 140a number of tests 141in the order as described below. Some tests introduce a delay of 142a few seconds. postscreen(8) maintains a temporary allowlist for 143clients that pass its tests; by allowing allowlisted clients to 144skip tests, postscreen(8) minimizes its impact on legitimate email 145traffic. </p> 146 147<p> By default, postscreen(8) hands off all connections to a Postfix 148SMTP server process after logging its findings. This mode is useful 149for non-destructive testing. </p> 150 151<p> In a typical production setting, postscreen(8) is configured 152to reject mail from clients that fail one or more tests, after 153logging the helo, sender and recipient information. </p> 154 155<p> Note: postscreen(8) is not an SMTP proxy; this is intentional. 156The purpose is to keep zombies away from Postfix, with minimal 157overhead for legitimate clients. </p> 158 159<h2> <a name="quick">Quick tests before everything else</a> </h2> 160 161<p> Before engaging in SMTP-level tests. postscreen(8) queries a 162number of local deny and allowlists. These tests speed up the 163handling of known clients. </p> 164 165<ul> 166 167<li> <a href="#perm_white_black"> Permanent allow/denylist test </a> 168 169<li> <a href="#temp_white"> Temporary allowlist test </a> 170 171<li> <a href="#white_veto"> MX Policy test </a> 172 173</ul> 174 175<h3> <a name="perm_white_black"> Permanent allow/denylist test </a> </h3> 176 177<p> The postscreen_access_list parameter (default: permit_mynetworks) 178specifies a permanent access list for SMTP client IP addresses. Typically 179one would specify something that allowlists local networks, followed 180by a CIDR table for selective allow- and denylisting. </p> 181 182<p> Example: </p> 183 184<pre> 185/etc/postfix/main.cf: 186 postscreen_access_list = permit_mynetworks, 187 cidr:/etc/postfix/postscreen_access.cidr 188 189/etc/postfix/postscreen_access.cidr: 190 # Rules are evaluated in the order as specified. 191 # Denylist 192.168.* except 192.168.0.1. 192 192.168.0.1 permit 193 192.168.0.0/16 reject 194</pre> 195 196<p> See the postscreen_access_list manpage documentation for more 197details. </p> 198 199<p> When the SMTP client address matches a "permit" action, 200postscreen(8) logs this with the client address and port number as: 201</p> 202 203<pre> 204 <b>WHITELISTED</b> <i>[address]:port</i> 205</pre> 206 207<p> The allowlist action is not configurable: immediately hand off the 208connection to a Postfix SMTP server process. </p> 209 210<p> When the SMTP client address matches a "reject" action, 211postscreen(8) logs this with the client address and port number as: 212</p> 213 214<pre> 215 <b>BLACKLISTED</b> <i>[address]:port</i> 216</pre> 217 218<p> The postscreen_blacklist_action parameter specifies the action 219that is taken next. See "<a href="#fail_before_220">When tests 220fail before the 220 SMTP server greeting</a>" below. </p> 221 222<h3> <a name="temp_white"> Temporary allowlist test </a> </h3> 223 224<p> The postscreen(8) daemon maintains a <i>temporary</i> 225allowlist for SMTP client IP addresses that have passed all 226the tests described below. The postscreen_cache_map parameter 227specifies the location of the temporary allowlist. The 228temporary allowlist is not used for SMTP client addresses 229that appear on the <i>permanent</i> access list. </p> 230 231<p> By default the temporary allowlist is not shared with other 232postscreen(8) daemons. See 233<a href="#temp_white_sharing"> Sharing 234the temporary allowlist </a> below for alternatives. </p> 235 236<p> When the SMTP client address appears on the temporary 237allowlist, postscreen(8) logs this with the client address and port 238number as: </p> 239 240<pre> 241 <b>PASS OLD</b> <i>[address]:port</i> 242</pre> 243 244<p> The action is not configurable: immediately hand off the 245connection to a Postfix SMTP server process. The client is 246excluded from further tests until its temporary allowlist 247entry expires, as controlled with the postscreen_*_ttl 248parameters. Expired entries are silently renewed if possible. </p> 249 250<h3> <a name="white_veto"> MX Policy test </a> </h3> 251 252<p> When the remote SMTP client is not on the static access list 253or temporary allowlist, postscreen(8) can implement a number of 254allowlist tests, before it grants the client a temporary allowlist 255status that allows it to talk to a Postfix SMTP server process. </p> 256 257<p> When postscreen(8) is configured to monitor all primary and 258backup MX addresses, it can refuse to allowlist clients that connect 259to a backup MX address only (an old spammer trick to take advantage 260of backup MX hosts with weaker anti-spam policies than primary MX 261hosts). </p> 262 263<blockquote> <p> NOTE: The following solution is for small sites. 264Larger sites would have to share the postscreen(8) cache between 265primary and backup MTAs, which would introduce a common point of 266failure. </p> </blockquote> 267 268<ul> 269 270<li> <p> First, configure the host to listen on both primary and 271backup MX addresses. Use the appropriate <tt>ifconfig</tt> or <tt>ip</tt> 272command for the local operating system, or update the appropriate 273configuration files and "refresh" the network protocol stack. </p> 274 275<p> <p> Second, configure Postfix to listen on the new IP address 276(this step is needed when you have specified inet_interfaces in 277main.cf). </p> 278 279<li> <p> Then, configure postscreen(8) to deny the temporary allowlist 280status on the backup MX address(es). An example for Wietse's 281server is: </p> 282 283<pre> 284/etc/postfix/main.cf: 285 postscreen_whitelist_interfaces = !168.100.189.8 static:all 286</pre> 287 288<p> Translation: allow clients to obtain the temporary allowlist 289status on all server IP addresses except 168.100.189.8, which is a 290backup MX address. </p> 291 292</ul> 293 294<p> When a non-allowlisted client connects the backup MX address, 295postscreen(8) logs this with the client address and port number as: 296</p> 297 298<pre> 299 <b>CONNECT from</b> <i>[address]:port</i> <b>to [168.100.189.8]:25</b> 300 <b>WHITELIST VETO</b> <i>[address]:port</i> 301</pre> 302 303<p> Translation: the client at <i>[address]:port</i> connected to 304the backup MX address 168.100.189.8 while it was not allowlisted. 305The client will not be granted the temporary allowlist status, even 306if passes all the allowlist tests described below. </p> 307 308<h2> <a name="before_220"> Tests before the 220 SMTP server greeting </a> </h2> 309 310<p> The postscreen_greet_wait parameter specifies a short time 311interval before the "220 <i>text</i>..." server greeting, where 312postscreen(8) can run a number of tests in parallel. </p> 313 314<p> When a good client passes these tests, and no "<a 315href="#after_220">deep protocol tests</a>" 316are configured, postscreen(8) 317adds the client to the temporary allowlist and hands off the "live" 318connection to a Postfix SMTP server process. The client can then 319continue as if postscreen(8) never even existed (except of course 320for the short postscreen_greet_wait delay). </p> 321 322<ul> 323 324<li> <a href="#pregreet"> Pregreet test </a> 325 326<li> <a href="#dnsbl"> DNS Allow/denylist test </a> 327 328<li> <a href="#fail_before_220">When tests fail before the 220 SMTP server greeting</a> 329 330</ul> 331 332<h3> <a name="pregreet"> Pregreet test </a> </h3> 333 334<p> The SMTP protocol is a classic example of a protocol where the 335server speaks before the client. postscreen(8) detects zombies 336that are in a hurry and that speak before their turn. This test is 337enabled by default. </p> 338 339<p> The postscreen_greet_banner parameter specifies the <i>text</i> 340portion of a "220-<i>text</i>..." teaser banner (default: $smtpd_banner). 341Note that this becomes the first part of a multi-line server greeting. 342The postscreen(8) daemon sends this before the postscreen_greet_wait 343timer is started. The purpose of the teaser banner is to confuse 344zombies so that they speak before their turn. It has no effect on 345SMTP clients that correctly implement the protocol. </p> 346 347<p> To avoid problems with poorly-implemented SMTP engines in network 348appliances or network testing tools, either exclude them from all 349tests with the postscreen_access_list feature or else specify 350an empty teaser banner: </p> 351 352<pre> 353/etc/postfix/main.cf: 354 # Exclude broken clients by allowlisting. Clients in mynetworks 355 # should always be allowlisted. 356 postscreen_access_list = permit_mynetworks, 357 cidr:/etc/postfix/postscreen_access.cidr 358 359/etc/postfix/postscreen_access.cidr: 360 192.168.254.0/24 permit 361</pre> 362 363<pre> 364/etc/postfix/main.cf: 365 # Disable the teaser banner (try allowlisting first if you can). 366 postscreen_greet_banner = 367</pre> 368 369<p> When an SMTP client sends a command before the 370postscreen_greet_wait time has elapsed, postscreen(8) logs this as: 371</p> 372 373<pre> 374 <b>PREGREET</b> <i>count</i> <b>after</b> <i>time</i> <b>from</b> <i>[address]:port text...</i> 375</pre> 376 377<p> Translation: the client at <i>[address]:port</i> sent <i>count</i> 378bytes before its turn to speak. This happened <i>time</i> seconds 379after the postscreen_greet_wait timer was started. The <i>text</i> 380is what the client sent (truncated to 100 bytes, and with non-printable 381characters replaced with C-style escapes such as \r for carriage-return 382and \n for newline). </p> 383 384<p> The postscreen_greet_action parameter specifies the action that 385is taken next. See "<a href="#fail_before_220">When tests fail 386before the 220 SMTP server greeting</a>" below. </p> 387 388<h3> <a name="dnsbl"> DNS Allow/denylist test </a> </h3> 389 390<p> The postscreen_dnsbl_sites parameter (default: empty) specifies 391a list of DNS blocklist servers with optional filters and weight 392factors (positive weights for denylisting, negative for allowlisting). 393These servers will be queried in parallel with the reverse client 394IP address. This test is disabled by default. </p> 395 396<blockquote> 397<p> 398CAUTION: when postscreen rejects mail, its SMTP reply contains the 399DNSBL domain name. Use the postscreen_dnsbl_reply_map feature to 400hide "password" information in DNSBL domain names. 401</p> 402</blockquote> 403 404<p> When the postscreen_greet_wait time has elapsed, and the combined 405DNSBL score is equal to or greater than the postscreen_dnsbl_threshold 406parameter value, postscreen(8) logs this as: </p> 407 408<pre> 409 <b>DNSBL rank</b> <i>count</i> <b>for</b> <i>[address]:port</i> 410</pre> 411 412<p> Translation: the SMTP client at <i>[address]:port</i> has a combined 413DNSBL score of <i>count</i>. </p> 414 415<p> The postscreen_dnsbl_action parameter specifies the action that 416is taken when the combined DNSBL score is equal to or greater than 417the threshold. See "<a href="#fail_before_220">When tests fail 418before the 220 SMTP server greeting</a>" below. </p> 419 420<h3> <a name="fail_before_220">When tests fail before the 220 SMTP server greeting</a> </h3> 421 422<p> When the client address matches the permanent denylist, or 423when the client fails the pregreet or DNSBL tests, the action is 424specified with postscreen_blacklist_action, postscreen_greet_action, 425or postscreen_dnsbl_action, respectively. </p> 426 427<dl> 428 429<dt> <b>ignore</b> (default) </dt> 430 431<dd> Ignore the failure of this test. Allow other tests to complete. 432Repeat this test the next time the client connects. This option 433is useful for testing and collecting statistics without blocking 434mail. </dd> 435 436<dt> <b>enforce</b> </dt> 437 438<dd> Allow other tests to complete. Reject attempts to deliver mail 439with a 550 SMTP reply, and log the helo/sender/recipient information. 440Repeat this test the next time the client connects. </dd> 441 442<dt> <b>drop</b> </dt> 443 444<dd> Drop the connection immediately with a 521 SMTP reply. Repeat 445this test the next time the client connects. </dd> 446 447</dl> 448 449<h2> <a name="after_220">Tests after the 220 SMTP server greeting</a> </h2> 450 451<p> In this phase of the protocol, postscreen(8) implements a 452number of "deep protocol" tests. These tests use an SMTP protocol 453engine that is built into the postscreen(8) server. </p> 454 455<p> Important note: these protocol tests are disabled by default. 456They are more intrusive than the pregreet and DNSBL tests, and they 457have limitations as discussed next. </p> 458 459<ul> 460 461<li> <p> The main limitation of "after 220 greeting" tests is that 462a new client must disconnect after passing these tests (reason: 463postscreen is not a proxy). Then the client must reconnect from 464the same IP address before it can deliver mail. The following 465measures may help to avoid email delays: </p> 466 467<ul> 468 469<li> <p> Allow "good" clients to skip tests with the 470postscreen_dnsbl_whitelist_threshold feature (Postfix 2.11 and 471later). This is especially effective for sites such as Google that 472never retry immediately from the same IP address. </p> 473 474<li> <p> Small sites: Configure postscreen(8) to listen on multiple 475IP addresses, published in DNS as different IP addresses for the 476same MX hostname or for different MX hostnames. This avoids mail 477delivery delays with clients that reconnect immediately from the 478same IP address. </p> 479 480<li> <p> Large sites: Share the postscreen(8) cache between different 481Postfix MTAs with a large-enough memcache_table(5). Again, this 482avoids mail delivery delays with clients that reconnect immediately 483from the same IP address. </p> 484 485</ul> 486 487<li> <p> postscreen(8)'s built-in SMTP engine does not implement the 488AUTH, XCLIENT, and XFORWARD features. If you need to make these 489services available on port 25, then do not enable the tests after 490the 220 server greeting. </p> 491 492<li> <p> End-user clients should connect directly to the submission 493service, so that they never have to deal with postscreen(8)'s tests. 494</p> 495 496</ul> 497 498<p> The following "after 220 greeting" tests are available: </p> 499 500<ul> 501 502<li> <a href="#pipelining">Command pipelining test</a> 503 504<li> <a href="#non_smtp">Non-SMTP command test</a> 505 506<li> <a href="#barelf">Bare newline test</a> 507 508<li> <a href="#fail_after_220">When tests fail after the 220 SMTP server greeting</a> 509 510</ul> 511 512<h3> <a name="pipelining">Command pipelining test</a> </h3> 513 514<p> By default, SMTP is a half-duplex protocol: the sender and 515receiver send one command and one response at a time. Unlike the 516Postfix SMTP server, postscreen(8) does not announce support 517for ESMTP command pipelining. Therefore, clients are not allowed 518to send multiple commands. postscreen(8)'s 519<a href="#after_220">deep 520protocol test</a> for this is disabled by default. </p> 521 522<p> With "postscreen_pipelining_enable = yes", postscreen(8) detects 523zombies that send multiple commands, instead of sending one command 524and waiting for the server to reply. </p> 525 526<p> This test is opportunistically enabled when postscreen(8) has 527to use the built-in SMTP engine anyway. This is to make postscreen(8) 528logging more informative. </p> 529 530<p> When a client sends multiple commands, postscreen(8) logs this 531as: </p> 532 533<pre> 534 <b>COMMAND PIPELINING from</b> <i>[address]:port</i> <b>after</b> <i>command</i>: <i>text</i> 535</pre> 536 537<p> Translation: the SMTP client at <i>[address]:port</i> sent 538multiple SMTP commands, instead of sending one command and then 539waiting for the server to reply. This happened after the client 540sent <i>command</i>. The <i>text</i> shows part of the input that 541was sent too early; it is not logged with Postfix 2.8. </p> 542 543<p> The postscreen_pipelining_action parameter specifies the action 544that is taken next. See "<a href="#fail_after_220">When tests fail 545after the 220 SMTP server greeting</a>" below. </p> 546 547<h3> <a name="non_smtp">Non-SMTP command test</a> </h3> 548 549<p> Some spambots send their mail through open proxies. A symptom 550of this is the usage of commands such as CONNECT and other non-SMTP 551commands. Just like the Postfix SMTP server's smtpd_forbidden_commands 552feature, postscreen(8) has an equivalent postscreen_forbidden_commands 553feature to block these clients. postscreen(8)'s 554<a href="#after_220">deep 555protocol test</a> for this is disabled by default. </p> 556 557<p> With "postscreen_non_smtp_command_enable = yes", postscreen(8) 558detects zombies that send commands specified with the 559postscreen_forbidden_commands parameter. This also detects commands 560with the syntax of a message header label. The latter is a symptom 561that the client is sending message content after ignoring all the 562responses from postscreen(8) that reject mail. </p> 563 564<p> This test is opportunistically enabled when postscreen(8) has 565to use the built-in SMTP engine anyway. This is to make postscreen(8) 566logging more informative. </p> 567 568<p> When a client sends non-SMTP commands, postscreen(8) logs this 569as: </p> 570 571<pre> 572 <b>NON-SMTP COMMAND from</b> <i>[address]:port</i> <b>after</b> <i>command: text</i> 573</pre> 574 575<p> Translation: the SMTP client at <i>[address]:port</i> sent a 576command that matches the postscreen_forbidden_commands 577parameter, or that has the syntax of a message header label (text 578followed by optional space and ":"). 579The "<tt><b>after</b> <i>command</i></tt>" portion is logged with 580Postfix 2.10 and later. </p> 581 582<p> The postscreen_non_smtp_command_action parameter specifies 583the action that is taken next. See "<a href="#fail_after_220">When 584tests fail after the 220 SMTP server greeting</a>" below. </p> 585 586<h3> <a name="barelf">Bare newline test</a> </h3> 587 588<p> SMTP is a line-oriented protocol: lines have a limited length, 589and are terminated with <CR><LF>. Lines ending in a 590"bare" <LF>, that is newline not preceded by carriage return, 591are not allowed in SMTP. postscreen(8)'s 592<a href="#after_220">deep 593protocol test</a> for this is disabled by default. </p> 594 595<p> With "postscreen_bare_newline_enable = yes", postscreen(8) 596detects clients that send lines ending in bare newline characters. 597</p> 598 599<p> This test is opportunistically enabled when postscreen(8) has 600to use the built-in SMTP engine anyway. This is to make postscreen(8) 601logging more informative. </p> 602 603<p> When a client sends bare newline characters, postscreen(8) logs 604this as: 605</p> 606 607<pre> 608 <b>BARE NEWLINE from</b> <i>[address]:port</i> <b>after</b> <i>command</i> 609</pre> 610 611<p> Translation: the SMTP client at <i>[address]:port</i> sent a bare 612newline character, that is newline not preceded by carriage 613return. 614The "<tt><b>after</b> <i>command</i></tt>" portion is logged with 615Postfix 2.10 and later. </p> 616 617<p> The postscreen_bare_newline_action parameter specifies the 618action that is taken next. See "<a href="#fail_after_220">When 619tests fail after the 220 SMTP server greeting</a>" below. </p> 620 621<h3> <a name="fail_after_220">When tests fail after the 220 SMTP server greeting</a> </h3> 622 623<p> When the client fails the pipelining, non-SMTP command or bare 624newline tests, the action is specified with postscreen_pipelining_action, 625postscreen_non_smtp_command_action or postscreen_bare_newline_action, 626respectively. </p> 627 628<dl> 629 630<dt> <b>ignore</b> (default for bare newline) </dt> 631 632<dd> Ignore the failure of this test. Allow other tests to complete. 633Do NOT repeat this test before the result from some other test 634expires. 635 636This option is useful for testing and collecting statistics without 637blocking mail permanently. </dd> 638 639<dt> <b>enforce</b> (default for pipelining) </dt> 640 641<dd> Allow other tests to complete. Reject attempts to deliver 642mail with a 550 SMTP reply, and log the helo/sender/recipient 643information. Repeat this test the next time the client connects. 644</dd> 645 646<dt> <b>drop</b> (default for non-SMTP commands) </dt> 647 648<dd> Drop the connection immediately with a 521 SMTP reply. Repeat 649this test the next time the client connects. This action is 650compatible with the Postfix SMTP server's smtpd_forbidden_commands 651feature. </dd> 652 653</dl> 654 655<h2> <a name="other_error">Other errors</a> </h2> 656 657<p> When an SMTP client hangs up unexpectedly, postscreen(8) logs 658this as: </p> 659 660<pre> 661 <b>HANGUP after</b> <i>time</i> <b>from</b> <i>[address]:port</i> <b>in</b> <i>test name</i> 662</pre> 663 664<p> Translation: the SMTP client at <i>[address]:port</i> disconnected 665unexpectedly, <i>time</i> seconds after the start of the 666test named <i>test name</i>. </p> 667 668<p> There is no punishment for hanging up. A client that hangs up 669without sending the QUIT command can still pass all postscreen(8) 670tests. </p> 671 672<!-- 673 674<p> While an unexpired penalty is in effect, an SMTP client is not 675allowed to pass any tests, and postscreen(8) logs each connection 676with the remaining amount of penalty time as: </p> 677 678<pre> 679 <b>PENALTY</b> <i>time</i> <b>for</b> <i>[address]:port</i> 680</pre> 681 682<p> During this time, all attempts by the client to deliver mail 683will be deferred with a 450 SMTP status. </p> 684 685--> 686 687<p> The following errors are reported by the built-in SMTP engine. 688This engine never accepts mail, therefore it has per-session limits 689on the number of commands and on the session length. </p> 690 691<pre> 692 <b>COMMAND TIME LIMIT</b> <b>from</b> <i>[address]:port</i> <b>after</b> <i>command</i> 693</pre> 694 695<p> Translation: the SMTP client at <i>[address]:port</i> reached the 696per-command time limit as specified with the postscreen_command_time_limit 697parameter. The session is terminated immediately. 698The "<tt><b>after</b> <i>command</i></tt>" portion is logged with 699Postfix 2.10 and later. </p> 700 701<pre> 702 <b>COMMAND COUNT LIMIT from</b> <i>[address]:port</i> <b>after</b> <i>command</i> 703</pre> 704 705<p> Translation: the SMTP client at <i>[address]:port</i> reached the 706per-session command count limit as specified with the 707postscreen_command_count_limit parameter. The session is terminated 708immediately. 709The "<tt><b>after</b> <i>command</i></tt>" portion is logged with 710Postfix 2.10 and later. </p> 711 712<pre> 713 <b>COMMAND LENGTH LIMIT from</b> <i>[address]:port</i> <b>after</b> <i>command</i> 714</pre> 715 716<p> Translation: the SMTP client at <i>[address]:port</i> reached the 717per-command length limit, as specified with the line_length_limit 718parameter. The session is terminated immediately. 719The "<tt><b>after</b> <i>command</i></tt>" portion is logged with 720Postfix 2.10 and later. </p> 721 722<p> When an SMTP client makes too many connections at the same time, 723postscreen(8) rejects the connection with a 421 status code and logs: </p> 724 725<pre> 726 <b>NOQUEUE: reject: CONNECT from</b> <i>[address]:port</i><b>: too many connections</b> 727</pre> 728 729<p> The postscreen_client_connection_count_limit parameter controls this limit. </p> 730 731<p> When an SMTP client connects after postscreen(8) has reached a 732connection count limit, postscreen(8) rejects the connection with 733a 421 status code and logs: </p> 734 735<pre> 736 <b>NOQUEUE: reject: CONNECT from</b> <i>[address]:port</i><b>: all screening ports busy</b> 737 <b>NOQUEUE: reject: CONNECT from</b> <i>[address]:port</i><b>: all server ports busy</b> 738</pre> 739 740<p> The postscreen_pre_queue_limit and postscreen_post_queue_limit 741parameters control these limits. </p> 742 743<h2> <a name="victory">When all tests succeed</a> </h2> 744 745<p> When a new SMTP client passes all tests (i.e. it is not allowlisted 746via some mechanism), postscreen(8) logs this as: </p> 747 748<pre> 749 <b>PASS NEW</b> <i>[address]:port</i> 750</pre> 751 752<p> Where <i>[address]:port</i> are the client IP address and port. 753Then, postscreen(8) 754creates a temporary allowlist entry that excludes the client IP 755address from further tests until the temporary allowlist entry 756expires, as controlled with the postscreen_*_ttl parameters. </p> 757 758<p> When no "<a href="#after_220">deep protocol tests</a>" are 759configured, postscreen(8) hands off the "live" connection to a Postfix 760SMTP server process. The client can then continue as if postscreen(8) 761never even existed (except for the short postscreen_greet_wait delay). 762</p> 763 764<p> When any "<a href="#after_220">deep protocol tests</a>" are 765configured, postscreen(8) cannot hand off the "live" connection to 766a Postfix SMTP server process in the middle of the session. Instead, 767postscreen(8) defers mail delivery attempts with a 4XX status, logs 768the helo/sender/recipient information, and waits for the client to 769disconnect. The next time the client connects it will be allowed 770to talk to a Postfix SMTP server process to deliver its mail. 771postscreen(8) mitigates the impact of this limitation by giving 772<a href="#after_220">deep protocol tests</a> a long expiration 773time. </p> 774 775<h2> <a name="config"> Configuring the postscreen(8) service</a> 776</h2> 777 778<p> postscreen(8) has been tested on FreeBSD [4-8], Linux 2.[4-6] 779and Solaris 9 systems. </p> 780 781<ul> 782 783<li> <a href="#enable"> Turning on postscreen(8) without blocking 784mail</a> 785 786<li> <a href="#starttls"> postscreen(8) TLS configuration </a> 787 788<li> <a href="#blocking"> Blocking mail with postscreen(8) </a> 789 790<li> <a href="#turnoff"> Turning off postscreen(8) </a> 791 792<li> <a href="#temp_white_sharing"> Sharing the temporary allowlist 793</a> 794 795</ul> 796 797<h3> <a name="enable"> Turning on postscreen(8) without blocking mail</a> </h3> 798 799<p> To enable the postscreen(8) service and log client information 800without blocking mail: </p> 801 802<ol> 803 804<li> <p> Make sure that local clients and systems with non-standard 805SMTP implementations are excluded from any postscreen(8) tests. The 806default is to exclude all clients in mynetworks. To exclude additional 807clients, for example, third-party performance monitoring tools (these 808tend to have broken SMTP implementations): </p> 809 810<pre> 811/etc/postfix/main.cf: 812 # Exclude broken clients by allowlisting. Clients in mynetworks 813 # should always be allowlisted. 814 postscreen_access_list = permit_mynetworks, 815 cidr:/etc/postfix/postscreen_access.cidr 816 817/etc/postfix/postscreen_access.cidr: 818 192.168.254.0/24 permit 819</pre> 820 821<li> <p> Comment out the "<tt>smtp inet ... smtpd</tt>" service 822in master.cf, including any "<tt>-o parameter=value</tt>" entries 823that follow. </p> 824 825<pre> 826/etc/postfix/master.cf: 827 #smtp inet n - n - - smtpd 828 # -o parameter=value ... 829</pre> 830 831<li> <p> Uncomment the new "<tt>smtpd pass ... smtpd</tt>" service 832in master.cf, and duplicate any "<tt>-o parameter=value</tt>" entries 833from the smtpd service that was commented out in the previous step. 834</p> 835 836<pre> 837/etc/postfix/master.cf: 838 smtpd pass - - n - - smtpd 839 -o parameter=value ... 840</pre> 841 842<li> <p> Uncomment the new "<tt>smtp inet ... postscreen</tt>" 843service in master.cf. </p> 844 845<pre> 846/etc/postfix/master.cf: 847 smtp inet n - n - 1 postscreen 848</pre> 849 850<li> <p> Uncomment the new "<tt>tlsproxy unix ... tlsproxy</tt>" 851service in master.cf. This service implements STARTTLS support for 852postscreen(8). </p> 853 854<pre> 855/etc/postfix/master.cf: 856 tlsproxy unix - - n - 0 tlsproxy 857</pre> 858 859<li> <p> Uncomment the new "<tt>dnsblog unix ... dnsblog</tt>" 860service in master.cf. This service does DNSBL lookups for postscreen(8) 861and logs results. </p> 862 863<pre> 864/etc/postfix/master.cf: 865 dnsblog unix - - n - 0 dnsblog 866</pre> 867 868<li> <p> To enable DNSBL lookups, list some DNS blocklist sites in 869main.cf, separated by whitespace. Different sites can have different 870weights. For example: 871 872<pre> 873/etc/postfix/main.cf: 874 postscreen_dnsbl_threshold = 2 875 postscreen_dnsbl_sites = zen.spamhaus.org*2 876 bl.spamcop.net*1 b.barracudacentral.org*1 877</pre> 878 879<p> Note: if your DNSBL queries have a "secret" in the domain name, 880you must censor this information from the postscreen(8) SMTP replies. 881For example: </p> 882 883<pre> 884/etc/postfix/main.cf: 885 postscreen_dnsbl_reply_map = texthash:/etc/postfix/dnsbl_reply 886</pre> 887 888<pre> 889/etc/postfix/dnsbl_reply: 890 # Secret DNSBL name Name in postscreen(8) replies 891 secret.zen.dq.spamhaus.net zen.spamhaus.org 892</pre> 893 894<p> The texthash: format is similar to hash: except that there is 895no need to run postmap(1) before the file can be used, and that it 896does not detect changes after the file is read. It is new with 897Postfix version 2.8. </p> 898 899<li> <p> Read the new configuration with "<tt>postfix reload</tt>". 900</p> 901 902</ol> 903 904<p> Notes: </p> 905 906<ul> 907 908<li> <p> Some postscreen(8) configuration parameters implement 909stress-dependent behavior. This is supported only when the default 910value is stress-dependent (that is, "postconf -d <i>parametername</i>" 911output shows 912"<i>parametername</i> = ${stress?<i>something</i>}${stress:<i>something</i>}" or 913"<i>parametername</i> = ${stress?{<i>something</i>}:{<i>something</i>}}"). 914Other parameters always evaluate as if the stress value is the empty 915string. </p> 916 917<li> <p> See "<a href="#before_220">Tests before the 220 SMTP server 918greeting</a>" for details about the logging from these 919postscreen(8) tests. </p> 920 921<li> <p> If you run Postfix 2.6 or earlier you must stop and start 922the master daemon ("<tt>postfix stop; postfix start</tt>"). This 923is needed because the Postfix "pass" master service type did not 924work reliably on all systems. </p> 925 926</ul> 927 928<h3> <a name="starttls"> postscreen(8) TLS configuration </a> </h3> 929 930<p> postscreen(8) TLS support is available for remote SMTP clients 931that aren't allowlisted, including clients that need to renew their 932temporary allowlist status. When a remote SMTP client requests TLS 933service, postscreen(8) invisibly hands off the connection to a 934tlsproxy(8) process. Then, tlsproxy(8) encrypts and decrypts the 935traffic between postscreen(8) and the remote SMTP client. One 936tlsproxy(8) process can handle multiple SMTP sessions. The number 937of tlsproxy(8) processes slowly increases with server load, but it 938should always be much smaller than the number of postscreen(8) TLS 939sessions. </p> 940 941<p> TLS support for postscreen(8) and tlsproxy(8) uses the same 942parameters as with smtpd(8). We recommend that you keep the relevant 943configuration parameters in main.cf. If you must specify "-o 944smtpd_mumble=value" parameter overrides in master.cf for a 945postscreen-protected smtpd(8) service, then you should specify those 946same parameter overrides for the postscreen(8) and tlsproxy(8) 947services. </p> 948 949<h3> <a name="blocking"> Blocking mail with postscreen(8) </a> </h3> 950 951<p> For compatibility with smtpd(8), postscreen(8) implements the 952soft_bounce safety feature. This causes Postfix to reject mail with 953a "try again" reply code. </p> 954 955<ul> 956 957<li> <p> To turn this on for all of Postfix, specify "<tt>soft_bounce 958= yes</tt>" in main.cf. </p> 959 960<li> <p> To turn this on for postscreen(8) only, append "<tt>-o 961soft_bounce=yes</tt>" (note: NO SPACES around '=') to the postscreen 962entry in master.cf. <p> 963 964</ul> 965 966<p> Execute "<tt>postfix reload</tt>" to make the change effective. </p> 967 968<p> After testing, do not forget to remove the soft_bounce feature, 969otherwise senders won't receive their non-delivery notification 970until many days later. </p> 971 972<p> To use the postscreen(8) service to block mail, edit main.cf and 973specify one or more of: </p> 974 975<ul> 976 977<li> <p> "<tt>postscreen_dnsbl_action = enforce</tt>", to reject 978clients that are on DNS blocklists, and to log the helo/sender/recipient 979information. With good DNSBLs this reduces the amount of load on 980Postfix SMTP servers dramatically. </p> 981 982<li> <p> "<tt>postscreen_greet_action = enforce</tt>", to reject 983clients that talk before their turn, and to log the helo/sender/recipient 984information. This stops over half of all known-to-be illegitimate 985connections to Wietse's mail server. It is backup protection for 986zombies that haven't yet been denylisted. </p> 987 988<li> <p> You can also enable "<a href="#after_220">deep protocol 989tests</a>", but these are more intrusive than the pregreet or DNSBL 990tests. </p> 991 992<p> When a good client passes the "<a href="#after_220">deep 993protocol tests</a>", 994postscreen(8) adds the client to the temporary 995allowlist but it cannot hand off the "live" connection to a Postfix 996SMTP server process in the middle of the session. Instead, postscreen(8) 997defers mail delivery attempts with a 4XX status, logs the 998helo/sender/recipient information, and waits for the client to 999disconnect. </p> 1000 1001<p> When the good client comes back in a later session, it is allowed 1002to talk directly to a Postfix SMTP server. See "<a href="#after_220">Tests 1003after the 220 SMTP server greeting</a>" above for limitations with 1004AUTH and other features that clients may need. </p> 1005 1006<p> An unexpected benefit from "<a href="#after_220">deep protocol 1007tests</a>" is that some "good" clients don't return after the 4XX 1008reply; these clients were not so good after all. </p> 1009 1010<p> Unfortunately, some senders will retry requests from different 1011IP addresses, and may never get allowlisted. For this reason, 1012Wietse stopped using "<a href="#after_220">deep protocol tests</a>" 1013on his own internet-facing mail server. </p> 1014 1015<li> <p> There is also support for permanent denylisting and 1016allowlisting; see the description of the postscreen_access_list 1017parameter for details. </p> 1018 1019</ul> 1020 1021<h3> <a name="turnoff"> Turning off postscreen(8) </a> </h3> 1022 1023<p> To turn off postscreen(8) and handle mail directly with Postfix 1024SMTP server processes: </p> 1025 1026<ol> 1027 1028<li> <p> Comment out the "<tt>smtp inet ... postscreen</tt>" service 1029in master.cf, including any "<tt>-o parameter=value</tt>" entries 1030that follow. </p> 1031 1032<pre> 1033/etc/postfix/master.cf: 1034 #smtp inet n - n - 1 postscreen 1035 # -o parameter=value ... 1036</pre> 1037 1038<li> <p> Comment out the "<tt>dnsblog unix ... dnsblog</tt>" service 1039in master.cf. </p> 1040 1041<pre> 1042/etc/postfix/master.cf: 1043 #dnsblog unix - - n - 0 dnsblog 1044</pre> 1045 1046<li> <p> Comment out the "<tt>smtpd pass ... smtpd</tt>" service 1047in master.cf, including any "<tt>-o parameter=value</tt>" entries 1048that follow. </p> 1049 1050<pre> 1051/etc/postfix/master.cf: 1052 #smtpd pass - - n - - smtpd 1053 # -o parameter=value ... 1054</pre> 1055 1056<li> <p> Comment out the "<tt>tlsproxy unix ... tlsproxy</tt>" 1057service in master.cf, including any "<tt>-o parameter=value</tt>" 1058entries that follow. </p> 1059 1060<pre> 1061/etc/postfix/master.cf: 1062 #tlsproxy unix - - n - 0 tlsproxy 1063 # -o parameter=value ... 1064</pre> 1065 1066<li> <p> Uncomment the "<tt>smtp inet ... smtpd</tt>" service in 1067master.cf, including any "<tt>-o parameter=value</tt>" entries that 1068may follow. </p> 1069 1070<pre> 1071/etc/postfix/master.cf: 1072 smtp inet n - n - - smtpd 1073 -o parameter=value ... 1074</pre> 1075 1076<li> <p> Read the new configuration with "<tt>postfix reload</tt>". 1077</p> 1078 1079</ol> 1080 1081<h3> <a name="temp_white_sharing"> Sharing the temporary allowlist </a> </h3> 1082 1083<p> By default, the temporary allowlist is not shared between 1084multiple postscreen(8) daemons. To enable sharing, choose one 1085of the following options: </p> 1086 1087<ul> 1088 1089<li> <p> A non-persistent memcache: temporary allowlist can be shared 1090 between postscreen(8) daemons on the same host or different 1091 hosts. Disable cache cleanup (postscreen_cache_cleanup_interval 1092 = 0) in all postscreen(8) daemons because memcache: has no 1093 first-next API (but see example 4 below for memcache: with 1094 persistent backup). This requires Postfix 2.9 or later. </p> 1095 1096 <pre> 1097 # Example 1: non-persistent memcache: allowlist. 1098 /etc/postfix/main.cf: 1099 postscreen_cache_map = memcache:/etc/postfix/postscreen_cache 1100 postscreen_cache_cleanup_interval = 0 1101 1102 /etc/postfix/postscreen_cache: 1103 memcache = inet:127.0.0.1:11211 1104 key_format = postscreen:%s 1105 </pre> 1106 1107<li> <p> 1108 A persistent lmdb: temporary allowlist can be shared between 1109 postscreen(8) daemons that run under the same master(8) daemon, 1110 or under different master(8) daemons on the same host. Disable 1111 cache cleanup (postscreen_cache_cleanup_interval = 0) in all 1112 postscreen(8) daemons except one that is responsible for cache 1113 cleanup. This requires Postfix 2.11 or later. </p> 1114 1115 <pre> 1116 # Example 2: persistent lmdb: allowlist. 1117 /etc/postfix/main.cf: 1118 postscreen_cache_map = lmdb:$data_directory/postscreen_cache 1119 # See note 1 below. 1120 # postscreen_cache_cleanup_interval = 0 1121 </pre> 1122 1123<li> <p> Other kinds of persistent temporary allowlist can be shared 1124 only between postscreen(8) daemons that run under the same 1125 master(8) daemon. In this case, temporary allowlist access must 1126 be shared through the proxymap(8) daemon. This requires Postfix 1127 2.9 or later. </p> 1128 1129 <pre> 1130 # Example 3: proxied btree: allowlist. 1131 /etc/postfix/main.cf: 1132 postscreen_cache_map = 1133 proxy:btree:/var/lib/postfix/postscreen_cache 1134 # See note 1 below. 1135 # postscreen_cache_cleanup_interval = 0 1136 1137 # Example 4: proxied btree: allowlist with memcache: accelerator. 1138 /etc/postfix/main.cf: 1139 postscreen_cache_map = memcache:/etc/postfix/postscreen_cache 1140 proxy_write_maps = 1141 proxy:btree:/var/lib/postfix/postscreen_cache 1142 ... other proxied tables ... 1143 # See note 1 below. 1144 # postscreen_cache_cleanup_interval = 0 1145 1146 /etc/postfix/postscreen_cache: 1147 # Note: the $data_directory macro is not defined in this context. 1148 memcache = inet:127.0.0.1:11211 1149 backup = proxy:btree:/var/lib/postfix/postscreen_cache 1150 key_format = postscreen:%s 1151 </pre> 1152 1153 <p> Note 1: disable cache cleanup (postscreen_cache_cleanup_interval 1154 = 0) in all postscreen(8) daemons except one that is responsible 1155 for cache cleanup. </p> 1156 1157 <p> Note 2: postscreen(8) cache sharing via proxymap(8) requires Postfix 1158 2.9 or later; earlier proxymap(8) implementations don't support 1159 cache cleanup. </p> 1160 1161</ul> 1162 1163<h2> <a name="historical"> Historical notes and credits </a> </h2> 1164 1165<p> Many ideas in postscreen(8) were explored in earlier work by 1166Michael Tokarev, in OpenBSD spamd, and in MailChannels Traffic 1167Control. </p> 1168 1169<p> Wietse threw together a crude prototype with pregreet and dnsbl 1170support in June 2009, because he needed something new for a Mailserver 1171conference presentation in July. Ralf Hildebrandt ran this code on 1172several servers to collect real-world statistics. This version used 1173the dnsblog(8) ad-hoc DNS client program. </p> 1174 1175<p> Wietse needed new material for a LISA conference presentation 1176in November 2010, so he added support for DNSBL weights and filters 1177in August, followed by a major code rewrite, deep protocol tests, 1178helo/sender/recipient logging, and stress-adaptive behavior in 1179September. Ralf Hildebrandt ran this code on several servers to 1180collect real-world statistics. This version still used the embarrassing 1181dnsblog(8) ad-hoc DNS client program. </p> 1182 1183<p> Wietse added STARTTLS support in December 2010. This makes 1184postscreen(8) usable for sites that require TLS support. The 1185implementation introduces the tlsproxy(8) event-driven TLS proxy 1186that decrypts/encrypts the sessions for multiple SMTP clients. </p> 1187 1188<p> The tlsproxy(8) implementation led to the discovery of a "new" 1189class of vulnerability (<a 1190href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-0411" 1191>CVE-2011-0411</a>) that affected multiple implementations of SMTP, 1192POP, IMAP, NNTP, and FTP over TLS. </p> 1193 1194<p> postscreen(8) was officially released as part of the Postfix 11952.8 stable release in January 2011.</p> 1196 1197</body> 1198 1199</html> 1200
