external/ibm-public/postfix/dist/man/man8/anvil.8

   1 .\"     $NetBSD$
   2 .\"
   3 .TH ANVIL 8
   4 .ad
   5 .fi
   6 .SH NAME
   7 anvil
   8 \-
   9 Postfix session count and request rate control
  10 .SH "SYNOPSIS"
  11 .na
  12 .nf
  13 \fBanvil\fR [generic Postfix daemon options]
  14 .SH DESCRIPTION
  15 .ad
  16 .fi
  17 The Postfix \fBanvil\fR(8) server maintains statistics about
  18 client connection counts or client request rates. This
  19 information can be used to defend against clients that
  20 hammer a server with either too many simultaneous sessions,
  21 or with too many successive requests within a configurable
  22 time interval.  This server is designed to run under control
  23 by the Postfix \fBmaster\fR(8) server.
  24
  25 In the following text, \fBident\fR specifies a (service,
  26 client) combination. The exact syntax of that information
  27 is application-dependent; the \fBanvil\fR(8) server does
  28 not care.
  29 .SH "CONNECTION COUNT/RATE CONTROL"
  30 .na
  31 .nf
  32 .ad
  33 .fi
  34 To register a new connection send the following request to
  35 the \fBanvil\fR(8) server:
  36
  37 .nf
  38     \fBrequest=connect\fR
  39     \fBident=\fIstring\fR
  40 .fi
  41
  42 The \fBanvil\fR(8) server answers with the number of
  43 simultaneous connections and the number of connections per
  44 unit time for the (service, client) combination specified
  45 with \fBident\fR:
  46
  47 .nf
  48     \fBstatus=0\fR
  49     \fBcount=\fInumber\fR
  50     \fBrate=\fInumber\fR
  51 .fi
  52
  53 To register a disconnect event send the following request
  54 to the \fBanvil\fR(8) server:
  55
  56 .nf
  57     \fBrequest=disconnect\fR
  58     \fBident=\fIstring\fR
  59 .fi
  60
  61 The \fBanvil\fR(8) server replies with:
  62
  63 .nf
  64     \fBstatus=0\fR
  65 .fi
  66 .SH "MESSAGE RATE CONTROL"
  67 .na
  68 .nf
  69 .ad
  70 .fi
  71 To register a message delivery request send the following
  72 request to the \fBanvil\fR(8) server:
  73
  74 .nf
  75     \fBrequest=message\fR
  76     \fBident=\fIstring\fR
  77 .fi
  78
  79 The \fBanvil\fR(8) server answers with the number of message
  80 delivery requests per unit time for the (service, client)
  81 combination specified with \fBident\fR:
  82
  83 .nf
  84     \fBstatus=0\fR
  85     \fBrate=\fInumber\fR
  86 .fi
  87 .SH "RECIPIENT RATE CONTROL"
  88 .na
  89 .nf
  90 .ad
  91 .fi
  92 To register a recipient request send the following request
  93 to the \fBanvil\fR(8) server:
  94
  95 .nf
  96     \fBrequest=recipient\fR
  97     \fBident=\fIstring\fR
  98 .fi
  99
 100 The \fBanvil\fR(8) server answers with the number of recipient
 101 addresses per unit time for the (service, client) combination
 102 specified with \fBident\fR:
 103
 104 .nf
 105     \fBstatus=0\fR
 106     \fBrate=\fInumber\fR
 107 .fi
 108 .SH "TLS SESSION NEGOTIATION RATE CONTROL"
 109 .na
 110 .nf
 111 .ad
 112 .fi
 113 The features described in this section are available with
 114 Postfix 2.3 and later.
 115
 116 To register a request for a new (i.e. not cached) TLS session
 117 send the following request to the \fBanvil\fR(8) server:
 118
 119 .nf
 120     \fBrequest=newtls\fR
 121     \fBident=\fIstring\fR
 122 .fi
 123
 124 The \fBanvil\fR(8) server answers with the number of new
 125 TLS session requests per unit time for the (service, client)
 126 combination specified with \fBident\fR:
 127
 128 .nf
 129     \fBstatus=0\fR
 130     \fBrate=\fInumber\fR
 131 .fi
 132
 133 To retrieve new TLS session request rate information without
 134 updating the counter information, send:
 135
 136 .nf
 137     \fBrequest=newtls_report\fR
 138     \fBident=\fIstring\fR
 139 .fi
 140
 141 The \fBanvil\fR(8) server answers with the number of new
 142 TLS session requests per unit time for the (service, client)
 143 combination specified with \fBident\fR:
 144
 145 .nf
 146     \fBstatus=0\fR
 147     \fBrate=\fInumber\fR
 148 .fi
 149 .SH "SECURITY"
 150 .na
 151 .nf
 152 .ad
 153 .fi
 154 The \fBanvil\fR(8) server does not talk to the network or to local
 155 users, and can run chrooted at fixed low privilege.
 156
 157 The \fBanvil\fR(8) server maintains an in-memory table with
 158 information about recent clients requests.  No persistent
 159 state is kept because standard system library routines are
 160 not sufficiently robust for update-intensive applications.
 161
 162 Although the in-memory state is kept only temporarily, this
 163 may require a lot of memory on systems that handle connections
 164 from many remote clients.  To reduce memory usage, reduce
 165 the time unit over which state is kept.
 166 .SH DIAGNOSTICS
 167 .ad
 168 .fi
 169 Problems and transactions are logged to \fBsyslogd\fR(8).
 170
 171 Upon exit, and every \fBanvil_status_update_time\fR
 172 seconds, the server logs the maximal count and rate values measured,
 173 together with (service, client) information and the time of day
 174 associated with those events.
 175 In order to avoid unnecessary overhead, no measurements
 176 are done for activity that isn't concurrency limited or
 177 rate limited.
 178 .SH BUGS
 179 .ad
 180 .fi
 181 Systems behind network address translating routers or proxies
 182 appear to have the same client address and can run into connection
 183 count and/or rate limits falsely.
 184
 185 In this preliminary implementation, a count (or rate) limited server
 186 process can have only one remote client at a time. If a
 187 server process reports
 188 multiple simultaneous clients, state is kept only for the last
 189 reported client.
 190
 191 The \fBanvil\fR(8) server automatically discards client
 192 request information after it expires.  To prevent the
 193 \fBanvil\fR(8) server from discarding client request rate
 194 information too early or too late, a rate limited service
 195 should always register connect/disconnect events even when
 196 it does not explicitly limit them.
 197 .SH "CONFIGURATION PARAMETERS"
 198 .na
 199 .nf
 200 .ad
 201 .fi
 202 On low-traffic mail systems, changes to \fBmain.cf\fR are
 203 picked up automatically as \fBanvil\fR(8) processes run for
 204 only a limited amount of time. On other mail systems, use
 205 the command "\fBpostfix reload\fR" to speed up a change.
 206
 207 The text below provides only a parameter summary. See
 208 \fBpostconf\fR(5) for more details including examples.
 209 .IP "\fBanvil_rate_time_unit (60s)\fR"
 210 The time unit over which client connection rates and other rates
 211 are calculated.
 212 .IP "\fBanvil_status_update_time (600s)\fR"
 213 How frequently the \fBanvil\fR(8) connection and rate limiting server
 214 logs peak usage information.
 215 .IP "\fBconfig_directory (see 'postconf -d' output)\fR"
 216 The default location of the Postfix main.cf and master.cf
 217 configuration files.
 218 .IP "\fBdaemon_timeout (18000s)\fR"
 219 How much time a Postfix daemon process may take to handle a
 220 request before it is terminated by a built-in watchdog timer.
 221 .IP "\fBipc_timeout (3600s)\fR"
 222 The time limit for sending or receiving information over an internal
 223 communication channel.
 224 .IP "\fBmax_idle (100s)\fR"
 225 The maximum amount of time that an idle Postfix daemon process waits
 226 for an incoming connection before terminating voluntarily.
 227 .IP "\fBmax_use (100)\fR"
 228 The maximal number of incoming connections that a Postfix daemon
 229 process will service before terminating voluntarily.
 230 .IP "\fBprocess_id (read-only)\fR"
 231 The process ID of a Postfix command or daemon process.
 232 .IP "\fBprocess_name (read-only)\fR"
 233 The process name of a Postfix command or daemon process.
 234 .IP "\fBsyslog_facility (mail)\fR"
 235 The syslog facility of Postfix logging.
 236 .IP "\fBsyslog_name (see 'postconf -d' output)\fR"
 237 The mail system name that is prepended to the process name in syslog
 238 records, so that "smtpd" becomes, for example, "postfix/smtpd".
 239 .SH "SEE ALSO"
 240 .na
 241 .nf
 242 smtpd(8), Postfix SMTP server
 243 postconf(5), configuration parameters
 244 master(5), generic daemon options
 245 .SH "README FILES"
 246 .na
 247 .nf
 248 .ad
 249 .fi
 250 Use "\fBpostconf readme_directory\fR" or
 251 "\fBpostconf html_directory\fR" to locate this information.
 252 .na
 253 .nf
 254 TUNING_README, performance tuning
 255 .SH "LICENSE"
 256 .na
 257 .nf
 258 .ad
 259 .fi
 260 The Secure Mailer license must be distributed with this software.
 261 .SH "HISTORY"
 262 .na
 263 .nf
 264 .ad
 265 .fi
 266 The anvil service is available in Postfix 2.2 and later.
 267 .SH "AUTHOR(S)"
 268 .na
 269 .nf
 270 Wietse Venema
 271 IBM T.J. Watson Research
 272 P.O. Box 704
 273 Yorktown Heights, NY 10598, USA