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