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