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