Debian Codegraph @

src/modules/corex/README

raw
1 COREX Module
2
3 Daniel-Constantin Mierla
4
5 <[email protected]>
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11 <[email protected]>
12
13 Muhammad Shahzad Shafi
14
15 <[email protected]>
16
17 Copyright © 2012 asipto.com
18 __________________________________________________________________
19
20 Table of Contents
21
22 1. Admin Guide
23
24 1. Overview
25 2. Dependencies
26
27 2.1. Kamailio Modules
28 2.2. External Libraries or Applications
29
30 3. Parameters
31
32 3.1. alias_subdomains (string)
33 3.2. dns_cache (string)
34 3.3. dns_file (string)
35 3.4. evcb_reply_out (string)
36 3.5. nio_intercept (int)
37 3.6. nio_min_msg_len (int)
38 3.7. nio_msg_avp (string)
39
40 4. Functions
41
42 4.1. append_branch([ uri, [ q ] ])
43 4.2. send_udp([ host [ :port ] ])
44 4.3. send_tcp([ host [ :port ] ])
45 4.4. send_data(uri, data)
46 4.5. sendx(uri, sock, data)
47 4.6. is_incoming()
48 4.7. msg_iflag_set(flagname)
49 4.8. msg_iflag_reset(flagname)
50 4.9. msg_iflag_is_set(flagname)
51 4.10. file_read(fpath, var)
52 4.11. file_write(fpath, content)
53 4.12. setxflag(flag)
54 4.13. isxflagset(flag)
55 4.14. resetxflag(flag)
56 4.15. set_send_socket(saddr)
57 4.16. set_send_socket_name(sname)
58 4.17. set_recv_socket(saddr)
59 4.18. set_recv_socket_name(sname)
60 4.19. set_source_address(saddr)
61 4.20. via_add_srvid(flags)
62 4.21. via_add_xavp_params(flags)
63 4.22. via_use_xavp_fields(flags)
64 4.23. via_reply_add_xavp_params(flags)
65 4.24. is_faked_msg()
66 4.25. is_socket_name(sockname)
67 4.26. forward_uac()
68 4.27. forward_uac_uri(vuri)
69 4.28. forward_reply()
70 4.29. msg_vbflag_set(flag)
71 4.30. msg_vbflag_is_set(flag)
72 4.31. msg_vbflag_reset(flag)
73 4.32. add_tcp_alias(port)
74
75 5. RPC Commands
76
77 5.1. corex.debug
78 5.2. corex.list_sockets
79 5.3. corex.list_aliases
80 5.4. corex.shm_status
81 5.5. corex.shm_summary
82 5.6. corex.pkg_summary
83 5.7. corex.shm.info
84 5.8. corex.shm.report
85 5.9. corex.shm.stats
86 5.10. corex.shm.rprint
87
88 6. Event Routes
89
90 6.1. event_route[network:msg]
91 6.2. event_route[corex:reply-out]
92
93 7. Examples of Usage
94
95 List of Examples
96
97 1.1. Set alias_subdomains parameter
98 1.2. Set dns_cache parameter
99 1.3. Set dns_file parameter
100 1.4. Set evcb_reply_out parameter
101 1.5. Set nio_intercept parameter
102 1.6. Set nio_min_msg_len parameter
103 1.7. Set nio_msg_avp parameter
104 1.8. append_branch usage
105 1.9. send_udp usage
106 1.10. send_tcp usage
107 1.11. send_data usage
108 1.12. sendx usage
109 1.13. is_incoming usage
110 1.14. msg_iflag_set usage
111 1.15. msg_iflag_reset usage
112 1.16. msg_iflag_is_set usage
113 1.17. file_read usage
114 1.18. file_write usage
115 1.19. setxflag usage
116 1.20. isxflagset usage
117 1.21. resetxflag usage
118 1.22. set_send_socket usage
119 1.23. set_send_socket_name usage
120 1.24. set_recv_socket usage
121 1.25. set_recv_socket_name usage
122 1.26. set_source_address usage
123 1.27. via_add_srvid usage
124 1.28. via_add_xavp_params usage
125 1.29. via_use_xavp_fields usage
126 1.30. via_reply_add_xavp_params usage
127 1.31. is_faked_msg usage
128 1.32. is_socket_name usage
129 1.33. forward_uac usage
130 1.34. forward_uac usage
131 1.35. forward_reply usage
132 1.36. msg_vbflag_set usage
133 1.37. msg_vbflag_is_set usage
134 1.38. msg_vbflag_reset usage
135 1.39. add_tcp_alias usage
136 1.40. event_route[network:msg] use cases
137 1.41. Sample PERL code for do_compress and do_uncompress
138
139 Chapter 1. Admin Guide
140
141 Table of Contents
142
143 1. Overview
144 2. Dependencies
145
146 2.1. Kamailio Modules
147 2.2. External Libraries or Applications
148
149 3. Parameters
150
151 3.1. alias_subdomains (string)
152 3.2. dns_cache (string)
153 3.3. dns_file (string)
154 3.4. evcb_reply_out (string)
155 3.5. nio_intercept (int)
156 3.6. nio_min_msg_len (int)
157 3.7. nio_msg_avp (string)
158
159 4. Functions
160
161 4.1. append_branch([ uri, [ q ] ])
162 4.2. send_udp([ host [ :port ] ])
163 4.3. send_tcp([ host [ :port ] ])
164 4.4. send_data(uri, data)
165 4.5. sendx(uri, sock, data)
166 4.6. is_incoming()
167 4.7. msg_iflag_set(flagname)
168 4.8. msg_iflag_reset(flagname)
169 4.9. msg_iflag_is_set(flagname)
170 4.10. file_read(fpath, var)
171 4.11. file_write(fpath, content)
172 4.12. setxflag(flag)
173 4.13. isxflagset(flag)
174 4.14. resetxflag(flag)
175 4.15. set_send_socket(saddr)
176 4.16. set_send_socket_name(sname)
177 4.17. set_recv_socket(saddr)
178 4.18. set_recv_socket_name(sname)
179 4.19. set_source_address(saddr)
180 4.20. via_add_srvid(flags)
181 4.21. via_add_xavp_params(flags)
182 4.22. via_use_xavp_fields(flags)
183 4.23. via_reply_add_xavp_params(flags)
184 4.24. is_faked_msg()
185 4.25. is_socket_name(sockname)
186 4.26. forward_uac()
187 4.27. forward_uac_uri(vuri)
188 4.28. forward_reply()
189 4.29. msg_vbflag_set(flag)
190 4.30. msg_vbflag_is_set(flag)
191 4.31. msg_vbflag_reset(flag)
192 4.32. add_tcp_alias(port)
193
194 5. RPC Commands
195
196 5.1. corex.debug
197 5.2. corex.list_sockets
198 5.3. corex.list_aliases
199 5.4. corex.shm_status
200 5.5. corex.shm_summary
201 5.6. corex.pkg_summary
202 5.7. corex.shm.info
203 5.8. corex.shm.report
204 5.9. corex.shm.stats
205 5.10. corex.shm.rprint
206
207 6. Event Routes
208
209 6.1. event_route[network:msg]
210 6.2. event_route[corex:reply-out]
211
212 7. Examples of Usage
213
214 1. Overview
215
216 This module provides reimplementation of a few very old functions that
217 used to be in the core and supported only static string or integer
218 parameters. The new versions bring support for dynamic parameters
219 (allowing variables inside the parameters).
220
221 There are also brand new features, related to core internals, but
222 controlled from configuration file or via control interfaces.
223
224 Contributions to this module must be done under the BSD license, to
225 follow the requirements of the core contributions.
226
227 This module now also provides access to network input / output (nio)
228 data through event_route[network:msg]. The raw data received from a
229 remote host or about to be sent to a remote host is available in
230 variable $mb. The script writer may manipulate this data and save the
231 final result in an AVP defined by msg_avp module parameter. The content
232 of this AVP will then be processed by SIP worker as normal, i.e. a
233 received message will be parsed and sent to appropriate route block
234 while a sent message is forwarded to remote host.
235
236 2. Dependencies
237
238 2.1. Kamailio Modules
239 2.2. External Libraries or Applications
240
241 2.1. Kamailio Modules
242
243 The following modules must be loaded before this module:
244 * None.
245
246 2.2. External Libraries or Applications
247
248 The following libraries or applications must be installed before
249 running Kamailio with this module loaded:
250 * None
251
252 3. Parameters
253
254 3.1. alias_subdomains (string)
255 3.2. dns_cache (string)
256 3.3. dns_file (string)
257 3.4. evcb_reply_out (string)
258 3.5. nio_intercept (int)
259 3.6. nio_min_msg_len (int)
260 3.7. nio_msg_avp (string)
261
262 3.1. alias_subdomains (string)
263
264 Register a domain and all its sub-domains to match the “myself”
265 condition. It can be set many times. Its full format is:
266 'proto:domain:port', allowing to set restrictions on protocol and port
267 as well. Protocol and port are optional.
268
269 Default value is “NULL”.
270
271 Example 1.1. Set alias_subdomains parameter
272 ...
273 modparam("corex", "alias_subdomains", "kamailio.org")
274 modparam("corex", "alias_subdomains", "udp:sip-router.org:5060")
275 ...
276
277 3.2. dns_cache (string)
278
279 Add A or AAAA records to internal DNS cache at startup. It can be set
280 many times to add more than one record.
281
282 The format of the value follows the SIP params style:
283 "attr1=val1;attr2=val2;...". The attributes can be:
284 * type - it can be "A" (IPv4), "AAAA" (IPv6) or "SRV"
285 * name - the domain name
286 * addr - the IP address
287 * ttl - TTL value
288 * priority - priority value for SRV record
289 * weight - weight value for SRV record
290 * port - port value for SRV record
291 * flags - can be: 1 - the domain is unresolvable (like blocklisted);
292 2 - the record is permanent (never times out, never deleted, never
293 overwritten)
294
295 Default value is “NULL”.
296
297 Example 1.2. Set dns_cache parameter
298 ...
299 modparam("corex", "dns_cache", "type=A;name=kamailio.org;addr=193.22.119.66;ttl=
300 3600000;flags=0")
301 modparam("corex", "dns_cache", "type=AAAA;name=kamailio.org;addr=2a00:d60:0:400:
302 :2;ttl=3600000;flags=0")
303 ...
304
305 3.3. dns_file (string)
306
307 Path to the file from where to load dns_cache records. It can be set
308 many times to add more than one file.
309
310 Inside the file, the dns_cache record has to be in a single line, with
311 the format of the dns_cache module parameter (see above). Empty lines
312 or lines with whitespaces only are ignored. Comment lines have to start
313 with '#'. Comments are not accepted after dns_cache records, only on
314 separate lines.
315
316 Default value is “NULL”.
317
318 Example 1.3. Set dns_file parameter
319 ...
320 # content of /etc/kamailio/kamailio-cache.dns
321
322 # IPv4 record
323 type=A;name=kamailio.org;addr=193.22.119.66;ttl=3600000;flags=0
324 # IPv6 record
325 type=AAAA;name=kamailio.org;addr=2a00:d60:0:400::2;ttl=3600000;flags=0
326 ...
327 ...
328 modparam("corex", "dns_file", "/etc/kamailio/kamailio-cache.dns")
329 ...
330
331 3.4. evcb_reply_out (string)
332
333 Name of KEMI callback function to be executed instead of
334 event_route[corex:reply-out].
335
336 Default value is “NULL”.
337
338 Example 1.4. Set evcb_reply_out parameter
339 ...
340 modparam("corex", "evcb_reply_out", "ksr_corex_reply_out")
341 ...
342
343 3.5. nio_intercept (int)
344
345 If set to non-zero then raw data received from a remote host or about
346 to be sent to a remote host is made available in
347 event_route[network:msg]. The script writer may modify this and save to
348 msg_avp, which will then be processed by SIP worker as normal.
349
350 Default value is 0, i.e. do not allow access to network io data.
351
352 Example 1.5. Set nio_intercept parameter
353 ...
354 modparam("corex", "nio_intercept", 1)
355 ...
356
357 3.6. nio_min_msg_len (int)
358
359 Minimum content length of the packet to execute the
360 event_route[network:msg]. This only works if nio_intercept parameter is
361 set to non-zero.
362
363 Default value is 0.
364
365 Example 1.6. Set nio_min_msg_len parameter
366 ...
367 modparam("corex", "nio_min_msg_len", 32)
368 ...
369
370 3.7. nio_msg_avp (string)
371
372 AVP name to store modified content to be set in the packet. If not set
373 in event_route[network:msg], then all changes are lost and original
374 contents are used. This only works if nio_intercept parameter is to set
375 non-zero.
376
377 Default value is empty.
378
379 Example 1.7. Set nio_msg_avp parameter
380 ...
381 modparam("corex", "nio_msg_avp", "$avp(msg)")
382 ...
383
384 4. Functions
385
386 4.1. append_branch([ uri, [ q ] ])
387 4.2. send_udp([ host [ :port ] ])
388 4.3. send_tcp([ host [ :port ] ])
389 4.4. send_data(uri, data)
390 4.5. sendx(uri, sock, data)
391 4.6. is_incoming()
392 4.7. msg_iflag_set(flagname)
393 4.8. msg_iflag_reset(flagname)
394 4.9. msg_iflag_is_set(flagname)
395 4.10. file_read(fpath, var)
396 4.11. file_write(fpath, content)
397 4.12. setxflag(flag)
398 4.13. isxflagset(flag)
399 4.14. resetxflag(flag)
400 4.15. set_send_socket(saddr)
401 4.16. set_send_socket_name(sname)
402 4.17. set_recv_socket(saddr)
403 4.18. set_recv_socket_name(sname)
404 4.19. set_source_address(saddr)
405 4.20. via_add_srvid(flags)
406 4.21. via_add_xavp_params(flags)
407 4.22. via_use_xavp_fields(flags)
408 4.23. via_reply_add_xavp_params(flags)
409 4.24. is_faked_msg()
410 4.25. is_socket_name(sockname)
411 4.26. forward_uac()
412 4.27. forward_uac_uri(vuri)
413 4.28. forward_reply()
414 4.29. msg_vbflag_set(flag)
415 4.30. msg_vbflag_is_set(flag)
416 4.31. msg_vbflag_reset(flag)
417 4.32. add_tcp_alias(port)
418
419 4.1. append_branch([ uri, [ q ] ])
420
421 Append a new branch to the destination set, useful to build the set of
422 destination addresses for parallel forking or redirect replies.
423
424 Both parameters are optional, If no uri parameter is provided, then the
425 address from request URI (r-uri) is used to build the new branch.
426
427 Meaning of the parameters is as follows:
428 * uri - SIP address of the branch to be used as R-URI in the outgoing
429 request.
430 * q - the Q value to set the priority of the branch based on Contact
431 address specifications
432
433 This function can be used from REQUEST_ROUTE or FAILURE_ROUTE.
434
435 Example 1.8. append_branch usage
436 ...
437 append_branch();
438 append_branch("$avp(uri)", "0.5");
439 ...
440
441 4.2. send_udp([ host [ :port ] ])
442
443 Send the original SIP message to a specific destination in stateless
444 mode. No changes are applied to received message, no Via header is
445 added. Host can be an IP address or hostname. Port is optional and
446 defaults to 5060. Used protocol: UDP.
447
448 The parameter is optional and defaults to the destination URI from the
449 SIP message if left out. Otherwise it's a string parameter (supporting
450 pseudo-variables) in format "hostname" or "hostname:port", where
451 hostname" can also be a numeric IP address.
452
453 This function can be used from REQUEST_ROUTE or FAILURE_ROUTE.
454
455 Example 1.9. send_udp usage
456 ...
457 send_udp();
458 send_udp("10.20.15.10");
459 send_udp("sip.example.com:5070");
460 send_udp("$var(res)");
461 ...
462
463 4.3. send_tcp([ host [ :port ] ])
464
465 This function is identical to send_udp() described above, except that
466 it sends the SIP message using the TCP protocol instead of UDP.
467
468 Example 1.10. send_tcp usage
469 ...
470 send_tcp();
471 send_tcp("10.20.15.10");
472 send_tcp("sip.example.com:5070");
473 send_tcp("$var(res)");
474 ...
475
476 4.4. send_data(uri, data)
477
478 Send the data to address specified by uri. Both parameters can contain
479 pseudo-variables. The uri parameter has to be a valid SIP URI. The data
480 parameter can by any arbitrary content.
481
482 This function can be used from ANY_ROUTE.
483
484 Example 1.11. send_data usage
485 ...
486 send_data("sip:example.com:5070;transport=sctp", "Message at $Ts");
487 ...
488
489 4.5. sendx(uri, sock, data)
490
491 Send the data to address specified by uri using a specific local
492 socket. All parameters can contain pseudo-variables. The uri parameter
493 has to be a valid SIP URI. The sock parameter has to be a valid socket
494 specifier (like values assigned to $fs). The data parameter can by any
495 arbitrary content.
496
497 This function can be used from ANY_ROUTE.
498
499 Example 1.12. sendx usage
500 ...
501 sendx("sip:example.com:5070;transport=sctp", "sctp:2.3.4.5:5060", "Message at $T
502 s");
503 ...
504
505 4.6. is_incoming()
506
507 Returns true if contents of message buffer $mb are the data received
508 from remote host, otherwise false indicating that the contents of $mb
509 are data that is about to be sent out to remote host. This only works
510 if nio_intercept parameter is set to non-zero.
511
512 This function can be used from event_route[network:msg].
513
514 Example 1.13. is_incoming usage
515 ...
516 event_route[network:msg] {
517 if (is_incoming()) {
518 xlog("L_INFO", "Received message '$mb' \n");
519 $avp(msg) = $mb;
520 } else {
521 xlog("L_INFO", "Sending message '$mb' \n");
522 $avp(msg) = $mb;
523 };
524 }
525 ...
526
527 4.7. msg_iflag_set(flagname)
528
529 Set internal SIP message flag. The parameter flagname can be:
530 USE_UAC_FROM, USE_UAC_TO, UAC_AUTH, MSG_APPLY_CHANGES or a number from
531 0 to 64 (the meaning of each value can be found in source code).
532
533 This functions should not be used in configuration file for (re)setting
534 the internal flags, those are done by various functions internally,
535 however, in very particular cases they might be useful (e.g., changing
536 From/To via textops functions, or during testing of C code
537 development).
538
539 This function can be used from ANY_ROUTE.
540
541 Example 1.14. msg_iflag_set usage
542 ...
543 msg_iflag_set("UAC_AUTH");
544 ...
545
546 4.8. msg_iflag_reset(flagname)
547
548 Reset the internal flag given as parameter.
549
550 This function can be used from ANY_ROUTE.
551
552 Example 1.15. msg_iflag_reset usage
553 ...
554 msg_iflag_reset("UAC_AUTH");
555 ...
556
557 4.9. msg_iflag_is_set(flagname)
558
559 Test if the internal flag given as parameter is set.
560
561 This function can be used from ANY_ROUTE.
562
563 Example 1.16. msg_iflag_is_set usage
564 ...
565 if(msg_iflag_is_set("UAC_AUTH")) { ... }
566 ...
567
568 4.10. file_read(fpath, var)
569
570 Read content of a text file into a variable.
571
572 This function can be used from ANY_ROUTE.
573
574 Example 1.17. file_read usage
575 ...
576 if(file_read("/tmp/data.txt", "$var(data)")) { ... }
577 ...
578
579 4.11. file_write(fpath, content)
580
581 Write content of parameter to a text file.
582
583 This function can be used from ANY_ROUTE.
584
585 Example 1.18. file_write usage
586 ...
587 if(file_write("/tmp/data.txt", "Data is: $var(data)")) { ... }
588 ...
589
590 4.12. setxflag(flag)
591
592 Set the extended message (transaction) flag.
593
594 Meaning of the parameters is as follows:
595 * flag - the index of the flag to be set. Can be integer or
596 pseudo-variable with integer value (range 0-63).
597
598 This function can be used from ANY_ROUTE.
599
600 Example 1.19. setxflag usage
601 ...
602 setxflag("1");
603 ...
604 $var(flag) = 11;
605 setxflag("$var(flag)");
606 ...
607
608 4.13. isxflagset(flag)
609
610 Return true if the extended message (transaction) flag is set.
611
612 Meaning of the parameters is as follows:
613 * flag - the index of the flag to be tested. Can be integer or
614 pseudo-variable with integer value (range 0-63).
615
616 This function can be used from ANY_ROUTE.
617
618 Example 1.20. isxflagset usage
619 ...
620 if(isxflagset("1"))
621 {
622 ...
623 }
624 ...
625
626 4.14. resetxflag(flag)
627
628 Reset the extended message (transaction) flag.
629
630 Meaning of the parameters is as follows:
631 * flag - the index of the flag to be reset. Can be integer or
632 pseudo-variable with integer value (range 0-63).
633
634 This function can be used from ANY_ROUTE.
635
636 Example 1.21. resetxflag usage
637 ...
638 resetxflag("1");
639 ...
640
641 4.15. set_send_socket(saddr)
642
643 Set the socket for sending out.
644
645 Meaning of the parameters is as follows:
646 * saddr - the address of the local socket (listen address). Can be a
647 static string or contain pseudo-variable.
648
649 This function can be used from ANY_ROUTE.
650
651 Example 1.22. set_send_socket usage
652 ...
653 set_send_socket("udp:127.0.0.1:5060");
654 ...
655
656 4.16. set_send_socket_name(sname)
657
658 Set the socket for sending out.
659
660 Meaning of the parameters is as follows:
661 * sname - the name of the local socket (listen address). Can be a
662 static string or contain pseudo-variable.
663
664 This function can be used from ANY_ROUTE.
665
666 Example 1.23. set_send_socket_name usage
667 ...
668 set_send_socket_name("sock1");
669 ...
670
671 4.17. set_recv_socket(saddr)
672
673 Switch local socket used for receiving the message.
674
675 Meaning of the parameters is as follows:
676 * saddr - the address of the local socket (listen address). Can be a
677 static string or contain pseudo-variable.
678
679 This function can be used from ANY_ROUTE.
680
681 Example 1.24. set_recv_socket usage
682 ...
683 set_recv_socket("udp:127.0.0.1:5060");
684 ...
685
686 4.18. set_recv_socket_name(sname)
687
688 Switch local socket used for receiving the message.
689
690 Meaning of the parameters is as follows:
691 * sname - the name of the local socket (listen address). Can be a
692 static string or contain pseudo-variable.
693
694 This function can be used from ANY_ROUTE.
695
696 Example 1.25. set_recv_socket_name usage
697 ...
698 set_recv_socket_name("sock1");
699 ...
700
701 4.19. set_source_address(saddr)
702
703 Set the source address for the message.
704
705 Meaning of the parameters is as follows:
706 * saddr - the source address in socket format. Can be a static string
707 or contain pseudo-variable.
708
709 This function can be used from ANY_ROUTE.
710
711 Example 1.26. set_source_address usage
712 ...
713 set_source_address("udp:127.0.0.1:5080");
714 ...
715
716 4.20. via_add_srvid(flags)
717
718 Control if srvid parameter is added or not to local Via. If yes, the
719 value is server_id, added only if it is different than 0.
720
721 Meaning of the parameters is as follows:
722 * flags: 1 - add srvid parameter; 0 - do not add srvid parameter.
723
724 This function can be used from ANY_ROUTE.
725
726 Example 1.27. via_add_srvid usage
727 ...
728 via_add_srv("1");
729 ...
730
731 4.21. via_add_xavp_params(flags)
732
733 Control if fields of the xavp with the name specified by
734 xavp_via_params global parameter are added or not to local Via.
735
736 Meaning of the parameters is as follows:
737 * flags: 1 - add xavp parameters; 0 - do not add xavp parameters.
738
739 This function can be used from ANY_ROUTE.
740
741 Example 1.28. via_add_xavp_params usage
742 ...
743 xavp_via_params="xvia"
744 ...
745 request_route {
746 ...
747 $xavp(xvia=>srvid) = "1";
748 $xavp(xvia[0]=>myval) = "xyz";
749 via_add_xavp_params("1");
750 ...
751 }
752 ...
753
754 4.22. via_use_xavp_fields(flags)
755
756 Control if fields of the xavp with the name specified by
757 xavp_via_fields global parameter are used or not to build local Via.
758
759 Meaning of the parameters is as follows:
760 * flags: 1 - use xavp fields; 0 - do not use xavp fields.
761
762 This function can be used from ANY_ROUTE.
763
764 Example 1.29. via_use_xavp_fields usage
765 ...
766 xavp_via_fields="mvia"
767 ...
768 request_route {
769 ...
770 $xavp(mvia=>address) = "10.10.10.10";
771 $xavp(mvia[0]=>port) = "5060";
772 via_use_xavp_fields("1");
773 ...
774 }
775 ...
776
777 4.23. via_reply_add_xavp_params(flags)
778
779 Control if fields of the xavp with the name specified by
780 xavp_via_reply_params global parameter are added or not to the top Via
781 of replies.
782
783 Meaning of the parameters is as follows:
784 * flags: 1 - add xavp parameters; 0 - do not add xavp parameters.
785
786 This function can be used from ANY_ROUTE.
787
788 Example 1.30. via_reply_add_xavp_params usage
789 ...
790 xavp_via_reply_params="xviarpl"
791 ...
792 request_route {
793 ...
794 $xavp(xviarpl=>srvid) = "1";
795 $xavp(xviarpl[0]=>myval) = "xyz";
796 via_reply_add_xavp_params("1");
797 ...
798 }
799 ...
800
801 4.24. is_faked_msg()
802
803 Returns 1 (native config true) if the SIP message under processing is
804 the internal faked msg structure. Returns -1 (native config false) if
805 the SIP message under processing is received from the network.
806
807 The function should be useful in event route blocks or async route
808 blocks where it can be processed either a message from the network or
809 the internal faked message.
810
811 This function can be used in ANY_ROUTE.
812
813 Example 1.31. is_faked_msg usage
814 ...
815 event_route[dispatcher:dst-down] {
816 if (is_faked_msg()) {
817 xinfo("Running with faked message\n");
818 }
819 }
820 ...
821
822 4.25. is_socket_name(sockname)
823
824 Returns 1 (native config true) if the parameter matches a local socket
825 name, otherwise -1 (native config false). The parameter can contain
826 variables.
827
828 This function can be used in ANY_ROUTE.
829
830 Example 1.32. is_socket_name usage
831 ...
832 if (is_socket_name("socktls")) {
833 xinfo("matched local socket name\n");
834 }
835 ...
836
837 4.26. forward_uac()
838
839 Forward received request with a single Via header, the one added by
840 Kamailio, the other ones being removed. Useful in cases when its reply
841 should not be sent back (e.g., the reply was already sent out from
842 Kamailio).
843
844 This function can be used in REQUEST_ROUTE.
845
846 Example 1.33. forward_uac usage
847 ...
848 request_route {
849 ...
850 sl_send_reply("200", "OK");
851 $du = "sip:mirror.com:5080";
852 forward_uac();
853 ...
854 }
855 ...
856
857 4.27. forward_uac_uri(vuri)
858
859 Similar to forward_uac() with the posibility to provide the target
860 address as a SIP URI via the parameter vuri. The parameter vuri can
861 contain variables.
862
863 This function can be used in REQUEST_ROUTE.
864
865 Example 1.34. forward_uac usage
866 ...
867 request_route {
868 ...
869 sl_send_reply("200", "OK");
870 forward_uac_uri("sip:mirror.com:5080");
871 ...
872 }
873 ...
874
875 4.28. forward_reply()
876
877 Forward received reply on demand.
878
879 This function can be used in CORE_ONREPLY_ROUTE.
880
881 Example 1.35. forward_reply usage
882 ...
883 route[reply] {
884 forward_reply();
885 }
886 ...
887
888 4.29. msg_vbflag_set(flag)
889
890 Set the via-body flag.
891
892 Meaning of the parameters is as follows:
893 * flag - the index of the flag to be set. Can be integer or
894 pseudo-variable with integer value (range 0-31).
895
896 This function can be used from ANY_ROUTE.
897
898 Example 1.36. msg_vbflag_set usage
899 ...
900 msg_vbflag_set("1");
901 ...
902 $var(flag) = 11;
903 msg_vbflag_set("$var(flag)");
904 ...
905
906 4.30. msg_vbflag_is_set(flag)
907
908 Return true if the via-body flag is set.
909
910 Meaning of the parameters is as follows:
911 * flag - the index of the flag to be tested. Can be integer or
912 pseudo-variable with integer value (range 0-31).
913
914 This function can be used from ANY_ROUTE.
915
916 Example 1.37. msg_vbflag_is_set usage
917 ...
918 if(msg_vbflag_is_set("1"))
919 {
920 ...
921 }
922 ...
923
924 4.31. msg_vbflag_reset(flag)
925
926 Reset the via-body flag.
927
928 Meaning of the parameters is as follows:
929 * flag - the index of the flag to be reset. Can be integer or
930 pseudo-variable with integer value (range 0-31).
931
932 This function can be used from ANY_ROUTE.
933
934 Example 1.38. msg_vbflag_reset usage
935 ...
936 msg_vbflag_reset("1");
937 ...
938
939 4.32. add_tcp_alias(port)
940
941 Add an alias to the TCP connection with the port parameter. If the port
942 is 0, then the port of the first Via-header is used. The parameter can
943 also be a variable holding an integer port value.
944
945 This function can be used from ANY_ROUTE.
946
947 Example 1.39. add_tcp_alias usage
948 ...
949 add_tcp_alias("5062");
950 ...
951 add_tcp_alias("$sp");
952 ...
953
954 5. RPC Commands
955
956 5.1. corex.debug
957 5.2. corex.list_sockets
958 5.3. corex.list_aliases
959 5.4. corex.shm_status
960 5.5. corex.shm_summary
961 5.6. corex.pkg_summary
962 5.7. corex.shm.info
963 5.8. corex.shm.report
964 5.9. corex.shm.stats
965 5.10. corex.shm.rprint
966
967 5.1. corex.debug
968
969 Set or get the global log level (the value for global parameter
970 'debug'). To set the debug, provide an integer parameter. If no
971 parameter is provided, then the current value is returned.
972
973 Example:
974 kamctl rpc corex.debug
975 kamctl rpc corex.debug 2
976
977 5.2. corex.list_sockets
978
979 Print the list of sockets the application is listening on.
980
981 Example:
982 kamcmd corex.list_sockets
983
984 5.3. corex.list_aliases
985
986 Print the list of hostname aliases used to match the myself condition.
987
988 Example:
989 kamcmd corex.list_aliases
990
991 5.4. corex.shm_status
992
993 Trigger shm status dump to syslog.
994
995 Example:
996 kamcmd corex.shm_status
997
998 5.5. corex.shm_summary
999
1000 Trigger shm summary dump to syslog.
1001
1002 Example:
1003 kamcmd corex.shm_summary
1004
1005 5.6. corex.pkg_summary
1006
1007 Trigger pkg summary dump to syslog for a specific pid or process index.
1008 It has two parameters: first to specify what matching type is desired
1009 (can be 'pid' or 'idx'); second to specify the value for desired match.
1010
1011 The dump is happening when the selected process is doing a runtime
1012 handling (e.g., processing a sip message).
1013
1014 Example:
1015 kamcmd corex.pkg_summary pid 2345
1016 kamcmd corex.pkg_summary idx 1
1017
1018 5.7. corex.shm.info
1019
1020 Return shared memory manager details.
1021
1022 Example:
1023 kamcli rpc shm.info
1024
1025 5.8. corex.shm.report
1026
1027 Return shared memory manager usage report.
1028
1029 Example:
1030 kamcli rpc shm.report
1031
1032 5.9. corex.shm.stats
1033
1034 Return shared memory statistics (values are in bytes).
1035
1036 Example:
1037 kamcli rpc shm.stats
1038
1039 5.10. corex.shm.rprint
1040
1041 Shared memory usage status report printed to file upon filter match
1042 with the file of allocation.
1043
1044 It takes two parameters: the path to file where to write the report;
1045 the string to match the allocation file (the match is done as value
1046 included in the path fo the allocation file).
1047
1048 Example:
1049 kamcli rpc shm.rprint /tmp/kamailioshm.txt dns_cache.c
1050
1051 6. Event Routes
1052
1053 6.1. event_route[network:msg]
1054 6.2. event_route[corex:reply-out]
1055
1056 6.1. event_route[network:msg]
1057
1058 Event route block to be executed when new data is received from network
1059 or the data that is about to be sent to a remote host by a SIP worker
1060 process.
1061
1062 The kamailio script writer can check which type of data triggered this
1063 event route using is_incoming method.
1064
1065 After executing of this event route, if msg_avp was defined and set
1066 then its value is used for further processing, otherwise, original
1067 value of $mb is used. If message was received from remote host, then it
1068 is parsed and proceeds to appropriate route. Otherwise if message set
1069 to send out, then is sent to remote host per configured SIP timers in
1070 config script.
1071
1072 Please note this event route is meant to prepare the message for
1073 on-wire communication, e.g. to do custom encryption or decryption,
1074 compression/decompression etc. of the message sent to or received from
1075 remote host. Therefore, except text operations, no module functions or
1076 pseudo variables are available in this event route.
1077
1078 6.2. event_route[corex:reply-out]
1079
1080 Event route block to be executed when a SIP reply is sent out.
1081
1082 7. Examples of Usage
1083
1084 To use network event_route[network:msg] the remote SIP UA must also
1085 implement and understand the encoding / decoding done in this event
1086 route. It is up to Kamailio config script writer to define and
1087 implement how encoding and decoding is done. Any language module such
1088 as app_perl or app_lua can be called in in event_route[network:msg] to
1089 implement desired logic.
1090
1091 The most simple use case is to compress the SIP packet on-wire. As SIP
1092 is a text based protocol, so it is highly compressable. Using this
1093 module, one can compress entire SIP message, including headers and
1094 message body before sending it to remote host using any compression
1095 algorithm of choice, thus saving significant bandwidth on mobile data
1096 networks.
1097
1098 A useful case is to use this function between SIP edge proxy and SIP
1099 application server. The SIP messages received from end-user at SIP edge
1100 proxy may be decrypted and sent to SIP application server at remote
1101 location unencrypted, where they are processed as normal. One the way
1102 back, the messages received from SIP application server at edge proxy
1103 can be encrypted before being sent to actual destination. The edge
1104 proxy can check whether received message came from end-user or SIP
1105 application server by using simple regular expressions.
1106
1107 Another use case is to implement a virtual HTTP tunnel for SIP
1108 messages. The SIP client app can convert SIP message to binary e.g. by
1109 doing XOR, Base64 etc., then prepend some fake HTTP headers to make it
1110 look like an HTTP request before sending it to kamailio over SIP TCP
1111 socket. At kamailio, the fake headers are removed and data is decoded
1112 back to normal SIP and processed per config script logic. For the data
1113 that is to be sent to SIP client app, one can prepend fake HTTP reply
1114 headers to encoded data before sending it to client app.
1115
1116 More advance use cases may involve custom encryption algorithms such as
1117 ITV encryption algorithm, https://github.com/mshary/itv
1118
1119 For example, the client app running on Android or iPhone, may send
1120 device UUID along with ITV key, encrypted using RSA or AES256 with
1121 pre-shared secret, as first packet, which is set as cookie by server in
1122 e.g. memcache. This cookie is referred by client app in each next
1123 packet, so server can retrieve encryption key from cache and use that
1124 for decryption. Same can be done for server at client app side, so
1125 messages encrypted by server can be decrypted at client app.
1126
1127 Next is a basic usage example where encoding and decoding is done using
1128 PERL.
1129
1130 Example 1.40. event_route[network:msg] use cases
1131 ...
1132 loadmodule "app_perl.so"
1133 loadmodule "corex.so"
1134 ...
1135 # ----- app_perl params -----
1136 modparam("app_perl", "filename", "/usr/local/etc/kamailio/custom_compress.pl")
1137 modparam("app_perl", "modpath", "/usr/local/lib64/kamailio/perl")
1138
1139 # ----- corex params -----
1140 modparam("corex", "nio_intercept", 32)
1141 modparam("corex", "nio_min_msg_len", 32)
1142 modparam("corex", "nio_msg_avp", "$avp(msg)")
1143 ...
1144 event_route[network:msg] {
1145 if (is_incoming()) {
1146 if (perl_exec_simple("do_uncompress", "" + $mb + "")) {
1147 xlog("L_INFO", "Received message '$avp(msg)' \n");
1148 } else {
1149 xlog("L_INFO", "Received message '$mb' \n");
1150 $avp(msg) = $mb;
1151 };
1152 } else {
1153 xlog("L_INFO", "Sending message '$mb' \n");
1154 if (!perl_exec_simple("do_compress", "" + $mb + "")) {
1155 $avp(msg) = $mb;
1156 };
1157 };
1158 }
1159 ...
1160
1161 Example 1.41. Sample PERL code for do_compress and do_uncompress
1162 ...
1163 use strict;
1164 use warnings;
1165 use IO::Compress::Gzip qw(gzip $GzipError) ;
1166 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
1167
1168 sub do_compress() {
1169 my $input = shift;
1170 my $output;
1171
1172 gzip \$input => \$output
1173 or eval {
1174 Kamailio::log(L_WARN, "GZIP failed: $GzipError\n");
1175 $output = $input;
1176 };
1177
1178 Kamailio::AVP::add("msg", $output);
1179 }
1180
1181 sub do_uncompress() {
1182 my $input = shift;
1183 my $output;
1184
1185 gunzip \$input => \$output
1186 or eval {
1187 Kamailio::log(L_WARN, "GUNZIP failed: $GzipError\n");
1188 $output = $input;
1189 };
1190
1191 Kamailio::AVP::add("msg", $output);
1192 }
1193 ...