    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.   While
           postscreen(8)  keeps  zombies and other bogus clients away
           from Postfix SMTP  server  processes,  more  Postfix  SMTP
           server  processes remain available for legitimate clients.

    GENERAL OPERATION
           The triage process involves a  number  of  tests,  in  the
           order as described below.  Some tests introduce a delay of
           a few seconds.  Once a client passes  all  tests,  its  IP
           address  is temporarily excluded from the tests, typically
           for 24 hours.  This minimizes the impact of the  tests  on
           legitimate mail clients.

           After  logging  the  result of its tests, postscreen(8) by
           default forwards all connections to  a  real  SMTP  server
           process.  This mode is useful for non-destructive testing.

           In a typical production setting, postscreen(8) is  config-
           ured to disconnect clients that fail some tests.  A future
           implementation may pass the connection  to  a  dummy  SMTP
           protocol engine that logs sender and recipient information
           before hanging up.

           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.

    1. PERMANENT WHITELIST TEST
           The  postscreen_whitelist_networks   parameter   (default:
           $mynetworks)  specifies  a  permanent  whitelist  for SMTP
           client IP addresses.

           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)
                  Continue with the SMTP GREETING PHASE TESTS  below.

           drop   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
           in parallel.  These tests are described below, and are run
           before  the  client  may  see  the real SMTP server's "220
           text..." server greeting.

           When the SMTP client passes all greeting-phase 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
           portion   of   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)
                  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   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)
                  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   Drop the connection immediately.

    4C. DNS BLOCKLIST TEST
           The   postscreen_dnsbl_sites  parameter  (default:  empty)
           specifies a list of DNS blocklist servers.  These  lookups
           are made in parallel.

           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)
                  Forward  the  connection  to  a  real  SMTP  server
                  process.

           drop   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_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.

    CACHE CONTROLS
           postscreen_cache_cleanup_interval (12h)
                  The amount  of  time  between  postscreen(8)  cache
                  cleanup runs.

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

           postscreen_cache_retention_time (1d)
                  The amount of time that postscreen(8) will cache an
                  expired  temporary  whitelist  entry  before  it is
                  removed.

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

    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)