1POSTSCREEN(8) System Manager's Manual POSTSCREEN(8)
2
6 postscreen - Postfix zombie blocker
7
9 postscreen [generic Postfix daemon options]
10
12 The Postfix postscreen(8) server provides additional protection against
13 mail server overload. One postscreen(8) process handles multiple in‐
14 bound SMTP connections, and decides which clients may talk to a Postfix
15 SMTP server process. By keeping spambots away, postscreen(8) leaves
16 more SMTP server processes available for legitimate clients, and delays
17 the onset of server overload conditions.
18 This program should not be used on SMTP ports that receive mail from
20 end-user clients (MUAs). In a typical deployment, postscreen(8) handles
21 the MX service on TCP port 25, and smtpd(8) receives mail from MUAs on
22 the submission service (TCP port 587) which requires client authentica‐
23 tion. Alternatively, a site could set up a dedicated, non-postscreen,
24 "port 25" server that provides submission service and client authenti‐
25 cation, but no MX service.
26 postscreen(8) maintains a temporary allowlist for clients that have
28 passed a number of tests. When an SMTP client IP address is al‐
29 lowlisted, postscreen(8) hands off the connection immediately to a
30 Postfix SMTP server process. This minimizes the overhead for legitimate
31 mail.
32 By default, postscreen(8) logs statistics and hands off each connection
34 to a Postfix SMTP server process, while excluding clients in mynetworks
35 from all tests (primarily, to avoid problems with non-standard SMTP im‐
36 plementations in network appliances). This default mode blocks no
37 clients, and is useful for non-destructive testing.
38 In a typical production setting, postscreen(8) is configured to reject
40 mail from clients that fail one or more tests. postscreen(8) logs re‐
41 jected mail with the client address, helo, sender and recipient infor‐
42 mation.
43 postscreen(8) is not an SMTP proxy; this is intentional. The purpose
45 is to keep spambots away from Postfix SMTP server processes, while min‐
46 imizing overhead for legitimate traffic.
47
49 The postscreen(8) server is moderately security-sensitive. It talks to
50 untrusted clients on the network. The process can be run chrooted at
51 fixed low privilege.
52
54 RFC 821 (SMTP protocol)
55 RFC 1123 (Host requirements)
56 RFC 1652 (8bit-MIME transport)
57 RFC 1869 (SMTP service extensions)
58 RFC 1870 (Message Size Declaration)
59 RFC 1985 (ETRN command)
60 RFC 2034 (SMTP Enhanced Status Codes)
61 RFC 2821 (SMTP protocol)
62 Not: RFC 2920 (SMTP Pipelining)
63 RFC 3030 (CHUNKING without BINARYMIME)
64 RFC 3207 (STARTTLS command)
65 RFC 3461 (SMTP DSN Extension)
66 RFC 3463 (Enhanced Status Codes)
67 RFC 5321 (SMTP protocol, including multi-line 220 banners)
68
70 Problems and transactions are logged to syslogd(8) or postlogd(8).
71
73 The postscreen(8) built-in SMTP protocol engine currently does not an‐
74 nounce support for AUTH, XCLIENT or XFORWARD. If you need to make
75 these services available on port 25, then do not enable the optional
76 "after 220 server greeting" tests.
77 The optional "after 220 server greeting" tests may result in unexpected
79 delivery delays from senders that retry email delivery from a different
80 IP address. Reason: after passing these tests a new client must dis‐
81 connect, and reconnect from the same IP address before it can deliver
82 mail. See POSTSCREEN_README, section "Tests after the 220 SMTP server
83 greeting", for a discussion.
84
86 Changes to main.cf are not picked up automatically, as postscreen(8)
87 processes may run for several hours. Use the command "postfix reload"
88 after a configuration change.
89 The text below provides only a parameter summary. See postconf(5) for
91 more details including examples.
92 NOTE: Some postscreen(8) parameters implement stress-dependent behav‐
94 ior. This is supported only when the default parameter value is
95 stress-dependent (that is, it looks like ${stress?{X}:{Y}}, or it is
96 the $name of an smtpd parameter with a stress-dependent default).
97 Other parameters always evaluate as if the stress parameter value is
98 the empty string.
99
101 postscreen_command_filter ($smtpd_command_filter)
102 A mechanism to transform commands from remote SMTP clients.
103 postscreen_discard_ehlo_keyword_address_maps ($smtpd_discard_ehlo_key‐
105 word_address_maps)
106 Lookup tables, indexed by the remote SMTP client address, with
107 case insensitive lists of EHLO keywords (pipelining, starttls,
108 auth, etc.) that the postscreen(8) server will not send in the
109 EHLO response to a remote SMTP client.
110 postscreen_discard_ehlo_keywords ($smtpd_discard_ehlo_keywords)
112 A case insensitive list of EHLO keywords (pipelining, starttls,
113 auth, etc.) that the postscreen(8) server will not send in the
114 EHLO response to a remote SMTP client.
115 Available in Postfix version 3.1 and later:
117 dns_ncache_ttl_fix_enable (no)
119 Enable a workaround for future libc incompatibility.
120 Available in Postfix version 3.4 and later:
122 postscreen_reject_footer_maps ($smtpd_reject_footer_maps)
124 Optional lookup table for information that is appended after a
125 4XX or 5XX postscreen(8) server response.
126 Available in Postfix 3.6 and later:
128 respectful_logging (see 'postconf -d' output)
130 Avoid logging that implies white is better than black.
131
133 postscreen_expansion_filter (see 'postconf -d' output)
134 List of characters that are permitted in postscreen_re‐
135 ject_footer attribute expansions.
136 postscreen_reject_footer ($smtpd_reject_footer)
138 Optional information that is appended after a 4XX or 5XX
139 postscreen(8) server response.
140 soft_bounce (no)
142 Safety net to keep mail queued that would otherwise be returned
143 to the sender.
144
146 Available in Postfix version 2.10 and later:
147 postscreen_upstream_proxy_protocol (empty)
149 The name of the proxy protocol used by an optional be‐
150 fore-postscreen proxy agent.
151 postscreen_upstream_proxy_timeout (5s)
153 The time limit for the proxy protocol specified with the
154 postscreen_upstream_proxy_protocol parameter.
155
157 This test is executed immediately after a remote SMTP client connects.
158 If a client is permanently allowlisted, the client will be handed off
159 immediately to a Postfix SMTP server process.
160 postscreen_access_list (permit_mynetworks)
162 Permanent allow/denylist for remote SMTP client IP addresses.
163 postscreen_blacklist_action (ignore)
165 Renamed to postscreen_denylist_action in Postfix 3.6.
166
168 When postscreen(8) is configured to monitor all primary and backup MX
169 addresses, it can refuse to allowlist clients that connect to a backup
170 MX address only. For small sites, this requires configuring primary and
171 backup MX addresses on the same MTA. Larger sites would have to share
172 the postscreen(8) cache between primary and backup MTAs, which would
173 introduce a common point of failure.
174 postscreen_allowlist_interfaces (static:all)
176 A list of local postscreen(8) server IP addresses where a
177 non-allowlisted remote SMTP client can obtain postscreen(8)'s
178 temporary allowlist status.
179
181 These tests are executed before the remote SMTP client receives the
182 "220 servername" greeting. If no tests remain after the successful com‐
183 pletion of this phase, the client will be handed off immediately to a
184 Postfix SMTP server process.
185 dnsblog_service_name (dnsblog)
187 The name of the dnsblog(8) service entry in master.cf.
188 postscreen_dnsbl_action (ignore)
190 The action that postscreen(8) takes when a remote SMTP client's
191 combined DNSBL score is equal to or greater than a threshold (as
192 defined with the postscreen_dnsbl_sites and
193 postscreen_dnsbl_threshold parameters).
194 postscreen_dnsbl_reply_map (empty)
196 A mapping from an actual DNSBL domain name which includes a se‐
197 cret password, to the DNSBL domain name that postscreen will re‐
198 ply with when it rejects mail.
199 postscreen_dnsbl_sites (empty)
201 Optional list of patterns with DNS allow/denylist domains, fil‐
202 ters and weight factors.
203 postscreen_dnsbl_threshold (1)
205 The inclusive lower bound for blocking a remote SMTP client,
206 based on its combined DNSBL score as defined with the
207 postscreen_dnsbl_sites parameter.
208 postscreen_greet_action (ignore)
210 The action that postscreen(8) takes when a remote SMTP client
211 speaks before its turn within the time specified with the
212 postscreen_greet_wait parameter.
213 postscreen_greet_banner ($smtpd_banner)
215 The text in the optional "220-text..." server response that
216 postscreen(8) sends ahead of the real Postfix SMTP server's "220
217 text..." response, in an attempt to confuse bad SMTP clients so
218 that they speak before their turn (pre-greet).
219 postscreen_greet_wait (normal: 6s, overload: 2s)
221 The amount of time that postscreen(8) will wait for an SMTP
222 client to send a command before its turn, and for DNS blocklist
223 lookup results to arrive (default: up to 2 seconds under stress,
224 up to 6 seconds otherwise).
225 smtpd_service_name (smtpd)
227 The internal service that postscreen(8) hands off allowed con‐
228 nections to.
229 Available in Postfix version 2.11 and later:
231 postscreen_dnsbl_whitelist_threshold (0)
233 Renamed to postscreen_dnsbl_allowlist_threshold in Postfix 3.6.
234 Available in Postfix version 3.0 and later:
236 postscreen_dnsbl_timeout (10s)
238 The time limit for DNSBL or DNSWL lookups.
239 Available in Postfix version 3.6 and later:
241 postscreen_denylist_action (ignore)
243 The action that postscreen(8) takes when a remote SMTP client is
244 permanently denylisted with the postscreen_access_list parame‐
245 ter.
246 postscreen_allowlist_interfaces (static:all)
248 A list of local postscreen(8) server IP addresses where a
249 non-allowlisted remote SMTP client can obtain postscreen(8)'s
250 temporary allowlist status.
251 postscreen_dnsbl_allowlist_threshold (0)
253 Allow a remote SMTP client to skip "before" and "after 220
254 greeting" protocol tests, based on its combined DNSBL score as
255 defined with the postscreen_dnsbl_sites parameter.
256
258 These tests are executed after the remote SMTP client receives the "220
259 servername" greeting. If a client passes all tests during this phase,
260 it will receive a 4XX response to all RCPT TO commands. After the
261 client reconnects, it will be allowed to talk directly to a Postfix
262 SMTP server process.
263 postscreen_bare_newline_action (ignore)
265 The action that postscreen(8) takes when a remote SMTP client
266 sends a bare newline character, that is, a newline not preceded
267 by carriage return.
268 postscreen_bare_newline_enable (no)
270 Enable "bare newline" SMTP protocol tests in the postscreen(8)
271 server.
272 postscreen_disable_vrfy_command ($disable_vrfy_command)
274 Disable the SMTP VRFY command in the postscreen(8) daemon.
275 postscreen_forbidden_commands ($smtpd_forbidden_commands)
277 List of commands that the postscreen(8) server considers in vio‐
278 lation of the SMTP protocol.
279 postscreen_helo_required ($smtpd_helo_required)
281 Require that a remote SMTP client sends HELO or EHLO before com‐
282 mencing a MAIL transaction.
283 postscreen_non_smtp_command_action (drop)
285 The action that postscreen(8) takes when a remote SMTP client
286 sends non-SMTP commands as specified with the postscreen_forbid‐
287 den_commands parameter.
288 postscreen_non_smtp_command_enable (no)
290 Enable "non-SMTP command" tests in the postscreen(8) server.
291 postscreen_pipelining_action (enforce)
293 The action that postscreen(8) takes when a remote SMTP client
294 sends multiple commands instead of sending one command and wait‐
295 ing for the server to respond.
296 postscreen_pipelining_enable (no)
298 Enable "pipelining" SMTP protocol tests in the postscreen(8)
299 server.
300
302 postscreen_cache_cleanup_interval (12h)
303 The amount of time between postscreen(8) cache cleanup runs.
304 postscreen_cache_map (btree:$data_directory/postscreen_cache)
306 Persistent storage for the postscreen(8) server decisions.
307 postscreen_cache_retention_time (7d)
309 The amount of time that postscreen(8) will cache an expired tem‐
310 porary allowlist entry before it is removed.
311 postscreen_bare_newline_ttl (30d)
313 The amount of time that postscreen(8) will use the result from a
314 successful "bare newline" SMTP protocol test.
315 postscreen_dnsbl_max_ttl
317 (${postscreen_dnsbl_ttl?{$postscreen_dnsbl_ttl}:{1}}h)
318 The maximum amount of time that postscreen(8) will use the re‐
319 sult from a successful DNS-based reputation test before a client
320 IP address is required to pass that test again.
321 postscreen_dnsbl_min_ttl (60s)
323 The minimum amount of time that postscreen(8) will use the re‐
324 sult from a successful DNS-based reputation test before a client
325 IP address is required to pass that test again.
326 postscreen_greet_ttl (1d)
328 The amount of time that postscreen(8) will use the result from a
329 successful PREGREET test.
330 postscreen_non_smtp_command_ttl (30d)
332 The amount of time that postscreen(8) will use the result from a
333 successful "non_smtp_command" SMTP protocol test.
334 postscreen_pipelining_ttl (30d)
336 The amount of time that postscreen(8) will use the result from a
337 successful "pipelining" SMTP protocol test.
338
340 line_length_limit (2048)
341 Upon input, long lines are chopped up into pieces of at most
342 this length; upon delivery, long lines are reconstructed.
343 postscreen_client_connection_count_limit ($smtpd_client_connec‐
345 tion_count_limit)
346 How many simultaneous connections any remote SMTP client is al‐
347 lowed to have with the postscreen(8) daemon.
348 postscreen_command_count_limit (20)
350 The limit on the total number of commands per SMTP session for
351 postscreen(8)'s built-in SMTP protocol engine.
352 postscreen_command_time_limit (normal: 300s, overload: 10s)
354 The time limit to read an entire command line with
355 postscreen(8)'s built-in SMTP protocol engine.
356 postscreen_post_queue_limit ($default_process_limit)
358 The number of clients that can be waiting for service from a
359 real Postfix SMTP server process.
360 postscreen_pre_queue_limit ($default_process_limit)
362 The number of non-allowlisted clients that can be waiting for a
363 decision whether they will receive service from a real Postfix
364 SMTP server process.
365 postscreen_watchdog_timeout (10s)
367 How much time a postscreen(8) process may take to respond to a
368 remote SMTP client command or to perform a cache operation be‐
369 fore it is terminated by a built-in watchdog timer.
370
372 postscreen_tls_security_level ($smtpd_tls_security_level)
373 The SMTP TLS security level for the postscreen(8) server; when a
374 non-empty value is specified, this overrides the obsolete param‐
375 eters postscreen_use_tls and postscreen_enforce_tls.
376 tlsproxy_service_name (tlsproxy)
378 The name of the tlsproxy(8) service entry in master.cf.
379
381 These parameters are supported for compatibility with smtpd(8) legacy
382 parameters.
383 postscreen_use_tls ($smtpd_use_tls)
385 Opportunistic TLS: announce STARTTLS support to remote SMTP
386 clients, but do not require that clients use TLS encryption.
387 postscreen_enforce_tls ($smtpd_enforce_tls)
389 Mandatory TLS: announce STARTTLS support to remote SMTP clients,
390 and require that clients use TLS encryption.
391
393 config_directory (see 'postconf -d' output)
394 The default location of the Postfix main.cf and master.cf con‐
395 figuration files.
396 delay_logging_resolution_limit (2)
398 The maximal number of digits after the decimal point when log‐
399 ging sub-second delay values.
400 command_directory (see 'postconf -d' output)
402 The location of all postfix administrative commands.
403 max_idle (100s)
405 The maximum amount of time that an idle Postfix daemon process
406 waits for an incoming connection before terminating voluntarily.
407 process_id (read-only)
409 The process ID of a Postfix command or daemon process.
410 process_name (read-only)
412 The process name of a Postfix command or daemon process.
413 syslog_facility (mail)
415 The syslog facility of Postfix logging.
416 syslog_name (see 'postconf -d' output)
418 A prefix that is prepended to the process name in syslog
419 records, so that, for example, "smtpd" becomes "prefix/smtpd".
420 Available in Postfix 3.3 and later:
422 service_name (read-only)
424 The master.cf service name of a Postfix daemon process.
425 Available in Postfix 3.5 and later:
427 info_log_address_format (external)
429 The email address form that will be used in non-debug logging
430 (info, warning, etc.).
431
433 smtpd(8), Postfix SMTP server
434 tlsproxy(8), Postfix TLS proxy server
435 dnsblog(8), DNS allow/denylist logger
436 postlogd(8), Postfix logging
437 syslogd(8), system logging
438
440 Use "postconf readme_directory" or "postconf html_directory" to locate
441 this information.
442 POSTSCREEN_README, Postfix Postscreen Howto
443
445 The Secure Mailer license must be distributed with this software.
446
448 This service was introduced with Postfix version 2.8.
449 Many ideas in postscreen(8) were explored in earlier work by Michael
451 Tokarev, in OpenBSD spamd, and in MailChannels Traffic Control.
452
454 Wietse Venema
455 IBM T.J. Watson Research
456 P.O. Box 704
457 Yorktown Heights, NY 10598, USA
458 Wietse Venema
460 Google, Inc.
461 111 8th Avenue
462 New York, NY 10011, USA
463 POSTSCREEN(8)