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