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