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