b45c29eb76d0f5fe77714b90ad2f7711814114bc
[sip-router] / src / modules / sipcapture / doc / sipcapture_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         
14         <title>&adminguide;</title>
15         
16         <section>
17         <title>Overview</title>
18         <para>
19                 The sipcapture module stores incoming/outgoing SIP messages in database.
20         </para>
21         <para>
22                 Kamailio can capture SIP messages in three modes
23                 <itemizedlist>
24                 <listitem>
25                 <para>
26                 IPIP encapsulation. (ETHHDR+IPHDR+IPHDR+UDPHDR).
27                 </para>
28                 </listitem>
29                 <listitem>
30                 <para>
31                 Monitoring/mirroring port.
32                 </para>
33                 </listitem>
34                 <listitem>
35                 <para>
36                 Homer encapsulation protocol mode (HEP v1, v2, v3). 
37                 </para>
38                 </listitem>
39                 </itemizedlist>
40         </para>
41
42         <para>
43         The capturing can be turned on/off using mi or rpc commands. Example:
44         </para>
45         <para>
46         &ctltool; fifo sip_capture on
47         </para>
48         <para>
49         &ctltool; fifo sip_capture off
50         </para>
51         </section>
52         <section>
53         <title>Dependencies</title>
54         <section>
55                 <title>&kamailio; Modules</title>
56                 <para>
57                 The following modules must be loaded before this module:
58                         <itemizedlist>
59                         <listitem>
60                         <para>
61                                 <emphasis>database module</emphasis> - mysql, postrgress,
62                                 dbtext, unixodbc...
63                         </para>
64                         </listitem>
65                         </itemizedlist>
66                 </para>
67         </section>
68         <section>
69                 <title>External Libraries or Applications</title>
70                 <para>
71                 The following libraries or applications must be installed before running
72                 &kamailio; with this module loaded:
73                         <itemizedlist>
74                         <listitem>
75                         <para>
76                                 <emphasis>None</emphasis>.
77                         </para>
78                         </listitem>
79                         </itemizedlist>
80                 </para>
81         </section>
82         </section>
83         <section>
84         <title>Parameters</title>
85         <section id="sipcapture.p.db_url">
86                 <title><varname>db_url</varname> (str)</title>
87                 <para>
88                 Database URL.
89                 </para>
90                 <para>
91                 <emphasis>
92                         Default value is "".
93                 </emphasis>
94                 </para>
95                 <example>
96                 <title>Set <varname>db_url</varname> parameter</title>
97                 <programlisting format="linespecific">
98 ...
99 modparam("sipcapture", "db_url", "mysql://user:passwd@host/dbname")
100 ...
101 </programlisting>
102                 </example>
103         </section>
104         <section id="sipcapture.p.table_name">
105                 <title><varname>table_name</varname> (str)</title>
106                 <para>
107                 Name of the table's name used to store the SIP messages. Can contain multiple tables, separated by "|".
108                 </para>
109                 <para>
110                 <emphasis>
111                         Default value is "sip_capture". Only for Homer 3. For Homer 5, please use an argument for the sip_capture function.
112                 </emphasis>
113                 </para>
114                 <example>
115                 <title>Set <varname>sip_capture</varname> parameter</title>
116                 <programlisting format="linespecific">
117 ...
118 modparam("sipcapture", "table_name", "homer_capture")
119 ...
120 modparam("sipcapture", "table_name", "homer_capture1|homer_capture2");
121 ...
122 </programlisting>
123                 </example>
124         </section>
125         <section id="sipcapture.p.mt_mode">
126                 <title><varname>mt_mode</varname> (str)</title>
127                 <para>
128                 Name of the mode used for storing data in multiple tables. Modes can be "rand" (random), "round_robin" (use a round_robin algorithm) or "hash" (use hashing to determine the table to store). These modes are only triggered if there is more than one table specified in table_name parameter, separated by "|". 
129                 </para>
130                 <para>
131                 <emphasis>
132                         Default value is "rand".
133                 </emphasis>
134                 </para>
135                 <example>
136                 <title>Set <varname>mt_mode</varname> parameter</title>
137                 <programlisting format="linespecific">
138 ...
139 modparam("sipcapture", "mt_mode", "hash")
140 ...
141 </programlisting>
142                 </example>
143         </section>
144         <section id="sipcapture.p.hash_source">
145                 <title><varname>hash_source</varname> (str)</title>
146                 <para>
147                 The field of the SIP message used for hashing, when mt_mode is set to "hash". The value can be "call_id", "to_user" or "from_user".
148                 </para>
149                 <para>
150                 <emphasis>
151                         Default value is "call_id".
152                 </emphasis>
153                 </para>
154                 <example>
155                 <title>Set <varname>mt_mode</varname> parameter</title>
156                 <programlisting format="linespecific">
157 ...
158 modparam("sipcapture", "hash_source", "to_user")
159 ...
160 </programlisting>
161                 </example>
162         </section>
163         <section id="sipcapture.p.db_insert_mode">
164                 <title><varname>db_insert_mode</varname> (integer)</title>
165                 <para>
166                 If set to 1, use INSERT DELAYED to store sip message into capture table
167                 when the DB driver has support for it. If no INSERT DELAYED support
168                 is offered by DB driver, then standard INSERT is used.
169                 </para>
170                 <para>
171                 If set to 2, use ASYNC INSERT to store sip message into capture table
172                 when the DB driver has support for it. If no ASYNC INSERT support is
173                 offered by DB driver, then standard INSERT is used.
174                 </para>
175                 <para>
176                 Default value is 0 (no INSERT DELAYED).
177                 </para>
178                 <example>
179                 <title>db_insert_mode example</title>
180                 <programlisting format="linespecific">
181 modparam("sipcapture", "db_insert_mode", 1)
182 </programlisting>
183                 </example>
184         </section>
185         <section id="sipcapture.p.capture_on">
186                 <title><varname>capture_on</varname> (integer)</title>
187                 <para>
188                 Parameter to enable/disable capture globaly (on(1)/off(0))
189                 </para>
190                 <para>
191                 <emphasis>
192                         Default value is "0".
193                 </emphasis>
194                 </para>
195                 <example>
196                 <title>Set <varname>capture_on</varname> parameter</title>
197                 <programlisting format="linespecific">
198 ...
199 modparam("sipcapture", "capture_on", 1)
200 ...
201 </programlisting>
202                 </example>
203         </section>
204
205         <section id="sipcapture.p.capture_mode">
206                 <title><varname>capture_mode</varname> (integer)</title>
207                 <para>
208                                 This parameter can be used for defining a capture mode which can be used in
209                                 the sip_capture calls as a parameter. A capture mode has a name and some parameters.
210                                 It must be defined in the format: name=>param1=val1;param2=val2;...
211                                 The parameters are db_url, table_name, mt_mode and hash_source (optional).
212                                 Multiple capture modes can be defined by using this parameter multiple times.
213                                 After this, the capture modes can be used like:
214                                 sip_capture ("", "CAPTURE_MODE");
215                                 </para>
216                 <example>
217                 <title>capture_mode example</title>
218                 <programlisting format="linespecific">
219 modparam("sipcapture", "capture_mode", "mode1=>db_url=mysql://user:passwd@host/dbname1;table_name=homer_capture1|homer_capture2;mt_mode=hash;hash_source=call_id;")
220 modparam("sipcapture", "capture_mode", "mode2=>db_url=mysql://user:passwd@host/dbname2;table_name=homer_capture3|homer_capture4;mt_mode=rand;")
221 </programlisting>
222                 </example>
223         </section>
224         <section id="sipcapture.p.hep_capture_on">
225                 <title><varname>hep_capture_on</varname> (integer)</title>
226                 <para>
227                 Parameter to enable/disable capture of HEP (on(1)/off(0))
228                 </para>
229                 <para>
230                 <emphasis>
231                         Default value is "0".
232                 </emphasis>
233                 </para>
234                 <example>
235                 <title>Set <varname>hep_capture_on</varname> parameter</title>
236                 <programlisting format="linespecific">
237 ...
238 modparam("sipcapture", "hep_capture_on", 1)
239 ...
240 </programlisting>
241                 </example>
242         </section>
243         <section id="sipcapture.p.raw_ipip_capture_on">
244                 <title><varname>raw_ipip_capture_on</varname> (integer)</title>
245                 <para>
246                 Parameter to enable/disable IPIP capturing (on(1)/off(0))
247                 </para>
248                 <para>
249                 <emphasis>
250                         Default value is "0".
251                 </emphasis>
252                 </para>
253                 <example>
254                 <title>Set <varname>raw_ipip_capture_on</varname> parameter</title>
255                 <programlisting format="linespecific">
256 ...
257 modparam("sipcapture", "raw_ipip_capture_on", 1)
258 ...
259 </programlisting>
260                 </example>
261         </section>
262         <section id="sipcapture.p.raw_moni_capture_on">
263                 <title><varname>raw_moni_capture_on</varname> (integer)</title>
264                 <para>
265                 Parameter to enable/disable monitoring/mirroring port capturing (on(1)/off(0))
266                 Only one mode on raw socket can be enabled! Monitoring port capturing currently 
267                 supported only on Linux.
268                 </para>
269                 <para>
270                 <emphasis>
271                         Default value is "0".
272                 </emphasis>
273                 </para>
274                 <example>
275                 <title>Set <varname>raw_moni_capture_on</varname> parameter</title>
276                 <programlisting format="linespecific">
277 ...
278 modparam("sipcapture", "raw_moni_capture_on", 1)
279 ...
280                 </programlisting>
281                 </example>
282         </section>
283         <section id="sipcapture.p.raw_socket_listen">
284                 <title><varname>raw_socket_listen</varname> (string)</title>
285                 <para>
286                 Parameter indicate an listen IP address of RAW socket for IPIP capturing. 
287                 You can also define a port/portrange for IPIP/Mirroring mode, to capture 
288                 SIP messages in specific ports:
289                 <para>
290                 "10.0.0.1:5060" - the source/destination port of the SIP message must be equal 5060
291                 </para>
292                 <para>
293                 "10.0.0.1:5060-5090" - the source/destination port of the SIP message must be 
294                 equal or be between 5060 and 5090.
295                 </para>
296                 <para>
297                 The port/portrange must be defined if you are planning to
298                 use mirroring capture! In this case, the part with IP address will be
299                 ignored, but to make parser happy, use i.e. 10.0.0.0
300                 </para>
301                 </para>
302                 <para>
303                 <emphasis>
304                         Default value is "".
305                 </emphasis>
306                 </para>
307                 <example>
308                 <title>Set <varname>raw_socket_listen</varname> parameter</title>
309                 <programlisting format="linespecific">
310 ...
311 modparam("sipcapture", "raw_socket_listen", "10.0.0.1:5060-5090")
312 ...
313 modparam("sipcapture", "raw_socket_listen", "10.0.0.1:5060")
314 ...
315 </programlisting>
316                 </example>
317         </section>
318         <section id="sipcapture.p.raw_interface">
319                 <title><varname>raw_interface</varname> (string)</title>
320                 <para>
321                 Name of the interface to bind on the raw socket.
322                 </para>
323                 <para>
324                 <emphasis>
325                         Default value is "".
326                 </emphasis>
327                 </para>
328                 <example>
329                 <title>Set <varname>raw_interface</varname> parameter</title>
330                 <programlisting format="linespecific">
331 ...
332 modparam("sipcapture", "raw_interface", "eth0")
333 ...
334 </programlisting>
335                 </example>
336         </section>
337         <section id="sipcapture.p.raw_sock_children">
338                 <title><varname>raw_sock_children</varname> (integer)</title>
339                 <para>
340                 Parameter define how many children that must be created to listen the raw socket.
341                 </para>
342                 <para>
343                 <emphasis>
344                         Default value is "1".
345                 </emphasis>
346                 </para>
347                 <example>
348                 <title>Set <varname>raw_sock_children</varname> parameter</title>
349                 <programlisting format="linespecific">
350 ...
351 modparam("sipcapture", "raw_sock_children", 6)
352 ...
353 </programlisting>
354                 </example>
355         </section>
356         <section id="sipcapture.p.promiscuous_on">
357                 <title><varname>promiscuous_on</varname> (integer)</title>
358                 <para>
359                 Parameter to enable/disable promiscuous mode on the raw socket.
360                 Linux only.
361                 </para>
362                 <para>
363                 <emphasis>
364                         Default value is "0".
365                 </emphasis>
366                 </para>
367                 <example>
368                 <title>Set <varname>promiscous_on</varname> parameter</title>
369                 <programlisting format="linespecific">
370 ...
371 modparam("sipcapture", "promiscuous_on", 1)
372 ...
373 </programlisting>
374                 </example>
375         </section>
376         <section id="sipcapture.p.raw_moni_bpf_on">
377                 <title><varname>raw_moni_bpf_on</varname> (integer)</title>
378                 <para>
379                 Activate Linux Socket Filter (LSF based on BPF) on the mirroring interface. 
380                 The structure is defined in linux/filter.h. The default LSF accept a port/portrange
381                 from the raw_socket_listen param. Currently LSF supported only on Linux.
382                 </para>
383                 <para>
384                 <emphasis>
385                         Default value is "0".
386                 </emphasis>
387                 </para>
388                 <example>
389                 <title>Set <varname>raw_moni_bpf_on</varname> parameter</title>
390                 <programlisting format="linespecific">
391 ...
392 modparam("sipcapture", "raw_moni_bpf_on", 1)
393 ...
394 </programlisting>
395                 </example>
396         </section>        
397         <section id="sipcapture.p.capture_node">
398                 <title><varname>capture_node</varname> (str)</title>
399                 <para>
400                 Name of the capture node.
401                 </para>
402                 <para>
403                 <emphasis>
404                         Default value is "homer01".
405                 </emphasis>
406                 </para>
407                 <example>
408                 <title>Set <varname>capture_node</varname> parameter</title>
409                 <programlisting format="linespecific">
410 ...
411 modparam("sipcapture", "capture_node", "homer03")
412 ...
413 </programlisting>
414                 </example>
415         </section>
416         <section id="sipcapture.p.insert_retries">
417                 <title><varname>insert_retries</varname> (integer)</title>
418                 <para>
419                 The number of times Kamailio should retry to write to the Homer database in case
420                 the first attempt failed. The retry is also limited timewise by the
421                 insert_retry_timeout parameter. Values allowed range from 0 to 500.
422                 </para>
423                 <para>
424                 <emphasis>
425                         Default value is 0 (no retries).
426                 </emphasis>
427                 </para>
428                 <example>
429                         <title>Set <varname>insert_retries</varname> parameter</title>
430                         <programlisting format="linespecific">
431 ...
432 modparam("sipcapture", "insert_retries", 5)
433 ...
434                         </programlisting>
435                 </example>
436         </section>
437         <section id="sipcapture.p.insert_retry_timeout">
438                 <title><varname>insert_retry_timeout</varname> (integer)</title>
439                 <para>
440                 The time limit in seconds Kamailio retries to write to the Homer database in case
441                 the first attempt failed. This parameter is only used together with the insert_retries
442                 parameter. Values allowed range from 0 to 300.
443                 </para>
444                 <para>
445                 <emphasis>
446                         Default value is 60 seconds.
447                 </emphasis>
448                 </para>
449                 <example>
450                         <title>Set <varname>insert_retry_timeout</varname> parameter</title>
451                         <programlisting format="linespecific">
452 ...
453 modparam("sipcapture", "insert_retry_timeout", 10)
454 ...
455                         </programlisting>
456                 </example>
457         </section>
458         <section id="sipcapture.p.callid_aleg_header">
459                 <title><varname>callid_aleg_header</varname> (str)</title>
460                 <para>
461                 Header name used to correlate A-leg with B-leg. It can take a list of headers,
462                 separated by semicolon, e.g. "X-CID0;X-CID1". First match wins.
463                 </para>
464                 <para>
465                 <emphasis>
466                         Default value is "X-CID".
467                 </emphasis>
468                 </para>
469                 <example>
470                         <title>Set <varname>callid_aleg_header</varname> parameter</title>
471                         <programlisting format="linespecific">
472 ...
473 modparam("sipcapture", "callid_aleg_header", "X-CallIDALeg")
474 ...
475                         </programlisting>
476                 </example>
477         </section>
478         <section id="sipcapture.p.topoh_unmask">
479                 <title><varname>topoh_unmask</varname> (int)</title>
480                 <para>
481                 If set to 1, call-id will be unmasked using topoh module api (topoh
482                 module must be loaded in this case).
483                 </para>
484                 <para>
485                         Default value is <emphasis>0</emphasis>.
486                 </para>
487                 <example>
488                         <title>Set <varname>topoh_unmask</varname> parameter</title>
489                         <programlisting format="linespecific">
490 ...
491 modparam("sipcapture", "topoh_unmask", 1)
492 ...
493                         </programlisting>
494                 </example>
495         </section>
496 </section>      
497 <section>
498         <title>Functions</title>
499         <section id="sipcapture.f.sip_capture">
500                 <title>
501                 <function moreinfo="none">sip_capture([table])</function>
502                 </title>
503                 <para>
504                 Store the current processed HEP/IPIP SIP message in database. It is stored in the
505                 form prior applying changes made to it.
506                 </para>
507                 <para>Meaning of the parameters is as follows:</para>
508                 <itemizedlist>
509                 <listitem>
510                 <para><emphasis>table</emphasis> - The table where HEP SIP message will be stored. Homer 5 use now tables with datestamp. 
511                 To generate an automatic table's name please use strftime parameters. I.e. $var(table) = "sip_capture_call_%Y%m%d" and set the variable
512                 as an argument of the sip_capture function.
513                 </para>
514                 </listitem>
515                 </itemizedlist>
516                 <para>
517                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
518                 ONREPLY_ROUTE, BRANCH_ROUTE.
519                 </para>
520                 <emphasis>
521                         Default value is "NULL".
522                 </emphasis>
523                 <example>
524                 <title><function>sip_capture()</function> usage</title>
525                 <programlisting format="linespecific">
526 ...
527 sip_capture();
528 ...
529 sip_capture("sip_capture_call_20160124");
530 ...
531 </programlisting>
532                 </example>
533         </section>
534         <section id="sipcapture.f.report_capture">
535                 <title>
536                 <function moreinfo="none">report_capture([table],[data])</function>
537                 </title>
538                 <para>
539                 Store the current processed HEP REPORT message in database. 
540                 </para>
541                 <para>Meaning of the parameters is as follows:</para>
542                 <itemizedlist>
543                 <listitem>
544                 <para><emphasis>table</emphasis> - The table where REPORT message will be stored.
545                 </para>
546                 <para><emphasis>data</emphasis> - The custom report data.
547                 </para>
548                 </listitem>
549                 </itemizedlist>
550                 <para>
551                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
552                 ONREPLY_ROUTE, BRANCH_ROUTE.
553                 </para>
554                 <emphasis>
555                         Default value is "NULL".
556                 </emphasis>
557                 <example>
558                 <title><function>report_capture()</function> usage</title>
559                 <programlisting format="linespecific">
560 ...
561 report_capture();
562 ...
563 report_capture("report_data");
564 ...
565 report_capture("report_data", "{\"MOS\":4.1,\"PACKET_LOST\":100"});
566 ...
567 </programlisting>
568                 </example>
569         </section>
570         
571         </section>
572
573
574     <section>
575         <title>MI Commands</title>
576         <section id="sipcapture.m.sip_capture">
577                 <title>
578                 <function moreinfo="none">sip_capture</function>
579                 </title>
580                 <para>
581
582                 </para>
583                 <para>
584                 Name: <emphasis>sip_capture</emphasis>
585                 </para>
586                 <para>Parameters: </para>
587                 <itemizedlist>
588                         <listitem><para>capture_mode : turns on/off SIP message capturing.
589                         Possible values are:</para>
590                         <itemizedlist>
591                                 <listitem><para> on </para></listitem> 
592                                 <listitem><para> off </para></listitem>
593                         </itemizedlist>
594                         <para>The parameter is optional - if missing, the command will
595                         return the status of the SIP message capturing (as string 
596                         <quote>on</quote> or <quote>off</quote> ) without changing
597                         anything.</para>
598                         </listitem>
599                 </itemizedlist>
600
601                 <para>
602                 MI FIFO Command Format:
603                 </para>
604                 <programlisting  format="linespecific">
605                 :sip_capture:_reply_fifo_file_
606                 capture_mode
607                 _empty_line_
608                 </programlisting>
609         </section>
610         </section><!-- MI commands -->
611         <section>
612         <title>RPC Commands</title>
613         <section id="sipcapture.r.sipcapture.status">
614                 <title>
615                 <function moreinfo="none">sipcapture.status param</function>
616                 </title>
617                 <para>
618
619                 </para>
620                 <para>
621                 Name: <emphasis>sipcapture.status</emphasis>
622                 </para>
623                 <para>Parameters: </para>
624                 <itemizedlist>
625                         <listitem><para>on or off: turns on/off SIP message capturing.
626                         Possible values are:</para>
627                         <itemizedlist>
628                                 <listitem><para>on</para></listitem> 
629                                 <listitem><para>off</para></listitem>
630                         </itemizedlist>
631                         </listitem>
632                         <listitem><para><quote>check</quote> does not change 
633                         sipcapture status, just reports the current status.</para>
634                         </listitem>
635                 </itemizedlist>
636
637         </section>
638         </section><!-- RPC commands -->
639         
640         <section>
641                 <title>Database setup</title>
642                 <para>
643                 Before running &kamailio; with the sipcapture module, you have to setup the database 
644                 tables where the module will store the data. For that, if the table were not 
645                 created by the installation script or you choose to install everything by 
646                 yourself you can use the homer_databases.sql, <acronym>SQL</acronym> script 
647                 in the sql folder of sipcapture module as template. You can also find the 
648                 complete database documentation on the project webpage, &kamailiodbdocslink;.
649                 </para>
650         </section>
651         <section>
652         <title>Limitations</title>
653         <itemizedlist>
654                 <listitem>
655                 1. Only one capturing mode on RAW socket is supported: IPIP or monitoring/mirroring port. 
656                    Don't activate both at the same time. Obsolete. Please use HEP mirroring now.
657                 </listitem>
658                 <listitem>
659                 2. Mirroring port capturing works only on Linux.
660                 </listitem>
661         </itemizedlist>
662         </section>
663 </chapter>
664