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