What is SIPTRACE ?
It 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:
- 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 parameter “traced_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.
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.
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
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”).
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.