In our previous blog post, we discussed the reasons why to deploy both passive monitoring and active testing measures in your Telco network. I outlined our requirements that we have at Sipfront, as well as our high level architecture how we deploy Homer as passive monitoring solution.

Scope of this blog post

In this blog post, we will focus on how to capture SIP traffic and send it off to our Homer instance.

Requirements

At Sipfront, the requirement for capturing traffic includes:

1. Capture traffic on specific interfaces of our Kamailio proxy instances
2. Capture encrypted SIP traffic routed via TLS
3. Our test agents generate hundreds and thousands of calls within a test session, and we want to be able to find them in Homer by our own Sipfront test session id (instead of individual call ids)

The second requirement to capture TLS traffic automatically rules out the typical passive capturing solutions such as:

• captagent - the standard passive capturing agent
• hepagent - the next-gen capture agent written in Rust
• heplify - captagent’s little brother, optimized for speed and simplicity

Kamailio siptrace module initialization

This leaves us with capturing traffic directly within Kamailio, using the siptrace module. This module supports various capturing modes, like automatically capturing subsequent SIP messages within the transaction of a request we mark to capture, and even subsequent messages in the overall SIP dialog (like ACK and re-INVITE and BYE). In our case, we focus on manually triggering the capturing, since we want to control specifically which leg of a call to trace. Your milage may vary, so check the docs and consult with QXIP if in doubt.

What you need to do as bare minimum is loading the module and providing some general information:

loadmodule "siptrace.so"
modparam("siptrace", "hep_mode_on", 1)
modparam("siptrace", "trace_to_database", 0)
modparam("siptrace", "trace_on", 1)
modparam("siptrace", "trace_init_mode", 2)
modparam("siptrace", "trace_mode", 0)
modparam("siptrace", "hep_version", 3)

Let’s go over each of them (consult the module docs for more details):

• hep_mode_on: we set it to one to send encapsulated HEP traffic. Not exactly sure what it does when turning this off (sending the plain SIP message? The module docs don’t explain this further, time for looking into the source?)
• trace_to_database: you can directly write from your kamailio instance to the DB. We rather send it to a specific web ingestion web service, so we turn it off.
• trace_on: We enable tracing. Not exactly sure what would happen if you turn this off, again not much info in the docs.
• trace_init_mode: This setting influences which kind of tracing modes you can do. We do manual tracing of each message from within the config, so it’s 2 for us according to the docs
• trace_mode: When set to something other than 0, siptrace will send your traffic automatically to the db or a HEP server etc. We want manual control over our messages, so it’s 0 for us to not automatically duplicate the traffic to somewhere.
• hep_version: the latest version is v3 and our HEP server we’re sending our traffic to is supporting it, so let’s go with it.

How to send specific messages to Homer

Since we’ve configured siptrace to act in full manual mode, we have to be extra careful to capture every message on the legs we need to capture. The idea works like this:

request_route {
  // ...
  if (loose_route()) {
    // ...
    // we want to capture loose-routed requests like e2e acks, re-invites, byes etc
    sip_trace("sip:our-hep-server:5090", "our-session-id", "m");
    // ...
  }

  // ...
  // we also want to capture initial requests
  sip_trace("sip:our-hep-server:5090", "our-session-id", "m");
  // ...
}

onreply_route {
  // ...
  // finally we want to capture all replies
  sip_trace("sip:our-hep-server:5090", "our-session-id", "m");
  // ...
}

Two things to consider in the above code:

1. We only call sip_trace() after checking whether the SIP message was received on a specific interface to satisfy our requirement to only capture on specific interfaces. You can use kamailio functions and pseudo-vars such as if ($si == "1.2.3.4") {} or if(is_ip_rfc1918("$si") {} etc to perform network matching.
2. We call sip_trace() with the optional parameter our-session-id (which we put into a config file template, so it will be different for each test run). siptrace will use this parameter as correlation id. That way, if for example a performance test generates hundreds or thousands of SIP dialogs, we are able to search for all SIP messages within this test, regardless of the call id, by using the correlation id as search parameter in Homer.

Conclusion

You can use several ways to send SIP traffic to homer. Typical ways are capturing it passively from the network, or sending it actively by instructing your SIP server to send it encapsulated in HEP.

When using an active approach with siptrace in Kamailio, you can either let the module automatically track SIP messages within a transaction or a dialog, or you can manually send messages off to Homer, as we do in the example above. If you have a scenario where multiple calls with different call ids belong together somehow, and you want to be able to find them via a common identifier, you can use the correlation id to group them.

This is the second part of a series of blog posts about deploying Homer. Follow me at LinkedIn to receive updates when new blog posts of this series are published.

Comments about corrections and improvements for the presented solution, your experience with deploying and running Homer, or passive monitoring solutions in general, are highly appreciated!