cc6ead11325138f22f8b9b7f6e2acf3cb85daf70
[sip-router] / src / modules / siptrace / doc / siptrace_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 SIPtrace module offer a possibility to store incoming and outgoing SIP
20                 messages in a database and/or duplicate to the capturing server (using <acronym>HEP</acronym>,
21                 the Homer encapsulation protocol, or plain SIP mode). Since version 5.3.0 new levels of tracing
22                 are available. Transactions and dialogs can be traced.
23         </para>
24         <para>
25                 There are multiple ways of storing information:
26                 <itemizedlist>
27                 <listitem>
28                 <para>
29                 by calling the sip_trace() method explicitly in the &kamailio; configuration
30                 file. In this case the original message is processed along with it's corresponding
31                 transaction/dialog if certain flags are used.
32                 </para>
33                 </listitem>
34                 <listitem>
35                 <para>
36                 by setting <quote>trace_mode</quote> to mirror or store to db all traffic.
37                 </para>
38                 </listitem>
39                 </itemizedlist>
40         </para>
41
42         <para>
43         The tracing can be turned on/off using Kamailio <acronym>RPC</acronym> commands.
44         </para>
45         <para>
46         &ctltool; rpc siptrace.status on
47         </para>
48         <para>
49         &ctltool; rpc siptrace.status 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 conditionally loaded before this module:
58                         <itemizedlist>
59                         <listitem>
60                         <para>
61                                 <emphasis>A database module</emphasis> - Mysql, Postgres,
62                                 dbtext, unixODBC... Optional, if tracing to DB is enabled.
63                         </para>
64                         </listitem>
65                         <listitem>
66                         <para>
67                                 <emphasis>dialog, tm and sl modules</emphasis> - optional, only if
68                                 you want to trace messages forwarded by these modules.
69                         </para>
70                         </listitem>
71                         </itemizedlist>
72                 </para>
73         </section>
74         <section>
75                 <title>External Libraries or Applications</title>
76                 <para>
77                 The following libraries or applications must be installed before running
78                 &kamailio; with this module loaded:
79                         <itemizedlist>
80                         <listitem>
81                         <para>
82                                 <emphasis>None</emphasis>.
83                         </para>
84                         </listitem>
85                         </itemizedlist>
86                 </para>
87         </section>
88         </section>
89         <section>
90         <title>Parameters</title>
91         <section id="siptrace.p.db_url">
92                 <title><varname>db_url</varname> (str)</title>
93                 <para>
94                 Database URL.
95                 </para>
96                 <para>
97                 <emphasis>
98                         Default value is "&defaultdb;".
99                 </emphasis>
100                 </para>
101                 <example>
102                 <title>Set <varname>db_url</varname> parameter</title>
103                 <programlisting format="linespecific">
104 ...
105 modparam("siptrace", "db_url", "&exampledb;")
106 ...
107 </programlisting>
108                 </example>
109         </section>
110         <section id="siptrace.p.table">
111                 <title><varname>table</varname> (str)</title>
112                 <para>
113                 Name of the table where to store the SIP messages.
114                 </para>
115                 <para>
116                 <emphasis>
117                         Default value is <quote>sip_trace</quote>.
118                 </emphasis>
119                 </para>
120                 <example>
121                 <title>Set <varname>table</varname> parameter</title>
122                 <programlisting format="linespecific">
123 ...
124 modparam("siptrace", "table", "strace")
125 ...
126 </programlisting>
127                 </example>
128         </section>
129         <section id="siptrace.p.trace_flag">
130                 <title><varname>trace_flag</varname> (integer)</title>
131                 <para>
132                 Which flag is used to mark messages to trace without
133                 traced user.
134                 </para>
135                 <para>
136                 <emphasis>
137                         Default value is "0".
138                 </emphasis>
139                 </para>
140                 <example>
141                 <title>Set <varname>trace_flag</varname> parameter</title>
142                 <programlisting format="linespecific">
143 ...
144 modparam("siptrace", "trace_flag", 22)
145 ...
146 </programlisting>
147                 </example>
148         </section>
149         <section id="siptrace.p.trace_on">
150                 <title><varname>trace_on</varname> (integer)</title>
151                 <para>
152                 Parameter to enable/disable trace (on(1)/off(0))
153                 </para>
154                 <para>
155                 <emphasis>
156                         Default value is "0".
157                 </emphasis>
158                 </para>
159                 <example>
160                 <title>Set <varname>trace_on</varname> parameter</title>
161                 <programlisting format="linespecific">
162 ...
163 modparam("siptrace", "trace_on", 1)
164 ...
165 </programlisting>
166                 </example>
167         </section>
168         <section id="siptrace.p.traced_user_avp">
169                 <title><varname>traced_user_avp</varname> (str)</title>
170                 <para>
171                 The name of the <acronym>AVP</acronym> storing the SIP URI of the traced user. If
172                 the AVP is set, messages are stored in database table and
173                 the <quote>traced_user</quote> column is filled with AVP's value. You can store
174                 the message many times for many users by having multiple values
175                 for this AVP.
176                 </para>
177                 <para>
178                 <emphasis>
179                         Default value is "NULL" (feature disabled).
180                 </emphasis>
181                 </para>
182                 <example>
183                 <title>Set <varname>traced_user_avp</varname> parameter</title>
184                 <programlisting format="linespecific">
185 ...
186 modparam("siptrace", "traced_user_avp", "$avp(user)")
187 ...
188 </programlisting>
189                 </example>
190         </section>
191         <section id="siptrace.p.trace_table_avp">
192                 <title><varname>trace_table_avp</varname> (str)</title>
193                 <para>
194                 The name of the AVP storing the name of the table where to
195                 store the SIP messages. If it is not set, the value of
196                 <quote>table</quote> parameter is used. In this way one can select
197                 dynamically where to store the traced messages. The table
198                 must exist, and must have the same structure as the <quote>sip_trace</quote>
199                 table.
200                 </para>
201                 <para>
202                 <emphasis>
203                         Default value is "NULL" (feature disabled).
204                 </emphasis>
205                 </para>
206                 <example>
207                 <title>Set <varname>trace_table_avp</varname> parameter</title>
208                 <programlisting format="linespecific">
209 ...
210 modparam("siptrace", "trace_table_avp", "$avp(i:345)")
211 modparam("siptrace", "trace_table_avp", "$avp(s:siptrace_table)")
212 ...
213 </programlisting>
214                 </example>
215         </section>
216         <section id="siptrace.p.duplicate_uri">
217                 <title><varname>duplicate_uri</varname> (str)</title>
218                 <para>
219                 The address in form of a SIP URI where to send a duplicate
220                 of traced message.
221                 </para>
222                 <para>
223                 <emphasis>
224                         Default value is "NULL".
225                 </emphasis>
226                 </para>
227                 <example>
228                 <title>Set <varname>duplicate_uri</varname> parameter</title>
229                 <programlisting format="linespecific">
230 ...
231 modparam("siptrace", "duplicate_uri", "sip:10.1.1.1:5888")
232 ...
233 </programlisting>
234                 </example>
235         </section>
236         <section id="siptrace.p.trace_to_database">
237                 <title><varname>trace_to_database</varname> (integer)</title>
238                 <para>
239                 Parameter to enable/disable inserts to the database from this
240                 &kamailio;.
241                 </para>
242                 <para>
243                 In case we only want to send the SIP messages to the
244                 <quote>duplicate_uri</quote> and not store the information to the local
245                 database we can set this to "0".
246                 </para>
247                 <para>
248                 <emphasis>
249                         Default value is "1".
250                 </emphasis>
251                 </para>
252                 <example>
253                 <title>Set <varname>trace_to_database</varname> parameter</title>
254                 <programlisting format="linespecific">
255 ...
256 modparam("siptrace", "trace_to_database", 0)
257 ...
258 </programlisting>
259                 </example>
260         </section>
261         <section id="siptrace.p.trace_local_ip">
262                 <title><varname>trace_local_ip</varname> (str)</title>
263                 <para>
264                 The address to be used in <quote>fromip</quote> field for
265                 locally generated messages. If not set, the module sets it to the address
266                 of the socket that will be used to send the message.
267                 </para>
268                 <para>
269                 <emphasis>
270                         Default value is "NULL".
271                 </emphasis>
272                 </para>
273                 <example>
274                 <title>Set <varname>trace_local_ip</varname> parameter</title>
275                 <programlisting format="linespecific">
276 ...
277 modparam("siptrace", "trace_local_ip", "10.1.1.1:5064")
278 ...
279 </programlisting>
280                 </example>
281         </section>
282         <section id="siptrace.p.trace_sl_acks">
283                 <title><varname>trace_sl_acks</varname> (integer)</title>
284                 <para>
285                 Parameter to enable/disable tracing of SL-filtered ACKs (on=1
286                 / off=0).
287                 </para>
288                 <para>
289                 By default all ACKs to replies generated by SL module are traced. There
290                 is no way to select among them. The SL module is able to run an event
291                 route when such an ACK arrives (<emphasis>event_route[sl:filtered-ack]</emphasis>).
292                 You can set this parameter to 0 and then execute sip_trace() in the event route,
293                 accompanied by config rules to decide which ACK to trace.
294                 </para>
295                 <para>
296                 <emphasis>
297                         Default value is "1".
298                 </emphasis>
299                 </para>
300                 <example>
301                 <title>Set <varname>trace_sl_acks</varname> parameter</title>
302                 <programlisting format="linespecific">
303 ...
304 modparam("siptrace", "trace_sl_acks", 0)
305 ...
306 </programlisting>
307                 </example>
308         </section>
309          <section id="siptrace.p.xheaders_write">
310                 <title><varname>xheaders_write</varname> (integer)</title>
311                 <para>
312                 Parameter to enable/disable writing of x-headers.
313                 </para>
314                 <para>
315                 Stores <quote>fromip</quote>, <quote>toip</quote>, <quote>method</quote> and
316                 <quote>direction</quote> in <quote>X-Siptrace-*</quote> headers.
317                 This allows to transmit them to a second &kamailio; server
318                 using the <quote>duplicate_uri</quote> feature.
319                 Because the headers are added after the data is written to the database,
320                 the headers only show up in the packets sent by duplicate_uri.
321                 </para>
322                 <para>
323                 See <varname>xheaders_read</varname>, it should be used on the receiving
324                 side.
325                 </para>
326                 <para>
327                 <emphasis>Note:</emphasis> The headers are first read, then written. This allows
328                 relaying the information over more than two &kamailio; servers by setting both
329                 <varname>xheaders_write</varname> and <varname>xheaders_read</varname>
330                 to "1" on the servers in the middle.
331                 </para>
332                 <para>
333                 <emphasis>
334                         Default value is "0".
335                 </emphasis>
336                 </para>
337                 <example>
338                 <title>Set <varname>xheaders_write</varname> parameter</title>
339                 <programlisting format="linespecific">
340 ...
341 modparam("siptrace", "xheaders_write", 0)
342 ...
343 </programlisting>
344                 </example>
345         </section>
346          <section id="siptrace.p.xheaders_read">
347                 <title><varname>xheaders_read</varname> (integer)</title>
348                 <para>
349                 Parameter to enable/disable reading of x-headers.
350                 </para>
351                 <para>
352                 Reads and removes the <quote>X-Siptrace-*</quote> headers. Packets not containing the
353                 headers are neither stored to the database nor relayed (duplicate_uri).
354                 See <varname>xheaders_write</varname> for further information.
355                 </para>
356                 <para>
357                 <emphasis>
358                         Default value is "0".
359                 </emphasis>
360                 </para>
361                 <example>
362                 <title>Set <varname>xheaders_read</varname> parameter</title>
363                 <programlisting format="linespecific">
364 ...
365 modparam("siptrace", "xheaders_read", 0)
366 ...
367 </programlisting>
368                 </example>
369         </section>
370         <section id="siptrace.p.hep_mode_on">
371                 <title><varname>hep_mode_on</varname> (integer)</title>
372                 <para>
373                 Parameter to enable/disable Homer encapsulate mode (on(1)/off(0))
374                 </para>
375                 <para>
376                 <emphasis>
377                         Default value is "0".
378                 </emphasis>
379                 </para>
380                 <example>
381                 <title>Set <varname>hep_mode_on</varname> parameter</title>
382                 <programlisting format="linespecific">
383 ...
384 modparam("siptrace", "hep_mode_on", 1)
385 ...
386 </programlisting>
387                 </example>
388         </section>
389
390         <section id="siptrace.p.hep_version">
391                 <title><varname>hep_version</varname> (integer)</title>
392                 <para>
393                 The parameter indicate the version of the HEP protocol.
394                 Can be <quote>1</quote>, <quote>2</quote> or <quote>3</quote>.
395                 In HEPv2 and HEPv3 the timestamp and capture agent ID will be
396                 included in the HEP header.
397                 </para>
398                 <para>
399                 <emphasis>
400                         Default value is "1".
401                 </emphasis>
402                 </para>
403                 <example>
404                 <title>Set <varname>hep_version</varname> parameter</title>
405                 <programlisting format="linespecific">
406 ...
407 modparam("siptrace", "hep_version", 3)
408 ...
409 </programlisting>
410                 </example>
411         </section>
412         <section id="siptrace.p.hep_capture_id">
413                 <title><varname>hep_capture_id</varname> (integer)</title>
414                 <para>
415                 The parameter indicate the capture agent ID for the <acronym>HEPv2</acronym>
416                 or <acronym>HEPv3</acronym> protocol.
417                 Limitation: 16-bit integer for HEPv2, 32-bit for HEPv3.
418                 </para>
419                 <para>
420                 <emphasis>
421                         Default value is "1".
422                 </emphasis>
423                 </para>
424                 <example>
425                 <title>Set <varname>hep_capture_id</varname> parameter</title>
426                 <programlisting format="linespecific">
427 ...
428 modparam("siptrace", "hep_capture_id", 234)
429 ...
430 </programlisting>
431                 </example>
432         </section>
433         <section id="siptrace.p.trace_delayed">
434                 <title><varname>trace_delayed</varname> (integer)</title>
435                 <para>
436                 Use <quote>INSERT DELAYED</quote> to store to database when it is available,
437                 instead of <quote>INSERT</quote>.
438                 </para>
439                 <para>
440                 Default value is <emphasis>0 (off)</emphasis>.
441                 </para>
442                 <example>
443                 <title>Set <varname>trace_delayed</varname>
444                 parameter</title>
445                 <programlisting format="linespecific">
446 ...
447 modparam("siptrace", "trace_delayed", 1)
448 ...
449 </programlisting>
450                 </example>
451         </section>
452         <section id="siptrace.p.send_sock_name">
453                 <title><varname>send_sock_name</varname> (str)</title>
454                 <para>
455                         The name of the local listen socket from where to send
456                         the duplicated traffic via SIP or HEP. In the absence of this parameter
457                         &kamailio; automatically picks an interface. It has priority over
458                         'send_sock_addr' parameter.
459                 </para>
460                 <example>
461                 <title>Set <varname>send_sock_name</varname> parameter</title>
462                 <programlisting format="linespecific">
463 ...
464 modparam("siptrace", "send_sock_name", "sock1")
465 ...
466 </programlisting>
467                 </example>
468         </section>
469         <section id="siptrace.p.send_sock_addr">
470                 <title><varname>send_sock_addr</varname> (str)</title>
471                 <para>
472                         The local interface in the form of SIP URI from where to send
473                         the duplicated traffic. In the absence of this parameter
474                         &kamailio; automatically picks an interface.
475                 </para>
476                 <example>
477                 <title>Set <varname>send_sock_addr</varname> parameter</title>
478                 <programlisting format="linespecific">
479 ...
480 modparam("siptrace", "send_sock_addr", "sip:10.1.1.2:5000")
481 ...
482 </programlisting>
483                 </example>
484         </section>
485         <section id="siptrace.p.force_send_sock">
486                 <title><varname>force_send_sock</varname> (str)</title>
487                                 <para>It is the same as 'send_sock_addr' parameter, this being
488                                 kept for backward compatibility when 'send_sock_name' and
489                                 'send_sock_addr' were introduced.</para>
490         </section>
491
492         <section id="siptrace.p.trace_init_mode">
493                 <title><varname>trace_init_mode</varname> (integer)</title>
494                                 <para>
495                                         Control what tracing modes are initialized.
496                 </para>
497                                 <para>
498                                 The value of the parameter can be a combination of next values:
499                                 <itemizedlist>
500                                 <listitem>
501                 <para>
502                 0 - all modes are initialized.
503                 </para>
504                                 </listitem>
505                                 <listitem>
506                 <para>
507                                 1 - module initialized to do tracing only with core callback
508                                 functions (see also 'trace_mode' parameter).
509                 </para>
510                                 </listitem>
511                                 <listitem>
512                 <para>
513                                 2 - module initialized to do tracing only using config script flags
514                                 and functions.
515                 </para>
516                                 </listitem>
517                                 </itemizedlist>
518                                 </para>
519                 <para>
520                 Default value is <emphasis>0</emphasis>.
521                 </para>
522                 <example>
523                 <title>Set <varname>trace_init_mode</varname> parameter</title>
524                 <programlisting format="linespecific">
525 ...
526 modparam("siptrace", "trace_init_mode", 1)
527 ...
528 </programlisting>
529                 </example>
530         </section>
531         <section id="siptrace.p.trace_mode">
532                 <title><varname>trace_mode</varname> (integer)</title>
533                 <para>
534                                 If not set to 0, the module uses core events triggered when receiving
535                                 or sending SIP traffic to store it to database or mirror it to a SIP
536                                 capture server using HEP or UDP forwarding.
537                                 It will automatically do the handling of all SIP traffic.
538                                 It is no longer needed to set the siptrace flag per request or
539                                 execute sip_trace(), if it is done, then the storing and mirroring is
540                                 duplicated.
541                 </para>
542                                 <para>
543                                 The value of the parameter can be a combination of next values:
544                                 <itemizedlist>
545                                 <listitem>
546                 <para>
547                 0 - no automatic mirroring or storing of SIP traffic.
548                 </para>
549                                 </listitem>
550                                 <listitem>
551                                 <para>
552                                 1 (1st bit set) - mirror the traffic to HEP server.
553                                 </para>
554                                 </listitem>
555                                 <listitem>
556                                 <para>
557                                 2 (2nd bit set) - store the traffic to database server.
558                                 </para>
559                                 </listitem>
560                                 <listitem>
561                                 <para>
562                                 4 (3rd bit set) - mirro the traffic to the SIP URI specified by
563                                 duplicate_uri.
564                                 </para>
565                                 </listitem>
566                                 </itemizedlist>
567                                 </para>
568                 <para>
569                 The trace_on parameter still has to be set, allowing also to control
570                 this mode of mirroring via RPC commands.
571                 </para>
572                 <para>
573                 Default value is <emphasis>0</emphasis>.
574                 </para>
575                 <example>
576                 <title>Set <varname>trace_mode</varname>
577                 parameter</title>
578                 <programlisting format="linespecific">
579 ...
580 modparam("siptrace", "trace_on", 1)
581 modparam("siptrace", "trace_mode", 1)
582 ...
583 modparam("siptrace", "trace_mode", 3)
584 ...
585 </programlisting>
586                 </example>
587         </section>
588         <section id="siptrace.p.auth_key">
589                 <title><varname>auth_key</varname> (integer)</title>
590                 <para>
591 A string with an authorization key.
592 Supported on HEPv3 only.
593                 </para>
594                 <para>
595                 Default value is empty.
596                 </para>
597                 <example>
598                 <title>Set <varname>auth_key</varname>
599                 parameter</title>
600                 <programlisting format="linespecific">
601 ...
602 modparam("siptrace", "auth_key", "spoihepuirthpeuia")
603 ...
604 </programlisting>
605                 </example>
606         </section>
607         </section>
608
609         <section>
610         <title>Functions</title>
611         <section id="siptrace.f.sip_trace">
612                 <title>
613                 <function moreinfo="none">sip_trace([address][,correlation_id][,mode])</function>
614                 </title>
615                 <para>
616                 Store or forward the current processed SIP message/transaction/dialog in database.
617                 It is stored in the form prior applying changes made to it. Based on mode, one can trace
618                 the current message('m' - default), the current transaction('t') or the current dialog('d').
619                 </para>
620                 <para>Meaning of the parameters is as follows:</para>
621                 <itemizedlist>
622                 <listitem>
623                 <para><emphasis>address</emphasis> - The address in form of SIP URI
624                 where to send a duplicate of traced message. This parameter trumps
625                 duplicate_uri and allows tracing to more than one server.
626                 </para>
627                 </listitem>
628                 <listitem>
629                 <para><emphasis>correlation_id</emphasis> - A string with a correlation ID
630                 to be added to the HEP header when using HEPv3.
631                 It's possible to use PVs.
632                 </para>
633                 </listitem>
634                 <listitem>
635                 <para><emphasis>mode</emphasis> - SIP messages to be traced. One can trace the current message
636                 (function can be called on either a reply or a request), the current transaction(the route must
637                 belong to a request) or the current dialog(the message has to be an invite).
638                 </para>
639                 </listitem>
640                 </itemizedlist>
641                 <para>
642                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
643                 ONREPLY_ROUTE, BRANCH_ROUTE.
644                 </para>
645                 <emphasis>
646                         Default value is "NULL".
647                 </emphasis>
648                 <example>
649                 <title><function>sip_trace()</function> usage</title>
650                 <programlisting format="linespecific">
651 ...
652 sip_trace();
653 ...
654 sip_trace("sip:10.1.1.2:5085");
655 ...
656 sip_trace("sip:10.1.1.2:5085", "$ci-abc");
657 ...
658 /* trace current dialog; needs to be done on initial INVITE and dialog has to be loaded */
659 sip_trace("sip:10.1.1.2:5085", "$ci-abc", "d");
660 ...
661 </programlisting>
662                 </example>
663         </section>
664
665         <section id="siptrace.f.sip_trace_mode">
666                 <title>
667                 <function moreinfo="none">sip_trace_mode(tmode)</function>
668                 </title>
669                 <para>
670                         Set the tracing mode: message, transaction or dialog. Only the first
671                         character of the parameter matters: m or M for message; t or T for
672                         transaction; d or D for dialog.
673                 </para>
674                 <para>
675                         In message tracing mode only the current message is stored or mirrored.
676                         In transaction tracing mode, all the messages of the current transaction
677                         are stored or mirrored. In dialog tracing mode, all the messages of the
678                         current dialog are stored or mirrored.
679                 </para>
680                 <para>
681                 This function can be used in ANY_ROUTE.
682                 </para>
683                 <example>
684                 <title><function>sip_trace_mode()</function> usage</title>
685                 <programlisting format="linespecific">
686 ...
687 sip_trace_mode("t");
688 ...
689 </programlisting>
690                 </example>
691         </section>
692
693         <section id="siptrace.f.hlog">
694                 <title>
695                 <function moreinfo="none">hlog([correlation_id,] message)</function>
696                 </title>
697                 <para>
698                 Sends a log event as a HEP3 packet to the homer host configured in
699                 <emphasis>duplicate_uri</emphasis>.
700                 </para>
701                 <para>Meaning of the parameters is as follows:</para>
702                 <itemizedlist>
703                         <listitem>
704                         <para><emphasis>correlation_id</emphasis> (optional) - Homer correlation
705                         ID for this event. If this parameter is not set, the current message's
706                         call-id will be used. (This parameter may contain PVs)
707                         </para>
708                         </listitem>
709                         <listitem>
710                         <para><emphasis>message</emphasis> - The text to send to Homer as log
711                         event. (This parameter may contain PVs)
712                         </para>
713                         </listitem>
714                 </itemizedlist>
715                 <example>
716                 <title><function>hlog()</function> usage</title>
717                 <programlisting format="linespecific">
718 ...
719 hlog("[cfg:$cfg(line)] This is a log from kamailio to Homer");
720 ...
721 hlog("$hdr(P-MyID)", "Another one with a custom correlation ID");
722 ...
723 </programlisting>
724                 </example>
725         </section>
726
727         </section>
728
729     <section>
730         <title>RPC Commands</title>
731         <section id="siptrace.r.siptrace.status">
732                 <title>
733                 <function moreinfo="none">siptrace.status param</function>
734                 </title>
735                 <para>
736
737                 </para>
738                 <para>
739                 Name: <emphasis>siptrace.status</emphasis>
740                 </para>
741                 <para>Parameters: </para>
742                 <itemizedlist>
743                         <listitem><para>on or off: turns on/off SIP message tracing.
744                         Possible values are:</para>
745                         <itemizedlist>
746                                 <listitem><para>on</para></listitem>
747                                 <listitem><para>off</para></listitem>
748                         </itemizedlist>
749                         </listitem>
750                         <listitem><para><quote>check</quote> does not change
751                         siptrace status, just reports the current status.</para>
752                         </listitem>
753                 </itemizedlist>
754                 <para>
755                 RPC Command Format:
756                 </para>
757                 <programlisting  format="linespecific">
758 ...
759 &kamcmd; siptrace.status on
760 &kamcmd; siptrace.status off
761 &kamcmd; siptrace.status check
762 ...
763                 </programlisting>
764         </section>
765         </section><!-- RPC commands -->
766
767         <section>
768                 <title>Database setup</title>
769                 <para>
770                 Before running &kamailio; with siptrace, you have to setup the database
771                 tables where the module will store the data. For that, if the
772                 table were not created by the installation script or you choose
773                 to install everything by yourself you can use the siptrace-create.sql
774                 <acronym>SQL</acronym> script in the database directories in the
775                 kamailio/scripts folder as template.
776                 You can also find the complete database documentation on the
777                 project webpage, &kamailiodbdocslink;.
778                 </para>
779         </section>
780
781         <section>
782         <title>Known issues</title>
783         <para>
784         Stateless forwarded messages (forward()) are not logged if you set the
785         flag, use sip_trace() inside <emphasis>onsend_route</emphasis> block.
786         </para>
787         <para>
788         If dialog level tracing is used internally generated BYE transaction(in
789         case of internal timeouts) won't be traced. At the moment kamailio offers
790         no posibility to trace those messages.
791         </para>
792         <para>
793                 <emphasis>Trace_info</emphasis> xavp name is reserved by this module.
794                 Any use of xavp with this name will result in overlapping internal
795                 avp used by the module therefore causing unknown consequences.
796         </para>
797         <example>
798         <title>Send relayed ACK message</title>
799         <programlisting format="linespecific">
800 ...
801 onsend_route {
802     if (is_method("ACK")) {
803         sip_trace();
804     }
805 }
806 ...
807 </programlisting>
808         </example>
809         </section>
810
811 </chapter>
812