Examples: opensips hepswitch

OpenSIPS as HEP Proxy/Switch

In OpenSIPS 2.2, the whole SIP capturing process was dramatically re-worked, to make it more flexible, higher performance and more powerful. The re-work covers the whole SIP capturing flow, from the filtering traffic and packing into HEP, to the routing HEP and storing it into the database. The existing sip_trace and sip_capture modules were re-designed and the new proto_hep module added to sync the implementation around the HEP protocol.

The new approach is more flexible as the sip trace module comes with a simpler logic in how to filter and select the traffic (message, transaction, dialog level). Introducing the concept of traceID gives more flexibility when comes to decide where to send the filtered traffic (to HEP, to DB, to SIP). Any combination of filters and destination is now possible, allowing the implementation of any complex tracing and capturing scenario.

The performance of the whole capturing process was also increased by using asynchronous operations when comes to sending/receiving HEP packets or to writing to DB - this means no more blocking under heavy load, lower chanche to get your OpenSIPS overloaded. Also the DB operations were improved by using multi-row inserts, to reduce the DB overhead.

HEP Proxying

OpenSIPS 2.2 comes with a new radical concept: HEPv3 Proxying

The HEP implementation in OpenSIPS is now more powerful - the script gives the possibility to access the HEP information, to change the HEP headers and to proxy further any incoming HEP traffic. The ability to act as HEP proxy/switch is the answer to heavy-load and complex capturing scenarios.

Considering all these improvements, OpenSIPS now puts on the table new ways for building advanced capturing architecture. If until now the capturing node could only store messages in the database, not being able to do anything else since it was not possible to make a difference between sip and hep messages, with the new additions one can also choose to route the hep messages to different destinations based on different factors or store hep messages directly into the database, leaving the script available for different type of processing.

All this work is a result of the collaboration between Sipcapture and OpenSIPS projects. How to improve the integration of these two pieces of software was the result of joined discussions and brainstorming, having the single goal of professional capturing system, from SIP traffic, all the way to the DB.

Overview of the changes:

• New proto_hep module to concentrate all the HEP protocol related operations (async send and receive via TCP).

• sip_trace module dropped all flags in favour of a single sip_trace() function where you can decide the tracing level (message, transaction, dialog) and where to trace (multiple trace-id’s point directly to a DB, to a HEP destination or to a SIP destination) in sip_capture module, the sip_capture function can now store messages in the database asynchronously which will save precious processing time.

• the sip_capture module now transformed into a fully hep-aware node capable of not only storing messages in the databases, but also acting as a hep proxy, forwarding messages to various hep destinations using the hep_relay function. The routing is done the same way as the sip routing allowing using all the routing modules has right now. What is more, for the third version of the protocol it is very easy to modify the hep chunks from the script before storing/forwarding the message.

• the sip_capture module can turn your capturing node into a hep proxy - we have also defined a new parameter called the hep_route through which one can define a special route through which all the hep messages should go. The major advantage this route brings is that the payload of the message is not parsed, saving precious time. Capturing messages from this route is not allowed since you don’t have a parsed message. Also this parameter brings you the possibility to store hep messages directly into the database, without going through the script at all.

HEP Switch Example

This example kindly shared by our friends at irontec

CFG "hello hep"

Elements:

• HEP Agent(s) sending HEP traffic of various types
• OpenSIPS 2.2+ instance listening for HEP traffic on port 9060

Required Modules

First thing we will load the proto_hep and sipcapture modules in our cfg:

loadmodule "proto_hep.so"
loadmodule "sipcapture.so"

Initiate our instance to listen for HEP on port 9060:

listen = hep_udp:10.10.0.156:9060

Next, assign our primary route for HEP packets:

modparam("sipcapture", "hep_route", "hep_route")

NOTE: With no route, traffic will be pass-through directly to the HEP collector

CFG Logic

Each received HEP packet will be sent to the defined hep_route for processing. We can identify the received HEP type as follows:

route[hep_route] {
 
hep_get("11", "$var(vendor)", "$var(data)");
xlog("L_DEBUG","HEP PROTO TYPE: $var(data)");

The resulting output:

sep 19 12:03:37 zgor-pruebas-opensips01 /usr/sbin/opensips[22924]: HEP PROTO TYPE: RTCP
sep 19 12:03:37 zgor-pruebas-opensips01 /usr/sbin/opensips[22922]: HEP PROTO TYPE: RTCP
sep 19 12:03:37 zgor-pruebas-opensips01 /usr/sbin/opensips[22924]: HEP PROTO TYPE: SIP
sep 19 12:03:37 zgor-pruebas-opensips01 /usr/sbin/opensips[22925]: HEP PROTO TYPE: SIP

The SIP HEP type can be resumed as parsed to the normal route with the dedicated command:

1.4.7.  hep_resume_sip()
Break hep route execution and resume into the main request route.
WARNING: USE THIS FUNCTION ONLY FROM A ROUTE DEFINED USING  hep_route  PARAMETER.

HEP Switching

The following example illustrates a few actions:

• HEP type identification
• HEP SIP condition, resuming to main route forking to multiple HEP receivers
• HEP RTCP condition, forwarding to a dedicated HEP receiver

route[hep_route] {

      hep_get("11", "$var(vendor)", "$var(data)");
      xlog("L_DEBUG","HEP PROTO TYPE: $var(data)");

      if ($var(data) == "SIP")
      {
       hep_resume_sip();
       exit;
      }

     hep_get("utf8-string", "0x0011", "$var(vendor)", "$var(correlation_id)");
     xlog("L_DEBUG","RTCP - CallID Domain $(var(correlation_id){s.select,1,@})");
     $du="sip:10.177.88.38:9060";
     hep_relay();

}

route{
      xlog("L_DEBUG","Request $rm desde $si con domain $rd");
      $du="sip:10.10.0.156:1001";
      hep_relay();

      $du="sip:10.10.0.156:1002";
      hep_relay();

}