Browse code

Update pipelimit_admin.xml

- added information about algorithms
- corrected rl typos
- corrected example (wrong algorithm)
- added note about algorithms being case sensitive
- added example using pipelimit for specific method (INVITE)
(cherry picked from commit b0f465bc6e402ba77923216affc2020ad25e97c0)

Fred Posner authored on 16/07/2015 19:17:52 • Daniel-Constantin Mierla committed on 17/07/2015 10:30:48
Showing 1 changed files
... ...
@@ -29,9 +29,66 @@
29 29
 		Pipelimit started from ratelimit module, adding support for definition
30 30
 		of pipes limits in database and dynamic names. Complexity of keeping
31 31
 		everything in a module and make it dual mode functional resulted in a
32
-		new module which is focused on just traffic shaping policies. For
33
-		description of the algorithms see the README of ratelimit.
32
+		new module which is focused on just traffic shaping policies.
34 33
 	</para>
34
+	<section>
35
+		<title>Algorithms</title>
36
+		<para>
37
+			Algorithms are based from the ratelimit module, which describes the
38
+			algorithms in more detail. The algorithms are used by the pipelimit
39
+			module to determine if a message should be blocked.
40
+		</para>
41
+		<para>
42
+			<emphasis>Tail Drop Algorithm (TAILDROP)</emphasis>
43
+		</para>
44
+		<para>
45
+			This is a trivial algorithm that imposes some risks when used in
46
+			conjunction with long timer intervals. At the start of each interval an
47
+			internal counter is reset and incremented for each incoming message.
48
+			Once the counter hits the configured limit pl_check returns an error.
49
+		</para>
50
+		<para>
51
+			<emphasis>Random Early Detection Algorithm (RED)</emphasis>
52
+		</para>
53
+		<para>
54
+			The Random Early Detection Algorithm tries to circumvent the
55
+			synchronization problem imposed by the tail drop algorithm by measuring
56
+			the average load and adapting the drop rate dynamically. When running
57
+			with the RED algorithm (enabled by default) Kamailio will return errors
58
+			to the Kamailio routing engine every n'th packet trying to evenly
59
+			spread the measured load of the last timer interval onto the current
60
+			interval. As a negative side effect Kamailio might drop messages
61
+			although the limit might not be reached within the interval. Decrease
62
+			the timer interval if you encounter this.
63
+		</para>
64
+		<para>
65
+			<emphasis>Network Algorithm (NETWORK)</emphasis>
66
+		</para>
67
+		<para>
68
+			This algorithm relies on information provided by network interfaces.
69
+			The total amount of bytes waiting to be consumed on all the network
70
+			interfaces is retrieved once every timer_interval seconds. If the
71
+			returned amount exceeds the limit specified in the modparam, pl_check
72
+			returns an error.
73
+		</para>
74
+		<para>
75
+			<emphasis>Feedback Algorithm (FEEDBACK)</emphasis>
76
+		</para>
77
+		<para>
78
+			Using the PID Controller model (see Wikipedia page), the drop rate is
79
+			adjusted dynamically based on the load factor so that the load factor
80
+			always drifts towards the specified limit (or setpoint, in PID terms).
81
+		</para>
82
+		<para>
83
+			As reading the CPU load average is relatively expensive (opening
84
+			/proc/stat, parsing it, etc), this only happens once every
85
+			timer_interval seconds and consequently the FEEDBACK value is only at
86
+			these intervals recomputed. This in turn makes it difficult for the
87
+			drop rate to adjust quickly. Worst case scenarios are request rates
88
+			going up/down instantly by thousands - it takes up to 20 seconds for
89
+			the controller to adapt to the new request rate.
90
+		</para>
91
+	</section>
35 92
 	</section>
36 93
 	<section>
37 94
 	<title>Dependencies</title>
... ...
@@ -291,7 +348,7 @@ modparam("pipelimit", "reply_reason", "Limiting")
291 348
 		<para>	
292 349
 		If algorithm and limit are provided, the function attempts to create a
293 350
 		new pipe of one with that name doesn't exit. If it exists, no changes
294
-		to algorithm and limit are done.
351
+		to algorithm and limit are done. Algorithm is case sensitive.
295 352
 		</para>
296 353
 		<para>	
297 354
 		The pipe name can be provided via a pseudo variabile.
... ...
@@ -311,7 +368,7 @@ modparam("pipelimit", "reply_reason", "Limiting")
311 368
 			</para></listitem>
312 369
 			<listitem><para>
313 370
 			<emphasis>algorithm</emphasis> - the string or pseudovariable with the
314
-			algorithm. The values can be: taildrop, red, network or feedback - see
371
+			algorithm. The values can be: TAILDROP, RED, NETWORK, or FEEDBACK - see
315 372
 			readme of ratelimit module for details on each algorithm.
316 373
 			</para></listitem>
317 374
 			<listitem><para>
... ...
@@ -322,7 +379,7 @@ modparam("pipelimit", "reply_reason", "Limiting")
322 379
 		This function can be used from REQUEST_ROUTE.
323 380
 		</para>
324 381
 		<example>
325
-		<title><function>rl_check</function> usage</title>
382
+		<title><function>pl_check</function> usage</title>
326 383
 		<programlisting format="linespecific">
327 384
 ...
328 385
 	# perform pipe match for current method
... ...
@@ -360,12 +417,20 @@ with unexpected retcode=$var(check_result)\n");
360 417
 ...
361 418
 	# perform pipe match for authenticated user
362 419
 	$var(limit) = 20;
363
-	if (!pl_check("$au", "traildrop", "$var(limit)")) {
420
+	if (!pl_check("$au", "TAILDROP", "$var(limit)")) {
364 421
 		pl_drop();
365 422
 		exit;
366 423
 	}
367 424
 ...
368
-
425
+	# perform pipe match for INVITE
426
+	if (is_method("INVITE")) {
427
+		$var(invlimit) = 10;
428
+		if (!pl_check("$si", "TAILDROP", "$var(invlimit)")) {
429
+			pl_drop();
430
+			exit;
431
+		}
432
+	}
433
+...
369 434
 </programlisting>
370 435
 		</example>
371 436
 	</section>