    ANVIL(8)                                                              ANVIL(8)

    NAME
           anvil - Postfix session count and request rate control

    SYNOPSIS
           anvil [generic Postfix daemon options]

    DESCRIPTION
           The  Postfix  anvil(8) server maintains short-term statis-
           tics to defend against clients that hammer a  server  with
           either  too  many  simultaneous sessions, or with too many
           successive requests within a configurable  time  interval.
           This  server is designed to run under control by the Post-
           fix master(8) server.

           The anvil(8)  server  maintains  no  persistent  database.
           Standard 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(8) server:

               request=connect
               ident=string

           This registers a new connection for the (service,  client)
           combination  specified  with  ident.  The  anvil(8) 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(8) server:

               request=disconnect
               ident=string

           This  registers  a  disconnect  event  for  the  (service,
           client) combination specified  with  ident.  The  anvil(8)
           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(8) server:

               request=message
               ident=string

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

               status=0
               rate=number

           In  order  to  prevent the anvil(8) server from discarding
           client request rates too early or too late, a message rate
           limited  service  should  also register connect/disconnect
           events.

    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(8) server:

               request=recipient
               ident=string

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

               status=0
               rate=number

           In  order  to  prevent the anvil(8) server from discarding
           client request rates too early or too  late,  a  recipient
           rate  limited service should also register connect/discon-
           nect events.

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

           The anvil(8) server  maintains  an  in-memory  table  with
           information about recent clients of a connection count (or
           rate) limited service.  Although state is kept only tempo-
           rarily,  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
                  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 (postfix)
                  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
           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 is available in Postfix 2.2 and later.

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

                                                                          ANVIL(8)