Following feedback from a user, I have revised the ACL ratelimit
documentation. Patch below...
Tony.
--
<fanf@???> <dot@???>
http://dotat.at/ ${sg{\N${sg{\
N\}{([^N]*)(.)(.)(.*)}{\$1\$3\$2\$1\$3\n\$2\$3\$4\$3\n\$3\$2\$4}}\
\N}{([^N]*)(.)(.)(.*)}{\$1\$3\$2\$1\$3\n\$2\$3\$4\$3\n\$3\$2\$4}}
Index: doc-docbook/spec.ascd
===================================================================
RCS file: /home/cvs/exim/exim-doc/doc-docbook/spec.ascd,v
retrieving revision 1.4
diff -u -r1.4 spec.ascd
--- doc-docbook/spec.ascd 5 Dec 2005 14:38:18 -0000 1.4
+++ doc-docbook/spec.ascd 19 Dec 2005 14:57:02 -0000
@@ -14930,12 +14930,19 @@
%smtp_ratelimit_hosts%, Use: 'main', Type: 'host list'!!, Default: 'unset'
===
+[revisionflag="changed"]
cindex:[SMTP,rate limiting]
cindex:[limit,rate of message arrival]
cindex:[RCPT,rate limiting]
Some sites find it helpful to be able to limit the rate at which certain hosts
can send them messages, and the rate at which an individual message can specify
-recipients. When a host matches %smtp_ratelimit_hosts%, the values of
+recipients.
+Exim has two rate-limiting facilities. This section describes the
+older facility, which can limit rates within a single connection. The
+newer ratelimit ACL condition can limit rates across all connections.
+See <<SECTratelimit>> for details.
+
+When a host matches %smtp_ratelimit_hosts%, the values of
%smtp_ratelimit_mail% and %smtp_ratelimit_rcpt% are used to control the
rate of acceptance of MAIL and RCPT commands in a single SMTP session,
respectively. Each option, if set, must contain a set of four comma-separated
@@ -27506,9 +27513,7 @@
which clients can send email. This is more powerful than the %smtp_ratelimit_*%
options, because those options control the rate of commands in a single SMTP
session only, whereas the %ratelimit% condition works across all connections
-(concurrent and sequential) from the same client host. There's a script in
-_util/ratelimit.pl_ which extracts sending rates from log files, to assist with
-choosing appropriate settings when deploying the %ratelimit% ACL condition.
+(concurrent and sequential) from the same client host.
The syntax of the %ratelimit% condition is:
[revisionflag="changed"]
@@ -27521,23 +27526,39 @@
period 'p' then the condition is false; otherwise it is true.
[revisionflag="changed"]
+As a side-effect, the %ratelimit% condition sets the expansion variable
+$sender_rate$ to the client's computed rate, $sender_rate_limit$ to the
+configured value of 'm', and $sender_rate_period$ to the configured value of
+'p'.
+
+[revisionflag="changed"]
The parameter 'p' is the smoothing time constant, in the form of an Exim
time interval, for example, `8h` for eight hours. A larger time constant means
that it takes Exim longer to forget a client's past behaviour. The parameter
-'m' is the maximum number of messages that a client is permitted to send in a
+'m' is the maximum number of messages that a client is permitted to send in
+each time interval. It also specifies the number of messages permitted in a
fast burst. By increasing both 'm' and 'p' but keeping 'm/p' constant, you can
allow a client to send more messages in a burst without changing its overall
sending rate limit. Conversely, if 'm' and 'p' are both small, messages must be
sent at an even rate.
[revisionflag="changed"]
+There's a script in _util/ratelimit.pl_ which extracts sending rates from log
+files, to assist with choosing appropriate settings for 'm' and 'p' when
+deploying the %ratelimit% ACL condition. The script prints usage instructions
+when it is run with no arguments.
+
+[revisionflag="changed"]
The key is used to look up the data for calculating the client's average
sending rate. This data is stored in a database maintained by Exim in its spool
-directory, alongside the retry and other hints databases. You can limit the
-sending rate of each authenticated user, independent of the computer they are
-sending from, by setting the key to $authenticated_id$. The default key is
-$sender_host_address$, which applies the limit to the client host, independent
-of the sender.
+directory, alongside the retry and other hints databases. The default key is
+$sender_host_address$, which applies the limit to each client host IP address.
+By changing the key you can change how Exim identifies clients for the purpose
+of ratelimiting. For example, to limit the sending rate of each authenticated
+user, independent of the computer they are sending from, set the key to
+$authenticated_id$. You must ensure that the lookup key is meaningful; for
+example, $authenticated_id$ is only meaningful if the client has
+authenticated, and you can check with with the %authenticated% ACL condition.
[revisionflag="changed"]
Internally, Exim includes the smoothing constant 'p' and the options in the
@@ -27553,9 +27574,11 @@
the other parameters.
[revisionflag="changed"]
-The %per_conn% option limits the client's connection rate. The %per_mail%
-option limits the client's rate of sending messages. This is the default if
-none of the %per_*% options is specified.
+The %per_conn% option limits the client's connection rate.
+
+[revisionflag="changed"]
+The %per_mail% option limits the client's rate of sending messages. This is
+the default if none of the %per_*% options is specified.
[revisionflag="changed"]
The %per_byte% option limits the sender's email bandwidth. Note that it is best
@@ -27598,13 +27621,8 @@
average rate of successfully sent email, which cannot be greater than the
maximum. If the client is over the limit it will suffer some counter-measures,
but it will still be able to send email at the configured maximum rate,
-whatever the rate of its attempts.
-
-[revisionflag="changed"]
-As a side-effect, the %ratelimit% condition sets the expansion variable
-$sender_rate$ to the client's computed rate, $sender_rate_limit$ to the
-configured value of 'm', and $sender_rate_period$ to the configured value of
-'p'.
+whatever the rate of its attempts. This is generally the better choice if you
+have clients that retry automatically.
[revisionflag="changed"]
Exim's other ACL facilities are used to define what counter-measures are taken
@@ -27627,6 +27645,7 @@
# Keep authenticated users under control
deny
+ authenticated = *
ratelimit = 100 / 1d / strict / $authenticated_id
# System-wide rate limit
