1ANVIL(8)                    System Manager's Manual                   ANVIL(8)
2
3
4

NAME

6       anvil - Postfix session count and request rate control
7

SYNOPSIS

9       anvil [generic Postfix daemon options]
10

DESCRIPTION

12       The  Postfix  anvil(8) server maintains statistics about client connec‐
13       tion counts or client request rates. This information can  be  used  to
14       defend against clients that hammer a server with either too many simul‐
15       taneous sessions, or with too many successive requests within a config‐
16       urable  time interval.  This server is designed to run under control by
17       the Postfix master(8) server.
18
19       In the following text, ident specifies a (service, client) combination.
20       The  exact  syntax  of  that  information is application-dependent; the
21       anvil(8) server does not care.
22

CONNECTION COUNT/RATE CONTROL

24       To register a new connection send the following request to the anvil(8)
25       server:
26
27           request=connect
28           ident=string
29
30       The anvil(8) server answers with the number of simultaneous connections
31       and the number of connections per unit time for the  (service,  client)
32       combination specified with ident:
33
34           status=0
35           count=number
36           rate=number
37
38       To  register  a  disconnect  event  send  the  following request to the
39       anvil(8) server:
40
41           request=disconnect
42           ident=string
43
44       The anvil(8) server replies with:
45
46           status=0
47

MESSAGE RATE CONTROL

49       To register a message delivery request send the  following  request  to
50       the anvil(8) server:
51
52           request=message
53           ident=string
54
55       The  anvil(8)  server  answers  with  the  number  of  message delivery
56       requests per unit time for the (service, client) combination  specified
57       with ident:
58
59           status=0
60           rate=number
61

RECIPIENT RATE CONTROL

63       To  register  a  recipient  request  send  the following request to the
64       anvil(8) server:
65
66           request=recipient
67           ident=string
68
69       The anvil(8) server answers with the number of recipient addresses  per
70       unit time for the (service, client) combination specified with ident:
71
72           status=0
73           rate=number
74

TLS SESSION NEGOTIATION RATE CONTROL

76       The  features  described in this section are available with Postfix 2.3
77       and later.
78
79       To register a request for a new (i.e. not cached) TLS session send  the
80       following request to the anvil(8) server:
81
82           request=newtls
83           ident=string
84
85       The anvil(8) server answers with the number of new TLS session requests
86       per unit time for the  (service,  client)  combination  specified  with
87       ident:
88
89           status=0
90           rate=number
91
92       To  retrieve  new TLS session request rate information without updating
93       the counter information, send:
94
95           request=newtls_report
96           ident=string
97
98       The anvil(8) server answers with the number of new TLS session requests
99       per  unit  time  for  the  (service, client) combination specified with
100       ident:
101
102           status=0
103           rate=number
104

AUTH RATE CONTROL

106       To register an AUTH request send the following request to the  anvil(8)
107       server:
108
109           request=auth
110           ident=string
111
112       The  anvil(8)  server answers with the number of auth requests per unit
113       time for the (service, client) combination specified with ident:
114
115           status=0
116           rate=number
117

SECURITY

119       The anvil(8) server does not talk to the network or to local users, and
120       can run chrooted at fixed low privilege.
121
122       The anvil(8) server maintains an in-memory table with information about
123       recent clients requests.  No persistent state is kept because  standard
124       system  library  routines are not sufficiently robust for update-inten‐
125       sive applications.
126
127       Although the in-memory state is kept only temporarily, this may require
128       a  lot  of  memory  on systems that handle connections from many remote
129       clients.  To reduce memory usage, reduce the time unit over which state
130       is kept.
131

DIAGNOSTICS

133       Problems and transactions are logged to syslogd(8) or postlogd(8).
134
135       Upon  exit, and every anvil_status_update_time seconds, the server logs
136       the maximal count and rate values  measured,  together  with  (service,
137       client)  information  and the time of day associated with those events.
138       In order to avoid unnecessary overhead, no measurements  are  done  for
139       activity that isn't concurrency limited or rate limited.
140

BUGS

142       Systems behind network address translating routers or proxies appear to
143       have the same client address and can run into connection  count  and/or
144       rate limits falsely.
145
146       In  this  preliminary  implementation, a count (or rate) limited server
147       process can have only one remote client at a time. If a server  process
148       reports  multiple simultaneous clients, state is kept only for the last
149       reported client.
150
151       The anvil(8) server automatically discards client  request  information
152       after  it  expires.   To  prevent  the  anvil(8) server from discarding
153       client request rate information too early or too late, a  rate  limited
154       service  should  always register connect/disconnect events even when it
155       does not explicitly limit them.
156

CONFIGURATION PARAMETERS

158       On low-traffic mail systems, changes to main.cf are picked up automati‐
159       cally  as  anvil(8) processes run for only a limited amount of time. On
160       other mail systems, use the command "postfix  reload"  to  speed  up  a
161       change.
162
163       The  text  below provides only a parameter summary. See postconf(5) for
164       more details including examples.
165
166       anvil_rate_time_unit (60s)
167              The time unit over which client connection rates and other rates
168              are calculated.
169
170       anvil_status_update_time (600s)
171              How  frequently the anvil(8) connection and rate limiting server
172              logs peak usage information.
173
174       config_directory (see 'postconf -d' output)
175              The default location of the Postfix main.cf and  master.cf  con‐
176              figuration files.
177
178       daemon_timeout (18000s)
179              How  much  time  a  Postfix  daemon process may take to handle a
180              request before it is terminated by a built-in watchdog timer.
181
182       ipc_timeout (3600s)
183              The time limit for sending  or  receiving  information  over  an
184              internal communication channel.
185
186       max_idle (100s)
187              The  maximum  amount of time that an idle Postfix daemon process
188              waits for an incoming connection before terminating voluntarily.
189
190       max_use (100)
191              The maximal number of incoming connections that a Postfix daemon
192              process will service before terminating voluntarily.
193
194       process_id (read-only)
195              The process ID of a Postfix command or daemon process.
196
197       process_name (read-only)
198              The process name of a Postfix command or daemon process.
199
200       syslog_facility (mail)
201              The syslog facility of Postfix logging.
202
203       syslog_name (see 'postconf -d' output)
204              A  prefix  that  is  prepended  to  the  process  name in syslog
205              records, so that, for example, "smtpd" becomes "prefix/smtpd".
206
207       Available in Postfix 3.3 and later:
208
209       service_name (read-only)
210              The master.cf service name of a Postfix daemon process.
211

SEE ALSO

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

README FILES

218       Use "postconf readme_directory" or "postconf html_directory" to  locate
219       this information.
220       TUNING_README, performance tuning
221

LICENSE

223       The Secure Mailer license must be distributed with this software.
224

HISTORY

226       The anvil service is available in Postfix 2.2 and later.
227

AUTHOR(S)

229       Wietse Venema
230       IBM T.J. Watson Research
231       P.O. Box 704
232       Yorktown Heights, NY 10598, USA
233
234       Wietse Venema
235       Google, Inc.
236       111 8th Avenue
237       New York, NY 10011, USA
238
239
240
241                                                                      ANVIL(8)
Impressum