Kamailio and FreeSWITCH on the same server with NSQ and JANSSON-RPC

This post will demonstrate how to run FreeSWITCH and Kamailio on a single server.
FreeSWITCH will handle authentication and act as registrar while Kamailio will handle presence updates using the NSQ module. You might be wondering why this setup would be useful. The reason we found, is that FreeSWITCH is not so great at handling presence updates. It relies heavily on SQL queries, and when you are dealing with 800+ user-agents all doing presence, FreeSWITCH can’t really keep up. You also may be wondering why not have Kamailio act as registrar. The reason FreeSWITCH will be registrar is we had a system in place already (single FreeSWITCH instance) and it would require too large of a change to move authentication to Kamailio. So this exact setup may not be so useful for many, it does contain helpful hints on how to run Kamailio and FreeSWITCH together on a single server, it also demonstrates use of NSQ and the JANSSON-RPC module.

In order for FreeSWITCH and Kamailio to run on a single server, both services must bind to different ports on a single interface or on separate interfaces altogether. In this setup, I have FreeSWITCH setup to bind SIP on the loopback interface (127.0.0.1), RTP on the public facing interface and Kamailio binding to the public facing interface (4.5.6.7:5060). I used the dispatcher module to detect if FreeSWITCH is up or down.
Here is my dispatcher.list:

#setid sipdest flags priority attrs
1 sip:127.0.0.1:5060 2 0 duid=1

Next you’ll have to setup a FreeSWITCH sofia profile to bind to loopback for SIP and public interface for RTP:

<configuration name="sofia.conf" description="Sofia">
  <profiles>
    <profile name="local">
      <settings>
        ...
        <param name="sip-ip" value="127.0.0.1"/>
        <param name="sip-port" value="5060"/>
        <param name="rtp-ip" value="4.5.6.7"/>
        ...
      </settings>
    </profile>
  </profiles>
</configuration>

I named the profile local but you can obviously name it whatever you like. That’s it for the FreeSWITCH side of things, make sure your profile is loaded by doing:
fs_cli -x "sofia status profile local"

You should see in output:

RTP-IP                 4.5.6.7
SIP-IP                 127.0.0.1
URL                     sip:mod_sofia@127.0.0.1:5060
BIND-URL                sip:mod_sofia@127.0.0.1:5060;transport=udp,tcp

Now it’s time to setup Kamailio, I’ll highlight some important sections and attach the entire kamailio.cfg at the end of post.
First thing I like to do in my kamailio.cfg is setup the global definitions that will be used later (that way the script is more portable):

# - defines
#!define DBURL "postgres://kamailio:kamailio@localhost/kamailio"
#!define JANSSON_RPC "conn=presence;addr=localhost;port=8080;priority=10;weight=10"
#!define LISTEN 4.5.6.7:5060

The DBURL is required for presence and NSQ modules, so you will need to provision your database with the appropriate tables. Now define the module parameters, the ones I will highlight are related to NSQ:

modparam("nsq", "db_url", DBURL)
modparam("nsq", "consumer_workers", 1)
modparam("nsq", "topic_channel", "presence:kamailio")
modparam("nsq", "max_in_flight", 200)
modparam("nsq", "lookupd_address", "nsqlookup01")
modparam("nsq", "pua_mode", 1)

The topic_channel tells Kamailio to listen for messages on the presence topic and uses the kamailio channel. The lookupd_address tells kamailio to how to find the producers. If you are unfamiliar with NSQ, I suggest you check out the documentation (http://nsq.io/)

I setup a JANSSON-RPC server running on the localhost (written in golang) which checks for active calls when a user-agent subscribes and sends an NSQ message to Kamailio in the event the To-User is actually on a call. Here we define the JANSSON-RPC server:

modparam("janssonrpc-c", "result_pv", "$var(jsrpc_result)")
modparam("janssonrpc-c", "server", JANSSON_RPC)

The result_pv is used to receive results from the RPC request. In our case, we don’t care about the result since our NSQ module will receive a message on result.

Now let’s check out the route section of our config. You’ll notice one of the first thing that happens in our config is CHECK_SOURCE_IP

route[CHECK_SOURCE_IP] {
    if ($si == "127.0.0.1") {
        setflag(FLAG_FROM_FREESWITCH);
    } else {
        route(NAT_TEST_AND_CORRECT);
    }
}

Since we should only be receiving requests from FreeSWITCH on the loopback, we can easily determine “who” is sending our SIP packet. I set a flag here, FLAG_FROM_FREESWITCH, which is very important later on. If the packet is not from FreeSWITCH, we do some NAT handling:

route[NAT_TEST_AND_CORRECT] {
    if (is_method("REGISTER")) {
        if (nat_uac_test("19")) {
            fix_nated_contact();
        }
    } else {
        if (nat_uac_test("3")) {
            fix_nated_contact();
            force_rport();
        }
        if (has_body("application/sdp") && nat_uac_test("8")) {
            fix_nated_sdp("10");
        }
    }
}

We handle NAT for REGISTERs in a specific way here because we must send the correct contact header to FreeSWITCH, otherwise FreeSWITCH will get contact header containing a private IP and will not know how to route INVITEs to the user-agent.

Next we handle the SIP SUBSCRIBE:

route[SUBSCRIBE] {
    if (is_method("SUBSCRIBE")) {
 
        if (!t_newtran()) {
            sl_reply_error();
            exit;
        }

        if ($tU == $null) {
            xlog("L_INFO", "$ci|stop|ignoring subscribe with empty TO username from a $ua");
            sl_send_reply(400, "Missing TO username");
            t_release();
            exit;
        }

        if ($fU == $null) {
            xlog("L_INFO", "$ci|stop|ignoring subscribe with empty FROM username from a $ua");
            sl_send_reply(400, "Missing FROM username");
            t_release();
            exit;
        }

        # do an RPC request to check for Active calls
        if ($rU != $null) {
            # forward message-summary SUBSCRIBEs to FreeSWITCH
            if ($hdr(Event) == "message-summary") {
                xlog("L_INFO", "$ci|log|CHECKING MESSAGE SUMMARY");
                record_route();
                route(DISPATCH);
                route(RELAY);
            } else {
                xlog("L_INFO", "$ci|log|CHECKING PRESENCE");
                janssonrpc_notification("presence", "Server.QueryPresence", '[{"CallId":"' + $ci + '","FromUser":"' + $fU + '","FromDomain":"' + $fd + '","ToUser":"' + $rU + '","ToDomain":"' + $rd + '"}]');
            }
        }

        if (!handle_subscribe()) {
            xlog("L_INFO", "$ci|stop|unsupported subsribe");
            t_release();
            exit;
        }

        t_release();
        exit;
    }
}

We are validating the SUBSCRIBE, then checking the event type. If it’s a message-summary event, we add a record-route header and forward it to FreeSWITCH. (We could handle message-summary using NSQ but right now it’s easier for FreeSWITCH to handle it and doesn’t put a strain on FreeSWITCH)
If it’s not a message-summary event, we send an RPC request to our service which should know if the To-User is on a call or not, if they are on a call, our RPC server sends an NSQ message to the presence topic.
You’ll notice the next section is for handling NSQ messages:

# receive presence updates from NSQ and update watchers
event_route[nsq:consumer-event-presence-update] {
    $var(call-id) = $(nsqE{nsq.json,Call-ID});
    xlog("L_INFO", "$var(call-id)|log|payload $nsqE");
    if ($(nsqE{nsq.json,Event-Package}) == "dialog") {   
        if($sht(p=>$var(call-id)) != $(nsqE{nsq.json,State}) || $(nsqE{nsq.json,Flush-Level}) != $null) {
             xlog("L_INFO", "$(nsqE{nsq.json,Call-ID})|log|received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{nsq.json,From}) state $(nsqE{nsq.json,State})");
             $sht(p=>$(nsqE{nsq.json,Call-ID})) = $(nsqE{nsq.json,State});
             nsq_pua_publish($nsqE);
             pres_refresh_watchers("$(nsqE{nsq.json,From})", "$(nsqE{nsq.json,Event-Package})", 1);
        } else {
            xlog("L_INFO", "$var(call-id)|log|received duplicate $(nsqE{nsq.json,Event-Package}) update for $(nsqE{nsq.json,From}) state $(nsqE{nsq.json,State})");
            xlog("L_INFO", "$var(call-id)|log|payload $nsqE");
        } 
    } else {
       xlog("L_INFO", "$var(call-id)|log|received $(nsqE{nsq.json,Event-Package}) update for $(nsqE{nsq.json,From}) $nsqE");
       nsq_pua_publish($nsqE);
       pres_refresh_watchers("$(nsqE{nsq.json,From})", "$(nsqE{nsq.json,Event-Package})", 1);
    }
}

The NSQ message must be json format and contain the required fields for the presence module to send an update. I’ll save those details for another post.

Let’s go back up to the main routing block of our config now.

    # handle SUBSCRIBE requests
    route(SUBSCRIBE);

    # handle requests within SIP dialogs
    route(WITHINDLG);

    ###############################
    ### HANDLE INITIAL REQUESTS ###
    # handle retransmissions
    if(t_precheck_trans()) {
        t_check_trans();
        exit;
    }
    t_check_trans();

    if (is_method("INVITE|REFER")) {
        record_route();
    }

    if (is_method("NOTIFY") && $hdr(event) == "check-sync" && isflagset(FLAG_FROM_FREESWITCH)) {
        record_route();
        xlog("L_INFO", "$ci|log|Rebooting phone [$ru]\n");
        t_on_reply("REPLY_FROM_DEVICE"); # handle NAT
        route(RELAY);
    }

After handling SUBSCRIBEs, we check for in-dialog request and route them. We add a record_route header if INVITE or REFER. Then we handle NOTIFYs with check-sync events specially. This allows us to remotely reboot phones which support the feature.

The next portion is important when forwarding a REGISTER to another registrar:

    if (!isflagset(FLAG_FROM_FREESWITCH) && is_method("REGISTER")) {
        add_path();
    }

If we do not add a path header to the REGISTER before forwarding to FreeSWITCH, FreeSWITCH will not know to send INVITEs to user-agents through Kamailio.

The last part of our main routing block does some final checks to decide how/where to send the packet.

    route(DISPATCH);
   
    route(RELAY);

Our dispatch route checks if the SIP signal is from FreeSWITCH, if so, fix NAT on replies to it. If not from FreeSWITCH (e.g. from outside user-agent), send to FreeSWITCH:

route[DISPATCH] {
    if (isflagset(FLAG_FROM_FREESWITCH)) {
        t_on_reply("REPLY_FROM_DEVICE"); # handle NAT
    } else if (!ds_select_dst("1", "0")) {
        #if we are here that means no destination is available. We notify the user by 404 and exit the script.
        xlog("L_NOTICE", "No destination available!");
        send_reply("404", "No destination");
        exit;
    }
}

And here is the relay route:

route[RELAY] {
    if (is_method("INVITE")) {
        if(!t_is_set("failure_route")) t_on_failure("MANAGE_FAILURE");
    }

    if (!t_relay()) {
       sl_reply_error();
    }
    exit;
}

And that’s it!
Here is the full kamailio.cfg

 

4 thoughts on “Kamailio and FreeSWITCH on the same server with NSQ and JANSSON-RPC”

  1. Great article, nice to see someone thinking outside the box. While it does solve the presence bottleneck on FreeSWITCH I’m curious if there are any security vulnerabilities using this method that you’ve come across?

    As Kamailio isn’t handling authentication does this make it vulnerable to an attack where someone could subscribe to presence using an unauthenticated extension or will it only allow subscriptions from authenticated (registered) extensions?

    1. You are probably correct but i should clarify, i wouldn’t recommend this setup if building a new system. This setup was more of a band-aid on a legacy system until a new platform could be released.
      Ideally, you would have Kamailio be the registrar and only allow subscriptions from already registered users.

  2. Great post, Emmanuel! You mentioned that “The NSQ message must be json format and contain the required fields for the presence module to send an update”. Do you have those payloads for NSQ and JANSSON_RPC that you can share? Also, on a separate note, what was the reason for using NSQ instead of rabbit? Although, it does appear the amqp module does not consume events.

    1. Hi Marvin,
      Sure– here is an example NSQ payload to update an example parking spot at 701:

      {
      	"Call-ID": "2ea46288-77d5-1236-428e-06d07bd303fe",
      	"Event-Category": "presence",
      	"Event-Name": "update",
      	"Event-Package": "dialog",
      	"Expires": "3600",
      	"From": "sip:myphone01@test01.domain.com",
      	"From-User": "myphone01",
      	"From-Realm": "test01.domain.com",
      	"To": "sip:park+701@test01.domain.com",
      	"To-User": "park+701",
      	"To-Realm": "test01.domain.com",
      	"State": "confirmed"
      }

      I’ve generally stayed away from rabbit since it requires a broker. And the broker can be a single point of failure. On a side note, I’m actually working on moving this logic out of NSQ altogether by using json and xhttp modules. I’m not sure if it will scale as well, but I like the idea of being able to directly “push” presence updates via an http request to kamailio. I’ll do a quick write up on that once I get the code completed.

Leave a Reply

Your email address will not be published. Required fields are marked *

Time limit is exhausted. Please reload CAPTCHA.

This site uses Akismet to reduce spam. Learn how your comment data is processed.