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