Debian Codegraph @

src/modules/pike/README

raw
1 pike Module
2
3 Bogdan-Andrei Iancu
4
5 Voice Sistem SRL
6
7 Edited by
8
9 Bogdan-Andrei Iancu
10
11 Copyright © 2003 FhG FOKUS
12 __________________________________________________________________
13
14 Table of Contents
15
16 1. Admin Guide
17
18 1. Overview
19 2. Dependencies
20
21 2.1. Kamailio Modules
22 2.2. External Libraries or Applications
23
24 3. Parameters
25
26 3.1. sampling_time_unit (integer)
27 3.2. reqs_density_per_unit (integer)
28 3.3. remove_latency (integer)
29 3.4. pike_log_level (integer)
30
31 4. Functions
32
33 4.1. pike_check_req()
34 4.2. pike_check_ip(ipaddr)
35
36 5. RPC Commands
37
38 5.1. pike.top
39
40 2. RPC calls
41
42 1. pike.top
43 2. pike.list
44
45 3. Developer Guide
46
47 List of Examples
48
49 1.1. Set sampling_time_unit parameter
50 1.2. Set reqs_density_per_unit parameter
51 1.3. Set remove_latency parameter
52 1.4. Set pike_log_level parameter
53 1.5. pike_check_req usage
54 1.6. pike_check_ip usage
55 2.1. Using pike.top
56 3.1. Tree of IP addresses
57
58 Chapter 1. Admin Guide
59
60 Table of Contents
61
62 1. Overview
63 2. Dependencies
64
65 2.1. Kamailio Modules
66 2.2. External Libraries or Applications
67
68 3. Parameters
69
70 3.1. sampling_time_unit (integer)
71 3.2. reqs_density_per_unit (integer)
72 3.3. remove_latency (integer)
73 3.4. pike_log_level (integer)
74
75 4. Functions
76
77 4.1. pike_check_req()
78 4.2. pike_check_ip(ipaddr)
79
80 5. RPC Commands
81
82 5.1. pike.top
83
84 1. Overview
85
86 The pike module keeps trace of all (or selected ones) incoming
87 request's IP source and blocks the ones that exceed the limit. It works
88 simultaneously for IPv4 and IPv6 addresses.
89
90 The module does not implement any actions on blocking - it just simply
91 reports that there is high traffic from an IP; what to do, is the
92 administrator decision (via scripting).
93
94 2. Dependencies
95
96 2.1. Kamailio Modules
97 2.2. External Libraries or Applications
98
99 2.1. Kamailio Modules
100
101 The following modules must be loaded before this module:
102 * No dependencies on other Kamailio modules.
103
104 2.2. External Libraries or Applications
105
106 The following libraries or applications must be installed before
107 running Kamailio with this module loaded:
108 * None.
109
110 3. Parameters
111
112 3.1. sampling_time_unit (integer)
113 3.2. reqs_density_per_unit (integer)
114 3.3. remove_latency (integer)
115 3.4. pike_log_level (integer)
116
117 3.1. sampling_time_unit (integer)
118
119 Time period in seconds used for sampling (or the sampling accuracy).
120 The smaller the better, but slower. If you want to detect peeks, use a
121 small one. To limit the access (like total number of requests on a long
122 period of time) to a proxy resource (a gateway for example), use a
123 bigger value of this parameter.
124
125 IMPORTANT: a too small value may lead to performance penalties due to
126 timer process overloading.
127
128 Default value is “2”.
129
130 Example 1.1. Set sampling_time_unit parameter
131 ...
132 modparam("pike", "sampling_time_unit", 10)
133 ...
134
135 3.2. reqs_density_per_unit (integer)
136
137 How many requests should be allowed per sampling_time_unit before
138 blocking all the incoming request from that IP. Practically, the
139 blocking limit is between ( let's have x=reqs_density_per_unit) x and
140 3*x for IPv4 addresses and between x and 8*x for IPv6 addresses.
141
142 Default value is 30.
143
144 Example 1.2. Set reqs_density_per_unit parameter
145 ...
146 modparam("pike", "reqs_density_per_unit", 30)
147 ...
148
149 3.3. remove_latency (integer)
150
151 Specifies for how long the IP address will be kept in memory after the
152 last request from that IP address. It's a sort of timeout value, in
153 seconds. Note that it is not the duration to keep the IP in state
154 'blocked'. An IP is unblocked next occurrence of 'sampling_time_unit'
155 that does not exceed 'reqs_density_per_unit'. Keeping an IP in memory
156 results in faster reaching of blocked state -- see the notes about the
157 limits of getting to state 'blocked'.
158
159 Default value is 120.
160
161 Example 1.3. Set remove_latency parameter
162 ...
163 modparam("pike", "remove_latency", 130)
164 ...
165
166 3.4. pike_log_level (integer)
167
168 Syslog log level to be used by module to auto report the blocking (only
169 first time) and unblocking of IPs detected as source of floods.
170
171 Default value is 1 (L_WARN).
172
173 Example 1.4. Set pike_log_level parameter
174 ...
175 modparam("pike", "pike_log_level", -1)
176 ...
177
178 4. Functions
179
180 4.1. pike_check_req()
181 4.2. pike_check_ip(ipaddr)
182
183 4.1. pike_check_req()
184
185 Process the source IP of the current request and return false if the IP
186 was exceeding the blocking limit.
187
188 Return codes:
189 * 1 (true) - IP is not to be blocked or internal error occurred.
190
191 Warning
192 IMPORTANT: in case of internal error, the function returns true to
193 avoid reporting the current processed IP as blocked.
194 * -1 (false) - IP is source of flooding, previously detected
195 * -2 (false) - IP is detected as a new source of flooding - first
196 time detection
197
198 This function can be used from REQUEST_ROUTE|ONREPLY_ROUTE.
199
200 Example 1.5. pike_check_req usage
201 ...
202 if (!pike_check_req()) { exit; };
203 ...
204
205 4.2. pike_check_ip(ipaddr)
206
207 Process the IP address parameter and return false if it was exceeding
208 the blocking limit. The return codes are the same from
209 pike_check_req().
210
211 The parameter can contain variables.
212
213 This function can be used from REQUEST_ROUTE|ONREPLY_ROUTE.
214
215 Example 1.6. pike_check_ip usage
216 ...
217 if (!pike_check_ip("1.2.3.4")) { exit; };
218 ...
219 if (!pike_check_ip("$si")) { exit; };
220 ...
221
222 5. RPC Commands
223
224 5.1. pike.top
225
226 5.1. pike.top
227
228 Lists nodes in the pike tree.
229
230 Name: pike.top
231
232 Parameters: filter (optional) - it can be "ALL", "HOT" or "WARM". If
233 missing, the "HOT" nodes are listed.
234
235 RPC Command Example:
236 ...
237 kamctl rpc pike.top
238 ...
239
240 Chapter 2. RPC calls
241
242 Table of Contents
243
244 1. pike.top
245 2. pike.list
246
247 1. pike.top
248
249 Pike.top behaves like a 'top' command and shows source IP addresses of
250 incoming requestes to pike_check_req() function.
251
252 The IP list is sorted by sum of leaf hits (prev and curr) descending
253 and in second level by hits.
254
255 Some IPs could be marked as HOT depending on theirs request rates.
256
257 pike.top command can take one string parameter which specifies what
258 kind of nodes you are interested in. Possible values are HOT or ALL. If
259 no argument is given, it behaves as HOT was used.
260
261 Marking nodes HOT is done on server side, client only presents given
262 data and make some postprocessing like sorting.
263
264 Output of this command is a simple dump of ip_tree nodes marked as
265 ip-leafs.
266
267 Example 2.1. Using pike.top
268 ...
269 kamcli rpc pike.top ALL
270 ...
271
272 2. pike.list
273
274 Alias for "pike.top" command.
275
276 Chapter 3. Developer Guide
277
278 One single tree (for both IPv4 and IPv6) is used. Each node contains a
279 byte, the IP addresses stretching from root to the leafs.
280
281 Example 3.1. Tree of IP addresses
282 / 193 - 175 - 132 - 164
283 tree root / \ - 142
284 \ 195 - 37 - 78 - 163
285 \ - 79 - 134
286
287 To detect the whole address, step by step, from the root to the leafs,
288 the nodes corresponding to each byte of the ip address are expanded. In
289 order to be expended a node has to be hit for a given number of times
290 (possible by different addresses; in the previous example, the node
291 “37” was expended by the 195.37.78.163 and 195.37.79.134 hits).
292
293 For 193.175.132.164 with x= reqs_density_per_unit:
294 * After first req hits -> the “193” node is built.
295 * After x more hits, the “175” node is built; the hits of “193” node
296 are split between itself and its child--both of them gone have x/2.
297 * And so on for node “132” and “164”.
298 * Once “164” build the entire address can be found in the tree. “164”
299 becomes a leaf. After it will be hit as a leaf for x times, it will
300 become “RED” (further request from this address will be blocked).
301
302 So, to build and block this address were needed 3*x hits. Now, if reqs
303 start coming from 193.175.132.142, the first 3 bytes are already in the
304 tree (they are shared with the previous address), so I will need only x
305 hits (to build node “142” and to make it “RED”) to make this address
306 also to be blocked. This is the reason for the variable number of hits
307 necessary to block an IP.
308
309 The maximum number of hits to turn an address red are (n is the
310 address' number of bytes):
311
312 1 (first byte) + x (second byte) + (x / 2) * (n - 2) (for the rest of
313 the bytes) + (n - 1) (to turn the node to red).
314
315 So, for IPv4 (n = 4) will be 3x and for IPv6 (n = 16) will be 9x. The
316 minimum number of hits to turn an address red is x.