modules: readme files regenerated - uac ... [skip ci]
[sip-router] / src / modules / sipcapture / README
1 SipCapture Module
2
3 Alexandr Dubovikov
4
5    <alexandr.dubovikov@gmail.com>
6
7 Edited by
8
9 Alexandr Dubovikov
10
11    <alexandr.dubovikov@gmail.com>
12
13    Copyright © 2011-15 SIPCAPTURE ORG
14
15    Copyright © 2011 QSC AG
16
17    Copyright © 2011 http://www.qsc.de
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. db_url (str)
33               3.2. table_name (str)
34               3.3. mt_mode (str)
35               3.4. hash_source (str)
36               3.5. db_insert_mode (integer)
37               3.6. capture_on (integer)
38               3.7. capture_mode (str)
39               3.8. hep_capture_on (integer)
40               3.9. raw_ipip_capture_on (integer)
41               3.10. raw_moni_capture_on (integer)
42               3.11. raw_socket_listen (string)
43               3.12. raw_interface (string)
44               3.13. raw_sock_children (integer)
45               3.14. promiscuous_on (integer)
46               3.15. raw_moni_bpf_on (integer)
47               3.16. capture_node (str)
48               3.17. insert_retries (integer)
49               3.18. insert_retry_timeout (integer)
50               3.19. callid_aleg_header (str)
51               3.20. topoh_unmask (int)
52               3.21. nonsip_hook (int)
53               3.22. event_callback (str)
54               3.23. capture_bad_msgs (int)
55
56         4. Functions
57
58               4.1. sip_capture([table], [cmode])
59               4.2. report_capture([table], [cid], [data])
60               4.3. float2int(fval, ival)
61               4.4. sip_capture_forward(uri)
62
63         5. Event Routes
64
65               5.1. event_route[sipcapture:request]
66
67         6. RPC Commands
68
69               6.1. sipcapture.status param
70
71         7. Database setup
72         8. Limitations
73
74    List of Examples
75
76    1.1. Set db_url parameter
77    1.2. Set sip_capture parameter
78    1.3. Set mt_mode parameter
79    1.4. Set mt_mode parameter
80    1.5. db_insert_mode example
81    1.6. Set capture_on parameter
82    1.7. capture_mode example
83    1.8. Set hep_capture_on parameter
84    1.9. Set raw_ipip_capture_on parameter
85    1.10. Set raw_moni_capture_on parameter
86    1.11. Set raw_socket_listen parameter
87    1.12. Set raw_interface parameter
88    1.13. Set raw_sock_children parameter
89    1.14. Set promiscuous_on parameter
90    1.15. Set raw_moni_bpf_on parameter
91    1.16. Set capture_node parameter
92    1.17. Set insert_retries parameter
93    1.18. Set insert_retry_timeout parameter
94    1.19. Set callid_aleg_header parameter
95    1.20. Set topoh_unmask parameter
96    1.21. Set nonsip_hook parameter
97    1.22. Set event_callback parameter
98    1.23. Set capture_bad_msgs parameter
99    1.24. sip_capture() usage
100    1.25. report_capture() usage
101    1.26. report_capture() usage
102    1.27. sip_capture_forward() usage
103    1.28. event_route[sipcapture:request] usage
104
105 Chapter 1. Admin Guide
106
107    Table of Contents
108
109    1. Overview
110    2. Dependencies
111
112         2.1. Kamailio Modules
113         2.2. External Libraries or Applications
114
115    3. Parameters
116
117         3.1. db_url (str)
118         3.2. table_name (str)
119         3.3. mt_mode (str)
120         3.4. hash_source (str)
121         3.5. db_insert_mode (integer)
122         3.6. capture_on (integer)
123         3.7. capture_mode (str)
124         3.8. hep_capture_on (integer)
125         3.9. raw_ipip_capture_on (integer)
126         3.10. raw_moni_capture_on (integer)
127         3.11. raw_socket_listen (string)
128         3.12. raw_interface (string)
129         3.13. raw_sock_children (integer)
130         3.14. promiscuous_on (integer)
131         3.15. raw_moni_bpf_on (integer)
132         3.16. capture_node (str)
133         3.17. insert_retries (integer)
134         3.18. insert_retry_timeout (integer)
135         3.19. callid_aleg_header (str)
136         3.20. topoh_unmask (int)
137         3.21. nonsip_hook (int)
138         3.22. event_callback (str)
139         3.23. capture_bad_msgs (int)
140
141    4. Functions
142
143         4.1. sip_capture([table], [cmode])
144         4.2. report_capture([table], [cid], [data])
145         4.3. float2int(fval, ival)
146         4.4. sip_capture_forward(uri)
147
148    5. Event Routes
149
150         5.1. event_route[sipcapture:request]
151
152    6. RPC Commands
153
154         6.1. sipcapture.status param
155
156    7. Database setup
157    8. Limitations
158
159 1. Overview
160
161    The sipcapture module stores incoming/outgoing SIP messages in
162    database.
163
164    Kamailio can capture SIP messages in three modes
165      * IPIP encapsulation. (ETHHDR+IPHDR+IPHDR+UDPHDR).
166      * Monitoring/mirroring port.
167      * Homer encapsulation protocol mode (HEP v1, v2, v3).
168
169    The capturing can be turned on/off using rpc commands. Example:
170
171    kamctl rpc sipcapture.status on
172
173    kamctl rpc sipcapture.status off
174
175 2. Dependencies
176
177    2.1. Kamailio Modules
178    2.2. External Libraries or Applications
179
180 2.1. Kamailio Modules
181
182    The following modules must be loaded before this module:
183      * database module - mysql, postgres, dbtext, unixodbc...
184
185 2.2. External Libraries or Applications
186
187    The following libraries or applications must be installed before
188    running Kamailio with this module loaded:
189      * None.
190
191 3. Parameters
192
193    3.1. db_url (str)
194    3.2. table_name (str)
195    3.3. mt_mode (str)
196    3.4. hash_source (str)
197    3.5. db_insert_mode (integer)
198    3.6. capture_on (integer)
199    3.7. capture_mode (str)
200    3.8. hep_capture_on (integer)
201    3.9. raw_ipip_capture_on (integer)
202    3.10. raw_moni_capture_on (integer)
203    3.11. raw_socket_listen (string)
204    3.12. raw_interface (string)
205    3.13. raw_sock_children (integer)
206    3.14. promiscuous_on (integer)
207    3.15. raw_moni_bpf_on (integer)
208    3.16. capture_node (str)
209    3.17. insert_retries (integer)
210    3.18. insert_retry_timeout (integer)
211    3.19. callid_aleg_header (str)
212    3.20. topoh_unmask (int)
213    3.21. nonsip_hook (int)
214    3.22. event_callback (str)
215    3.23. capture_bad_msgs (int)
216
217 3.1. db_url (str)
218
219    Database URL.
220
221    Default value is "".
222
223    Example 1.1. Set db_url parameter
224 ...
225 modparam("sipcapture", "db_url", "mysql://user:passwd@host/dbname")
226 ...
227
228 3.2. table_name (str)
229
230    Name of the table's name used to store the SIP messages. Can contain
231    multiple tables, separated by "|".
232
233    Default value is "sip_capture". Only for Homer 3. For Homer 5, please
234    use an argument for the sip_capture function.
235
236    Example 1.2. Set sip_capture parameter
237 ...
238 modparam("sipcapture", "table_name", "homer_capture")
239 ...
240 modparam("sipcapture", "table_name", "homer_capture1|homer_capture2");
241 ...
242
243 3.3. mt_mode (str)
244
245    Name of the mode used for storing data in multiple tables. Modes can be
246    "rand" (random), "round_robin" (use a round_robin algorithm) or "hash"
247    (use hashing to determine the table to store). These modes are only
248    triggered if there is more than one table specified in table_name
249    parameter, separated by "|".
250
251    Default value is "rand".
252
253    Example 1.3. Set mt_mode parameter
254 ...
255 modparam("sipcapture", "mt_mode", "hash")
256 ...
257
258 3.4. hash_source (str)
259
260    The field of the SIP message used for hashing, when mt_mode is set to
261    "hash". The value can be "call_id", "to_user" or "from_user".
262
263    Default value is "call_id".
264
265    Example 1.4. Set mt_mode parameter
266 ...
267 modparam("sipcapture", "hash_source", "to_user")
268 ...
269
270 3.5. db_insert_mode (integer)
271
272    If set to 1, use INSERT DELAYED to store sip message into capture table
273    when the DB driver has support for it. If no INSERT DELAYED support is
274    offered by DB driver, then standard INSERT is used.
275
276    If set to 2, use ASYNC INSERT to store sip message into capture table
277    when the DB driver has support for it. If no ASYNC INSERT support is
278    offered by DB driver, then standard INSERT is used.
279
280    Default value is 0 (no INSERT DELAYED).
281
282    Example 1.5. db_insert_mode example
283 modparam("sipcapture", "db_insert_mode", 1)
284
285 3.6. capture_on (integer)
286
287    Parameter to enable/disable capture globally (on(1)/off(0))
288
289    Default value is "0".
290
291    Example 1.6. Set capture_on parameter
292 ...
293 modparam("sipcapture", "capture_on", 1)
294 ...
295
296 3.7. capture_mode (str)
297
298    This parameter can be used for defining a capture mode which can be
299    used in the sip_capture calls as a parameter. A capture mode has a name
300    and some parameters. It must be defined in the format:
301    name=>param1=val1;param2=val2;... The parameters are db_url,
302    table_name, mt_mode and hash_source (optional). Multiple capture modes
303    can be defined by using this parameter multiple times. After this, the
304    capture modes can be used like: sip_capture ("", "CAPTURE_MODE");
305
306    Example 1.7. capture_mode example
307 modparam("sipcapture", "capture_mode", "mode1=>db_url=mysql://user:passwd@host/d
308 bname1;table_name=homer_capture1|homer_capture2;mt_mode=hash;hash_source=call_id
309 ;")
310 modparam("sipcapture", "capture_mode", "mode2=>db_url=mysql://user:passwd@host/d
311 bname2;table_name=homer_capture3|homer_capture4;mt_mode=rand;")
312
313 3.8. hep_capture_on (integer)
314
315    Parameter to enable/disable capture of HEP (on(1)/off(0))
316
317    Default value is "0".
318
319    Example 1.8. Set hep_capture_on parameter
320 ...
321 modparam("sipcapture", "hep_capture_on", 1)
322 ...
323
324 3.9. raw_ipip_capture_on (integer)
325
326    Parameter to enable/disable IPIP capturing (on(1)/off(0))
327
328    Default value is "0".
329
330    Example 1.9. Set raw_ipip_capture_on parameter
331 ...
332 modparam("sipcapture", "raw_ipip_capture_on", 1)
333 ...
334
335 3.10. raw_moni_capture_on (integer)
336
337    Parameter to enable/disable monitoring/mirroring port capturing
338    (on(1)/off(0)) Only one mode on raw socket can be enabled! Monitoring
339    port capturing currently supported only on Linux.
340
341    Default value is "0".
342
343    Example 1.10. Set raw_moni_capture_on parameter
344 ...
345 modparam("sipcapture", "raw_moni_capture_on", 1)
346 ...
347
348 3.11. raw_socket_listen (string)
349
350    Parameter indicate an listen IP address of RAW socket for IPIP
351    capturing. You can also define a port/portrange for IPIP/Mirroring
352    mode, to capture SIP messages in specific ports:
353
354    "10.0.0.1:5060" - the source/destination port of the SIP message must
355    be equal 5060
356
357    "10.0.0.1:5060-5090" - the source/destination port of the SIP message
358    must be equal or be between 5060 and 5090.
359
360    The port/portrange must be defined if you are planning to use mirroring
361    capture! In this case, the part with IP address will be ignored, but to
362    make parser happy, use i.e. 10.0.0.0
363
364    Default value is "".
365
366    Example 1.11. Set raw_socket_listen parameter
367 ...
368 modparam("sipcapture", "raw_socket_listen", "10.0.0.1:5060-5090")
369 ...
370 modparam("sipcapture", "raw_socket_listen", "10.0.0.1:5060")
371 ...
372
373 3.12. raw_interface (string)
374
375    Name of the interface to bind on the raw socket.
376
377    Default value is "".
378
379    Example 1.12. Set raw_interface parameter
380 ...
381 modparam("sipcapture", "raw_interface", "eth0")
382 ...
383
384 3.13. raw_sock_children (integer)
385
386    Parameter define how many children that must be created to listen the
387    raw socket.
388
389    Default value is "1".
390
391    Example 1.13. Set raw_sock_children parameter
392 ...
393 modparam("sipcapture", "raw_sock_children", 6)
394 ...
395
396 3.14. promiscuous_on (integer)
397
398    Parameter to enable/disable promiscuous mode on the raw socket. Linux
399    only.
400
401    Default value is "0".
402
403    Example 1.14. Set promiscuous_on parameter
404 ...
405 modparam("sipcapture", "promiscuous_on", 1)
406 ...
407
408 3.15. raw_moni_bpf_on (integer)
409
410    Activate Linux Socket Filter (LSF based on BPF) on the mirroring
411    interface. The structure is defined in linux/filter.h. The default LSF
412    accept a port/portrange from the raw_socket_listen param. Currently LSF
413    supported only on Linux.
414
415    Default value is "0".
416
417    Example 1.15. Set raw_moni_bpf_on parameter
418 ...
419 modparam("sipcapture", "raw_moni_bpf_on", 1)
420 ...
421
422 3.16. capture_node (str)
423
424    Name of the capture node.
425
426    Default value is "homer01".
427
428    Example 1.16. Set capture_node parameter
429 ...
430 modparam("sipcapture", "capture_node", "homer03")
431 ...
432
433 3.17. insert_retries (integer)
434
435    The number of times Kamailio should retry to write to the Homer
436    database in case the first attempt failed. The retry is also limited
437    timewise by the insert_retry_timeout parameter. Values allowed range
438    from 0 to 500.
439
440    Default value is 0 (no retries).
441
442    Example 1.17. Set insert_retries parameter
443 ...
444 modparam("sipcapture", "insert_retries", 5)
445 ...
446
447 3.18. insert_retry_timeout (integer)
448
449    The time limit in seconds Kamailio retries to write to the Homer
450    database in case the first attempt failed. This parameter is only used
451    together with the insert_retries parameter. Values allowed range from 0
452    to 300.
453
454    Default value is 60 seconds.
455
456    Example 1.18. Set insert_retry_timeout parameter
457 ...
458 modparam("sipcapture", "insert_retry_timeout", 10)
459 ...
460
461 3.19. callid_aleg_header (str)
462
463    Header name used to correlate A-leg with B-leg. It can take a list of
464    headers, separated by semicolon, e.g. "X-CID0;X-CID1". First match
465    wins.
466
467    Default value is "X-CID".
468
469    Example 1.19. Set callid_aleg_header parameter
470 ...
471 modparam("sipcapture", "callid_aleg_header", "X-CallIDALeg")
472 ...
473
474 3.20. topoh_unmask (int)
475
476    If set to 1, call-id will be unmasked using topoh module api (topoh
477    module must be loaded in this case).
478
479    Default value is 0.
480
481    Example 1.20. Set topoh_unmask parameter
482 ...
483 modparam("sipcapture", "topoh_unmask", 1)
484 ...
485
486 3.21. nonsip_hook (int)
487
488    If set to 1, event route sipcapture:siprequest is run when HEP message
489    is received.
490
491    Default value is 0.
492
493    Example 1.21. Set nonsip_hook parameter
494 ...
495 modparam("sipcapture", "nonsip_hook", 1)
496 ...
497
498 3.22. event_callback (str)
499
500    The name of the function in the kemi configuration file (embedded
501    scripting language such as Lua, Python, ...) to be executed instead of
502    event_route[...] blocks.
503
504    The function receives a string parameter with the name of the event,
505    the values can be: 'sipcapture:request'.
506
507    Default value is 'empty' (no function is executed for events).
508
509    Example 1.22. Set event_callback parameter
510 ...
511 modparam("sipcapture", "event_callback", "ksr_sipcapture_event")
512 ...
513 -- event callback function implemented in Lua
514 function ksr_sipcapture_event(evname)
515         KSR.info("===== sipcapture module triggered event: " .. evname .. "\n");
516         return 1;
517 end
518 ...
519
520 3.23. capture_bad_msgs (int)
521
522    If set to something different than 0, tries to capture also the broken
523    SIP messages.
524
525    Default value is 0.
526
527    Example 1.23. Set capture_bad_msgs parameter
528 ...
529 modparam("sipcapture", "capture_bad_msgs", 1)
530 ...
531
532 4. Functions
533
534    4.1. sip_capture([table], [cmode])
535    4.2. report_capture([table], [cid], [data])
536    4.3. float2int(fval, ival)
537    4.4. sip_capture_forward(uri)
538
539 4.1.  sip_capture([table], [cmode])
540
541    Store the current processed HEP/IPIP SIP message in database. It is
542    stored in the form prior applying changes made to it.
543
544    Meaning of the parameters is as follows:
545      * table - The table where HEP SIP message will be stored. Homer 5 use
546        now tables with datestamp. To generate an automatic table's name
547        please use strftime parameters. I.e. $var(table) =
548        "sip_capture_call_%Y%m%d" and set the variable as an argument of
549        the sip_capture function.
550      * cmode - The reference to the capture_mode parameter.
551
552    This function can be used from ANY_ROUTE.
553    Default value is "NULL".
554
555    Example 1.24. sip_capture() usage
556 ...
557 sip_capture();
558 ...
559 sip_capture("sip_capture_call_20160124");
560 ...
561 sip_capture("", "cmode");
562 ...
563
564 4.2.  report_capture([table], [cid], [data])
565
566    Store the current processed HEP REPORT message in database.
567
568    Meaning of the parameters is as follows:
569      * table - The table where REPORT message will be stored.
570      * cid - The correlation id.
571      * data - The custom report data in JSON format.
572
573    This function can be used from ANY_ROUTE.
574    Default value is "NULL".
575
576    Example 1.25. report_capture() usage
577 ...
578 report_capture();
579 ...
580 report_capture("report_data", "$ci");
581 ...
582 report_capture("report_data", "$ci", "{\"MOS\":4.1,\"PACKET_LOST\":100"});
583 ...
584
585 4.3.  float2int(fval, ival)
586
587    Return the value of atof(fval) * atoi(ival). On case the result is 0,
588    then -1 is returned.
589
590    This function can be used from ANY_ROUTE.
591
592    Example 1.26. report_capture() usage
593 ...
594 $var(res) = float2int("10.5", "1");
595 ...
596
597 4.4.  sip_capture_forward(uri)
598
599    Forward the HEP packet to an address specified by the parameter uri (it
600    has to be a sip uri format). The function should be used inside
601    event_route[sipcapture:request]. After using this function, add a
602    return 0 in order to stop processing further the packet in the local
603    Kamailio instance.
604
605    This function can be used from ANY_ROUTE.
606
607    Example 1.27. sip_capture_forward() usage
608 ...
609     event_route[sipcapture:request] {
610         ...
611         if(src_ip==1.2.3.4) {
612             sip_capture_forward("sip:2.3.4.5:5090");
613             return 0;
614         }
615         ...
616     }
617 ...
618
619 5. Event Routes
620
621    5.1. event_route[sipcapture:request]
622
623 5.1. event_route[sipcapture:request]
624
625    Event route block to be executed when HEP packet is received. It
626    requires module parameter 'nonsip_hook' to be set to 1.
627
628    Example 1.28. event_route[sipcapture:request] usage
629 ...
630 # new event sipcapture socket
631 modparam("sipcapture", "nonsip_hook", 1)
632 ...
633
634 event_route[sipcapture:request] {
635
636         xlog("HEP Request!\n");
637         xlog("received sipcapture request from $si:$sp\n");
638         xlog("HEP VERSION $hep(version) request from $si:$sp\n");
639         xlog("HEP CHUNK Source IP $hep(0x002) request from $si:$sp\n");
640
641         # is it SIP ?
642         if($hep(0x00b) == 1) {
643
644                 # do parsing internal
645                 return 1;
646         } else {
647                 # if report lets proceed here with payload
648                 xlog("HEP CHUNK PAYLOAD $hep(0x00f) request from $si:$sp\n");
649                 return 0;
650         }
651 }
652 ...
653
654 6. RPC Commands
655
656    6.1. sipcapture.status param
657
658 6.1.  sipcapture.status param
659
660    Name: sipcapture.status
661
662    Parameters:
663      * on or off: turns on/off SIP message capturing. Possible values are:
664           + on
665           + off
666      * “check” does not change sipcapture status, just reports the current
667        status.
668
669    RPC Command Format:
670 ...
671 kamcmd sipcapture.status on
672 kamcmd sipcapture.status off
673 kamcmd sipcapture.status check
674 ...
675
676 7. Database setup
677
678    Before running Kamailio with the sipcapture module, you have to setup
679    the database tables where the module will store the data. For that, if
680    the table were not created by the installation script or you choose to
681    install everything by yourself you can use the homer_databases.sql, SQL
682    script in the sql folder of sipcapture module as template. You can also
683    find the complete database documentation on the project webpage,
684    https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
685
686 8. Limitations
687
688      * 1. Only one capturing mode on RAW socket is supported: IPIP or
689        monitoring/mirroring port. Don't activate both at the same time.
690        Obsolete. Please use HEP mirroring now.
691      * 2. Mirroring port capturing works only on Linux.