anvil



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 statistics 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
       Postfix 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  (service,  client)
       combination  specified with ident. The anvil(8) server answers with the
       number of message delivery requests 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 message rate limited service should also
       register connect/disconnect events.


RECIPIENT RATE LIMITING

       When  a  remote client sends a recipient address, a recipient rate lim-
       ited server should send the following request to the anvil(8) server:

           request=recipient
           ident=string

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

           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/disconnect 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 temporarily, this may require a lot of mem-
       ory  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
       activity 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)  limited  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 con-
              figuration 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 dae-
              mon 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, "post-
              fix/smtpd".


SEE ALSO

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


README FILES

       Use "postconf readme_directory" or "postconf html_directory" to  locate
       this information.
       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)

Man(1) output converted with man2html