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