So now we’ve made a functional bare-bones PBX using Kamailio, and we’ve touched upon a few of the key functions Kamailio can do, but let’s go over them again to recap.

Future Kamailio posts I’ll be talking about using specific modules and using Kamailio for specific use cases, such as load balancing traffic between carriers and monitoring their up/down status, scaling Asterisk by front ending it with Kamailio, adding/rewriting/removing headers with Kamailio and stateful vs stateless operation, so stick around, but here’s an overview of what we’ve learned.

Routing Blocks & Structure

Routing blocks make code cleaner and allow reuse of the same blocks, you can call a route to do a function without having to write out what to do every time.

In the below example we go from the default “request_route” block, where all new messages start, and jump to the block named “RESPOND_501”.

request_route {
        route(RESPOND_501);    #Jump to the RESPOND_501 block
}

route[RESPOND_501]{
        sl_reply("501", "Not Implemented");   #Send 501 reply
}

From RESPOND_501 we send a stateless reply to whoever sent us the message.

We introduced xlog to write data to the log, and then viewed that data in Syslog.

xlog("Hello, I am in the request_route");

We determined the SIP method of the request using

if(method=="INVITE"){

to tailor our responses based on the method used.

Kamailio as a SIP REGISTRAR

This was covered in Part 4 of Kamailio 101,

The main takeaway from this was the use of

save("location");

We expanded this to only for REGISTER messages and to stop processing after the location was saved.

        if(method=="REGISTER"){
                save("location");
                exit;
        }

Then we used kamcmd for the first time to dump the user location so we could see our registered endpoints.

 
kamcmd ul.dump 

First Call

Building upon having saved the location of registered endpoints we looked up the locations we had Address on Record entries for and forwarded the traffic to them, to allow to make calls between registered UAs.

       if(method=="INVITE"){
                lookup("location");
                t_relay();
                exit();
        }

Quickly we saw issues with this though, if the UA we wanted to reach wasn’t registered, if we hung up before the called party answered, and a host of other scenarios,

We addressed the user not registered scenario and then talked briefly about the routing blocks that come with Kamailio and how they’ll be our savoir.

Reusing Code

We put back the default routing blocks that come with Kamailio after highlighting the difficulties with trying to do everything yourself.

We talked about how route(RELAY); will better handle message relaying than tm_relay(); alone, and using route(WITHINDLG); to manage within dialog requests & branching.

Security in Theory

We talked about the importance of AAA (Authentication, Authorisation & Accounting) and the perils of naming your son Bobby Droptables.

Security in Practice

We put what we talked about into practice.

Using a database back-end (MySQL) we setup our UAs to be authenticated when registering and before making calls, and listed our Carrier’s IPs so we’d only accept inbound calls from our carrier, not random folks online.

We used kamctl to add users and manage address groups.

route(REQINIT); was used to manage traffic validation.

auth_challenge(“$fd”, “0”); was used to authenticate UAs

and (allow_source_address(“200”)) was used to authenticate carriers.

Adding Carrier Links

Lastly we put all the pieces together and put in a carrier link / trunk to allow calls to be made / from to the PSTN using rewritehost()

So where to now?

You’ve made it to the end of this tutorial, but chances are it’s only the beginning of your Kamailio journey.

There’s a lot of posts on this site regarding Kamailio and it’s many modules, uses and functionalities, explore and good luck!

Before we get too much further, we’ll take a breather and talk about security. We saw in the last tutorial how we’ve got to have a way to handle every scenario, like how to handle a CANCEL to an INVITE, and security is the same.

You are responsible for the code you write being secure.

In this series we’ll ultimately end up with a basic PBX with the ability to make and receive calls between registered users and via trunks from a carrier.

Soon we’ll add the ability to call numbers not registered on our system (trunks) to our system, but now is a good time to talk about securing your system, as the threat of toll fraud is very real, as well as calls from random devices waking you up in the middle of the night.

VoIP security is a big topic, there’s a whole lot of wrong ways to do things, so think before you do.

Authentication, Authorisation and Accounting

Most telephony platforms employ some form of AAA, it’s a good minimum starting point for our system to ensure we Authenticate traffic, to make sure it is who it claims to be, we Authorise traffic to make sure it’s allowed to traverse this part of the network and use theses resources, and finally we’ll Account for resources used, for example recording CDRs and cost for the services used.

Authentication

Authentication in this example we’ll using the Challenge / Response based authentication for traffic from users (Such as REGISTER and INVITE messages), as shown in this example.

When we get an INVITE or a REGISTER from a user, we’ll check their username / password matches what we’ve got on record.

For this we’ll use Kamailio’s Auth_DB module.

Authorization

We’ll use IP Address authorisation for inbound traffic from carriers (so we can make sure that we’ll only allow calls from carriers, not just any IP on the internet sending INVITES).

This means when we get an INVITE from a Carrier to send us an inbound call, we’ll make sure it’s from the Carrier’s IP address before we start our user’s phones ringing.

For this we’ll use Kamailio’s Permissions module.

Accounting

We’ll skip Accounting for now as we’re not going to be charging users at this stage.

Kamailio has the Accounting module you can use for this, which we’ll talk about another day.

Traffic Validation

Now’s probably a good time to talk about validating your traffic in the wild west world that is the internet.

Let’s say we implement a database lookup in Kamailio to take the To part of the Request URI and lookup where to route it, we receive something like:

INVITE sip:[email protected]

So we’ve got that and we lookup 1234567 in our database and get where we need to route it to:

SELECT 'forward_destination' FROM 'imaginary_route_database' WHERE 'dialed_number' = '1234567';

Seems harmless enough right?

Now imagine someone sends an INVITE that looks like this:

INVITE sip:'; DROP TABLE *;@example.com

Now let’s look at how our SQL query would look:

SELECT 'forward_destination' FROM 'imaginary_route_database' WHERE 'dialed_number' = ''; 
DROP TABLE *; 
''; 

And suddenly we find all our tables have been deleted.

So it’s important we filter everything, and make sure the traffic is valid.

SQL injection is a fun example, but more common examples could include not checking the Max Forwards header and looping packets out and back in infinitely (imagine no spanning tree and plugging a switch into itself) and not responding to known bad user agents like sipcli and sipvicious.

Luckily again the Kamailio team have covered this before, Kamailio comes with a module for handling a lot of the common threats.

With the boilerplate routes we talked about in the last tutorial all you have to do is add route(REQINIT); at the start of your routing block and you’ll get:

• Dodgy UA filtering (You may want to add your own)
• Basics of Flood Prevention (if you want it)
• max_forward checking (for handling routing loops)
• OPTIONS response handling
• Sanity checking

In the next post we’ll go about putting these things into practice.

Next Post – Kamailio 101 – Tutorial 8 – Security in Practice | This Post – Kamailio 101 – Tutorial 7 – Security in Theory| Previous Post – Kamailio 101 – Tutorial 6- Reusing Code|

Other posts in the Kamailio 101 Series:
Kamailio 101 – Tutorial 1 – Introduction

Kamailio 101 – Tutorial 2 – Installation & First Run

Kamailio 101 – Tutorial 3 – Routing Blocks & Structure

Kamailio 101 – Tutorial 4 – Taking Registrations

Kamailio 101 – Tutorial 5 – First Call

Kamailio 101 – Tutorial 6 – Reusing Code

Kamailio 101 – Tutorial 7 – Security in Theory

Kamailio 101 – Tutorial 8 – Security in Practice

Kamailio 101 – Tutorial 9 – Adding Carrier Links

Kamailio 101 – Tutorial 10 – Recap

In the last tutorial we saw some issues, calls hung up before they were answered (CANCEL), we also would have run into issues with timeouts, issues if the remote end was registered but no longer responding, behind a NAT etc.

We saw a real example of what I touched on on the opener to this series, that you have to deal with everything, and it’s a daunting task.

Kamailio allows you to deal with all these problems yourself, writing your own routing blocks, but it also comes with a bunch of useful routing blocks in the example config, that we can re-use so we don’t need to specify how to manage every little thing ourselves – unless we want to.

So lets add some of these useful routing blocks,

We’ll add this at the start of our request_route{ block

request_route {

        if (is_method("CANCEL")) {
                if (t_check_trans()) {
                        route(RELAY);
                }
                exit;
        }


        if (!is_method("ACK")) {
                if(t_precheck_trans()) {
                        t_check_trans();
                        exit;
                }
                t_check_trans();
        }

        # handle requests within SIP dialogs
        route(WITHINDLG);

So now our config looks like this:

request_route {



        if (is_method("CANCEL")) {
                if (t_check_trans()) {
                        route(RELAY);
                }
                exit;
        }


        if (!is_method("ACK")) {
                if(t_precheck_trans()) {
                        t_check_trans();
                        exit;
                }
                t_check_trans();
        }

        # handle requests within SIP dialogs
        route(WITHINDLG);


    if(method=="INVITE"){
            if(!lookup("location")){
                            sl_reply("404", "User not Registered");
                            exit;
            }

            lookup("location");
            t_relay();
            exit();
    }


        if(method=="REGISTER"){
                save("location");
                exit;
        }
        xlog("No idea how to respond to method $rm");
        sl_reply("501", "Not Implemented");
}

As you can see we’ve added an if statement to match if the method is CANCEL or ACK, and referenced some routing blocks:

• route(RELAY)
• route(WITHINDLG);

We’ve also added some code to manage ACKs, but we’ll go through that on our lesson on Statefulness, for now just roll with it.

You’ll probably notice if you try and use this config that it won’t work, that’s because we’re referencing these two routing blocks without actually having defined them.

To keep us moving I’ve added all the routing blocks that come with the default Kamailio config, and added in our code to the link below;

GitHub – NickvsNetworking – Kamailio101

And finally we’ll restart and be good to go:

To recap, we added the boilerplate routes that come with Kamailio and referenced them in our code to better handle in dialog responses.

This is because handling all these possible scenarios, like NAT, cancel, no response, REINVITE, UPDATE, etc, etc, would take us ages to cover, and require a pretty good understanding of Kamailio and of SIP in practice.

So use the example I’ve linked above and tune in next time, where we’ll talk about adding security and authentication to our system before we connect it to the outside world.

Kamailio 101 – Tutorial 7 – Security in Theory| This Post – Kamailio 101 – Tutorial 6| Previous Post – Kamailio 101 – Tutorial 5 – First Call

Other posts in the Kamailio 101 Series:
Kamailio 101 – Tutorial 1 – Introduction

Kamailio 101 – Tutorial 2 – Installation & First Run

Kamailio 101 – Tutorial 3 – Routing Blocks & Structure

Kamailio 101 – Tutorial 4 – Taking Registrations

Kamailio 101 – Tutorial 5 – First Call

Kamailio 101 – Tutorial 6 – Reusing Code

Kamailio 101 – Tutorial 7 – Security in Theory

Kamailio 101 – Tutorial 8 – Security in Practice

Kamailio 101 – Tutorial 9 – Adding Carrier Links

Kamailio 101 – Tutorial 10 – Recap

So now we’ve got Kamailio handling REGISTER traffic, and we know what IPs endpoints are on, so let’s join this together and let’s route a call between two endpoints via our Proxy!

We’ll work on the config we were working on in the previous tutorial:

/* Main SIP request routing logic
 * - processing of any incoming SIP request starts with this route
 * - note: this is the same as route { ... } */
request_route {
        if(method=="INVITE"){
                sl_reply("480", "Temporarily Unavailable");
                exit;
        }
        if(method=="REGISTER"){
                save("location");
                exit;
        }
        sl_reply("501", "Not Implemented");
}

Let’s change how we handle the INVITE messages in our if(method==”INVITE”) block so instead of responding with a 480 Unavailable response, let’s lookup the location we saved if it was a REGISTER and forward the INVITE to the IP we’ve got.

        if(method=="INVITE"){
                lookup("location");
                t_relay();
                exit();
        }

Let’s break down each of the new functions we’ve introduced:

lookup(“location”);

In the last post we introduced save(“location”); which saves an Address on Record for the URI. lookup(“location”); looks up the IP address of the URI we’re after in the Address on Record table we wrote to with our save(“location”); call and automatically sets it as the destination IP of where we’re going to send the message.

When a user registered via a SIP REGISTER request, we saved their details, now we’re looking them up.

You could even replace the lookup(“location”) call with say a SQL lookup on an address book, and save the output to the IP the INVITE will be forwarded to, but lookup(“location”); does this it all in one function.

t_relay();

t_relay is transactional relay function. By transactional it means Kamailio remembers this session next time it’s referenced, we’ll touch upon transaction aware / stateful SIP proxies later, but for now what you need to know is it forwards the INVITE we just received to the address we got from our lookup(“location”).

exit();

Exit bails out so we won’t keep processing after that, it doesn’t just bail out of our current conditional but stops processing this request further. Without it we’d still go on and send the 501 Not Implemented reply.

The Setup

I’ve setup two phones – One using the username 106 and the other using 108, I’ve pointed both to the IP of our Kamailio instance and they’ve registered. Keep in mind if you’ve restarted Kamailio it’ll lose it’s location table, as it’s stored in memory, so you’ll have to force the phones to register again.

You can check you’ve got devices registered by using kamcmd ul.dump at the command line to confirm you’ve got entries for both. I have so I’ll try dialling 108 from 106:

Here we can see the INVITE coming in, the lookup(“location”) doing it’s magic and forwarding the messages to the IP of 108.

The 100 Trying, 180 Ringing and 200 OK messages all go through on their own as they’re part of an existing dialog which we’ll touch on why later in the series,

So we’re done here right? Well, not quite…

What if a call is made to an endpoint that isn’t registered? Or if they send a CANCEL before the call is answered?

Let’s take a look at what happens if we try this:

The INVITE is received by Kamailio, a 100 TRYING response is sent back, but Kamailio isn’t really doing anything, after about 10 seconds I try and end the call from my softphone (CANCEL) and I get a 501 response back as we haven’t defined how to handle CANCEL messages, so there’s no way to end the call, and we’re stuck…

When things don’t go to plan…

As I said in the Introduction to Kamailio post, the power in Kamailio is the ability to define how every part functions, but to quote Spiderman – With great power comes great responsibility, and Peter Parker didn’t have the 269 pages of RFC3261 to grapple with…

We know the above example works fine when there’s a device registered on the other end and if they answer, but if they don’t? As we’ve seen, we’ve got to cater for every scenario.

Handling no registered user

Instead of just lookup(“location”) to lookup location we can put it in an if statement with some code to be run if it fails.

We’ll use the the if(!lookup(“location”)){ } call to create a new conditional for if lookup location fails, and inside it we can reply with a 404 and exit.

The if(!){} block can be used to try and run a command, and if it fails, it’ll run what’s between the {}.

In our scenario we try and lookup the location, if that fails, for example because we don’t have an Address on Record for that destination, it executes what’s between the {} in this case we use sl_reply to send a 404 error back and then exit:

    if(method=="INVITE"){
            if(!lookup("location")){
                            sl_reply("404", "User not Registered");
                            exit;
            }

            lookup("location");
            t_relay();
            exit();
    }

So now if an INVITE is received to a destination we can’t find via a lookup(“location”); we respond with a 404 and exit.

Handling CANCEL (Calls terminated before answered)

So now we’ve specified how we’ll handle calling a device that isn’t registered, next we have to specify how we deal with CANCEL messages, so if the calling party hangs up (cancels) the call before it’s answered by the called party, it stops ringing the called party.

CANCEL is a bit of a headache. – Here’s why:

CANCEL is treated differently to a lot of in-dialog messages. Let’s take a look at the IETF’s example call flows & best practices example:

Note that the CANCEL message is acknowledged with a 200 OK on a hop by hop basis, rather than end to end.

RFC 3665 – SIP Basic Call Flow Examples – Unsuccessful No Answer

This means our SIP server has to get the CANCEL message from the caller who’s given up, respond with it with a 200 OK to the caller, before forwarding that CANCEL onto the next hop (the user we were trying to call).

By this point you’re probably dreading your work ahead of you as you try and understand how to handle every scenario, every eventuality and all the weird gotchas like CANCEL.

If only there was someone else that had done this before…

Luckily the Kamailio team have got pretty great examples in the kamailio.cfg file that ships by default (that one we ruthlessly gutted to keep it simple in the second tutorial) and now is a good time to re-introduce some of these routing blocks, that are reused in most Kamailio instances.

The boilerplate that gets you up and running faster and means you don’t have to worry about quite as many possible scenarios or read about how to handle CANCELS ad nauseam.

In the next tutorial we’ll talk about these routing blocks, and add them to our code to manage scenarios like CANCEL, timeouts to the remote destination, and how you can use these blocks to speed things up and keep everything RFC compliant.

Next Post – Kamailio 101 – Tutorial 6| Kamailio 101 – Tutorial 5 – First Call| Kamailio 101 – Tutorial 4- Taking Registrations

Other posts in the Kamailio 101 Series:
Kamailio 101 – Tutorial 1 – Introduction

Kamailio 101 – Tutorial 2 – Installation & First Run

Kamailio 101 – Tutorial 3 – Routing Blocks & Structure

Kamailio 101 – Tutorial 4 – Taking Registrations

Kamailio 101 – Tutorial 5 – First Call

Kamailio 101 – Tutorial 6 – Reusing Code

Kamailio 101 – Tutorial 7 – Security in Theory

Kamailio 101 – Tutorial 8 – Security in Practice

Kamailio 101 – Tutorial 9 – Adding Carrier Links

Kamailio 101 – Tutorial 10 – Recap

So far we’ve made Kamailio tell clients it can’t do things, today this changes!

In this example we’ll implement a simple SIP Registrar, without authentication.

Please don’t use this in the real world – You really need to authenticate REGISTER traffic and we cover security later in the series…

As we talked about in the post on SIP Registrars, SIP Registrars take the REGISTER requests from SIP endpoints and store their contact details in the form of an Address on Record (AoR). This AoR contains the URI and the endpoints’ current IP it just sent the REGISTER message from.

The primary use of this is it allow us to know how to reach people. It’s kind of like an address book for mapping current IP against a SIP URI, as IP Addresses of SIP endpoints may change often.

So our Kamailio instance is going to receive an REGISTER message, store the Contact as an address on record, and respond 200 OK. Let’s build upon the config we started with in the last tutorial:

/* Main SIP request routing logic
 * - processing of any incoming SIP request starts with this route
 * - note: this is the same as route { ... } */
request_route {
        if(method=="INVITE"){
                sl_reply("480", "Temporarily Unavailable");
                exit;
        }
        sl_reply("501", "Not Implemented");
}

So let’s add an if statement to manage REGISTER messages, and save their location:

/* Main SIP request routing logic
 * - processing of any incoming SIP request starts with this route
 * - note: this is the same as route { ... } */
request_route {
        if(method=="INVITE"){
                sl_reply("480", "Temporarily Unavailable");
                exit;
        }
        if(method=="REGISTER"){
                save("location");
                exit;
        }
        sl_reply("501", "Not Implemented");
}

So we’ve added an IF statement to find if the SIP method is a REGISTER message, and if it is, we’ll call the save(“location”); function.

The save() function saves the Contact address we just received to a database (in this case one in memory) in the form of a SIP URI and current Contact location, these two bits of info combined are known as an address on record (AoR) and the save function, if successful, responds with a 200 OK automatically.

I’ve pointed a SIP endpoint at it again, we revive the REGISTER, respond with 200 OK,

As you can see REGISTER sent to us, 200 OK responded.

So that’s it – Our SIP endpoint is happy and by calling the save(“location”) we’ve called the built in function to store the Contact as an Address on Record and respond with 200 OK.

So how do we access this information and what can we do with it?

Kamailio comes with two tools for accessing Kamailio while it’s running. In this example we’ll use kamcmd to check what’s registered on our system. After we’ve seen a device register, from command line we’ll run:

kamcmd ul.dump

This calls kamcmd the Kamailio command line tool, and calls the ul.dump function. ul is short for userloc – The module for user location management, and dump outputs all the contents of the userloc table.

Here we can see the info we’ve stored from the URI of the user (sip:[email protected]:60153) who sent a REGISTER at the Unix timestamp in “Last-Modified”.

So now we’ve created a SIP registrar, in the next tutorial we’ll use this information to route SIP INVITE messages to a registered endpoint, looking up it’s IP and get a call happening!

You can find the full Kamailio config for this in the GitHub repo.

Next Post – Kamailio 101 – Tutorial 5| Kamailio 101 – Tutorial 4 | Kamailio 101 – Tutorial 2 | Kamailio 101 – Tutorial 1

In production you’d generally not have a SIP registrar like this open to accept any registrations, you’d authenticate SIP endpoints using the REGISTER -> 401 Unauthorised -> REGISTER -> 200 OK process outlined here.
To do this using the usrloc module we’d need to introduce the concept of a stateful proxy, as we need to remember what the challenge we sent them was to compare it with what we’re expecting, but we’ll touch upon this later in the series.

Other posts in the Kamailio 101 Series:
Kamailio 101 – Tutorial 1 – Introduction

Kamailio 101 – Tutorial 2 – Installation & First Run

Kamailio 101 – Tutorial 3 – Routing Blocks & Structure

Kamailio 101 – Tutorial 4 – Taking Registrations

Kamailio 101 – Tutorial 5 – First Call

Kamailio 101 – Tutorial 6 – Reusing Code

Kamailio 101 – Tutorial 7 – Security in Theory

Kamailio 101 – Tutorial 8 – Security in Practice

Kamailio 101 – Tutorial 9 – Adding Carrier Links

Kamailio 101 – Tutorial 10 – Recap