1Perlbal::Plugin::ThrottUlsee(r3)Contributed Perl DocumenPteartliboanl::Plugin::Throttle(3)
2
6 Perlbal::Plugin::Throttle - Perlbal plugin that throttles connections
7 from hosts that connect too frequently.
8
10 # in perlbal.conf
11 LOAD Throttle
13 CREATE POOL web
15 POOL web ADD 10.0.0.1:80
16 CREATE SERVICE throttler
18 SET role = reverse_proxy
19 SET listen = 0.0.0.0:80
20 SET pool = web
21 # adjust throttler aggressiveness
23 SET initial_delay = 10
24 SET max_delay = 60
25 SET throttle_threshold_seconds = 3
26 SET max_concurrent = 2
27 SET ban_threshold = 4
28 SET ban_expiration = 180
29 # limit which requests are throttled
31 SET path_regex = ^/webapp/
32 SET method_regex = ^GET$
33 # allow or ban specific addresses or range (requires Net::CIDR::Lite)
35 SET whitelist_file = conf/whitelist.txt
36 SET blacklist_file = conf/blacklist.txt
37 # granular logging (requires Perlbal::Plugin::Syslogger)
39 SET log_events = ban,unban,throttled,banned
40 SET log_only = false
41 # share state between perlbals (requires Cache::Memcached::Async)
43 SET memcached_servers = 10.0.2.1:11211,10.0.2.2:11211
44 SET memcached_async_clients = 4
45 SET instance_name = mywebapp
46 SET plugins = Throttle
48 ENABLE throttler
49
51 This plugin intercepts HTTP requests to a Perlbal service and slows or
52 drops connections from IP addresses which are determined to be
53 connecting too fast.
54
56 An IP address address may be in one of four states depending on its
57 recent activity; that state determines how new requests from the IP are
58 handled:
59 • allowed
61 An IP begins in the allowed state. When a request is received from
63 an IP in this state, the request is handled immediately and the IP
64 enters the probation state.
65 • probation
67 If no requests are received from an IP in the probation state for
69 throttle_threshold_seconds, it returns to the allowed state.
70 When a new request is received from an IP in the probation state,
72 the IP enters the throttled state and is assigned a delay property
73 initially equal to initial_delay. Connection to a backend is
74 postponed for delay seconds while perlbal continues to work. If the
75 connection is still open after the delay, the request is then
76 handled normally. A dropped connection does not change the IP's
77 delay value.
78 • throttled
80 If no requests are received from an IP in the throttled state for
82 delay seconds, it returns to the probation state.
83 When a new request is received from an IP in the throttled state,
85 its violations property is incremented, and its delay property is
86 doubled (up to a maximum of max_delay). The request is postponed
87 for the new value of delay.
88 Only after the most recently created connection from a given IP
90 exits the throttled state do violations and delay reset to 0.
91 Furthermore, if the violations exceeds ban_threshold, the
93 connection is closed and the IP moves to the banned state.
94 IPs in the throttled state may have no more than max_concurrent
96 connections being delayed at once. Any additional requests received
97 in that circumstance are sent a "503 Too many connections"
98 response. Long-running requests which have already been connected
99 to a backend do not count towards this limit.
100 • banned
102 New connections from IPs in the banned state are immediately closed
104 with a 403 error response.
105 An IP leaves the banned state after ban_expiration seconds have
107 elapsed.
108
110 • IP whitelist
111 Connections from IPs/CIDRs listed in the file specified by
113 whitelist_file are always allowed.
114 • IP blacklist
116 Connections from IPs/CIDRs listed in the file specified by
118 blacklist_file immediately sent a "403 Forbidden" response.
119 • Flexible attack response
121 For services where throttling should not normally be enabled, use
123 the default_action tunable. When default_action is set to "allow",
124 new connections from non-white/blacklisted IPs will not be
125 throttled.
126 Furthermore, if throttling should only apply to specific clients,
128 set blacklist_action to "throttle". Blacklisted connections will
129 then be throttled instead of denied.
130 • Dynamic configuration
132 Most service tunables may be updated from the management port,
134 after which the new values will be respected (although see
135 "CAVEATS"). To reload the whitelist and blacklist files, issue the
136 throttle reload whitelist or throttle reload blacklist command to
137 the service.
138 • Path specificity
140 Throttling may be restricted to URI paths matching the path_regex
142 regex.
143 • External shared state
145 The plugin stores state which IPs have been seen in a memcached(1)
147 instance. This allows many throttlers to share their state and
148 also minimizes memory use within the perlbal. If state exceeds the
149 capacity of the memcacheds, the least-recently seen IPs will be
150 forgotten, effectively resetting them to the allowed state.
151 Orthogonally, multiple throttlers which need to share memcacheds
153 but not state may specify distinct instance_name values.
154 • Logging
156 If Perlbal::Plugin::Syslogger is installed and registered with the
158 service, Throttle can use it to send syslog messages regarding
159 actions that are taken. Granular control for which events are
160 logged is available via the log_events parameter. log_events is
161 composed of one or more of the following events, separated by
162 commas:
163 • ban
165 Log when a temporary local ban is added for an IP address.
167 • unban
169 Log when a temporary local ban is removed for an IP address.
171 • whitelisted
173 Log when a request is allowed because the source IP is on the
175 whitelist.
176 • blacklisted
178 Log when a request is denied or throttled because the source IP
180 is on the blacklist.
181 • banned
183 Log when a request is denied because the source IP is on the
185 temporary ban list for connecting excessively.
186 • concurrent
188 Log when a request is denied because the source IP has too many
190 open connections waiting to be unthrottled.
191 • throttled
193 Log when a request is throttled because the source IP was not
195 on the whitelist or blacklist.
196 • all
198 Enables all the above logging options.
200 • none
202 Disables all the above logging options.
204
206 • Dynamic configuration changes
207 Changes to certain service tunables will not be noticed until the
209 throttle reload config management command is issued. These include
210 log_events, path_regex, and method_regex).
211 Changes to certain other tunables will not be respected after the
213 plugin has been registered. These include memcached_servers and
214 memcached_async_clients.
215 • List loading is blocking
217 The throttle reload whitelist and throttle reload blacklist
219 management commands load the whitelist and blacklist files
220 synchronously, which will cause the perlbal to hang until it
221 completes.
222 • Redirects
224 If a handled request returns a 30x response code and the redirect
226 URI is also throttled, then the client's attempt to follow the
227 redirect will necessarily be delayed by initial_delay. Fixing this
228 would require that the plugin inspect the HTTP response headers,
229 which would incur a lot of overhead. To workaround, try to have
230 your backend not return 30x's if both the original and redirect URI
231 are proxied by the same throttler instance (yes, this is difficult
232 for the case where a backend 302s to add a trailing / to a
233 directory).
234
236 • Cache::Memcached::Async
237 Required for memcached support. This is the supported way to share
239 state between different perlbal instances.
240 • Net::CIDR::Lite
242 Required for blacklist/whitelist support.
244 • Perlbal::Plugin::Syslogger
246 Required for event logging support.
248
250 • List of tunables in Throttle.pm.
251
253 • Fix white/blacklist loading
254 Load CIDR lists asynchronously (perhaps in the manner of
256 Perlbal::Pool::_load_nodefile_async).
257
259 Adam Thomason, <athomason@cpan.org>
260
262 Copyright (C) 2007-2011 by Say Media Inc, <cpan@sixapart.com>
263 This library is free software; you can redistribute it and/or modify it
265 under the same terms as Perl itself, either Perl version 5.8.6 or, at
266 your option, any later version of Perl 5 you may have available.
267perl v5.36.0 2023-01-18 Perlbal::Plugin::Throttle(3)