    POSTSCREEN(8)                                                    POSTSCREEN(8)

    NAME
           postscreen - Postfix SMTP triage server

    SYNOPSIS
           postscreen [generic Postfix daemon options]

    DESCRIPTION
           The Postfix postscreen(8) server performs triage on multi-
           ple 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  num-
           ber  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 connec-
           tion.  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 inten-
           tional. 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 black-
           list, 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 possi-
           ble.

    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_ban-
           ner).   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 appli-
                  cable. Either perform DNSBL-related actions or for-
                  ward  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 appli-
                  cable.  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 spec-
                  ified 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 spec-
                  ified 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  ser-
                  vice 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  com-
                  mands.

           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

                                                                     POSTSCREEN(8)