POSTSCREEN(8)

NAME
postscreen - Postfix SMTP triage server

SYNOPSIS
postscreen [generic Postfix daemon options]

DESCRIPTION
The Postfix postscreen(8) server performs triage on multiple inbound SMTP connections in parallel. The program can run in two basic modes. The purpose of observation mode is to collect statistics without actually blocking mail. postscreen(8) runs a number of tests before it forwards a connection to a real SMTP server process. These tests introduce a delay of a few seconds; once a client passes the tests as "clean", its IP address is temporarily whitelisted and subsequent connections incur no delays until the temporary whitelist entry expires. The purpose of enforcement mode is to block mail without using up one Postfix SMTP server process for every connection. Here, postscreen(8) terminates connections from SMTP clients that fail the above tests, and forwards only the remaining connections to a real SMTP server process. By running time-consuming spam tests in parallel in postscreen(8), more Postfix SMTP server processes remain available for legitimate clients.

Note: postscreen(8) is not an SMTP proxy; this is intentional. The purpose is to prioritize legitimate clients with as little overhead as possible. postscreen(8) performs tests in the order described below.

1. PERMANENT WHITELIST TEST
The postscreen_whitelist_networks parameter (default: $mynetworks) specifies a permanent whitelist for SMTP client IP addresses. This feature is not used for addresses that appear on the permanent blacklist. When the SMTP client address matches the permanent whitelist, this is logged as:

WHITELISTED address

The action is not configurable: immediately forward the connection to a real SMTP server process.

2. PERMANENT BLACKLIST TEST
The postscreen_blacklist_networks parameter (default: empty) specifies a permanent blacklist for SMTP client IP addresses. The address syntax is as with mynetworks. When the SMTP client address matches the permanent blacklist, this is logged as:

BLACKLISTED address

The postscreen_blacklist_action parameter specifies the action that is taken next:

continue (default, observation mode)
    Continue with the SMTP GREETING PHASE TESTS below.

drop (enforcement mode)
    Drop the connection immediately with a 521 SMTP reply. In a future implementation, the connection may instead be passed to a dummy SMTP protocol engine that logs sender and recipient information.

3. TEMPORARY WHITELIST TEST
The postscreen(8) daemon maintains a temporary whitelist for SMTP client IP addresses that have passed all the tests described below. The postscreen_cache_map parameter specifies the location of the temporary whitelist. The temporary whitelist is not used for SMTP client addresses that appear on the permanent blacklist or whitelist. When the SMTP client address appears on the temporary whitelist, this is logged as:

PASS OLD address

The action is not configurable: immediately forward the connection to a real SMTP server process. The client is excluded from further tests until its temporary whitelist entry expires, as controlled with the postscreen_cache_ttl parameter. Expired entries are silently renewed if possible.

4. SMTP GREETING PHASE TESTS
The postscreen_greet_wait parameter specifies a time interval during which postscreen(8) runs a number of tests as described below. These tests run before the client may see the real SMTP server's "220 text..." server greeting. When the SMTP client passes all the tests, this is logged as:

PASS NEW address

The action is to forward the connection to a real SMTP server process and to create a temporary whitelist entry that excludes the client IP address from further tests until the temporary whitelist entry expires, as controlled with the postscreen_cache_ttl parameter. In a future implementation, the connection may first be passed to a dummy SMTP protocol engine that implements more protocol tests including greylisting, before the client is allowed to talk to a real SMTP server process.

4A. PREGREET TEST
The postscreen_greet_banner parameter specifies the text for a "220-text..." teaser banner (default: $smtpd_banner). The postscreen(8) daemon sends this before the postscreen_greet_wait timer is started. The purpose of the teaser banner is to confuse SPAM clients so that they speak before their turn. It has no effect on SMTP clients that correctly implement the protocol. To avoid problems with broken SMTP engines in network appliances, either exclude them from all tests with the postscreen_whitelist_networks feature or else specify an empty postscreen_greet_banner value to disable the "220-text..." teaser banner. When an SMTP client sends a command before the postscreen_greet_wait time has elapsed, this is logged as:

PREGREET count after time from address text...

Translation: the client at address sent count bytes before its turn to speak, and 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 "?"). The postscreen_greet_action parameter specifies the action that is taken next:

continue (default, observation mode)
    Wait until the postscreen_greet_wait time has elapsed, then report DNSBL lookup results if applicable. Either perform DNSBL-related actions or forward the connection to a real SMTP server process.

drop (enforcement mode)
    Drop the connection immediately with a 521 SMTP reply. In a future implementation, the connection may instead be passed to a dummy SMTP protocol engine that logs sender and recipient information.

4B. HANGUP TEST
When the SMTP client hangs up without sending any data before the postscreen_greet_wait time has elapsed, this is logged as:

HANGUP after time from address

The postscreen_hangup_action specifies the action that is taken next:

continue (default, observation mode)
    Wait until the postscreen_greet_wait time has elapsed, then report DNSBL lookup results if applicable. Do not forward the broken connection to a real SMTP server process.

drop (enforcement mode)
    Drop the connection immediately.

4C. DNS BLOCKLIST TEST
The postscreen_dnsbl_sites parameter (default: empty) specifies a list of DNS blocklist servers. When the postscreen_greet_wait time has elapsed, and the SMTP client address is listed with at least one of these blocklists, this is logged as:

DNSBL rank count for address

Translation: the client at address is listed with count DNSBL servers. The count does not depend on the number of DNS records that an individual DNSBL server returns. The postscreen_dnsbl_action parameter specifies the action that is taken next:

continue (default, observation mode)
    Forward the connection to a real SMTP server process.

drop (enforcement mode)
    Drop the connection immediately with a 521 SMTP reply. In a future implementation, the connection may instead be passed to a dummy SMTP protocol engine that logs sender and recipient information.

SECURITY
The postscreen(8) server is moderately security-sensitive. It talks to untrusted clients on the network. The process can be run chrooted at fixed low privilege.

STANDARDS
RFC 5321 (SMTP, including multi-line 220 greetings)
RFC 2920 (SMTP Pipelining)

DIAGNOSTICS
Problems and transactions are logged to syslogd(8).

CONFIGURATION PARAMETERS
Changes to main.cf are not picked up automatically, as postscreen(8) processes may run for several hours. Use the command "postfix reload" after a configuration change. The text below provides only a parameter summary. See postconf(5) for more details including examples.

TRIAGE PARAMETERS

postscreen_blacklist_action (continue)
    The action that postscreen(8) takes when an SMTP client is permanently blacklisted with the postscreen_blacklist_networks parameter.

postscreen_blacklist_networks (empty)
    Network addresses that are permanently blacklisted; see the postscreen_blacklist_action parameter for possible actions.

postscreen_cache_map (btree:$data_directory/ps_whitelist)
    Persistent storage for the postscreen(8) server decisions.

postscreen_cache_ttl (1d)
    The amount of time that postscreen(8) will cache a decision for a specific SMTP client IP address.

postscreen_dnsbl_action (continue)
    The action that postscreen(8) takes when an SMTP client is listed at the DNS blocklist domains specified with the postscreen_dnsbl_sites parameter.

postscreen_dnsbl_sites (empty)
    Optional list of DNS blocklist domains.

postscreen_greet_action (continue)
    The action that postscreen(8) takes when an SMTP client speaks before its turn within the time specified with the postscreen_greet_wait parameter.

postscreen_greet_banner ($smtpd_banner)
    The text in the optional "220-text..." server response that postscreen(8) sends ahead of the real Postfix SMTP server's "220 text..." response, in an attempt to confuse bad SMTP clients so that they speak before their turn (pre-greet).

postscreen_greet_wait (4s)
    The amount of time that postscreen(8) will wait for an SMTP client to send a command before its turn, and for DNS blocklist lookup results to arrive.

postscreen_hangup_action (continue)
    The action that postscreen(8) takes when an SMTP client disconnects without sending data, within the time specified with the postscreen_greet_wait parameter.

postscreen_post_queue_limit ($default_process_limit)
    The number of clients that can be waiting for service from a real SMTP server process.

postscreen_pre_queue_limit ($default_process_limit)
    The number of non-whitelisted clients that can be waiting for a decision whether they will receive service from a real SMTP server process.

postscreen_whitelist_networks ($mynetworks)
    Network addresses that are permanently whitelisted, and that will not be subjected to postscreen(8) checks.

smtpd_service (smtpd)
    The internal service that postscreen(8) forwards allowed connections to.

MISCELLANEOUS CONTROLS

config_directory (see 'postconf -d' output)
    The default location of the Postfix main.cf and master.cf configuration files.

daemon_timeout (18000s)
    How much time a Postfix daemon process may take to handle a request before it is terminated by a built-in watchdog timer.

delay_logging_resolution_limit (2)
    The maximal number of digits after the decimal point when logging sub-second delay values.

command_directory (see 'postconf -d' output)
    The location of all postfix administrative commands.

ipc_timeout (3600s)
    The time limit for sending or receiving information over an internal communication channel.

max_idle (100s)
    The maximum amount of time that an idle Postfix daemon process waits for an incoming connection before terminating voluntarily.

process_id (read-only)
    The process ID of a Postfix command or daemon process.

process_name (read-only)
    The process name of a Postfix command or daemon process.

syslog_facility (mail)
    The syslog facility of Postfix logging.

syslog_name (see 'postconf -d' output)
    The mail system name that is prepended to the process name in syslog records, so that "smtpd" becomes, for example, "postfix/smtpd".

SEE ALSO
smtpd(8), Postfix SMTP server
dnsblog(8), temporary DNS helper
syslogd(8), system logging

LICENSE
The Secure Mailer license must be distributed with this software.

AUTHOR(S)
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA