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