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 “”

  • 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 “”
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)”)) {
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/” and update the proxy list addresses and the name of OpenSIPS ‘s  sip_trace table.

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


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




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:″) # 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

OpenSIPS-CP Installation & Configuration



Installation and Configuration Steps:

Apache must be Installed and Configured:

# yum install httpd

Run it :

# systemctl start httpd

Then be sure it is running: # ps aux |grep http or # netstat -lpn |grep http

Go to and get the source:

# cd /var/www

# svn checkout svn:// opensips-cp

Install PHP and some extensions: Here i have Fedora Red Hat:

 #  yum install php php-common php-gd php-mysql php-xmlrpc php-pear

Install Mysql Driver

# pear install mdb2#mysql

Check if the Extensions are Installed Correctly:

For Redhat check “mysql.ini”/”mysqlnd.ini”, “gd.ini”, “xmlrpc.ini” in “/etc/php.d/”.

Enable short_open_tag in “/etc/php.ini”:

 short_open_tag = On

Configure OpenSIPS-CP’s Database Connection:

# cd /var/www/opensips-cp

# vi config/

Configure OpenSIPS-CP Boxes:

The configuration of these boxes determines how the OpenSIPS-CP will communicate with OpenSIPS. For example you can configure Mi box to access the OpenSIPS Mi interface. This can be through RPC protocol, FIFO, UDP, or JSON.

 # vi config/

Part of this file:

            // options: fifo:/path/to/fifo_file | xmlrpc:host:port | udp:host:port | json:json_url


This file “/tmp/opensips_fifo” is configured  in OpenSIPS’s configuration file in the FIFO module section:

            #### FIFO Management Interface

            loadmodule “”

            modparam(“mi_fifo”, “fifo_name”, “/tmp/opensips_fifo”)

            modparam(“mi_fifo”, “fifo_mode”, 0666)

This file is created by OpenSIPS. so the access permission to this file is determined by OpenSIPS. “0666” is the (read&write for all ) permission to the fifo file.

Note: The global  file “/var/www/opensips-cp/config/” is important but also the local file for each module is important. For example: the file “/var/www/opensips-cp/config/tools/system/dialog/” contains some options  for “dialog” module.

If you have any problem related to accessing the fifo file please click here.

Now OpenSIPS-CP can access the opensips database and can communicate with opensips through Mi interface.

OpenSIPS-CP needs an extra table as an addition to OpenSIPS’s Database. We need to push it in the opensips database. Install the “ocp_admin_privileges” table schema.

# cd /var/www/opensips-cp

# mysql -Dopensips -p < config/tools/admin/add_admin/ocp_admin_privileges.mysql

Create Admin Account with all Privileges:

You will use this account from the opensips-cp web interface. I will add the user admin with password admin withh full permission:

Login to the Database as Root

         # mysql -uroot -p

Mysql> use opensips;

Mysql> INSERT INTO ocp_admin_privileges (username,password,ha1,available_tools,permissions) values (‘admin’,’admin’,md5(‘admin:admin’),’all’,’all’);

Configure Apache:

# vi /etc/httpd/conf/httpd.conf

Add the following:

<Directory /var/www/opensips-cp>

Options Indexes FollowSymLinks MultiViews
AllowOverride None
Require all denied


<Directory  /var/www/opensips-cp/web>

Options Indexes FollowSymLinks MultiViews

AllowOverride None
Require all granted


Alias /cp /var/www/opensips-cp/web

Restart Apache:

# systemctl restart httpd

Make apache, the owner of opensips-cp folder:

# chown -R apache:apache /var/www/opensips-cp/

Open the browser and go to OpenSIPS-CP main page: http://localhost/cp

 snapshot6Login by username:admin and password:admin


Go a head and explore it.

More Information