SIPTRACE OpenSIPS Tracing Tool

.

What is SIPTRACE ?

siptraceIt is a tracing tool tied to OpenSIPS. With this tool, you can trace all calls or a specific user calls in real time (i.e. You can see the SIP messages related to a specific user and passed the OpenSIPS in real time).  As this tool logs the signalling messages in the database, this affects the the performance when enabled. To enable this tool, the module “siptrace” must be loaded and configured in the configuration file of the OpenSIPS (routing script).

Steps To Trace Specific User’s  SIP Messages

  • Load “siptrace” module. Add this line in the configuration file:

loadmodule “siptrace.so”

  • Set db_url module parameter (database URL).

modparam(“siptrace”, “db_url“, “mysql://user:passwd@host/dbname”)

  • Set trace_flag parameter (Which flag is used to mark messages to trace):

modparam(“siptrace”, “trace_flag“, “22”)    # Here the trace_flag will 22.

  • The module parametertraced_user_avp” specifies the AVP which stores the SIP URI of the traced user. The name of the user will be shown in the “traced_user” field in the “sip_trace” table. Setting the “traced_user_avp” will automatically enable tracing. You can store multiple values in the AVP if you want to trace more than one user.

modparam(“siptrace”, “traced_user_avp“, “$avp(traced_user)”)

  • Set trace_on parameter (1(on) or 0(off)): Default value is 0.

modparam(“siptrace”, “trace_on”, 1)

If this parameter is not set (remained 0) in the configuration file, the tracing can be enabled by setting the module parameter “traced_user_avp” or using opensipsctl tool:

# opensipsctl fifo sip_trace on

  • Before writing the code responsible for actual tracing of sip messages, You should be familiar with what is called Attribute Value Pair (AVP) variables. This is found here. Add this block to load and configure the “avpops” module which is needed for managing AVPs (Add/Remove/Update/Delete) in the database.

loadmodule “avpops.so”
modparam(“avpops”,”db_url”,“mysql://user:passwd@host/dbname”) # Customize This
modparam(“avpops”, “avp_table”, “New_usr_preferences”) # Customize this If you are using another table.

  • To trace the current SIP message, we need to call the function (sip_trace). To trace all messages related to the current SIP meesage (i.e. messages related to the transaction created by that request), we need to set  the tracing flag (setflag(22)). Remember this flag is defined as trace_flag (modparam(“siptrace”, “trace_flag“, “22“)).

Write the following code in the main request routing block of the routing script.

if(avp_db_load(“$fu”,”$avp(trace)”)) {
$avp(traced_user)=$fu;
setflag(22);
sip_trace();
xlog(“L_INFO”,”User $fu being traced”);
}

The $fu is a reference to URI of “From” header. The function avp_db_load(“$fu”,”$avp(trace)”) loads the AVP which belongs to $fu and has the name “trace”. This AVP must be added in the “usr_preferences” table.  Use “opensipsctl” tool to add it. # opensipsctl avp add –T usr_preferences test@youripaddress trace 1 1. This add AVP which has the name “trace”, type 1 (string,integer), and the value =1 (e.g. <=> true). This correspond to $(AVP(trace)) in the routing script. This AVP when loaded by avp_db_load function, its value will be 1 (<=> True ). The function returns true if it loaded a value in $(AVP(trace)) and this means the message/transaction belongs to that user will be traced.

Note: In the request route, you get only requests (no replies can be traced there). setting the tracing flag will solve the problem.

  • Restart OpenSIPS

# systemctl restart opensips.service

  • Use opensipsctl tool to start tracing

# opensipsctl fifo sip_trace on

OpenSIPS-CP view of “sip_trace” Table

To see the traced messages, you can look directly in the “sip_trace” table or in the OpenSIPS Control Panel. OpenSIPS-CP ‘s siptrace should also be configured. Open the local configuration of the siptrace tool in your OpenSIPS-CP folder :”opensips-cp/config/tools/system/siptrace/local.inc.php” and update the proxy list addresses and the name of OpenSIPS ‘s  sip_trace table.

$config->table_trace = “sip_trace”; # Table Name

$proxy_list=array(“udp:Your_Server_IP_Address:Port”,”tcp:Your_Server_IP_Address:5060″);

To see the traced messages, open the web page “System –> SIP Trace”. You will get something like these figures.

trace

trace1

trace2

You can also disable or enable tracing through the web (the red/green button on the right of the page “System –> SIP Trace”).

trace3SIPTRACE as a SIP Capturing Agent

SIPTRACE module can send the captured packets to an external HEP server (e.g. Homer) instead of storing them in the local database. The following is the configuration:

modparam(“siptrace”, “duplicate_uri”, “sip:10.0.0.1:9060″) # The capturing server address to send a duplicate of traced message to.

modparam(“siptrace”, “duplicate_with_hep”, 1)  # Enable HEP

modparam(“siptrace”, “trace_to_database”, 0) # Disable tracing to the local database

 Here you can find an example to make OpenSIPS (SIPTRACE module) operate as a SIP capturing agent.


More Information


Advertisements

SIP Stress Testing -Part 1 (Opensipsctl & OpenSIPS-CP)

.

What is Stress Testing ?

It is the process of putting so great load on the system and measuring its response. It helps to determine the maximum operating capacity of the system. The behaviour of the system will be predictable under high/peak loads.

I will mention some tools which help you in the testing of OpenSIPS SIP server under stress.

.

Using SIP traffic generator , we can highly load the SIP server and read the statistics. For example under certain high load, the number of dropped packets became unacceptable or the number of SIP transactions that are in use in memory is so large.

Opensipsctl Tool

It is shell script and it is used as management and monitoring tool. It has some options to generate some statistics. This script communicates with OpenSIPS server through either FIFO pipe or unix socket (The control engine is either fifo or unixsocket). The script is present in OpenSIPS sbin directory. Its configuration file opensipsctlrc is stored in OpenSIPS etc directory. Check the name of your fifo file in the configuration file. To display the available commands, type: #./opensipsctl fifo which

Here is a list of commands available in OpenSIPS 1.11.

get_statistics, reset_statistics, uptime, version, pwd, arg, which, ps, kill, debug, cache_store, cache_fetch, cache_remove, event_subscribe, events_list, subscribers_list, list_tcp_conns, help, list_blacklists, t_uac_dlg, t_uac_cancel, t_hash, t_reply, ul_rm, ul_rm_contact, ul_dump, ul_flush, ul_add, ul_show_contact, ul_sync, dlg_list, dlg_list_ctx, dlg_end_dlg, dlg_db_sync, dlg_restore_db, profile_get_size, profile_list_dlgs, profile_get_values, list_all_profiles.

  • For example to execute the command “ps”, type: #./opensipsctl fifo ps. This command display all  processes running by OpenSIPS. The output looks like:

Process::  ID=0 PID=9739 Type=attendant
Process::  ID=1 PID=9747 Type=MI FIFO
Process::  ID=2 PID=9749 Type=SIP receiver udp:10.0.0.9:5060
Process::  ID=3 PID=9751 Type=SIP receiver udp:10.0.0.9:5060
Process::  ID=4 PID=9753 Type=SIP receiver udp:10.0.0.9:5060
Process::  ID=5 PID=9755 Type=SIP receiver udp:10.0.0.9:5060
Process::  ID=6 PID=9756 Type=time_keeper
Process::  ID=7 PID=9757 Type=timer: tm-utimer
Process::  ID=8 PID=9760 Type=TCP receiver
Process::  ID=9 PID=9762 Type=TCP receiver
Process::  ID=10 PID=9764 Type=TCP receiver
Process::  ID=11 PID=9765 Type=TCP receiver
Process::  ID=12 PID=9768 Type=TCP main

  • To get the number of simultaneous calls (=dialogs in case no presence), type: #./opensipsctl fifo get_statistics dialog. Both SIP INVITE message (Establishing a Call) and SUBSCRIBE message (subscription to presence service) creates dialog. If the SIP server provides call management + presence,  the number of active dialogs will not be equal to the number of calls. The length of the call affects the memory of the SIP server not the processing because the dialog remains in the memory till one of the end parties (caller or calle) ends the dialog by sending SIP BYE message.
  • To take information about specific command, use “help” command with the name of the command as an argument. For example if you want to take information about  the command “ps”, type: #./opensipsctl fifo help ps. The output looks like:

Help:: lists all processes used by OpenSIPS
Exported by:: core

Note: Current opensipsctl does not support NoSQL databases.

OpenSIPS Control Panel (OpenSIPS-CP)

You can also use OpenSIPS control panel (OpenSIPS-CP) to do the same things. Open the web interface. Click on “System” –> “MI Commands”. Choose a command from the command list and press “Enter”. Dont forget the parameters.

OpenSIPS-CP Statistics Monitor Page

  • There are two tables needed for statistics monitoring in OpenSIPS-CP. Do the following to download the structures of monitored_stats and monitoring_stats tables in mysql opensips database:

#cd /var/www/opensips-cp/

#mysql -Dopensips -p < config/tools/system/smonitor/tables.mysql

  • On the web interface, click on “System” –> “Statistics Monitor”. You will get the following:

omslag1

For example you can get some real time statistics about transaction module (TM)  by clicking on the corresponding item in the list “Module:tm”. The “inuse_transaction” sub-item gives the number of transactions in use in memory. The transactions should be released quickly and the average value of this number should be stable (transactions created and released quickly). The number of  transactions per second defines the performance of SIP proxy.

Also you can get statistics on the number of TCP/UDP packets which waiting to be processed. By clicking on “Module:net” item, you can see “waiting_udp” and “waiting_tcp” sub-items.

  • Edit the cron_job/get_opensips_stats.php file and check the value of the variable $path_to_smonitor if it is correct according to your opensips-cp.
  • Add a cron job that collects data from the opensips:

# crontab -e

Append the following entry:

* * * * *   root   php /var/www/opensips-cp/cron_job/get_opensips_stats.php > /dev/null

Note

The MI exported functions can be called only if the corresponded modules are loaded.  Otherwise you will get an error message (command not available). For example enabling tracing by calling sip_trace (# ./opensipsctl fifo sip_trace on) will not work if the module “siptrace.so” is not loaded (i.e. configured to be loaded in the configuration file). You will get this error message “500 command ‘sip_trace’ not available”.

Module Not loaded –> No Exported Functions –> Error upon calling “not exist” Function


Next

The Next Part will be about SIPSAK command line tool which is used as a SIP traffic generator to test the performance and the security of the SIP servers or user agents.