POSTSCREEN(8)                                                    POSTSCREEN(8)

NAME
       postscreen - Postfix zombie blocker

SYNOPSIS
       postscreen [generic Postfix daemon options]

DESCRIPTION
       The Postfix postscreen(8) server performs triage on multi-
       ple inbound SMTP connections at the  same  time.  While  a
       single  postscreen(8)  process  keeps  spambots  away from
       Postfix SMTP server processes, more  Postfix  SMTP  server
       processes remain available for legitimate clients.

       This program should not be used on SMTP ports that receive
       mail from end-user clients (MUAs). In  a  typical  deploy-
       ment,  postscreen(8)  is  used  on  the "port 25" service,
       while MUA clients submit mail via the submission  service.

       postscreen(8)  maintains a temporary whitelist for clients
       that have passed a number of tests.  When an  SMTP  client
       IP  address  is  whitelisted,  postscreen(8) hands off the
       connection immediately to a Postfix SMTP  server  process.
       This minimizes the overhead for legitimate mail.

       By  default,  postscreen(8)  logs statistics and hands off
       every connection to a Postfix SMTP server  process,  while
       excluding clients in mynetworks from all tests (primarily,
       to avoid problems with non-standard  SMTP  implementations
       in  network  appliances).   This  mode  is useful for non-
       destructive testing.

       In a typical production setting, postscreen(8) is  config-
       ured  to  reject  mail  from clients that fail one or more
       tests. postscreen(8) logs rejected mail  with  the  client
       address, helo, sender and recipient information.

       postscreen(8)  is  not an SMTP proxy; this is intentional.
       The purpose is to keep spambots  away  from  Postfix  SMTP
       server processes, while minimizing overhead for legitimate
       traffic.

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 821 (SMTP protocol)
       RFC 1123 (Host requirements)
       RFC 1652 (8bit-MIME transport)
       RFC 1869 (SMTP service extensions)
       RFC 1870 (Message Size Declaration)
       RFC 1985 (ETRN command)
       RFC 2034 (SMTP Enhanced Status Codes)
       RFC 2821 (SMTP protocol)
       Not: RFC 2920 (SMTP Pipelining)
       RFC 3207 (STARTTLS command)
       RFC 3461 (SMTP DSN Extension)
       RFC 3463 (Enhanced Status Codes)
       RFC 5321 (SMTP protocol, including multi-line 220 banners)

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

BUGS
       The postscreen(8) built-in SMTP protocol engine  currently
       does  not  announce support for AUTH, XCLIENT or XFORWARD.
       Support for AUTH may be added in the future.  In the  mean
       time, if you need to make these services available on port
       25, then do not enable  the  optional  "after  220  server
       greeting" tests, and do not use DNSBLs that reject traffic
       from dial-up and residential networks.

       The optional "after 220  server  greeting"  tests  involve
       postscreen(8)'s  built-in SMTP protocol engine. When these
       tests succeed, postscreen(8) adds the client to the tempo-
       rary  whitelist but it cannot not hand off the "live" con-
       nection to a Postfix SMTP server process in the middle  of
       a  session.   Instead,  postscreen(8)  defers  attempts to
       deliver mail with a 4XX status, and waits for  the  client
       to  disconnect.   The next time a good client connects, it
       will be allowed to talk to a Postfix SMTP  server  process
       to  deliver  mail.  postscreen(8)  mitigates the impact of
       this limitation by giving such  tests  a  long  expiration
       time.

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.

       NOTE:  Some  postscreen(8)  parameters  implement  stress-
       dependent behavior.   This  is  supported  only  when  the
       default  parameter  value is stress-dependent (that is, it
       looks like ${stress?X}${stress:Y}, or it is the  $name  of
       an  smtpd  parameter  with  a  stress-dependent  default).
       Other parameters always evaluate as if the stress  parame-
       ter value is the empty string.

COMPATIBILITY CONTROLS
       postscreen_command_filter ($smtpd_command_filter)
              A  mechanism to transform commands from remote SMTP
              clients.

       postscreen_discard_ehlo_keyword_address_maps  ($smtpd_dis-
       card_ehlo_keyword_address_maps)
              Lookup tables, indexed by the  remote  SMTP  client
              address,  with  case insensitive lists of EHLO key-
              words (pipelining, starttls, auth, etc.)  that  the
              postscreen(8)  server  will  not  send  in the EHLO
              response to a remote SMTP client.

       postscreen_discard_ehlo_keywords ($smtpd_discard_ehlo_key-
       words)
              A case insensitive list of EHLO keywords  (pipelin-
              ing,  starttls,  auth, etc.) that the postscreen(8)
              server will not send in  the  EHLO  response  to  a
              remote SMTP client.

TROUBLE SHOOTING CONTROLS
       postscreen_expansion_filter (see 'postconf -d' output)
              List   of   characters   that   are   permitted  in
              postscreen_reject_footer attribute expansions.

       postscreen_reject_footer ($smtpd_reject_footer)
              Optional information that is appended after  a  4XX
              or 5XX server response.

       soft_bounce (no)
              Safety net to keep mail queued that would otherwise
              be returned to the sender.

PERMANENT WHITE/BLACKLIST TEST
       This test is executed  immediately  after  a  remote  SMTP
       client  connects.  If a client is permanently whitelisted,
       the client will be handed off  immediately  to  a  Postfix
       SMTP server process.

       postscreen_access_list (permit_mynetworks)
              Permanent white/blacklist for remote SMTP client IP
              addresses.

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

MAIL EXCHANGER POLICY TESTS
       When a remote SMTP client is not on the  permanent  access
       list,  postscreen(8)  can  implement a number of whitelist
       tests before it grants the client  a  temporary  whitelist
       status to talk to a Postfix SMTP server process.

       By  listening  on  both  primary  and backup MX addresses,
       postscreen(8) can deny the temporary whitelist  status  to
       clients that connect only to backup MX hosts.

       postscreen_whitelist_interfaces (static:all)
              A  list  of local postscreen(8) server IP addresses
              where a  non-whitelisted  SMTP  client  can  obtain
              postscreen(8)'s  temporary whitelist status to talk
              to a Postfix SMTP server process.

BEFORE-GREETING TESTS
       These tests are executed before  the  remote  SMTP  client
       receives the "220 servername" greeting. If no tests remain
       after the successful completion of this phase, the  client
       will  be  handed  off immediately to a Postfix SMTP server
       process.

       dnsblog_service_name (dnsblog)
              The name of the dnsblog(8) service  entry  in  mas-
              ter.cf.

       postscreen_dnsbl_action (ignore)
              The  action  that  postscreen(8) takes when an SMTP
              client's  combined  DNSBL  score  is  equal  to  or
              greater  than  a  threshold  (as  defined  with the
              postscreen_dnsbl_sites and postscreen_dnsbl_thresh-
              old parameters).

       postscreen_dnsbl_reply_map (empty)
              A  mapping  from  actual  DNSBL  domain  name which
              includes a secret password,  to  the  DNSBL  domain
              name  that  postscreen  will  reply  with  when  it
              rejects mail.

       postscreen_dnsbl_sites (empty)
              Optional list of DNS white/blacklist domains,  fil-
              ters and weight factors.

       postscreen_dnsbl_threshold (1)
              The  inclusive  lower  bound  for  blocking an SMTP
              client,  based  on  its  combined  DNSBL  score  as
              defined  with the postscreen_dnsbl_sites parameter.

       postscreen_greet_action (ignore)
              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 (${stress?2}${stress:6}s)
              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
              (default:  up  to  2  seconds under stress, up to 6
              seconds otherwise).

       smtpd_service_name (smtpd)
              The internal service that postscreen(8)  hands  off
              allowed connections to.

AFTER-GREETING TESTS
       These  tests  are  executed  after  the remote SMTP client
       receives the "220 servername" greeting. If a client passes
       all  tests  during  this  phase,  it  will  receive  a 4XX
       response to RCPT TO commands until the  client  hangs  up.
       After this, the client will be allowed to talk directly to
       a Postfix SMTP server process.

       postscreen_bare_newline_action (ignore)
              The action that postscreen(8) takes  when  an  SMTP
              client  sends  a bare newline character, that is, a
              newline not preceded by carriage return.

       postscreen_bare_newline_enable (no)
              Enable "bare newline" SMTP protocol  tests  in  the
              postscreen(8) server.

       postscreen_disable_vrfy_command ($disable_vrfy_command)
              Disable  the SMTP VRFY command in the postscreen(8)
              daemon.

       postscreen_forbidden_commands ($smtpd_forbidden_commands)
              List of commands that the postscreen(8) server con-
              siders in violation of the SMTP protocol.

       postscreen_helo_required ($smtpd_helo_required)
              Require  that  a  remote  SMTP client sends HELO or
              EHLO before commencing a MAIL transaction.

       postscreen_non_smtp_command_action (drop)
              The action that postscreen(8) takes  when  an  SMTP
              client  sends  non-SMTP  commands as specified with
              the postscreen_forbidden_commands parameter.

       postscreen_non_smtp_command_enable (no)
              Enable   "non-SMTP   command"    tests    in    the
              postscreen(8) server.

       postscreen_pipelining_action (enforce)
              The  action  that  postscreen(8) takes when an SMTP
              client sends multiple commands instead  of  sending
              one  command and waiting for the server to respond.

       postscreen_pipelining_enable (no)
              Enable "pipelining"  SMTP  protocol  tests  in  the
              postscreen(8) server.

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

       postscreen_cache_map                   (btree:$data_direc-
       tory/postscreen_cache)
              Persistent storage  for  the  postscreen(8)  server
              decisions.

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

       postscreen_bare_newline_ttl (30d)
              The  amount of time that postscreen(8) will use the
              result from a successful "bare newline" SMTP proto-
              col test.

       postscreen_dnsbl_ttl (1h)
              The  amount of time that postscreen(8) will use the
              result from a successful DNS blocklist test.

       postscreen_greet_ttl (1d)
              The amount of time that postscreen(8) will use  the
              result from a successful PREGREET test.

       postscreen_non_smtp_command_ttl (30d)
              The  amount of time that postscreen(8) will use the
              result from a  successful  "non_smtp_command"  SMTP
              protocol test.

       postscreen_pipelining_ttl (30d)
              The  amount of time that postscreen(8) will use the
              result from a successful "pipelining" SMTP protocol
              test.

RESOURCE CONTROLS
       line_length_limit (2048)
              Upon  input,  long lines are chopped up into pieces
              of at most this length; upon delivery,  long  lines
              are reconstructed.

       postscreen_client_connection_count_limit
       ($smtpd_client_connection_count_limit)
              How  many  simultaneous  connections  any client is
              allowed to have with the postscreen(8) daemon.

       postscreen_command_count_limit (20)
              The limit on the total number of commands per  SMTP
              session  for postscreen(8)'s built-in SMTP protocol
              engine.

       postscreen_command_time_limit (${stress?10}${stress:300}s)
              The time limit to read an entire command line  with
              postscreen(8)'s built-in SMTP protocol engine.

       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_watchdog_timeout (10s)
              How much time a postscreen(8) process may  take  to
              respond  to  an SMTP client command or to perform a
              cache operation before it is terminated by a built-
              in watchdog timer.

STARTTLS CONTROLS
       postscreen_tls_security_level ($smtpd_tls_security_level)
              The  SMTP  TLS security level for the postscreen(8)
              server; when a non-empty value is  specified,  this
              overrides       the       obsolete       parameters
              postscreen_use_tls and postscreen_enforce_tls.

       tlsproxy_service_name (tlsproxy)
              The name of the tlsproxy(8) service entry  in  mas-
              ter.cf.

OBSOLETE STARTTLS SUPPORT CONTROLS
       These  parameters  are  supported  for  compatibility with
       smtpd(8) legacy parameters.

       postscreen_use_tls ($smtpd_use_tls)
              Opportunistic TLS:  announce  STARTTLS  support  to
              SMTP  clients,  but do not require that clients use
              TLS encryption.

       postscreen_enforce_tls ($smtpd_enforce_tls)
              Mandatory TLS: announce STARTTLS  support  to  SMTP
              clients,  and  require that clients use TLS encryp-
              tion.

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

       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.

       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
       tlsproxy(8), Postfix TLS proxy server
       dnsblog(8), DNS black/whitelist logger
       syslogd(8), system logging

README FILES
       POSTSCREEN_README, Postfix Postscreen Howto

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

HISTORY
       This service was introduced with Postfix version 2.8.

       Many  ideas in postscreen(8) were explored in earlier work
       by Michael Tokarev, in OpenBSD spamd, and in  MailChannels
       Traffic Control.

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

                                                                 POSTSCREEN(8)