postfix-master/anvil.8.html

   1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
   2         "http://www.w3.org/TR/html4/loose.dtd">
   3 <html> <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
   5 <title> Postfix manual - anvil(8) </title>
   6 </head> <body> <pre>
   7 ANVIL(8)                                                              ANVIL(8)
   8
   9 <b>NAME</b>
  10        anvil - Postfix session count and request rate control
  11
  12 <b>SYNOPSIS</b>
  13        <b>anvil</b> [generic Postfix daemon options]
  14
  15 <b>DESCRIPTION</b>
  16        The  Postfix  <a href="anvil.8.html"><b>anvil</b>(8)</a>  server  maintains statistics about
  17        client connection counts or  client  request  rates.  This
  18        information  can  be  used  to defend against clients that
  19        hammer a server with either  too  many  simultaneous  ses-
  20        sions,  or with too many successive requests within a con-
  21        figurable time interval.  This server is designed  to  run
  22        under control by the Postfix <a href="master.8.html"><b>master</b>(8)</a> server.
  23
  24        In the following text, <b>ident</b> specifies a (service, client)
  25        combination. The  exact  syntax  of  that  information  is
  26        application-dependent;  the <a href="anvil.8.html"><b>anvil</b>(8)</a> server does not care.
  27
  28 <b>CONNECTION COUNT/RATE CONTROL</b>
  29        To register a new connection send the following request to
  30        the <a href="anvil.8.html"><b>anvil</b>(8)</a> server:
  31
  32            <b>request=connect</b>
  33            <b>ident=</b><i>string</i>
  34
  35        The  <a href="anvil.8.html"><b>anvil</b>(8)</a> server answers with the number of simultane-
  36        ous connections and the number  of  connections  per  unit
  37        time  for the (service, client) combination specified with
  38        <b>ident</b>:
  39
  40            <b>status=0</b>
  41            <b>count=</b><i>number</i>
  42            <b>rate=</b><i>number</i>
  43
  44        To register a disconnect event send the following  request
  45        to the <a href="anvil.8.html"><b>anvil</b>(8)</a> server:
  46
  47            <b>request=disconnect</b>
  48            <b>ident=</b><i>string</i>
  49
  50        The <a href="anvil.8.html"><b>anvil</b>(8)</a> server replies with:
  51
  52            <b>status=0</b>
  53
  54 <b>MESSAGE RATE CONTROL</b>
  55        To  register a message delivery request send the following
  56        request to the <a href="anvil.8.html"><b>anvil</b>(8)</a> server:
  57
  58            <b>request=message</b>
  59            <b>ident=</b><i>string</i>
  60
  61        The <a href="anvil.8.html"><b>anvil</b>(8)</a> server answers with  the  number  of  message
  62        delivery  requests per unit time for the (service, client)
  63        combination specified with <b>ident</b>:
  64
  65            <b>status=0</b>
  66            <b>rate=</b><i>number</i>
  67
  68 <b>RECIPIENT RATE CONTROL</b>
  69        To register a recipient request send the following request
  70        to the <a href="anvil.8.html"><b>anvil</b>(8)</a> server:
  71
  72            <b>request=recipient</b>
  73            <b>ident=</b><i>string</i>
  74
  75        The  <a href="anvil.8.html"><b>anvil</b>(8)</a>  server answers with the number of recipient
  76        addresses per unit time for the (service, client) combina-
  77        tion specified with <b>ident</b>:
  78
  79            <b>status=0</b>
  80            <b>rate=</b><i>number</i>
  81
  82 <b>TLS SESSION NEGOTIATION RATE CONTROL</b>
  83        The  features described in this section are available with
  84        Postfix 2.3 and later.
  85
  86        To register a request for a new (i.e. not cached) TLS ses-
  87        sion send the following request to the <a href="anvil.8.html"><b>anvil</b>(8)</a> server:
  88
  89            <b>request=newtls</b>
  90            <b>ident=</b><i>string</i>
  91
  92        The  <a href="anvil.8.html"><b>anvil</b>(8)</a>  server  answers  with the number of new TLS
  93        session requests per unit time for the  (service,  client)
  94        combination specified with <b>ident</b>:
  95
  96            <b>status=0</b>
  97            <b>rate=</b><i>number</i>
  98
  99        To retrieve new TLS session request rate information with-
 100        out updating the counter information, send:
 101
 102            <b>request=newtls_report</b>
 103            <b>ident=</b><i>string</i>
 104
 105        The <a href="anvil.8.html"><b>anvil</b>(8)</a> server answers with the  number  of  new  TLS
 106        session  requests  per unit time for the (service, client)
 107        combination specified with <b>ident</b>:
 108
 109            <b>status=0</b>
 110            <b>rate=</b><i>number</i>
 111
 112 <b>SECURITY</b>
 113        The <a href="anvil.8.html"><b>anvil</b>(8)</a> server does not talk to  the  network  or  to
 114        local  users, and can run chrooted at fixed low privilege.
 115
 116        The <a href="anvil.8.html"><b>anvil</b>(8)</a> server  maintains  an  in-memory  table  with
 117        information  about recent clients requests.  No persistent
 118        state is kept because standard system library routines are
 119        not sufficiently robust for update-intensive applications.
 120
 121        Although the in-memory state  is  kept  only  temporarily,
 122        this  may  require  a lot of memory on systems that handle
 123        connections from many remote clients.   To  reduce  memory
 124        usage, reduce the time unit over which state is kept.
 125
 126 <b>DIAGNOSTICS</b>
 127        Problems and transactions are logged to <b>syslogd</b>(8).
 128
 129        Upon exit, and every <b><a href="postconf.5.html#anvil_status_update_time">anvil_status_update_time</a></b> seconds, the
 130        server logs the maximal count and  rate  values  measured,
 131        together  with  (service, client) information and the time
 132        of day associated with those events.  In  order  to  avoid
 133        unnecessary  overhead, no measurements are done for activ-
 134        ity that isn't concurrency limited or rate limited.
 135
 136 <b>BUGS</b>
 137        Systems behind  network  address  translating  routers  or
 138        proxies appear to have the same client address and can run
 139        into connection count and/or rate limits falsely.
 140
 141        In this preliminary implementation, a count (or rate) lim-
 142        ited  server  process can have only one remote client at a
 143        time. If a server process  reports  multiple  simultaneous
 144        clients,  state is kept only for the last reported client.
 145
 146        The <a href="anvil.8.html"><b>anvil</b>(8)</a> server automatically discards client  request
 147        information  after  it  expires.   To prevent the <a href="anvil.8.html"><b>anvil</b>(8)</a>
 148        server from discarding client request rate information too
 149        early  or  too  late, a rate limited service should always
 150        register connect/disconnect events even when it  does  not
 151        explicitly limit them.
 152
 153 <b>CONFIGURATION PARAMETERS</b>
 154        On low-traffic mail systems, changes to <a href="postconf.5.html"><b>main.cf</b></a> are picked
 155        up automatically as <a href="anvil.8.html"><b>anvil</b>(8)</a> processes run for only a lim-
 156        ited  amount  of time. On other mail systems, use the com-
 157        mand "<b>postfix reload</b>" to speed up a change.
 158
 159        The text below provides  only  a  parameter  summary.  See
 160        <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
 161
 162        <b><a href="postconf.5.html#anvil_rate_time_unit">anvil_rate_time_unit</a> (60s)</b>
 163               The  time  unit  over which client connection rates
 164               and other rates are calculated.
 165
 166        <b><a href="postconf.5.html#anvil_status_update_time">anvil_status_update_time</a> (600s)</b>
 167               How frequently the  <a href="anvil.8.html"><b>anvil</b>(8)</a>  connection  and  rate
 168               limiting server logs peak usage information.
 169
 170        <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
 171               The  default  location  of  the Postfix <a href="postconf.5.html">main.cf</a> and
 172               <a href="master.5.html">master.cf</a> configuration files.
 173
 174        <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
 175               How much time a Postfix daemon process may take  to
 176               handle  a  request  before  it  is  terminated by a
 177               built-in watchdog timer.
 178
 179        <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
 180               The time limit for sending or receiving information
 181               over an internal communication channel.
 182
 183        <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b>
 184               The  maximum  amount  of  time that an idle Postfix
 185               daemon process waits  for  an  incoming  connection
 186               before terminating voluntarily.
 187
 188        <b><a href="postconf.5.html#max_use">max_use</a> (100)</b>
 189               The  maximal  number of incoming connections that a
 190               Postfix daemon process will service  before  termi-
 191               nating voluntarily.
 192
 193        <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
 194               The  process  ID  of  a  Postfix  command or daemon
 195               process.
 196
 197        <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
 198               The process name of a  Postfix  command  or  daemon
 199               process.
 200
 201        <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
 202               The syslog facility of Postfix logging.
 203
 204        <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
 205               The  mail  system  name  that  is  prepended to the
 206               process name in syslog  records,  so  that  "smtpd"
 207               becomes, for example, "postfix/smtpd".
 208
 209 <b>SEE ALSO</b>
 210        <a href="smtpd.8.html">smtpd(8)</a>, Postfix SMTP server
 211        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 212        <a href="master.5.html">master(5)</a>, generic daemon options
 213
 214 <b>README FILES</b>
 215        <a href="TUNING_README.html">TUNING_README</a>, performance tuning
 216
 217 <b>LICENSE</b>
 218        The Secure Mailer license must be  distributed  with  this
 219        software.
 220
 221 <b>HISTORY</b>
 222        The anvil service is available in Postfix 2.2 and later.
 223
 224 <b>AUTHOR(S)</b>
 225        Wietse Venema
 226        IBM T.J. Watson Research
 227        P.O. Box 704
 228        Yorktown Heights, NY 10598, USA
 229
 230                                                                       ANVIL(8)
 231 </pre> </body> </html>