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