Debian Codegraph @

src/modules/cfgutils/README

raw
1 cfgutils Module
2
3 Henning Westerholt
4
5 1und1 Internet AG
6 <[email protected]>
7
8 Carsten Bock
9
10 BASIS AudioNet GmbH
11
12 Elena-Ramona Modroiu
13
14 rosdev.ro
15 <[email protected]>
16
17 Jiri Kuthan
18
19 <[email protected]>
20
21 Olle E. Johansson
22
23 <[email protected]>
24
25 Juha Heinanen
26
27 <[email protected]>
28
29 Edited by
30
31 Daniel-Constantin Mierla
32
33 <[email protected]>
34
35 Copyright © 2014, 2013, 2007, 2008, 2004 Edvina AB, 1und1 Internet AG,
36 BASIS AudioNet GmbH, Elena-Ramona Modroiu, Juha Heinanen, FhG FOKUS
37 __________________________________________________________________
38
39 Table of Contents
40
41 1. Admin Guide
42
43 1. Overview
44 2. Dependencies
45 3. Parameters
46
47 3.1. initial_probability (string)
48 3.2. hash_file (string)
49 3.3. initial_gflags (integer)
50 3.4. lock_set_size (integer)
51
52 4. Functions
53
54 4.1. rand_event()
55 4.2. rand_set_prob(probability)
56 4.3. rand_reset_prob()
57 4.4. rand_get_prob()
58 4.5. sleep(time)
59 4.6. usleep(time)
60 4.7. abort()
61 4.8. pkg_status()
62 4.9. pkg_summary()
63 4.10. shm_status()
64 4.11. shm_summary()
65 4.12. set_gflag(flag)
66 4.13. reset_gflag(flag)
67 4.14. is_gflag(flag)
68 4.15. lock(key [, key2])
69 4.16. trylock(key [, key2])
70 4.17. unlock(key [, key2])
71 4.18. check_route_exists(route)
72 4.19. route_if_exists(route)
73 4.20. core_hash(string1, string2, size)
74
75 5. RPC Commands
76
77 5.1. cfgutils.rand_set_prop
78 5.2. cfgutils.rand_reset_prob
79 5.3. cfgutils.rand_get_prob
80 5.4. cfgutils.check_config_hash
81 5.5. cfgutils.get_config_hash
82 5.6. cfgutils.set_gflag
83 5.7. cfgutils.reset_gflag
84 5.8. cfgutils.is_gflag
85 5.9. cfgutils.get_gflags
86
87 6. Exported pseudo-variables
88
89 6.1. $RANDOM
90
91 List of Examples
92
93 1.1. initial_probability parameter usage
94 1.2. hash_file parameter usage
95 1.3. initial parameter usage
96 1.4. lock_set_size parameter usage
97 1.5. rand_event() usage
98 1.6. rand_set_prob() usage
99 1.7. rand_reset_prob() usage
100 1.8. rand_get_prob() usage
101 1.9. sleep usage
102 1.10. usleep usage
103 1.11. abort usage
104 1.12. pkg_status usage
105 1.13. pkg_summary usage
106 1.14. shm_status usage
107 1.15. shm_summary usage
108 1.16. set_gflag() usage
109 1.17. reset_gflag() usage
110 1.18. is_gflag() usage
111 1.19. lock() usage
112 1.20. trylock() usage
113 1.21. unlock() usage
114 1.22. check_route_exists() usage
115 1.23. route_if_exists() usage
116 1.24. core_hash() usage
117 1.25. cfgutils.rand_set_prob usage
118 1.26. cfgutils.rand_reset_prob usage
119 1.27. cfgutils.rand_get_prob usage
120 1.28. cfgutils.check_config_hash usage
121 1.29. cfgutils.get_config_hash usage
122 1.30. cfgutils.set_gflag usage
123 1.31. cfgutils.reset_gflag usage
124 1.32. cfgutils.is_gflag usage
125 1.33. cfgutils.get_gflags usage
126 1.34. RANDOM pseudo-variable usage
127
128 Chapter 1. Admin Guide
129
130 Table of Contents
131
132 1. Overview
133 2. Dependencies
134 3. Parameters
135
136 3.1. initial_probability (string)
137 3.2. hash_file (string)
138 3.3. initial_gflags (integer)
139 3.4. lock_set_size (integer)
140
141 4. Functions
142
143 4.1. rand_event()
144 4.2. rand_set_prob(probability)
145 4.3. rand_reset_prob()
146 4.4. rand_get_prob()
147 4.5. sleep(time)
148 4.6. usleep(time)
149 4.7. abort()
150 4.8. pkg_status()
151 4.9. pkg_summary()
152 4.10. shm_status()
153 4.11. shm_summary()
154 4.12. set_gflag(flag)
155 4.13. reset_gflag(flag)
156 4.14. is_gflag(flag)
157 4.15. lock(key [, key2])
158 4.16. trylock(key [, key2])
159 4.17. unlock(key [, key2])
160 4.18. check_route_exists(route)
161 4.19. route_if_exists(route)
162 4.20. core_hash(string1, string2, size)
163
164 5. RPC Commands
165
166 5.1. cfgutils.rand_set_prop
167 5.2. cfgutils.rand_reset_prob
168 5.3. cfgutils.rand_get_prob
169 5.4. cfgutils.check_config_hash
170 5.5. cfgutils.get_config_hash
171 5.6. cfgutils.set_gflag
172 5.7. cfgutils.reset_gflag
173 5.8. cfgutils.is_gflag
174 5.9. cfgutils.get_gflags
175
176 6. Exported pseudo-variables
177
178 6.1. $RANDOM
179
180 1. Overview
181
182 Useful extensions for the server configuration.
183
184 The cfgutils module can be used to introduce randomness to the
185 behaviour of the server. It provides setup functions and the
186 “rand_event” function. This function return either true or false,
187 depending on a random value and a specified probability. E.g. if you
188 set via fifo or script a probability value of 5%, then 5% of all calls
189 to rand_event will return true. The pseudovariable “$RANDOM” could be
190 used to introduce random values e.g. into a SIP reply.
191
192 The benefit of this module is the probability of the decision can be
193 manipulated by external applications such as web interface or command
194 line tools. The probability must be specified as percent value, ranging
195 from 0 to 100.
196
197 The module exports commands to FIFO server that can be used to change
198 the global settings via FIFO interface. The FIFO commands are:
199 “set_prob”, “reset_prob” and “get_prob”.
200
201 This module can be used for simple load-shedding, e.g. reply 5% of the
202 Invites with a 503 error and an adequate random Retry-After value.
203
204 The module provides as well functions to delay the execution of the
205 server. The functions “sleep” and “usleep” could be used to let the
206 server wait a specific time interval.
207
208 It can also hash the config file used from the server with a (weak)
209 cryptographic hash function on startup. This value is saved and can be
210 later compared to the actual hash, to detect modifications of this file
211 after the server start. This functions are available as the FIFO
212 commands “check_config_hash” and “get_config_hash”.
213
214 The gflags functionality (global flags) keeps a bitmap of flags in
215 shared memory and may be used to change behaviour of server based on
216 value of the flags. Example:
217 if (is_gflag("1")) {
218 t_relay("udp:10.0.0.1:5060");
219 } else {
220 t_relay("udp:10.0.0.2:5060");
221 }
222
223 The benefit of this is the value of the switch flags can be manipulated
224 by external applications such as web interface or command line tools.
225 The size of bitmap is 32.
226
227 The module exports external commands that can be used to change the
228 global flags via Management Interface and RPC. See relevant sections
229 below.
230
231 2. Dependencies
232
233 The module depends on the following modules (in other words the listed
234 modules must be loaded before this module):
235 * none
236
237 3. Parameters
238
239 3.1. initial_probability (string)
240 3.2. hash_file (string)
241 3.3. initial_gflags (integer)
242 3.4. lock_set_size (integer)
243
244 3.1. initial_probability (string)
245
246 The initial value of the probability.
247
248 Default value is “10”.
249
250 Example 1.1. initial_probability parameter usage
251 ...
252 modparam("cfgutils", "initial_probability", 15)
253 ...
254
255 3.2. hash_file (string)
256
257 The config file name for that a hash value should be calculated on
258 startup.
259
260 There is no default value, is no parameter is given the hash
261 functionality is disabled.
262
263 Example 1.2. hash_file parameter usage
264 ...
265 modparam("cfgutils", "hash_file", "/etc/kamailio/kamailio.cfg")
266 ...
267
268 3.3. initial_gflags (integer)
269
270 The initial value of global flags bitmap.
271
272 Default value is “0”.
273
274 Example 1.3. initial parameter usage
275 ...
276 modparam("cfgutils", "initial_gflags", 15)
277 ...
278
279 3.4. lock_set_size (integer)
280
281 Size of lock set - the value is used as power of two to compute the
282 size of lock array.
283
284 Default value is “0” - no lock set created.
285
286 Example 1.4. lock_set_size parameter usage
287 ...
288 modparam("cfgutils", "lock_set_size", 4)
289 ...
290
291 4. Functions
292
293 4.1. rand_event()
294 4.2. rand_set_prob(probability)
295 4.3. rand_reset_prob()
296 4.4. rand_get_prob()
297 4.5. sleep(time)
298 4.6. usleep(time)
299 4.7. abort()
300 4.8. pkg_status()
301 4.9. pkg_summary()
302 4.10. shm_status()
303 4.11. shm_summary()
304 4.12. set_gflag(flag)
305 4.13. reset_gflag(flag)
306 4.14. is_gflag(flag)
307 4.15. lock(key [, key2])
308 4.16. trylock(key [, key2])
309 4.17. unlock(key [, key2])
310 4.18. check_route_exists(route)
311 4.19. route_if_exists(route)
312 4.20. core_hash(string1, string2, size)
313
314 4.1. rand_event()
315
316 Return true or false, depending on a random value and a probability
317 value.
318
319 Example 1.5. rand_event() usage
320 ...
321 if (rand_event()) {
322 append_to_reply("Retry-After: 120\n");
323 sl_send_reply("503", "Try later");
324 exit;
325 };
326 # normal message processing follows
327 ...
328
329 4.2. rand_set_prob(probability)
330
331 Set the “probability” of the decision.
332
333 “probability” can have a value from the range 0..100.
334
335 Example 1.6. rand_set_prob() usage
336 ...
337 rand_set_prob("4");
338 ...
339
340 4.3. rand_reset_prob()
341
342 Reset the probability back to the initial value.
343
344 Example 1.7. rand_reset_prob() usage
345 ...
346 rand_reset_prob();
347 ...
348
349 4.4. rand_get_prob()
350
351 Return the current probability setting, e.g. for logging purposes.
352
353 Example 1.8. rand_get_prob() usage
354 ...
355 rand_get_prob();
356 ...
357
358 4.5. sleep(time)
359
360 Waits "time" seconds.
361
362 Meaning of the parameters is as follows:
363 * time - Time to wait in seconds. It can be an integer or a variable
364 holding an integer.
365
366 This function can be used from ANY_ROUTE.
367
368 Example 1.9. sleep usage
369 ...
370 sleep("1");
371 ...
372
373 4.6. usleep(time)
374
375 Waits "time" micro-seconds.
376
377 Meaning of the parameters is as follows:
378 * time - Time to wait in micro-seconds (1/1000000 of a second). It
379 can be an integer or a variable holding an integer.
380
381 This function can be used from ANY_ROUTE.
382
383 Example 1.10. usleep usage
384 ...
385 # wait 5 milliseconds
386 usleep("5000");
387 ...
388
389 4.7. abort()
390
391 Debugging function that aborts the server. Depending on the
392 configuration of the server a core dump will be created.
393
394 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
395 FAILURE_ROUTE, BRANCH_ROUTE.
396
397 Example 1.11. abort usage
398 ...
399 abort();
400 ...
401
402 4.8. pkg_status()
403
404 Debugging function that dumps the status for the private (PKG) memory.
405 This information is logged to the default log facility, depending on
406 the general log level and the memlog setting. You need to compile the
407 server with activated memory debugging to get detailed informations.
408
409 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
410 FAILURE_ROUTE, BRANCH_ROUTE.
411
412 Example 1.12. pkg_status usage
413 ...
414 pkg_status();
415 ...
416
417 4.9. pkg_summary()
418
419 Debugging function that dumps the summary for the private (PKG) memory
420 usage. This information is logged to the default log facility,
421 depending on the general log level and the memlog setting. You need to
422 compile the server with activated memory debugging to get detailed
423 informations.
424
425 This function can be used from ANY_ROUTE.
426
427 Example 1.13. pkg_summary usage
428 ...
429 pkg_summary();
430 ...
431
432 4.10. shm_status()
433
434 Debugging function that dumps the status for the shared (SHM) memory.
435 This information is logged to the default log facility, depending on
436 the general log level and the memlog setting. You need to compile the
437 server with activated memory debugging to get detailed informations.
438
439 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
440 FAILURE_ROUTE, BRANCH_ROUTE.
441
442 Example 1.14. shm_status usage
443 ...
444 shm_status();
445 ...
446
447 4.11. shm_summary()
448
449 Debugging function that dumps the summary for the shared (SHM) memory
450 usage. This information is logged to the default log facility,
451 depending on the general log level and the memlog setting. You need to
452 compile the server with activated memory debugging to get detailed
453 informations.
454
455 This function can be used from ANY_ROUTE.
456
457 Example 1.15. shm_summary usage
458 ...
459 shm_summary();
460 ...
461
462 4.12. set_gflag(flag)
463
464 Set the bit at the position “flag” in global flags.
465
466 “flag” can have a value in the range of 0..31.
467
468 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
469 ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
470
471 Example 1.16. set_gflag() usage
472 ...
473 set_gflag("4");
474 ...
475
476 4.13. reset_gflag(flag)
477
478 Reset the bit at the position “flag” in global flags.
479
480 “flag” can have a value in the range of 0..31.
481
482 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
483 ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
484
485 Example 1.17. reset_gflag() usage
486 ...
487 reset_gflag("4");
488 ...
489
490 4.14. is_gflag(flag)
491
492 Check if bit at the position “flag” in global flags is set.
493
494 “flag” can have a value in the range of 0..31.
495
496 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
497 ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
498
499 Example 1.18. is_gflag() usage
500 ...
501 if(is_gflag("4"))
502 {
503 log("global flag 4 is set\n");
504 } else {
505 log("global flag 4 is not set\n");
506 };
507 ...
508
509 4.15. lock(key [, key2])
510
511 Lock the key. Can be used to synchronize operations in config file, a
512 hash id is computed over the keys and appropriate lock is set in the
513 lock array controlled by parameter "lock_set_size". Do not use lock()
514 after another lock() unless you are sure the keys hit different array
515 entries.
516
517 “key” can be static string or string with PVs.
518
519 “key2” is optional and can be static string or string with PVs.
520
521 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
522 ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
523
524 Example 1.19. lock() usage
525 ...
526 lock("$rU");
527 ...
528
529 4.16. trylock(key [, key2])
530
531 Try to lock the key. If the lock can not be obtained (possibly already
532 locked), the function returns an error and script execution continues.
533
534 “key” can be static string or string with PVs.
535
536 “key2” is optional and can be static string or string with PVs.
537
538 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
539 ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
540
541 Example 1.20. trylock() usage
542 ...
543 if (trylock("$rU")) {
544 xlog("L_INFO", "Doing some cool stuff\n");
545 unlock("$rU");
546 }
547 ...
548
549 4.17. unlock(key [, key2])
550
551 Unlock the key.
552
553 “key” can be static string or string with PVs.
554
555 “key2” is optional and can be static string or string with PVs.
556
557 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
558 ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
559
560 Example 1.21. unlock() usage
561 ...
562 unlock("$rU");
563 ...
564
565 4.18. check_route_exists(route)
566
567 Check if a route block exists. It returns true (1) on found and false
568 on not found or error.
569
570 Parameters:
571
572 “name” of a route block in the config file, like “route[FROGJUMP]”
573
574 This function can be used from any route. You can only check for
575 route[] blocks, not reply, event or other routes.
576
577 Example 1.22. check_route_exists() usage
578 ...
579 if(check_route_exists("JUMP") {
580 $var(jumping_frogs) = 1;
581 };
582 ...
583
584 4.19. route_if_exists(route)
585
586 Execute a routing block only if it is defined. If it's not defined,
587 silently move to the next action in the configuration script.
588
589 It returns the code of last action in the route block, if that exists,
590 or false if the route doesn't exists or was an error executing it.
591
592 Parameters:
593
594 “name” of a route block in the config file, like “route[FROGJUMP]”
595
596 This function can be used from any route. You can only execute it for
597 route[] blocks, not reply, event or other routes.
598
599 Example 1.23. route_if_exists() usage
600 ...
601 if(route_if_exists("JUMP")) {
602 exit;
603 }
604 ...
605
606 4.20. core_hash(string1, string2, size)
607
608 Exported function that enables the core_hash() function to be used from
609 the configuration file.
610
611 This is a quick and simple hash function and it is not
612 cryptographically secure. This function should not be used for any
613 security related purposes.
614
615 Parameters:
616 * “string1” first string to hash
617 * “string2” (optional) second string to hash (set to "" if not
618 needed)
619 * “size” size of the hash space (used as a power of 2)
620
621 This function can be used from ANY_ROUTE.
622
623 Example 1.24. core_hash() usage
624 ...
625 core_hash("$ci", "", 4);
626 ...
627
628 5. RPC Commands
629
630 5.1. cfgutils.rand_set_prop
631 5.2. cfgutils.rand_reset_prob
632 5.3. cfgutils.rand_get_prob
633 5.4. cfgutils.check_config_hash
634 5.5. cfgutils.get_config_hash
635 5.6. cfgutils.set_gflag
636 5.7. cfgutils.reset_gflag
637 5.8. cfgutils.is_gflag
638 5.9. cfgutils.get_gflags
639
640 Functions that check or change some global flags accepts one parameter
641 which is the flag bitmap/mask specifying the corresponding flags. It is
642 not possible to specify directly the flag position that should be
643 changed as in the functions available in the routing script.
644
645 5.1. cfgutils.rand_set_prop
646
647 Set the probability value to the given parameter. The parameter should
648 be a percent value.
649
650 The parameter value must be a number from 0 to 100.
651
652 Example 1.25. cfgutils.rand_set_prob usage
653 ...
654 $ kamctl rpc cfgutils.rand_set_prob 10
655 ...
656
657 5.2. cfgutils.rand_reset_prob
658
659 Reset the probability value to the initial start value.
660
661 This command don't need a parameter.
662
663 Example 1.26. cfgutils.rand_reset_prob usage
664 ...
665 $ kamctl rpc cfgutils.rand_reset_prob
666 ...
667
668 5.3. cfgutils.rand_get_prob
669
670 Return the actual probability setting.
671
672 The function return the actual probability value.
673
674 Example 1.27. cfgutils.rand_get_prob usage
675 ...
676 $ kamctl rpc cfgutils.rand_get_prob
677 ...
678
679 5.4. cfgutils.check_config_hash
680
681 Check if the actual config file hash is identical to the stored one.
682
683 The function returns 200 OK if the hash values are identical, 400 if
684 there are not identical, 404 if no file for hashing has been configured
685 and 500 on errors. Additional a short text message is printed.
686
687 Example 1.28. cfgutils.check_config_hash usage
688 ...
689 $ kamctl rpc cfgutils.check_config_hash
690 ...
691
692 5.5. cfgutils.get_config_hash
693
694 Return the stored config file hash.
695
696 The function returns 200 OK and the hash value on success or 404 if no
697 file for hashing has been configured.
698
699 Example 1.29. cfgutils.get_config_hash usage
700 ...
701 $ kamctl rpc cfgutils.get_config_hash
702 ...
703
704 5.6. cfgutils.set_gflag
705
706 Set the value of some flags (specified by bitmask) to 1.
707
708 The parameter value must be a bitmask in decimal or hexadecimal format.
709 The bitmask has a 32 bit size.
710
711 Example 1.30. cfgutils.set_gflag usage
712 ...
713 $ kamctl rpc cfgutils.set_gflag 1
714 ...
715
716 5.7. cfgutils.reset_gflag
717
718 Reset the value of some flags to 0.
719
720 The parameter value must be a bitmask in decimal or hexadecimal format.
721 The bitmask has a 32 bit size.
722
723 Example 1.31. cfgutils.reset_gflag usage
724 ...
725 $ kamctl rpc cfgutils.reset_gflag 1
726 ...
727
728 5.8. cfgutils.is_gflag
729
730 Returns true if all the flags from the bitmask are set.
731
732 The parameter value must be a bitmask in decimal or hexadecimal format.
733 The bitmask has a 32 bit size.
734
735 The function returns TRUE if all the flags from the set are set and
736 FALSE if at least one is not set.
737
738 Example 1.32. cfgutils.is_gflag usage
739 ...
740 $ kamctl rpc cfgutils.set_gflag 1024
741 $ kamctl rpc cfgutils.is_gflag 1024
742 TRUE
743 ...
744
745 5.9. cfgutils.get_gflags
746
747 Return the bitmap with all flags. The function gets no parameters and
748 returns the bitmap in hexadecimal and decimal format.
749
750 Example 1.33. cfgutils.get_gflags usage
751 ...
752 $ kamctl rpc cfgutils.get_gflags
753 ...
754
755 6. Exported pseudo-variables
756
757 6.1. $RANDOM
758
759 6.1. $RANDOM
760
761 Returns a random value from the [0 - 2^31) range.
762
763 Example 1.34. RANDOM pseudo-variable usage
764 ...
765 if (rand_event()) {
766 $var(value) = ($RANDOM / 16777216); # 2^24
767 if ($var(value) < 10) {
768 $var(value) = 10;
769 }
770 append_to_reply("Retry-After: $var(value)\n");
771 sl_send_reply("503", "Try later");
772 exit;
773 };
774 # normal message processing follows