As many already know, the HEP (or EEP) extensible encapsulation protocol is the glue of the SIPCAPTURE ecosystem and HOMER project. Natively supported by leading Open-Source VoIP and RTC platforms, HEP is used to safely freeze, mirror and transfer packets and protocols between HEP capture clients and HEP capture servers for monitoring, troubleshooting, technical/business analytics and much more.

Thanks to the true love relationship between the SIPCAPTURE and OpenSIPS groups, the HEP implementation available in OpenSIPS 2.3 is currently the most full-featured in the global HEP ecosystem, providing internally correlated emission of Signaling, Logs, REST Interfaces and beyond, driving the latest features in upcoming HOMER releases.

Unknown to the most, starting with OpenSIPS 2.2 the revolutionary HEP Switching is introduced – a powerful new feature allowing users to access, manipulate and proxy steams of HEP packets, specifically designed to support heavy-load and complex capturing scenarios where HEP balancing is required for redundancy and distribution of capacity across multiple capture servers and agents composing HOMER nodes or HEPIC clusters.

Let’s see how to leverage this new functionality with a real-life usage scenario, adapting a few examples kindly shared by our sngrep making friends at irontec

---

HEP Switch Example

CFG “Hello HEP”

Required 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 to do is loading the proto_hep and sipcapture modules in our cfg:

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

Let’s initiate our instance with a HEP socket listening on port 9060:

listen = hep_udp:10.10.0.156:9060

Next, enable and assign our primary route for HEP packets:

modparam("sipcapture", "hep_capture_on", 1)
modparam("sipcapture", "hep_route", "hep_route")

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

---

OpenSIPS CFG Logic

In the latest versions of OpenSIPS, each received HEP packet will be sent to the defined hep_route for processing.

First action will be to identify the received HEP types:

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

The resulting output would reveal the HEP PROTO TYPE being processed:

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

HEP SIP Parsing

One of the key features allows for SIP HEP payloads to be parsed and resumed back via the normal route, using the dedicated hep_resume_sip() command, providing a multitude of elements for routing decisions based on the HEP payload contents.

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 Switch Example

The following example illustrates a few key actions:

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

OpenSIPS HEP Configuration:

####### Global Parameters #########

log_level=3
log_stderror=no
log_facility=LOG_LOCAL0
children=4

listen = hep_udp:127.0.0.1:9060

####### Modules Section ########
mpath="/usr/local/lib64/opensips/modules/"

#### CORE modules
loadmodule "proto_udp.so"
loadmodule "cfgutils.so"
loadmodule "signaling.so"
loadmodule "sl.so"
loadmodule "tm.so"
loadmodule "rr.so"
loadmodule "maxfwd.so"
loadmodule "sipmsgops.so"
loadmodule "mi_fifo.so"
loadmodule "uri.so"
loadmodule "avpops.so"

#### HEP modules
loadmodule "proto_hep.so"
loadmodule "sipcapture.so"
modparam("sipcapture", "hep_capture_on", 1)
modparam("sipcapture", "hep_route", "hep_route")

####### HEP Routing Logic ########

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.0.0.1:9060";
 hep_relay();
}

route{
 xlog("L_DEBUG","Request $rm from $si with domain $rd");
 
 /* Conditional HEP Routing based on Source IP */
 if ($si == "10.20.30.40" || $rd == "qxip.net")
 {
   $du="sip:10.0.0.1:9060";
   hep_relay();
 } else {
   $du="sip:10.0.0.2:9060";
   hep_relay();
 }
}

Conclusion

That’s it! If you followed the instructions, congratulations on your first HEP Switched packet – we’re looking forward to the ideas and creative usage our community will report for this feature and any suggestions on how to make it better.

In forthcoming episodes, we’ll discover the new HEP Types OpenSIPS 2.3 offers and how to leverage them in your HEP stack.