1Perlbal::Plugin::ThrottUlsee(r3)Contributed Perl DocumenPteartliboanl::Plugin::Throttle(3)
2
3
4

NAME

6       Perlbal::Plugin::Throttle - Perlbal plugin that throttles connections
7       from hosts that connect too frequently.
8

SYNOPSIS

10           # in perlbal.conf
11
12           LOAD Throttle
13
14           CREATE POOL web
15               POOL web ADD 10.0.0.1:80
16
17           CREATE SERVICE throttler
18               SET role                        = reverse_proxy
19               SET listen                      = 0.0.0.0:80
20               SET pool                        = web
21
22               # 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
30               # limit which requests are throttled
31               SET path_regex                  = ^/webapp/
32               SET method_regex                = ^GET$
33
34               # 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
38               # granular logging (requires Perlbal::Plugin::Syslogger)
39               SET log_events                  = ban,unban,throttled,banned
40               SET log_only                    = false
41
42               # 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
47               SET plugins                     = Throttle
48           ENABLE throttler
49

DESCRIPTION

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

BEHAVIOR

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
60allowed
61
62           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
66probation
67
68           If no requests are received from an IP in the probation state for
69           throttle_threshold_seconds, it returns to the allowed state.
70
71           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
79throttled
80
81           If no requests are received from an IP in the throttled state for
82           delay seconds, it returns to the probation state.
83
84           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
89           Only after the most recently created connection from a given IP
90           exits the throttled state do violations and delay reset to 0.
91
92           Furthermore, if the violations exceeds ban_threshold, the
93           connection is closed and the IP moves to the banned state.
94
95           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
101banned
102
103           New connections from IPs in the banned state are immediately closed
104           with a 403 error response.
105
106           An IP leaves the banned state after ban_expiration seconds have
107           elapsed.
108

FEATURES

110       •   IP whitelist
111
112           Connections from IPs/CIDRs listed in the file specified by
113           whitelist_file are always allowed.
114
115       •   IP blacklist
116
117           Connections from IPs/CIDRs listed in the file specified by
118           blacklist_file immediately sent a "403 Forbidden" response.
119
120       •   Flexible attack response
121
122           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
127           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
131       •   Dynamic configuration
132
133           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
139       •   Path specificity
140
141           Throttling may be restricted to URI paths matching the path_regex
142           regex.
143
144       •   External shared state
145
146           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
152           Orthogonally, multiple throttlers which need to share memcacheds
153           but not state may specify distinct instance_name values.
154
155       •   Logging
156
157           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
164           •   ban
165
166               Log when a temporary local ban is added for an IP address.
167
168           •   unban
169
170               Log when a temporary local ban is removed for an IP address.
171
172           •   whitelisted
173
174               Log when a request is allowed because the source IP is on the
175               whitelist.
176
177           •   blacklisted
178
179               Log when a request is denied or throttled because the source IP
180               is on the blacklist.
181
182           •   banned
183
184               Log when a request is denied because the source IP is on the
185               temporary ban list for connecting excessively.
186
187           •   concurrent
188
189               Log when a request is denied because the source IP has too many
190               open connections waiting to be unthrottled.
191
192           •   throttled
193
194               Log when a request is throttled because the source IP was not
195               on the whitelist or blacklist.
196
197           •   all
198
199               Enables all the above logging options.
200
201           •   none
202
203               Disables all the above logging options.
204

CAVEATS

206       •   Dynamic configuration changes
207
208           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
212           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
216       •   List loading is blocking
217
218           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
223       •   Redirects
224
225           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

OPTIONAL DEPENDENCIES

236       •   Cache::Memcached::Async
237
238           Required for memcached support. This is the supported way to share
239           state between different perlbal instances.
240
241       •   Net::CIDR::Lite
242
243           Required for blacklist/whitelist support.
244
245       •   Perlbal::Plugin::Syslogger
246
247           Required for event logging support.
248

SEE ALSO

250       •   List of tunables in Throttle.pm.
251

TODO

253       •   Fix white/blacklist loading
254
255           Load CIDR lists asynchronously (perhaps in the manner of
256           Perlbal::Pool::_load_nodefile_async).
257

AUTHOR

259       Adam Thomason, <athomason@cpan.org>
260
262       Copyright (C) 2007-2011 by Say Media Inc, <cpan@sixapart.com>
263
264       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.
267
268
269
270perl v5.36.0                      2022-07-20      Perlbal::Plugin::Throttle(3)
Impressum