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

SECURITY

106       The anvil(8) server does not talk to the network or to local users, and
107       can run chrooted at fixed low privilege.
108
109       The anvil(8) server maintains an in-memory table with information about
110       recent clients requests.  No persistent state is kept because  standard
111       system  library  routines are not sufficiently robust for update-inten‐
112       sive applications.
113
114       Although the in-memory state is kept only temporarily, this may require
115       a  lot  of  memory  on systems that handle connections from many remote
116       clients.  To reduce memory usage, reduce the time unit over which state
117       is kept.
118

DIAGNOSTICS

120       Problems and transactions are logged to syslogd(8).
121
122       Upon  exit, and every anvil_status_update_time seconds, the server logs
123       the maximal count and rate values  measured,  together  with  (service,
124       client)  information  and the time of day associated with those events.
125       In order to avoid unnecessary overhead, no measurements  are  done  for
126       activity that isn't concurrency limited or rate limited.
127

BUGS

129       Systems behind network address translating routers or proxies appear to
130       have the same client address and can run into connection  count  and/or
131       rate limits falsely.
132
133       In  this  preliminary  implementation, a count (or rate) limited server
134       process can have only one remote client at a time. If a server  process
135       reports  multiple simultaneous clients, state is kept only for the last
136       reported client.
137
138       The anvil(8) server automatically discards client  request  information
139       after  it  expires.   To  prevent  the  anvil(8) server from discarding
140       client request rate information too early or too late, a  rate  limited
141       service  should  always register connect/disconnect events even when it
142       does not explicitly limit them.
143

CONFIGURATION PARAMETERS

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

SEE ALSO

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

README FILES

201       Use  "postconf readme_directory" or "postconf html_directory" to locate
202       this information.
203       TUNING_README, performance tuning
204

LICENSE

206       The Secure Mailer license must be distributed with this software.
207

HISTORY

209       The anvil service is available in Postfix 2.2 and later.
210

AUTHOR(S)

212       Wietse Venema
213       IBM T.J. Watson Research
214       P.O. Box 704
215       Yorktown Heights, NY 10598, USA
216
217
218
219                                                                      ANVIL(8)
Impressum