ANVIL(8)                                                 ANVIL(8)

NAME
       anvil - Postfix per-client count and rate control

SYNOPSIS
       anvil [generic Postfix daemon options]

DESCRIPTION
       The  Postfix  anvil server maintains short-term statistics
       to defend against clients that hammer a server with either
       too  many parallel connections or with too many successive
       requests within a configurable time interval.  This server
       is  designed  to  run  under control by the Postfix master
       server.

       The anvil server maintains no persistent  database.  Stan-
       dard library utilities do not meet Postfix performance and
       robustness requirements.

CONNECTION COUNT/RATE LIMITING
       When a remote client  connects,  a  connection  count  (or
       rate)  limited server should send the following request to
       the anvil server:

           request=connect
           ident=string

       This registers a new connection for the (service,  client)
       combination specified with ident. The anvil server answers
       with the number of simultaneous connections and the number
       of  connections  per  unit time for that (service, client)
       combination:

           status=0
           count=number
           rate=number

       The rate is computed as the  number  of  connections  that
       were  registered  in the current "time unit" interval.  It
       is left up to the server to decide if  the  remote  client
       exceeds the connection count (or rate) limit.

       When  a  remote client disconnects, a connection count (or
       rate) limited server should send the following request  to
       the anvil server:

           request=disconnect
           ident=string

       This  registers  a  disconnect  event  for  the  (service,
       client) combination specified with ident. The anvil server
       replies with:

           status=0

MESSAGE RATE LIMITING
       When  a  remote client sends a message delivery request, a
       message rate limited  server  should  send  the  following
       request to the anvil server:

           request=message
           ident=string

       This  registers  a  message delivery request for the (ser-
       vice, client) combination specified with ident. The  anvil
       server   answers  with  the  number  of  message  delivery
       requests per unit time for that (service, client) combina-
       tion:

           status=0
           rate=number

       In  order  prevent the anvil server from discarding client
       request rates too early or too late, a message  rate  lim-
       ited   service  should  also  register  connect/disconnect
       events.

       This feature is available in Postfix 2.2 and later.

RECIPIENT RATE LIMITING
       When a remote client sends a recipient address, a  recipi-
       ent  rate limited server should send the following request
       to the anvil server:

           request=recipient
           ident=string

       This registers  a  recipient  address  for  the  (service,
       client) combination specified with ident. The anvil server
       answers with the number of recipient  addresses  per  unit
       time for that (service, client) combination:

           status=0
           rate=number

       In  order  prevent the anvil server from discarding client
       request rates too early or too late, a recipient rate lim-
       ited   service  should  also  register  connect/disconnect
       events.

       This feature is available in Postfix 2.2 and later.

SECURITY
       The anvil server does not talk to the network or to  local
       users, and can run chrooted at fixed low privilege.

       The  anvil server maintains an in-memory table with infor-
       mation about recent clients  of  a  connection  count  (or
       rate)  limited  service.  Although state is kept only tem-
       porarily, this may require a lot of memory on systems that
       handle  connections  from  many remote clients.  To reduce
       memory usage, reduce the time unit  over  which  state  is
       kept.

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

       Upon exit, and every anvil_status_update_time seconds, the
       server logs the maximal count and  rate  values  measured,
       together  with  (service, client) information and the time
       of day associated with those events.  In  order  to  avoid
       unnecessary  overhead, no measurements are done for activ-
       ity that isn't concurrency limited or rate limited.

BUGS
       Systems behind  network  address  translating  routers  or
       proxies appear to have the same client address and can run
       into connection count and/or rate limits falsely.

       In this preliminary implementation, a count (or rate) lim-
       ited  server can have only one remote client at a time. If
       a server reports multiple simultaneous  clients,  all  but
       the last reported client are ignored.

CONFIGURATION PARAMETERS
       Changes to main.cf are picked up automatically as anvil(8)
       processes run for only a limited amount of time.  Use  the
       command "postfix reload" to speed up a change.

       The  text  below  provides  only  a parameter summary. See
       postconf(5) for more details including examples.

       anvil_rate_time_unit (60s)
              The time unit over which  client  connection  rates
              and other rates are calculated.

       anvil_status_update_time (600s)
              How  frequently  the  anvil(8)  connection and rate
              limiting server logs peak usage information.

       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.

       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 the next service request
              before exiting.

       max_use (100)
              The maximal number of connection requests before  a
              Postfix daemon process terminates.

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

       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 (postfix)
              The  mail system name that is prepended to the pro-
              cess  name  in  syslog  records,  so  that  "smtpd"
              becomes, for example, "postfix/smtpd".

SEE ALSO
       smtpd(8), Postfix SMTP server
       postconf(5), configuration parameters
       master(5), generic daemon options

README FILES
       TUNING_README, performance tuning

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

HISTORY
       The anvil service was introduced with Postfix 2.1.

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

                                                         ANVIL(8)