git.sip-router.org Git - sip-router/blob - 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().