summaryrefslogtreecommitdiffstats
path: root/README_FILES/POSTSCREEN_3_5_README
blob: ab67800bef3a3c50a0d4e7e89679a7096e62820a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
PPoossttffiixx PPoossttssccrreeeenn HHoowwttoo ((PPoossttffiixx 22..88 -- 33..55))

-------------------------------------------------------------------------------

IInnttrroodduuccttiioonn

This document describes features that are available in Postfix 2.8 - 3.5.

The Postfix postscreen(8) daemon provides additional protection against mail
server overload. One postscreen(8) process handles multiple inbound SMTP
connections, and decides which clients may talk to a Postfix SMTP server
process. By keeping spambots away, postscreen(8) leaves more SMTP server
processes available for legitimate clients, and delays the onset of server
overload conditions.

postscreen(8) should not be used on SMTP ports that receive mail from end-user
clients (MUAs). In a typical deployment, postscreen(8) handles the MX service
on TCP port 25, while MUA clients submit mail via the submission service on TCP
port 587 which requires client authentication. Alternatively, a site could set
up a dedicated, non-postscreen, "port 25" server that provides submission
service and client authentication, but no MX service.

postscreen(8) maintains a temporary allowlist for clients that pass its tests;
by allowing allowlisted clients to skip tests, postscreen(8) minimizes its
impact on legitimate email traffic.

postscreen(8) is part of a multi-layer defense.

  * As the first layer, postscreen(8) blocks connections from zombies and other
    spambots that are responsible for about 90% of all spam. It is implemented
    as a single process to make this defense as inexpensive as possible.

  * The second layer implements more complex SMTP-level access checks with
    Postfix SMTP servers, policy daemons, and Milter applications.

  * The third layer performs light-weight content inspection with the Postfix
    built-in header_checks and body_checks. This can block unacceptable
    attachments such as executable programs, and worms or viruses with easy-to-
    recognize signatures.

  * The fourth layer provides heavy-weight content inspection with external
    content filters. Typical examples are Amavisd-new, SpamAssassin, and Milter
    applications.

Each layer reduces the spam volume. The general strategy is to use the less
expensive defenses first, and to use the more expensive defenses only for the
spam that remains.

Topics in this document:

  * Introduction
  * The basic idea behind postscreen(8)
  * General operation
  * Quick tests before everything else
  * Tests before the 220 SMTP server greeting
  * Tests after the 220 SMTP server greeting
  * Other errors
  * When all tests succeed
  * Configuring the postscreen(8) service
  * Historical notes and credits

TThhee bbaassiicc iiddeeaa bbeehhiinndd ppoossttssccrreeeenn((88))

Most email is spam, and most spam is sent out by zombies (malware on
compromised end-user computers). Wietse expects that the zombie problem will
get worse before things improve, if ever. Without a tool like postscreen(8)
that keeps the zombies away, Postfix would be spending most of its resources
not receiving email.

The main challenge for postscreen(8) is to make an is-a-zombie decision based
on a single measurement. This is necessary because many zombies try to fly
under the radar and avoid spamming the same site repeatedly. Once postscreen(8)
decides that a client is not-a-zombie, it allowlists the client temporarily to
avoid further delays for legitimate mail.

Zombies have challenges too: they have only a limited amount of time to deliver
spam before their IP address becomes denylisted. To speed up spam deliveries,
zombies make compromises in their SMTP protocol implementation. For example,
they speak before their turn, or they ignore responses from SMTP servers and
continue sending mail even when the server tells them to go away.

postscreen(8) uses a variety of measurements to recognize zombies. First,
postscreen(8) determines if the remote SMTP client IP address is denylisted.
Second, postscreen(8) looks for protocol compromises that are made to speed up
delivery. These are good indicators for making is-a-zombie decisions based on
single measurements.

postscreen(8) does not inspect message content. Message content can vary from
one delivery to the next, especially with clients that (also) send legitimate
email. Content is not a good indicator for making is-a-zombie decisions based
on single measurements, and that is the problem that postscreen(8) is focused
on.

GGeenneerraall ooppeerraattiioonn

For each connection from an SMTP client, postscreen(8) performs a number of
tests in the order as described below. Some tests introduce a delay of a few
seconds. postscreen(8) maintains a temporary allowlist for clients that pass
its tests; by allowing allowlisted clients to skip tests, postscreen(8)
minimizes its impact on legitimate email traffic.

By default, postscreen(8) hands off all connections to a Postfix SMTP server
process after logging its findings. This mode is useful for non-destructive
testing.

In a typical production setting, postscreen(8) is configured to reject mail
from clients that fail one or more tests, after logging the helo, sender and
recipient information.

Note: postscreen(8) is not an SMTP proxy; this is intentional. The purpose is
to keep zombies away from Postfix, with minimal overhead for legitimate
clients.

QQuuiicckk tteessttss bbeeffoorree eevveerryytthhiinngg eellssee

Before engaging in SMTP-level tests. postscreen(8) queries a number of local
deny and allowlists. These tests speed up the handling of known clients.

  * Permanent allow/denylist test
  * Temporary allowlist test
  * MX Policy test

PPeerrmmaanneenntt aallllooww//ddeennyylliisstt tteesstt

The postscreen_access_list parameter (default: permit_mynetworks) specifies a
permanent access list for SMTP client IP addresses. Typically one would specify
something that allowlists local networks, followed by a CIDR table for
selective allow- and denylisting.

Example:

/etc/postfix/main.cf:
    postscreen_access_list = permit_mynetworks,
        cidr:/etc/postfix/postscreen_access.cidr

/etc/postfix/postscreen_access.cidr:
   # Rules are evaluated in the order as specified.
   # Denylist 192.168.* except 192.168.0.1.
   192.168.0.1          permit
   192.168.0.0/16       reject

See the postscreen_access_list manpage documentation for more details.

When the SMTP client address matches a "permit" action, postscreen(8) logs this
with the client address and port number as:

    WWHHIITTEELLIISSTTEEDD [address]:port

The allowlist action is not configurable: immediately hand off the connection
to a Postfix SMTP server process.

When the SMTP client address matches a "reject" action, postscreen(8) logs this
with the client address and port number as:

    BBLLAACCKKLLIISSTTEEDD [address]:port

The postscreen_blacklist_action parameter specifies the action that is taken
next. See "When tests fail before the 220 SMTP server greeting" below.

TTeemmppoorraarryy aalllloowwlliisstt tteesstt

The postscreen(8) daemon maintains a temporary allowlist for SMTP client IP
addresses that have passed all the tests described below. The
postscreen_cache_map parameter specifies the location of the temporary
allowlist. The temporary allowlist is not used for SMTP client addresses that
appear on the permanent access list.

By default the temporary allowlist is not shared with other postscreen(8)
daemons. See Sharing the temporary allowlist below for alternatives.

When the SMTP client address appears on the temporary allowlist, postscreen(8)
logs this with the client address and port number as:

    PPAASSSS OOLLDD [address]:port

The action is not configurable: immediately hand off the connection to a
Postfix SMTP server process. The client is excluded from further tests until
its temporary allowlist entry expires, as controlled with the postscreen_*_ttl
parameters. Expired entries are silently renewed if possible.

MMXX PPoolliiccyy tteesstt

When the remote SMTP client is not on the static access list or temporary
allowlist, postscreen(8) can implement a number of allowlist tests, before it
grants the client a temporary allowlist status that allows it to talk to a
Postfix SMTP server process.

When postscreen(8) is configured to monitor all primary and backup MX
addresses, it can refuse to allowlist clients that connect to a backup MX
address only (an old spammer trick to take advantage of backup MX hosts with
weaker anti-spam policies than primary MX hosts).

    NOTE: The following solution is for small sites. Larger sites would have to
    share the postscreen(8) cache between primary and backup MTAs, which would
    introduce a common point of failure.

  * First, configure the host to listen on both primary and backup MX
    addresses. Use the appropriate ifconfig or ip command for the local
    operating system, or update the appropriate configuration files and
    "refresh" the network protocol stack.

    Second, configure Postfix to listen on the new IP address (this step is
    needed when you have specified inet_interfaces in main.cf).

  * Then, configure postscreen(8) to deny the temporary allowlist status on the
    backup MX address(es). An example for Wietse's server is:

    /etc/postfix/main.cf:
        postscreen_whitelist_interfaces = !168.100.189.8 static:all

    Translation: allow clients to obtain the temporary allowlist status on all
    server IP addresses except 168.100.189.8, which is a backup MX address.

When a non-allowlisted client connects the backup MX address, postscreen(8)
logs this with the client address and port number as:

    CCOONNNNEECCTT ffrroomm [address]:port ttoo [[116688..110000..118899..88]]::2255
    WWHHIITTEELLIISSTT VVEETTOO [address]:port

Translation: the client at [address]:port connected to the backup MX address
168.100.189.8 while it was not allowlisted. The client will not be granted the
temporary allowlist status, even if passes all the allowlist tests described
below.

TTeessttss bbeeffoorree tthhee 222200 SSMMTTPP sseerrvveerr ggrreeeettiinngg

The postscreen_greet_wait parameter specifies a short time interval before the
"220 text..." server greeting, where postscreen(8) can run a number of tests in
parallel.

When a good client passes these tests, and no "deep protocol tests" are
configured, postscreen(8) adds the client to the temporary allowlist and hands
off the "live" connection to a Postfix SMTP server process. The client can then
continue as if postscreen(8) never even existed (except of course for the short
postscreen_greet_wait delay).

  * Pregreet test
  * DNS Allow/denylist test
  * When tests fail before the 220 SMTP server greeting

PPrreeggrreeeett tteesstt

The SMTP protocol is a classic example of a protocol where the server speaks
before the client. postscreen(8) detects zombies that are in a hurry and that
speak before their turn. This test is enabled by default.

The postscreen_greet_banner parameter specifies the text portion of a "220-
text..." teaser banner (default: $smtpd_banner). Note that this becomes the
first part of a multi-line server greeting. The postscreen(8) daemon sends this
before the postscreen_greet_wait timer is started. The purpose of the teaser
banner is to confuse zombies so that they speak before their turn. It has no
effect on SMTP clients that correctly implement the protocol.

To avoid problems with poorly-implemented SMTP engines in network appliances or
network testing tools, either exclude them from all tests with the
postscreen_access_list feature or else specify an empty teaser banner:

/etc/postfix/main.cf:
    # Exclude broken clients by allowlisting. Clients in mynetworks
    # should always be allowlisted.
    postscreen_access_list = permit_mynetworks,
        cidr:/etc/postfix/postscreen_access.cidr

/etc/postfix/postscreen_access.cidr:
    192.168.254.0/24 permit

/etc/postfix/main.cf:
    # Disable the teaser banner (try allowlisting first if you can).
    postscreen_greet_banner =

When an SMTP client sends a command before the postscreen_greet_wait time has
elapsed, postscreen(8) logs this as:

    PPRREEGGRREEEETT count aafftteerr time ffrroomm [address]:port text...

Translation: the client at [address]:port sent count bytes before its turn to
speak. This happened time seconds after the postscreen_greet_wait timer was
started. The text is what the client sent (truncated to 100 bytes, and with
non-printable characters replaced with C-style escapes such as \r for carriage-
return and \n for newline).

The postscreen_greet_action parameter specifies the action that is taken next.
See "When tests fail before the 220 SMTP server greeting" below.

DDNNSS AAllllooww//ddeennyylliisstt tteesstt

The postscreen_dnsbl_sites parameter (default: empty) specifies a list of DNS
blocklist servers with optional filters and weight factors (positive weights
for denylisting, negative for allowlisting). These servers will be queried in
parallel with the reverse client IP address. This test is disabled by default.

    CAUTION: when postscreen rejects mail, its SMTP reply contains the DNSBL
    domain name. Use the postscreen_dnsbl_reply_map feature to hide "password"
    information in DNSBL domain names.

When the postscreen_greet_wait time has elapsed, and the combined DNSBL score
is equal to or greater than the postscreen_dnsbl_threshold parameter value,
postscreen(8) logs this as:

    DDNNSSBBLL rraannkk count ffoorr [address]:port

Translation: the SMTP client at [address]:port has a combined DNSBL score of
count.

The postscreen_dnsbl_action parameter specifies the action that is taken when
the combined DNSBL score is equal to or greater than the threshold. See "When
tests fail before the 220 SMTP server greeting" below.

WWhheenn tteessttss ffaaiill bbeeffoorree tthhee 222200 SSMMTTPP sseerrvveerr ggrreeeettiinngg

When the client address matches the permanent denylist, or when the client
fails the pregreet or DNSBL tests, the action is specified with
postscreen_blacklist_action, postscreen_greet_action, or
postscreen_dnsbl_action, respectively.

iiggnnoorree (default)
    Ignore the failure of this test. Allow other tests to complete. Repeat this
    test the next time the client connects. This option is useful for testing
    and collecting statistics without blocking mail.
eennffoorrccee
    Allow other tests to complete. Reject attempts to deliver mail with a 550
    SMTP reply, and log the helo/sender/recipient information. Repeat this test
    the next time the client connects.
ddrroopp
    Drop the connection immediately with a 521 SMTP reply. Repeat this test the
    next time the client connects.

TTeessttss aafftteerr tthhee 222200 SSMMTTPP sseerrvveerr ggrreeeettiinngg

In this phase of the protocol, postscreen(8) implements a number of "deep
protocol" tests. These tests use an SMTP protocol engine that is built into the
postscreen(8) server.

Important note: these protocol tests are disabled by default. They are more
intrusive than the pregreet and DNSBL tests, and they have limitations as
discussed next.

  * The main limitation of "after 220 greeting" tests is that a new client must
    disconnect after passing these tests (reason: postscreen is not a proxy).
    Then the client must reconnect from the same IP address before it can
    deliver mail. The following measures may help to avoid email delays:

      o Allow "good" clients to skip tests with the
        postscreen_dnsbl_whitelist_threshold feature (Postfix 2.11 and later).
        This is especially effective for sites such as Google that never retry
        immediately from the same IP address.

      o Small sites: Configure postscreen(8) to listen on multiple IP
        addresses, published in DNS as different IP addresses for the same MX
        hostname or for different MX hostnames. This avoids mail delivery
        delays with clients that reconnect immediately from the same IP
        address.

      o Large sites: Share the postscreen(8) cache between different Postfix
        MTAs with a large-enough memcache_table(5). Again, this avoids mail
        delivery delays with clients that reconnect immediately from the same
        IP address.

  * postscreen(8)'s built-in SMTP engine does not implement the AUTH, XCLIENT,
    and XFORWARD features. If you need to make these services available on port
    25, then do not enable the tests after the 220 server greeting.

  * End-user clients should connect directly to the submission service, so that
    they never have to deal with postscreen(8)'s tests.

The following "after 220 greeting" tests are available:

  * Command pipelining test
  * Non-SMTP command test
  * Bare newline test
  * When tests fail after the 220 SMTP server greeting

CCoommmmaanndd ppiippeelliinniinngg tteesstt

By default, SMTP is a half-duplex protocol: the sender and receiver send one
command and one response at a time. Unlike the Postfix SMTP server, postscreen
(8) does not announce support for ESMTP command pipelining. Therefore, clients
are not allowed to send multiple commands. postscreen(8)'s deep protocol test
for this is disabled by default.

With "postscreen_pipelining_enable = yes", postscreen(8) detects zombies that
send multiple commands, instead of sending one command and waiting for the
server to reply.

This test is opportunistically enabled when postscreen(8) has to use the built-
in SMTP engine anyway. This is to make postscreen(8) logging more informative.

When a client sends multiple commands, postscreen(8) logs this as:

    CCOOMMMMAANNDD PPIIPPEELLIINNIINNGG ffrroomm [address]:port aafftteerr command: text

Translation: the SMTP client at [address]:port sent multiple SMTP commands,
instead of sending one command and then waiting for the server to reply. This
happened after the client sent command. The text shows part of the input that
was sent too early; it is not logged with Postfix 2.8.

The postscreen_pipelining_action parameter specifies the action that is taken
next. See "When tests fail after the 220 SMTP server greeting" below.

NNoonn--SSMMTTPP ccoommmmaanndd tteesstt

Some spambots send their mail through open proxies. A symptom of this is the
usage of commands such as CONNECT and other non-SMTP commands. Just like the
Postfix SMTP server's smtpd_forbidden_commands feature, postscreen(8) has an
equivalent postscreen_forbidden_commands feature to block these clients.
postscreen(8)'s deep protocol test for this is disabled by default.

With "postscreen_non_smtp_command_enable = yes", postscreen(8) detects zombies
that send commands specified with the postscreen_forbidden_commands parameter.
This also detects commands with the syntax of a message header label. The
latter is a symptom that the client is sending message content after ignoring
all the responses from postscreen(8) that reject mail.

This test is opportunistically enabled when postscreen(8) has to use the built-
in SMTP engine anyway. This is to make postscreen(8) logging more informative.

When a client sends non-SMTP commands, postscreen(8) logs this as:

    NNOONN--SSMMTTPP CCOOMMMMAANNDD ffrroomm [address]:port aafftteerr command: text

Translation: the SMTP client at [address]:port sent a command that matches the
postscreen_forbidden_commands parameter, or that has the syntax of a message
header label (text followed by optional space and ":"). The "aafftteerr command"
portion is logged with Postfix 2.10 and later.

The postscreen_non_smtp_command_action parameter specifies the action that is
taken next. See "When tests fail after the 220 SMTP server greeting" below.

BBaarree nneewwlliinnee tteesstt

SMTP is a line-oriented protocol: lines have a limited length, and are
terminated with <CR><LF>. Lines ending in a "bare" <LF>, that is newline not
preceded by carriage return, are not allowed in SMTP. postscreen(8)'s deep
protocol test for this is disabled by default.

With "postscreen_bare_newline_enable = yes", postscreen(8) detects clients that
send lines ending in bare newline characters.

This test is opportunistically enabled when postscreen(8) has to use the built-
in SMTP engine anyway. This is to make postscreen(8) logging more informative.

When a client sends bare newline characters, postscreen(8) logs this as:

    BBAARREE NNEEWWLLIINNEE ffrroomm [address]:port aafftteerr command

Translation: the SMTP client at [address]:port sent a bare newline character,
that is newline not preceded by carriage return. The "aafftteerr command" portion is
logged with Postfix 2.10 and later.

The postscreen_bare_newline_action parameter specifies the action that is taken
next. See "When tests fail after the 220 SMTP server greeting" below.

WWhheenn tteessttss ffaaiill aafftteerr tthhee 222200 SSMMTTPP sseerrvveerr ggrreeeettiinngg

When the client fails the pipelining, non-SMTP command or bare newline tests,
the action is specified with postscreen_pipelining_action,
postscreen_non_smtp_command_action or postscreen_bare_newline_action,
respectively.

iiggnnoorree (default for bare newline)
    Ignore the failure of this test. Allow other tests to complete. Do NOT
    repeat this test before the result from some other test expires. This
    option is useful for testing and collecting statistics without blocking
    mail permanently.
eennffoorrccee (default for pipelining)
    Allow other tests to complete. Reject attempts to deliver mail with a 550
    SMTP reply, and log the helo/sender/recipient information. Repeat this test
    the next time the client connects.
ddrroopp (default for non-SMTP commands)
    Drop the connection immediately with a 521 SMTP reply. Repeat this test the
    next time the client connects. This action is compatible with the Postfix
    SMTP server's smtpd_forbidden_commands feature.

OOtthheerr eerrrroorrss

When an SMTP client hangs up unexpectedly, postscreen(8) logs this as:

    HHAANNGGUUPP aafftteerr time ffrroomm [address]:port iinn test name

Translation: the SMTP client at [address]:port disconnected unexpectedly, time
seconds after the start of the test named test name.

There is no punishment for hanging up. A client that hangs up without sending
the QUIT command can still pass all postscreen(8) tests.

The following errors are reported by the built-in SMTP engine. This engine
never accepts mail, therefore it has per-session limits on the number of
commands and on the session length.

    CCOOMMMMAANNDD TTIIMMEE LLIIMMIITT ffrroomm [address]:port aafftteerr command

Translation: the SMTP client at [address]:port reached the per-command time
limit as specified with the postscreen_command_time_limit parameter. The
session is terminated immediately. The "aafftteerr command" portion is logged with
Postfix 2.10 and later.

    CCOOMMMMAANNDD CCOOUUNNTT LLIIMMIITT ffrroomm [address]:port aafftteerr command

Translation: the SMTP client at [address]:port reached the per-session command
count limit as specified with the postscreen_command_count_limit parameter. The
session is terminated immediately. The "aafftteerr command" portion is logged with
Postfix 2.10 and later.

    CCOOMMMMAANNDD LLEENNGGTTHH LLIIMMIITT ffrroomm [address]:port aafftteerr command

Translation: the SMTP client at [address]:port reached the per-command length
limit, as specified with the line_length_limit parameter. The session is
terminated immediately. The "aafftteerr command" portion is logged with Postfix 2.10
and later.

When an SMTP client makes too many connections at the same time, postscreen(8)
rejects the connection with a 421 status code and logs:

    NNOOQQUUEEUUEE:: rreejjeecctt:: CCOONNNNEECCTT ffrroomm [address]:port:: ttoooo mmaannyy ccoonnnneeccttiioonnss

The postscreen_client_connection_count_limit parameter controls this limit.

When an SMTP client connects after postscreen(8) has reached a connection count
limit, postscreen(8) rejects the connection with a 421 status code and logs:

    NNOOQQUUEEUUEE:: rreejjeecctt:: CCOONNNNEECCTT ffrroomm [address]:port:: aallll ssccrreeeenniinngg ppoorrttss bbuussyy
    NNOOQQUUEEUUEE:: rreejjeecctt:: CCOONNNNEECCTT ffrroomm [address]:port:: aallll sseerrvveerr ppoorrttss bbuussyy

The postscreen_pre_queue_limit and postscreen_post_queue_limit parameters
control these limits.

WWhheenn aallll tteessttss ssuucccceeeedd

When a new SMTP client passes all tests (i.e. it is not allowlisted via some
mechanism), postscreen(8) logs this as:

    PPAASSSS NNEEWW [address]:port

Where [address]:port are the client IP address and port. Then, postscreen(8)
creates a temporary allowlist entry that excludes the client IP address from
further tests until the temporary allowlist entry expires, as controlled with
the postscreen_*_ttl parameters.

When no "deep protocol tests" are configured, postscreen(8) hands off the
"live" connection to a Postfix SMTP server process. The client can then
continue as if postscreen(8) never even existed (except for the short
postscreen_greet_wait delay).

When any "deep protocol tests" are configured, postscreen(8) cannot hand off
the "live" connection to a Postfix SMTP server process in the middle of the
session. Instead, postscreen(8) defers mail delivery attempts with a 4XX
status, logs the helo/sender/recipient information, and waits for the client to
disconnect. The next time the client connects it will be allowed to talk to a
Postfix SMTP server process to deliver its mail. postscreen(8) mitigates the
impact of this limitation by giving deep protocol tests a long expiration time.

CCoonnffiigguurriinngg tthhee ppoossttssccrreeeenn((88)) sseerrvviiccee

postscreen(8) has been tested on FreeBSD [4-8], Linux 2.[4-6] and Solaris 9
systems.

  * Turning on postscreen(8) without blocking mail
  * postscreen(8) TLS configuration
  * Blocking mail with postscreen(8)
  * Turning off postscreen(8)
  * Sharing the temporary allowlist

TTuurrnniinngg oonn ppoossttssccrreeeenn((88)) wwiitthhoouutt bblloocckkiinngg mmaaiill

To enable the postscreen(8) service and log client information without blocking
mail:

 1. Make sure that local clients and systems with non-standard SMTP
    implementations are excluded from any postscreen(8) tests. The default is
    to exclude all clients in mynetworks. To exclude additional clients, for
    example, third-party performance monitoring tools (these tend to have
    broken SMTP implementations):

    /etc/postfix/main.cf:
        # Exclude broken clients by allowlisting. Clients in mynetworks
        # should always be allowlisted.
        postscreen_access_list = permit_mynetworks,
            cidr:/etc/postfix/postscreen_access.cidr

    /etc/postfix/postscreen_access.cidr:
        192.168.254.0/24 permit

 2. Comment out the "smtp inet ... smtpd" service in master.cf, including any
    "-o parameter=value" entries that follow.

    /etc/postfix/master.cf:
        #smtp      inet  n       -       n       -       -       smtpd
        #    -o parameter=value ...

 3. Uncomment the new "smtpd pass ... smtpd" service in master.cf, and
    duplicate any "-o parameter=value" entries from the smtpd service that was
    commented out in the previous step.

    /etc/postfix/master.cf:
        smtpd     pass  -       -       n       -       -       smtpd
            -o parameter=value ...

 4. Uncomment the new "smtp inet ... postscreen" service in master.cf.

    /etc/postfix/master.cf:
        smtp      inet  n       -       n       -       1       postscreen

 5. Uncomment the new "tlsproxy unix ... tlsproxy" service in master.cf. This
    service implements STARTTLS support for postscreen(8).

    /etc/postfix/master.cf:
        tlsproxy  unix  -       -       n       -       0       tlsproxy

 6. Uncomment the new "dnsblog unix ... dnsblog" service in master.cf. This
    service does DNSBL lookups for postscreen(8) and logs results.

    /etc/postfix/master.cf:
        dnsblog   unix  -       -       n       -       0       dnsblog

 7. To enable DNSBL lookups, list some DNS blocklist sites in main.cf,
    separated by whitespace. Different sites can have different weights. For
    example:

    /etc/postfix/main.cf:
        postscreen_dnsbl_threshold = 2
        postscreen_dnsbl_sites = zen.spamhaus.org*2
            bl.spamcop.net*1 b.barracudacentral.org*1

    Note: if your DNSBL queries have a "secret" in the domain name, you must
    censor this information from the postscreen(8) SMTP replies. For example:

    /etc/postfix/main.cf:
        postscreen_dnsbl_reply_map = texthash:/etc/postfix/dnsbl_reply

    /etc/postfix/dnsbl_reply:
        # Secret DNSBL name           Name in postscreen(8) replies
        secret.zen.dq.spamhaus.net    zen.spamhaus.org

    The texthash: format is similar to hash: except that there is no need to
    run postmap(1) before the file can be used, and that it does not detect
    changes after the file is read. It is new with Postfix version 2.8.

 8. Read the new configuration with "postfix reload".

Notes:

  * Some postscreen(8) configuration parameters implement stress-dependent
    behavior. This is supported only when the default value is stress-dependent
    (that is, "postconf -d parametername" output shows "parametername = $
    {stress?something}${stress:something}" or "parametername = ${stress?
    {something}:{something}}"). Other parameters always evaluate as if the
    stress value is the empty string.

  * See "Tests before the 220 SMTP server greeting" for details about the
    logging from these postscreen(8) tests.

  * If you run Postfix 2.6 or earlier you must stop and start the master daemon
    ("postfix stop; postfix start"). This is needed because the Postfix "pass"
    master service type did not work reliably on all systems.

ppoossttssccrreeeenn((88)) TTLLSS ccoonnffiigguurraattiioonn

postscreen(8) TLS support is available for remote SMTP clients that aren't
allowlisted, including clients that need to renew their temporary allowlist
status. When a remote SMTP client requests TLS service, postscreen(8) invisibly
hands off the connection to a tlsproxy(8) process. Then, tlsproxy(8) encrypts
and decrypts the traffic between postscreen(8) and the remote SMTP client. One
tlsproxy(8) process can handle multiple SMTP sessions. The number of tlsproxy
(8) processes slowly increases with server load, but it should always be much
smaller than the number of postscreen(8) TLS sessions.

TLS support for postscreen(8) and tlsproxy(8) uses the same parameters as with
smtpd(8). We recommend that you keep the relevant configuration parameters in
main.cf. If you must specify "-o smtpd_mumble=value" parameter overrides in
master.cf for a postscreen-protected smtpd(8) service, then you should specify
those same parameter overrides for the postscreen(8) and tlsproxy(8) services.

BBlloocckkiinngg mmaaiill wwiitthh ppoossttssccrreeeenn((88))

For compatibility with smtpd(8), postscreen(8) implements the soft_bounce
safety feature. This causes Postfix to reject mail with a "try again" reply
code.

  * To turn this on for all of Postfix, specify "soft_bounce = yes" in main.cf.

  * To turn this on for postscreen(8) only, append "-o soft_bounce=yes" (note:
    NO SPACES around '=') to the postscreen entry in master.cf.

Execute "postfix reload" to make the change effective.

After testing, do not forget to remove the soft_bounce feature, otherwise
senders won't receive their non-delivery notification until many days later.

To use the postscreen(8) service to block mail, edit main.cf and specify one or
more of:

  * "postscreen_dnsbl_action = enforce", to reject clients that are on DNS
    blocklists, and to log the helo/sender/recipient information. With good
    DNSBLs this reduces the amount of load on Postfix SMTP servers
    dramatically.

  * "postscreen_greet_action = enforce", to reject clients that talk before
    their turn, and to log the helo/sender/recipient information. This stops
    over half of all known-to-be illegitimate connections to Wietse's mail
    server. It is backup protection for zombies that haven't yet been
    denylisted.

  * You can also enable "deep protocol tests", but these are more intrusive
    than the pregreet or DNSBL tests.

    When a good client passes the "deep protocol tests", postscreen(8) adds the
    client to the temporary allowlist but it cannot hand off the "live"
    connection to a Postfix SMTP server process in the middle of the session.
    Instead, postscreen(8) defers mail delivery attempts with a 4XX status,
    logs the helo/sender/recipient information, and waits for the client to
    disconnect.

    When the good client comes back in a later session, it is allowed to talk
    directly to a Postfix SMTP server. See "Tests after the 220 SMTP server
    greeting" above for limitations with AUTH and other features that clients
    may need.

    An unexpected benefit from "deep protocol tests" is that some "good"
    clients don't return after the 4XX reply; these clients were not so good
    after all.

    Unfortunately, some senders will retry requests from different IP
    addresses, and may never get allowlisted. For this reason, Wietse stopped
    using "deep protocol tests" on his own internet-facing mail server.

  * There is also support for permanent denylisting and allowlisting; see the
    description of the postscreen_access_list parameter for details.

TTuurrnniinngg ooffff ppoossttssccrreeeenn((88))

To turn off postscreen(8) and handle mail directly with Postfix SMTP server
processes:

 1. Comment out the "smtp inet ... postscreen" service in master.cf, including
    any "-o parameter=value" entries that follow.

    /etc/postfix/master.cf:
        #smtp      inet  n       -       n       -       1       postscreen
        #    -o parameter=value ...

 2. Comment out the "dnsblog unix ... dnsblog" service in master.cf.

    /etc/postfix/master.cf:
        #dnsblog   unix  -       -       n       -       0       dnsblog

 3. Comment out the "smtpd pass ... smtpd" service in master.cf, including any
    "-o parameter=value" entries that follow.

    /etc/postfix/master.cf:
        #smtpd     pass  -       -       n       -       -       smtpd
        #    -o parameter=value ...

 4. Comment out the "tlsproxy unix ... tlsproxy" service in master.cf,
    including any "-o parameter=value" entries that follow.

    /etc/postfix/master.cf:
        #tlsproxy  unix  -       -       n       -       0       tlsproxy
        #    -o parameter=value ...

 5. Uncomment the "smtp inet ... smtpd" service in master.cf, including any "-
    o parameter=value" entries that may follow.

    /etc/postfix/master.cf:
        smtp       inet  n       -       n       -       -       smtpd
            -o parameter=value ...

 6. Read the new configuration with "postfix reload".

SShhaarriinngg tthhee tteemmppoorraarryy aalllloowwlliisstt

By default, the temporary allowlist is not shared between multiple postscreen
(8) daemons. To enable sharing, choose one of the following options:

  * A non-persistent memcache: temporary allowlist can be shared between
    postscreen(8) daemons on the same host or different hosts. Disable cache
    cleanup (postscreen_cache_cleanup_interval = 0) in all postscreen(8)
    daemons because memcache: has no first-next API (but see example 4 below
    for memcache: with persistent backup). This requires Postfix 2.9 or later.

        # Example 1: non-persistent memcache: allowlist.
        /etc/postfix/main.cf:
            postscreen_cache_map = memcache:/etc/postfix/postscreen_cache
            postscreen_cache_cleanup_interval = 0

        /etc/postfix/postscreen_cache:
            memcache = inet:127.0.0.1:11211
            key_format = postscreen:%s

  * A persistent lmdb: temporary allowlist can be shared between postscreen(8)
    daemons that run under the same master(8) daemon, or under different master
    (8) daemons on the same host. Disable cache cleanup
    (postscreen_cache_cleanup_interval = 0) in all postscreen(8) daemons except
    one that is responsible for cache cleanup. This requires Postfix 2.11 or
    later.

        # Example 2: persistent lmdb: allowlist.
        /etc/postfix/main.cf:
            postscreen_cache_map = lmdb:$data_directory/postscreen_cache
            # See note 1 below.
            # postscreen_cache_cleanup_interval = 0

  * Other kinds of persistent temporary allowlist can be shared only between
    postscreen(8) daemons that run under the same master(8) daemon. In this
    case, temporary allowlist access must be shared through the proxymap(8)
    daemon. This requires Postfix 2.9 or later.

        # Example 3: proxied btree: allowlist.
        /etc/postfix/main.cf:
            postscreen_cache_map =
                proxy:btree:/var/lib/postfix/postscreen_cache
            # See note 1 below.
            # postscreen_cache_cleanup_interval = 0

        # Example 4: proxied btree: allowlist with memcache: accelerator.
        /etc/postfix/main.cf:
            postscreen_cache_map = memcache:/etc/postfix/postscreen_cache
            proxy_write_maps =
                proxy:btree:/var/lib/postfix/postscreen_cache
                ... other proxied tables ...
            # See note 1 below.
            # postscreen_cache_cleanup_interval = 0

        /etc/postfix/postscreen_cache:
            # Note: the $data_directory macro is not defined in this context.
            memcache = inet:127.0.0.1:11211
            backup = proxy:btree:/var/lib/postfix/postscreen_cache
            key_format = postscreen:%s

    Note 1: disable cache cleanup (postscreen_cache_cleanup_interval = 0) in
    all postscreen(8) daemons except one that is responsible for cache cleanup.

    Note 2: postscreen(8) cache sharing via proxymap(8) requires Postfix 2.9 or
    later; earlier proxymap(8) implementations don't support cache cleanup.

HHiissttoorriiccaall nnootteess aanndd ccrreeddiittss

Many ideas in postscreen(8) were explored in earlier work by Michael Tokarev,
in OpenBSD spamd, and in MailChannels Traffic Control.

Wietse threw together a crude prototype with pregreet and dnsbl support in June
2009, because he needed something new for a Mailserver conference presentation
in July. Ralf Hildebrandt ran this code on several servers to collect real-
world statistics. This version used the dnsblog(8) ad-hoc DNS client program.

Wietse needed new material for a LISA conference presentation in November 2010,
so he added support for DNSBL weights and filters in August, followed by a
major code rewrite, deep protocol tests, helo/sender/recipient logging, and
stress-adaptive behavior in September. Ralf Hildebrandt ran this code on
several servers to collect real-world statistics. This version still used the
embarrassing dnsblog(8) ad-hoc DNS client program.

Wietse added STARTTLS support in December 2010. This makes postscreen(8) usable
for sites that require TLS support. The implementation introduces the tlsproxy
(8) event-driven TLS proxy that decrypts/encrypts the sessions for multiple
SMTP clients.

The tlsproxy(8) implementation led to the discovery of a "new" class of
vulnerability (CVE-2011-0411) that affected multiple implementations of SMTP,
POP, IMAP, NNTP, and FTP over TLS.

postscreen(8) was officially released as part of the Postfix 2.8 stable release
in January 2011.