Development News, News

The master branch of Kamailio (to be released in a few months as v5.4.0) introduced a new feature part of usrloc (user location) module: sending keepalive requests to registered contacts and measuring the round trip time (the duration between sending the keepalive request and receiving the response).

This metric is an indication of connectivity quality between Kamailio server and end user devices. The value can be seen in the output of the RPC command listing the location records in memory:

  # kamctl ul dump

{
  "jsonrpc":  "2.0",
  "result": {
    "Domains":  [{
        "Domain": {
          "Domain": "location",
          "Size": 1024,
          "AoRs": [{
              "Info": {
                "AoR":  "echo",
                "HashID": 1776258701,
                "Contacts": [{
                    "Contact":  {
                      "Address":  "sip:echo-0x7fc281c1dd40@192.168.188.20:51254",
                      "Expires":  570,
                      "Q":  -1,
                      "Call-ID":  "95efb4f587cbf46b",
                      "CSeq": 7750,
                      "User-Agent": "baresip v0.6.5 (x86_64/darwin)",
                      "Received": "[not set]",
                      "Path": "[not set]",
                      "State":  "CS_NEW",
                      "Flags":  0,
                      "CFlags": 0,
                      "Socket": "udp:192.168.188.20:5060",
                      "Methods":  5087,
                      "Ruid": "uloc-5e831144-158a-1",
                      "Instance": "<urn:uuid:e3d22d26-5660-4a8b-6169-7f0968f76bde>",
                      "Reg-Id": 0,
                      "Server-Id":  0,
                      "Tcpconn-Id": -1,
                      "Keepalive":  0,
                      "Last-Keepalive": 1585647980,
                      "KA-Roundtrip": 2862,
                      "Last-Modified":  1585647958
                    }
                  }]
              }
            }
  ],
          "Stats":  {
            "Records":  1,
            "Max-Slots":  1
          }
        }
      }]
  },
  "id": 5534
}

There are two fields:

  • last keepalive – it is the unix timestamp (in seconds) when the last keepalive was sent. This field already existed, being set also by the keepalives sent by nathelper module
  • ka roundtrip – the round trip duration (in microseconds) of the last keepalive

To turn on this feature, you have to set the ka_mode parameter for usrloc module, see the options for it at:

There are couple of new other module parameters prefixed with ka_ which can be set to tune the behaviour of the keepalive mechanism. Just scroll down at the link provided above to read more about them.

Besides getting the roundtrip time via RPC, its value can be printed to syslog in a flexible manner by setting ka_loglevel and ka_logmsg parameters. This can be quite useful when usrloc is used in DB-only mode.

Another parameter of usrloc module that worth setting is timer_procs, so the module creates its own timer processes, offloading the core timer processes.

This keepalive mechanism was designed for very good vertical scalability, the requests are sent in stateless mode, to avoid creating many SIP transactions (which could lead to retransmissions and more processing load on the server).

Being a brand new feature, testing and feedback is very appreciated! Write your thoughts via email to sr-users@lists.kamailio.org mailing list.

Note that you have to disable the SIP-based NAT keepalive sent by the nathelper module, if you used that before turning this feature on. The new internal SIP-based keepalive from usrloc it is a complete replacement of the one from nathelper. If you want to use the old style 4-bytes UDP pinging, then nathelper needs to be used. In addition, the usrloc keepalive can be sent to all contacts, no matter the transport layer, while the nathelper keepalive is sent only to UDP contacts.

Thanks for flying Kamailio!