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)