modules: readme files regenerated - siptrace ... [skip ci]
[kamailio] / src / modules / siptrace / README
1 SipTrace Module
2
3 Daniel-Constantin Mierla
4
5    <miconda@gmail.com>
6
7 Edited by
8
9 Alexandr Dubovikov
10
11    <alexandr.dubovikov@gmail.com>
12
13 Daniel-Constantin Mierla
14
15    <miconda@gmail.com>
16
17 Giacomo Vacca
18
19    <giacomo.vacca@gmail.com>
20
21 Camille Oudot
22
23    <camille.oudot@orange.com>
24
25    Copyright © 2010 asipto.com
26
27    Copyright © 2006 voice-system.ro
28      __________________________________________________________________
29
30    Table of Contents
31
32    1. Admin Guide
33
34         1. Overview
35         2. Dependencies
36
37               2.1. Kamailio Modules
38               2.2. External Libraries or Applications
39
40         3. Parameters
41
42               3.1. db_url (str)
43               3.2. table (str)
44               3.3. trace_flag (integer)
45               3.4. trace_on (integer)
46               3.5. traced_user_avp (str)
47               3.6. trace_table_avp (str)
48               3.7. duplicate_uri (str)
49               3.8. trace_to_database (integer)
50               3.9. trace_local_ip (str)
51               3.10. trace_sl_acks (integer)
52               3.11. xheaders_write (integer)
53               3.12. xheaders_read (integer)
54               3.13. hep_mode_on (integer)
55               3.14. hep_version (integer)
56               3.15. hep_capture_id (integer)
57               3.16. trace_delayed (integer)
58               3.17. force_send_sock (str)
59               3.18. trace_mode (integer)
60               3.19. auth_key (integer)
61
62         4. Functions
63
64               4.1. sip_trace([address][,correlation_id][,mode])
65               4.2. hlog([correlation_id,] message)
66
67         5. RPC Commands
68
69               5.1. siptrace.status param
70
71         6. Database setup
72         7. Known issues
73
74    List of Examples
75
76    1.1. Set db_url parameter
77    1.2. Set sip_trace parameter
78    1.3. Set trace_flag parameter
79    1.4. Set trace_on parameter
80    1.5. Set traced_user_avp parameter
81    1.6. Set trace_table_avp parameter
82    1.7. Set duplicate_uri parameter
83    1.8. Set trace_to_database parameter
84    1.9. Set trace_local_ip parameter
85    1.10. Set trace_sl_acks parameter
86    1.11. Set xheaders_write parameter
87    1.12. Set xheaders_read parameter
88    1.13. Set hep_mode_on parameter
89    1.14. Set hep_version parameter
90    1.15. Set hep_capture_id parameter
91    1.16. Set trace_delayed parameter
92    1.17. Set force_send_sock parameter
93    1.18. Set trace_mode parameter
94    1.19. Set auth_key parameter
95    1.20. sip_trace() usage
96    1.21. hlog() usage
97    1.22. Send relayed ACK message
98
99 Chapter 1. Admin Guide
100
101    Table of Contents
102
103    1. Overview
104    2. Dependencies
105
106         2.1. Kamailio Modules
107         2.2. External Libraries or Applications
108
109    3. Parameters
110
111         3.1. db_url (str)
112         3.2. table (str)
113         3.3. trace_flag (integer)
114         3.4. trace_on (integer)
115         3.5. traced_user_avp (str)
116         3.6. trace_table_avp (str)
117         3.7. duplicate_uri (str)
118         3.8. trace_to_database (integer)
119         3.9. trace_local_ip (str)
120         3.10. trace_sl_acks (integer)
121         3.11. xheaders_write (integer)
122         3.12. xheaders_read (integer)
123         3.13. hep_mode_on (integer)
124         3.14. hep_version (integer)
125         3.15. hep_capture_id (integer)
126         3.16. trace_delayed (integer)
127         3.17. force_send_sock (str)
128         3.18. trace_mode (integer)
129         3.19. auth_key (integer)
130
131    4. Functions
132
133         4.1. sip_trace([address][,correlation_id][,mode])
134         4.2. hlog([correlation_id,] message)
135
136    5. RPC Commands
137
138         5.1. siptrace.status param
139
140    6. Database setup
141    7. Known issues
142
143 1. Overview
144
145    The SIPtrace module offer a possibility to store incoming and outgoing
146    SIP messages in a database and/or duplicate to the capturing server
147    (using HEP, the Homer encapsulation protocol, or plain SIP mode). Since
148    version 5.4 new levels of tracing are available. Transactions and
149    dialogs can be traced.
150
151    There are multiple ways of storing information:
152      * by calling the sip_trace() method explicitly in the Kamailio
153        configuration file. In this case the original message is processed
154        along with it's corresponding transaction/dialog if certain flags
155        are used.
156      * by setting “trace_mode” to mirror all traffic.
157
158    The tracing can be turned on/off using Kamailio RPC commands.
159
160    kamctl fifo sip_trace on
161
162    kamctl fifo sip_trace off
163
164 2. Dependencies
165
166    2.1. Kamailio Modules
167    2.2. External Libraries or Applications
168
169 2.1. Kamailio Modules
170
171    The following modules must be conditionally loaded before this module:
172      * A database module - Mysql, Postgres, dbtext, unixODBC... Optional,
173        if tracing to DB is enabled.
174      * dialog, tm and sl modules - optional, only if you want to trace
175        messages forwarded by these modules.
176
177 2.2. External Libraries or Applications
178
179    The following libraries or applications must be installed before
180    running Kamailio with this module loaded:
181      * None.
182
183 3. Parameters
184
185    3.1. db_url (str)
186    3.2. table (str)
187    3.3. trace_flag (integer)
188    3.4. trace_on (integer)
189    3.5. traced_user_avp (str)
190    3.6. trace_table_avp (str)
191    3.7. duplicate_uri (str)
192    3.8. trace_to_database (integer)
193    3.9. trace_local_ip (str)
194    3.10. trace_sl_acks (integer)
195    3.11. xheaders_write (integer)
196    3.12. xheaders_read (integer)
197    3.13. hep_mode_on (integer)
198    3.14. hep_version (integer)
199    3.15. hep_capture_id (integer)
200    3.16. trace_delayed (integer)
201    3.17. force_send_sock (str)
202    3.18. trace_mode (integer)
203    3.19. auth_key (integer)
204
205 3.1. db_url (str)
206
207    Database URL.
208
209    Default value is "mysql://kamailio:kamailiorw@localhost/kamailio".
210
211    Example 1.1. Set db_url parameter
212 ...
213 modparam("siptrace", "db_url", "dbdriver://username:password@dbhost/dbname")
214 ...
215
216 3.2. table (str)
217
218    Name of the table where to store the SIP messages.
219
220    Default value is “sip_trace”.
221
222    Example 1.2. Set sip_trace parameter
223 ...
224 modparam("siptrace", "table", "strace")
225 ...
226
227 3.3. trace_flag (integer)
228
229    Which flag is used to mark messages to trace without traced user.
230
231    Default value is "0".
232
233    Example 1.3. Set trace_flag parameter
234 ...
235 modparam("siptrace", "trace_flag", 22)
236 ...
237
238 3.4. trace_on (integer)
239
240    Parameter to enable/disable trace (on(1)/off(0))
241
242    Default value is "0".
243
244    Example 1.4. Set trace_on parameter
245 ...
246 modparam("siptrace", "trace_on", 1)
247 ...
248
249 3.5. traced_user_avp (str)
250
251    The name of the AVP storing the SIP URI of the traced user. If the AVP
252    is set, messages are stored in database table and the “traced_user”
253    column is filled with AVP's value. You can store the message many times
254    for many users by having multiple values for this AVP.
255
256    Default value is "NULL" (feature disabled).
257
258    Example 1.5. Set traced_user_avp parameter
259 ...
260 modparam("siptrace", "traced_user_avp", "$avp(i:123)")
261 modparam("siptrace", "traced_user_avp", "$avp(s:user)")
262 ...
263
264 3.6. trace_table_avp (str)
265
266    The name of the AVP storing the name of the table where to store the
267    SIP messages. If it is not set, the value of “table” parameter is used.
268    In this way one can select dynamically where to store the traced
269    messages. The table must exist, and must have the same structure as the
270    “sip_trace” table.
271
272    Default value is "NULL" (feature disabled).
273
274    Example 1.6. Set trace_table_avp parameter
275 ...
276 modparam("siptrace", "trace_table_avp", "$avp(i:345)")
277 modparam("siptrace", "trace_table_avp", "$avp(s:siptrace_table)")
278 ...
279
280 3.7. duplicate_uri (str)
281
282    The address in form of a SIP URI where to send a duplicate of traced
283    message. It uses UDP all the time.
284
285    Default value is "NULL".
286
287    Example 1.7. Set duplicate_uri parameter
288 ...
289 modparam("siptrace", "duplicate_uri", "sip:10.1.1.1:5888")
290 ...
291
292 3.8. trace_to_database (integer)
293
294    Parameter to enable/disable inserts to the database from this Kamailio.
295
296    In case we only want to send the SIP messages to the “duplicate_uri”
297    and not store the information to the local database we can set this to
298    "0".
299
300    Default value is "1".
301
302    Example 1.8. Set trace_to_database parameter
303 ...
304 modparam("siptrace", "trace_to_database", 0)
305 ...
306
307 3.9. trace_local_ip (str)
308
309    The address to be used in “fromip” field for locally generated
310    messages. If not set, the module sets it to the address of the socket
311    that will be used to send the message.
312
313    Default value is "NULL".
314
315    Example 1.9. Set trace_local_ip parameter
316 ...
317 modparam("siptrace", "trace_local_ip", "10.1.1.1:5064")
318 ...
319
320 3.10. trace_sl_acks (integer)
321
322    Parameter to enable/disable tracing of SL-filtered ACKs (on=1 / off=0).
323
324    By default all ACKs to replies generated by SL module are traced. There
325    is no way to select among them. The SL module is able to run an event
326    route when such an ACK arrives (event_route[sl:filtered-ack]). You can
327    set this parameter to 0 and then execute sip_trace() in the event
328    route, accompanied by config rules to decide which ACK to trace.
329
330    Default value is "1".
331
332    Example 1.10. Set trace_sl_acks parameter
333 ...
334 modparam("siptrace", "trace_sl_acks", 0)
335 ...
336
337 3.11. xheaders_write (integer)
338
339    Parameter to enable/disable writing of x-headers.
340
341    Stores “fromip”, “toip”, “method” and “direction” in “X-Siptrace-*”
342    headers. This allows to transmit them to a second Kamailio server using
343    the “duplicate_uri” feature. Because the headers are added after the
344    data is written to the database, the headers only show up in the
345    packets sent by duplicate_uri.
346
347    See xheaders_read, it should be used on the receiving side.
348
349    Note: The headers are first read, then written. This allows relaying
350    the information over more than two Kamailio servers by setting both
351    xheaders_write and xheaders_read to "1" on the servers in the middle.
352
353    Default value is "0".
354
355    Example 1.11. Set xheaders_write parameter
356 ...
357 modparam("siptrace", "xheaders_write", 0)
358 ...
359
360 3.12. xheaders_read (integer)
361
362    Parameter to enable/disable reading of x-headers.
363
364    Reads and removes the “X-Siptrace-*” headers. Packets not containing
365    the headers are neither stored to the database nor relayed
366    (duplicate_uri). See xheaders_write for further information.
367
368    Default value is "0".
369
370    Example 1.12. Set xheaders_read parameter
371 ...
372 modparam("siptrace", "xheaders_read", 0)
373 ...
374
375 3.13. hep_mode_on (integer)
376
377    Parameter to enable/disable Homer encapsulate mode (on(1)/off(0))
378
379    Default value is "0".
380
381    Example 1.13. Set hep_mode_on parameter
382 ...
383 modparam("siptrace", "hep_mode_on", 1)
384 ...
385
386 3.14. hep_version (integer)
387
388    The parameter indicate the version of the HEP protocol. Can be “1”, “2”
389    or “3”. In HEPv2 and HEPv3 the timestamp and capture agent ID will be
390    included in the HEP header.
391
392    Default value is "1".
393
394    Example 1.14. Set hep_version parameter
395 ...
396 modparam("siptrace", "hep_version", 3)
397 ...
398
399 3.15. hep_capture_id (integer)
400
401    The parameter indicate the capture agent ID for the HEPv2 or HEPv3
402    protocol. Limitation: 16-bit integer for HEPv2, 32-bit for HEPv3.
403
404    Default value is "1".
405
406    Example 1.15. Set hep_capture_id parameter
407 ...
408 modparam("siptrace", "hep_capture_id", 234)
409 ...
410
411 3.16. trace_delayed (integer)
412
413    Use “INSERT DELAYED” to store to database when it is available, instead
414    of “INSERT”.
415
416    Default value is 0 (off).
417
418    Example 1.16. Set trace_delayed parameter
419 ...
420 modparam("siptrace", "trace_delayed", 1)
421 ...
422
423 3.17. force_send_sock (str)
424
425    The local interface in the form of SIP URI from where to send the
426    duplicated traffic. In the absence of this parameter Kamailio
427    automatically picks an interface.
428
429    Example 1.17. Set force_send_sock parameter
430 ...
431 modparam("siptrace", "force_send_sock", "sip:10.1.1.2:5000")
432 ...
433
434 3.18. trace_mode (integer)
435
436    If set to 1, the module uses core events triggered when receiving or
437    sending SIP traffic to mirror traffic to a SIP capture server using
438    HEP. It will automatically do the mirroring of all traffic, no need to
439    set the siptrace flag per request.
440
441    If set to 0, no automatic mirroring of SIP traffic via HEP.
442
443    Default value is 0.
444
445    Example 1.18. Set trace_mode parameter
446 ...
447 modparam("siptrace", "trace_mode", 1)
448 ...
449
450 3.19. auth_key (integer)
451
452    A string with an authorization key. Supported on HEPv3 only.
453
454    Default value is empty.
455
456    Example 1.19. Set auth_key parameter
457 ...
458 modparam("siptrace", "auth_key", "spoihepuirthpeuia")
459 ...
460
461 4. Functions
462
463    4.1. sip_trace([address][,correlation_id][,mode])
464    4.2. hlog([correlation_id,] message)
465
466 4.1.  sip_trace([address][,correlation_id][,mode])
467
468    Store or forward the current processed SIP message/transaction/dialog
469    in database. It is stored in the form prior applying changes made to
470    it. Based on mode, one can trace the current message('m' - default),
471    the current transaction('t') or the current dialog('d').
472
473    Meaning of the parameters is as follows:
474      * address - The address in form of SIP URI where to send a duplicate
475        of traced message. This parameter trumps duplicate_uri and allows
476        tracing to more than one server.
477      * correlation_id - A string with a correlation ID to be added to the
478        HEP header when using HEPv3. It's possible to use PVs.
479      * mode - SIP messages to be traced. One can trace the current message
480        (function can be called on either a reply or a request), the
481        current transaction(the route must belong to a request) or the
482        current dialog(the message has to be an invite).
483
484    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
485    ONREPLY_ROUTE, BRANCH_ROUTE.
486    Default value is "NULL".
487
488    Example 1.20. sip_trace() usage
489 ...
490 sip_trace();
491 ...
492 sip_trace("sip:10.1.1.2:5085");
493 ...
494 sip_trace("sip:10.1.1.2:5085", "$ci-abc");
495 ...
496 /* trace current dialog; needs to be done on initial INVITE and dialog has to be
497  loaded */
498 sip_trace("sip:10.1.1.2:5085", "$ci-abc", "d");
499 ...
500
501 4.2.  hlog([correlation_id,] message)
502
503    Sends a log event as a HEP3 packet to the homer host configured in
504    duplicate_uri.
505
506    Meaning of the parameters is as follows:
507      * correlation_id (optional) - Homer correlation ID for this event. If
508        this parameter is not set, the current message's call-id will be
509        used. (This parameter may contain PVs)
510      * message - The text to send to Homer as log event. (This parameter
511        may contain PVs)
512
513    Example 1.21. hlog() usage
514 ...
515 hlog("[cfg:$cfg(line)] This is a log from kamailio to Homer");
516 ...
517 hlog("$hdr(P-MyID)", "Another one with a custom correlation ID");
518 ...
519
520 5. RPC Commands
521
522    5.1. siptrace.status param
523
524 5.1.  siptrace.status param
525
526    Name: siptrace.status
527
528    Parameters:
529      * on or off: turns on/off SIP message tracing. Possible values are:
530           + on
531           + off
532      * “check” does not change siptrace status, just reports the current
533        status.
534
535    RPC Command Format:
536 ...
537 kamcmd siptrace.status on
538 kamcmd siptrace.status off
539 kamcmd siptrace.status check
540 ...
541
542 6. Database setup
543
544    Before running Kamailio with siptrace, you have to setup the database
545    tables where the module will store the data. For that, if the table
546    were not created by the installation script or you choose to install
547    everything by yourself you can use the siptrace-create.sql SQL script
548    in the database directories in the kamailio/scripts folder as template.
549    You can also find the complete database documentation on the project
550    webpage,
551    https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
552
553 7. Known issues
554
555    Stateless forwarded messages (forward()) are not logged if you set the
556    flag, use sip_trace() inside onsend_route block.
557
558    If dialog level tracing is used internally generated BYE transaction(in
559    case of internal timeouts) won't be traced. At the moment kamailio
560    offers no posibility to trace those messages.
561
562    Trace_info xavp name is reserved by this module. Any use of xavp with
563    this name will result in overlapping internal avp used by the module
564    therefore causing unknown consequences.
565
566    Example 1.22. Send relayed ACK message
567 ...
568 onsend_route {
569     if (is_method("ACK")) {
570         sip_trace();
571     }
572 }
573 ...