Debian Codegraph @

src/modules/pipelimit/README

raw
1 pipelimit Module
2
3 Daniel-Constantin Mierla
4
5 Hendrik Scholz
6
7 Edited by
8
9 Ovidiu Sas
10
11 Daniel-Constantin Mierla
12
13 Copyright © 2013 VoIPEmbedded Inc.
14
15 Copyright © 2010 Asipto.com
16
17 Copyright © 2006 Freenet Cityline GmbH
18 __________________________________________________________________
19
20 Table of Contents
21
22 1. Admin Guide
23
24 1. Overview
25 2. Algorithms
26 3. Dependencies
27
28 3.1. Kamailio Modules
29 3.2. External Libraries or Applications
30
31 4. Parameters
32
33 4.1. hash_size (int)
34 4.2. db_url (string)
35 4.3. plp_table_name (string)
36 4.4. plp_pipeid_column (string)
37 4.5. plp_limit_column (string)
38 4.6. plp_algorithm_column (string)
39 4.7. timer_interval (integer)
40 4.8. timer_mode (integer)
41 4.9. load_fetch (integer)
42 4.10. reply_code (integer)
43 4.11. reply_reason (string)
44 4.12. clean_unused (int)
45
46 5. Functions
47
48 5.1. pl_check(name [, algorithm, limit])
49 5.2. pl_active(name)
50 5.3. pl_drop([ [min ], max ])
51
52 6. RPC Commands
53
54 6.1. pl.list
55 6.2. pl.stats
56 6.3. pl.set_pipe
57 6.4. pl.reset_pipe
58 6.5. pl.rm_pipe
59 6.6. pl.get_pipes
60 6.7. pl.set_pid
61 6.8. pl.get_pid
62 6.9. pl.push_load
63
64 List of Examples
65
66 1.1. Set hash_size parameter
67 1.2. Set db_url parameter
68 1.3. Set plp_table_name parameter
69 1.4. Set plp_pipeid_column parameter
70 1.5. Set plp_limit_column parameter
71 1.6. Set plp_algorithm_column parameter
72 1.7. Set timer_interval parameter
73 1.8. Set timer_mode parameter
74 1.9. Set load_fetch parameter
75 1.10. Set reply_code parameter
76 1.11. Set reply_code parameter at runtime
77 1.12. Set reply_reason parameter
78 1.13. Set reply_reason parameter at runtime
79 1.14. Set clean_unused parameter
80 1.15. Set clean_unused parameter at runtime
81 1.16. pl_check usage
82 1.17. pl_active usage
83 1.18. pl_drop usage
84
85 Chapter 1. Admin Guide
86
87 Table of Contents
88
89 1. Overview
90 2. Algorithms
91 3. Dependencies
92
93 3.1. Kamailio Modules
94 3.2. External Libraries or Applications
95
96 4. Parameters
97
98 4.1. hash_size (int)
99 4.2. db_url (string)
100 4.3. plp_table_name (string)
101 4.4. plp_pipeid_column (string)
102 4.5. plp_limit_column (string)
103 4.6. plp_algorithm_column (string)
104 4.7. timer_interval (integer)
105 4.8. timer_mode (integer)
106 4.9. load_fetch (integer)
107 4.10. reply_code (integer)
108 4.11. reply_reason (string)
109 4.12. clean_unused (int)
110
111 5. Functions
112
113 5.1. pl_check(name [, algorithm, limit])
114 5.2. pl_active(name)
115 5.3. pl_drop([ [min ], max ])
116
117 6. RPC Commands
118
119 6.1. pl.list
120 6.2. pl.stats
121 6.3. pl.set_pipe
122 6.4. pl.reset_pipe
123 6.5. pl.rm_pipe
124 6.6. pl.get_pipes
125 6.7. pl.set_pid
126 6.8. pl.get_pid
127 6.9. pl.push_load
128
129 1. Overview
130
131 This module implements traffic limiting for SIP requests.
132
133 The module defines in an abstract mode the notion of 'pipe', which can
134 be a reference to an IP address, to a network or a trunk. The
135 association of traffic to a pipe is done in the config file, therefore,
136 a pipe could represent SIP traffic coming from a user or the flow of
137 specific SIP requests such as INVITE or REGISTER.
138
139 Pipelimit started from ratelimit module, adding support for definition
140 of pipes limits in database and dynamic names. Complexity of keeping
141 everything in a module and make it dual mode functional resulted in a
142 new module which is focused on just traffic shaping policies, the
143 implementation of queues was discarded.
144
145 2. Algorithms
146
147 Algorithms are based from the ratelimit module, which describes the
148 algorithms in more detail. The algorithms are used by the pipelimit
149 module to determine if a message should be blocked.
150
151 Tail Drop Algorithm (TAILDROP)
152
153 This is a trivial algorithm that imposes some risks when used in
154 conjunction with long timer intervals. At the start of each interval an
155 internal counter is reset and incremented for each incoming message.
156 Once the counter hits the configured limit pl_check() returns false
157 (negative value).
158
159 Random Early Detection Algorithm (RED)
160
161 The Random Early Detection Algorithm tries to circumvent the
162 synchronization problem imposed by the tail drop algorithm by measuring
163 the average load and adapting the drop rate dynamically. When running
164 with the RED algorithm (enabled by default) Kamailio will return errors
165 to the Kamailio routing engine every n'th packet trying to evenly
166 spread the measured load of the last timer interval onto the current
167 interval. As a negative side effect Kamailio might drop messages
168 although the limit might not be reached within the interval. Decrease
169 the timer interval if you encounter this.
170
171 Network Algorithm (NETWORK)
172
173 This algorithm relies on information provided by network interfaces.
174 The total amount of bytes waiting to be consumed on all the network
175 interfaces is retrieved once every timer_interval seconds. If the
176 returned amount exceeds the limit specified in the modparam, pl_check()
177 returns false (negative value).
178
179 Feedback Algorithm (FEEDBACK)
180
181 Using the PID Controller model (see Wikipedia page), the drop rate is
182 adjusted dynamically based on the load factor so that the load factor
183 always drifts towards the specified limit (or setpoint, in PID terms).
184
185 As reading the CPU load average is relatively expensive (opening
186 /proc/stat, parsing it, etc), this only happens once every
187 timer_interval seconds and consequently the FEEDBACK value is only at
188 these intervals recomputed. This in turn makes it difficult for the
189 drop rate to adjust quickly. Worst case scenarios are request rates
190 going up/down instantly by thousands - it takes up to 20 seconds for
191 the controller to adapt to the new request rate.
192
193 3. Dependencies
194
195 3.1. Kamailio Modules
196 3.2. External Libraries or Applications
197
198 3.1. Kamailio Modules
199
200 The following modules must be loaded before this module:
201 * database connection module.
202 * sl: Stateless Request Handling.
203
204 3.2. External Libraries or Applications
205
206 The following libraries or applications must be installed before
207 running Kamailio with this module loaded:
208 * None.
209
210 4. Parameters
211
212 4.1. hash_size (int)
213 4.2. db_url (string)
214 4.3. plp_table_name (string)
215 4.4. plp_pipeid_column (string)
216 4.5. plp_limit_column (string)
217 4.6. plp_algorithm_column (string)
218 4.7. timer_interval (integer)
219 4.8. timer_mode (integer)
220 4.9. load_fetch (integer)
221 4.10. reply_code (integer)
222 4.11. reply_reason (string)
223 4.12. clean_unused (int)
224
225 4.1. hash_size (int)
226
227 Used to compute the number of slots for the internal hash table, as
228 power of 2 (number of slots = 2^hash_size, aka 1<<hash_size). If you
229 have many pipes, increase this value for proper performances, but don't
230 go too high (hash_size=10 means 1024 slots).
231
232 Default value is “6” (64 slots).
233
234 Example 1.1. Set hash_size parameter
235 ...
236 modparam("pipelimit", "hash_size", 10)
237 ...
238
239 4.2. db_url (string)
240
241 URL of the database server to be used.
242
243 Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
244
245 Example 1.2. Set db_url parameter
246 ...
247 modparam("pipelimit", "db_url", "dbdriver://username:password@dbhost/dbname")
248 ...
249
250 4.3. plp_table_name (string)
251
252 Name of DB table where data definition for pipes is stored.
253
254 Default value is “pl_pipes”.
255
256 Example 1.3. Set plp_table_name parameter
257 ...
258 modparam("pipelimit", "plp_table_name", "mypipes")
259 ...
260
261 4.4. plp_pipeid_column (string)
262
263 Name of 'pipeid' column.
264
265 Default value is “pipeid”.
266
267 Example 1.4. Set plp_pipeid_column parameter
268 ...
269 modparam("pipelimit", "plp_pipeid_column", "name")
270 ...
271
272 4.5. plp_limit_column (string)
273
274 Name of 'limit' column.
275
276 Default value is “plimit”.
277
278 Example 1.5. Set plp_limit_column parameter
279 ...
280 modparam("pipelimit", "plp_limit_column", "name")
281 ...
282
283 4.6. plp_algorithm_column (string)
284
285 Name of 'algorithm' column.
286
287 Default value is “algorithm”.
288
289 Example 1.6. Set plp_algorithm_column parameter
290 ...
291 modparam("pipelimit", "plp_algorithm_column", "name")
292 ...
293
294 4.7. timer_interval (integer)
295
296 The length of the timer interval in seconds. Counted messages are reset
297 each timer_interval, therefore the amounts of messages have to be
298 divided by this timer_interval value to get the messages per second
299 value. For example, if you want to allow an average of 10 messages per
300 second with a timer interval of 10 seconds, then the limit value has to
301 be 100.
302
303 Note: A too small value may lead to performance penalties due to timer
304 process overloading.
305
306 Default value is 10.
307
308 Example 1.7. Set timer_interval parameter
309 ...
310 modparam("pipelimit", "timer_interval", 5)
311 ...
312
313 4.8. timer_mode (integer)
314
315 Control what timer process to be used: 0 - use main fast timer; 1 - use
316 secondary wheel timer.
317
318 Default value is 0.
319
320 Example 1.8. Set timer_mode parameter
321 ...
322 modparam("pipelimit", "timer_mode", 1)
323 ...
324
325 4.9. load_fetch (integer)
326
327 Control if the module should fetch the load for CPU and network
328 traffic. If set to 0, no load is fetched; if set to 1, the load is
329 fetched every timer interval.
330
331 Default value is 1.
332
333 Example 1.9. Set load_fetch parameter
334 ...
335 modparam("pipelimit", "load_fetch", 0)
336 ...
337
338 4.10. reply_code (integer)
339
340 The code of the reply sent by Kamailio while limiting.
341
342 Default value is 503.
343
344 Example 1.10. Set reply_code parameter
345 ...
346 modparam("pipelimit", "reply_code", 505)
347 ...
348
349 This value can be modified at runtime using kamcmd
350
351 Example 1.11. Set reply_code parameter at runtime
352 kamcmd cfg.set_now_int pipelimit reply_code 505
353
354 4.11. reply_reason (string)
355
356 The reason of the reply sent by Kamailio while limiting.
357
358 Default value is "Server Unavailable".
359
360 Example 1.12. Set reply_reason parameter
361 ...
362 modparam("pipelimit", "reply_reason", "Limiting")
363 ...
364
365 This value can be modified at runtime using kamcmd
366
367 Example 1.13. Set reply_reason parameter at runtime
368 kamcmd cfg.set_now_string pipelimit reply_reason "Limiting"
369
370 4.12. clean_unused (int)
371
372 Clean unused pipes after this number of timer intervals.
373
374 Default value is 0 (cleanup disabled).
375
376 Example 1.14. Set clean_unused parameter
377 ...
378 modparam("pipelimit", "clean_unused", 10)
379 ...
380
381 This value can be modified at runtime using kamcmd
382
383 Example 1.15. Set clean_unused parameter at runtime
384 kamcmd cfg.set_now_int pipelimit clean_unused 10
385
386 5. Functions
387
388 5.1. pl_check(name [, algorithm, limit])
389 5.2. pl_active(name)
390 5.3. pl_drop([ [min ], max ])
391
392 5.1. pl_check(name [, algorithm, limit])
393
394 Check the current request against the 'name' pipe.
395
396 If algorithm and limit are provided, the function attempts to create a
397 new pipe if one with that name doesn't exit. If it exists, no changes
398 to algorithm is done and the pipe limit is set to the 'limit' parameter
399 value, if this is greater than 0. Algorithm is case sensitive.
400
401 The pipe name can be provided via a pseudo variable.
402
403 The method will return:
404 * -2 if no pipe was found
405 * -1 if pipe limit was reached
406 * 1 if pipe limit was NOT reached
407 * 2 if pipe has NOP algorithm
408
409 Meaning of the parameters is as follows:
410 * name - the string or pseudovariable with the pipe name.
411 * algorithm - the string or pseudovariable with the algorithm. The
412 values can be: TAILDROP, RED, NETWORK, or FEEDBACK - see readme of
413 ratelimit module for details on each algorithm.
414 * limit - the integer or pseudovariable with the limit value per
415 timer_interval.
416
417 This function can be used from ANY_ROUTE.
418
419 Example 1.16. pl_check usage
420 ...
421 # perform pipe match for current method
422 if (!pl_check("one")) {
423 pl_drop();
424 exit;
425 }
426 ...
427 # use pipe 'one' for the current method via PV
428 $var(p) = "one";
429 $var(check_result) = pl_check("$var(p)");
430 switch($var(check_result)) {
431 case -2:
432 xlog("L_ALERT","pl_check(\"$var(p)\") drop -pipe NOT found\n");
433 pl_drop();
434 exit;
435 break;
436 case -1:
437 xlog("L_ALERT","pl_check(\"$var(p)\") drop\n");
438 pl_drop();
439 exit;
440 break;
441 case 1:
442 xlog("L_INFO", "pl_check(\"$var(p)\") pass\n");
443 break;
444 case 2:
445 xlog("L_ALERT","pl_check(\"$var(p)\") pass -NOP algorithm\n");
446 break;
447 default:
448 xlog("L_ERR","pl_check(\"$var(p)\") dropping \
449 with unexpected retcode=$var(check_result)\n");
450 pl_drop();
451 exit;
452 }
453 ...
454 # perform pipe match for authenticated user
455 $var(limit) = 20;
456 if (!pl_check("$au", "TAILDROP", "$var(limit)")) {
457 pl_drop();
458 exit;
459 }
460 ...
461 # perform pipe match for INVITE
462 if (is_method("INVITE")) {
463 $var(invlimit) = 10;
464 if (!pl_check("$si", "TAILDROP", "$var(invlimit)")) {
465 pl_drop();
466 exit;
467 }
468 }
469 ...
470
471 5.2. pl_active(name)
472
473 Check the pipe 'name' was already created. Return 1 (true) if the pipe
474 is found, -1 (false) if the pipe is not found.
475
476 This function can be used from ANY_ROUTE.
477
478 Example 1.17. pl_active usage
479 ...
480 if (!pl_active("one")) {
481 # pipe does not exist
482 exit;
483 }
484 ...
485
486 5.3. pl_drop([ [min ], max ])
487
488 For the current request, a "503 - Server Unavailable" reply is sent
489 back. The reply may or may not have a "Retry-After" header. If no
490 parameter is given, there will be no "Retry-After" header. If only the
491 max parameter is given, the reply will contain a "Retry-After: max"
492 header. If both min and max params are given, the reply will contain a
493 "Retry-After: random" header with random being a random value between
494 the given min and max.
495
496 Meaning of the parameters is as follows:
497 * min - the minimum value of "Retry-After" header.
498 * max - the maximum value of "Retry-After" header.
499
500 This function can be used from
501 REQUEST_ROUTE|BRANCH_ROUTE|FAILURE_ROUTE|ONSEND_ROUTE.
502
503 Example 1.18. pl_drop usage
504 ...
505 if (!pl_check("one")) {
506 # send back a "503 - Server Unavailable"
507 # with a "Retry-After: 5"
508 pl_drop("5");
509 exit;
510 }
511 ...
512
513 6. RPC Commands
514
515 6.1. pl.list
516 6.2. pl.stats
517 6.3. pl.set_pipe
518 6.4. pl.reset_pipe
519 6.5. pl.rm_pipe
520 6.6. pl.get_pipes
521 6.7. pl.set_pid
522 6.8. pl.get_pid
523 6.9. pl.push_load
524
525 6.1. pl.list
526
527 Lists the details of one or all pipes, respectively the attributes pipe
528 name (id), algorithm, limit and counter.
529
530 Name: pl.list
531
532 Parameters: name - (optional) pipe name
533
534 RPC Command Format:
535 ...
536 kamctl rpc pl.list
537 kamctl rpc pl.list testid
538 ...
539
540 6.2. pl.stats
541
542 Lists the parameters and variables in the pipelimit module: pipe id,
543 pipe load and pipe counter.
544
545 Name: pl.stats
546
547 Parameters: none
548
549 RPC Command Format:
550 ...
551 kamctl rpc pl.stats
552 ...
553
554 6.3. pl.set_pipe
555
556 Sets the pipe parameters for the given pipe id.
557
558 Name: pl.set_pipe
559
560 Parameters:
561 * pipe_id - pipe id.
562 * pipe_algorithm - the algorithm assigned to the given pipe id.
563 * pipe_limit - the limit assigned to the given pipe id.
564
565 RPC Command Format:
566 ...
567 kamctl rpc pl.set_pipe 2 RED 10
568 ...
569
570 6.4. pl.reset_pipe
571
572 Reset the values associated with the pipe.
573
574 Name: pl.reset_pipe
575
576 Parameters:
577 * pipe_id - pipe id.
578
579 RPC Command Format:
580 ...
581 kamctl rpc pl.reset_pipe p01
582 ...
583
584 6.5. pl.rm_pipe
585
586 Remove the pipe structure matching the given pipe id.
587
588 Name: pl.rm_pipe
589
590 Parameters:
591 * pipe_id - pipe id.
592
593 RPC Command Format:
594 ...
595 kamctl rpc pl.rm_pipe p01
596 ...
597
598 6.6. pl.get_pipes
599
600 Gets the list of in use pipes.
601
602 Name: pl.get_pipes
603
604 Parameters: none
605
606 RPC Command Format:
607 ...
608 kamctl rpc pl.get_pipes
609 ...
610
611 6.7. pl.set_pid
612
613 Sets the PID Controller parameters for the Feedback Algorithm.
614
615 Name: pl.set_pid
616
617 Parameters:
618 * ki - the integral parameter.
619 * kp - the proportional parameter.
620 * kd - the derivative parameter.
621
622 RPC Command Format:
623 ...
624 kamctl rpc pl.set_pid 0.5 0.5 0.5
625 ...
626
627 6.8. pl.get_pid
628
629 Gets the list of in use PID Controller parameters.
630
631 Name: pl.get_pid
632
633 Parameters: none
634
635 RPC Command Format:
636 ...
637 kamctl rpc pl.get_pid
638 ...
639
640 6.9. pl.push_load
641
642 Force the value of the load parameter. This command is useful for
643 testing the Feedback algorithm.
644
645 Name: pl.push_load
646
647 Parameters:
648 * load - the forced value of load (it must be greater than 0.0 and
649 smaller than 1.0).
650
651 RPC Command Format:
652 ...
653 kamctl rpc pl.push_load 0.85
654 ...