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

I know when I look back on code I’ve written in the past I cringe a little. As you go along you learn more efficient ways to do things, so before we hop to far into Kamailio we’re going to talk about how we’ll write our kamailio.cfg file.

General Rules

Some rules of thumb to get you started with writing Kamailio configs:

• All lines that do things (instructions) have to end with a semicolon
• Comments start with # if single line or /* blah */ for multi-line
• Changes to the config only take effect when you restart Kamailio
• With what we have setup restarting Kamailio causes it to forget all about your active Registrations (Even though your devices might say they’re still registered) (For now, although we can change this behaviour)

Now we’ve got that out of the way let’s continue on from our last tutorial and start routing requests!

(We’ll skip all the config above the request_route{} block that configures the modules and their setup, it’s all very important, but we’ll touch upon that in a later tutorial I promise)

As I touched upon in the Introduction post, you define what Kamailio is and does in terms of routing SIP requests, so let’s jump straight in and get started on the blocks that take care of this.

The request_route{} Block

The request_route{} block is where all our incoming SIP requests start off. Replies / responses are handled a bit differently (more on that later), but essentially every new SIP request / message / dialog starts off here.

We can create new blocks other than request_route{} to help keep our code clean, in the same way we might define functions while programming.

Let’s take a look:

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

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

We can see in the above example, any SIP Request coming in will enter our request_route{},

In our request_route{} block we only have one instruction, which is route().

The route() command allows us to then specify another block of the config file / code to continue on from. Think of it kind of like calling a function or god forbid – a GoTo. So in this example the call comes in and then routed off to a new routing block called route[RESPOND_501],

This allows us to reuse bits of code multiple times and generally keep everything a lot cleaner.

It’s worth noting that unless you tell it to, routing to another block won’t stop Kamailio from continuing to execute it’s way through the code, it’ll do what it’s told in the other routing block and then finish what it started.

Let’s look at an example:

request_route {
        xlog("Hello, I am in the request_route");
        route(RESPOND_501);    #Jump to the RESPOND_501 block
        xlog("Back in request_route");
}

route[RESPOND_501]{
        xlog("Now I am in the respond 501 route");
        sl_reply("501", "Not Implemented");   #Send 501 reply
}

If we’re to run this code and send a SIP Request to it, we’d see each of these xlog entries in your syslog,

• As the message firsts hits the xlog(“Hello, I am in the request_route”);, then is routed off to route[RESPOND_501]
• In route[RESPOND_501] we’ll see the xlog(Now I am in the respond 501 route”); – Kamailio has now executed the route[RESPOND_501] block and resumes from where it was in request_route{}
• When we get back to request_route we get the final xlog(“Back in request_route”);.

We can stop routing in a specific block using the exit; command which stops processing that request once hit. For example:

request_route {
        xlog("Hello, I am in the request_route");
        route(RESPOND_501);    #Jump to the RESPOND_501 block
        xlog("Back in request_route");
}

route[RESPOND_501]{
        xlog(Now I am in the respond 501 route");
        sl_reply("501", "Not Implemented");   #Send 501 reply
        exit;
}

Because of the exit we added in the route[RESPOND_501] Kamailio stops executing at that point, so we don’t continue passing through the config file and this time we won’t get the final xlog(“Back in request_route”); call.

Boilerplate Routes

Kamailio’s example config by default comes with a lot of preconfigured routes that can be reused over and over again, so you don’t have to create everything from scratch if you don’t want to. We’ll talk about using these in an upcoming tutorial, but for now just keep in mind there’s pre-written routing blocks for things like managing NAT, sanity checking traffic, etc.

Basic Message Routing

Let’s take a very basic use case, and write some code in the request_route{} block.

We’ll set it up so if we receive an INVITE request, we’re going to respond with a 480 Temporarily Unavailable message, and for everything else, we’ll respond with 501 “Not Implemented”.

/* 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 break this down,

First we have a an if statement – If the method of the SIP message is an INVITE request, then execute the code inside the curly brackets.

Inside the curly brackets we’ll respond with 480 Temporarily Unavailable, using sl_reply() (You may remember from the last post that sl_reply sends a reply back to the sender of the message with the response code and text specified) and then exit, meaning we won’t continue executing what’s next in the config.

Finally outside of our if statement (so catching any SIP requests who’s method isn’t INVITE) we’ll respond with 501 “Not Implemented”.

We’ll restart Kamailio & fire up a packet capture as we did in Part 2 of the series. Let’s take a look:

Here we can see our REGISTER message got back a 501 Not Implemented response, while our INVITE got a 480 Temporarily Unavailable response.

We’ve now expanded upon our useless SIP server, in the next tutorial we’ll cover doing something useful!

Link to Kamailio 101 – Tutorial 4 | Kamailio 101 – Tutorial 2 | Kamailio 101 – Tutorial 1

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

This tutorial will use Kamailio on Ubuntu 18.04, installed from the default repos using apt-get, but these concepts will apply to any version 4.x Kamailio instance, though some of your directories & file names may differ.

After setting up our Ubuntu box we’ll update our repos and install Kamailio

apt-get update 
apt-get install kamailio*

Now we’ve installed Kamailio with all the extra modules and plugins.

In production you’d only install what you need, but this would mean our development environment won’t be complaining about not having modules, so we’re installing the lot.

So now Kamailio is installed we can get to work making it do something.

Kamailio is driven by a text based config file that defines the routing rules and how we’ll handle SIP messages.

You need to specify how to handle the different types of SIP messages (aka SIP methods / requests), in a way the other devices communicating with it will understand and that generally follows the standards.

But for our example, we’ll create a really basic config that replies to any SIP message sent to it, saying it doesn’t know how to handle that message.

We’ll open kamailio.cfg – the text file that contains all our routing info, and get to work.

vi /etc/kamailio/kamailio.cfg

You’ll see the config starts by defining what modules to load, and the config for each of these modules. For us, the defaults will work for now, let’s get to the juicy bits. Keep moving down the config file until you hit this section:

/* Main SIP request routing logic
 * - processing of any incoming SIP request starts with this route
 * - note: this is the same as route { ... } */
request_route {

The request_route section is what handles the initial SIP message that comes through.

We’ll remove all the text after request_route { leaving us with a blank canvas in terms of how we handle messages. We’ll then put in a single line to log to syslog when we get a SIP message:

/* Main SIP request routing logic
 * - processing of any incoming SIP request starts with this route
 * - note: this is the same as route { ... } */
request_route {
        xlog("I got a message");
}

If we were to stop here and restart Kamailio, when a SIP message comes into our SIP server, we’d just write an entry to syslog saying “I got a message” each time we get a SIP message, but Kamailio won’t respond to the received SIP message, it’ll just enter a log entry each time it gets a SIP message. So let’s respond to any SIP message we get with a 501 “Not Implemented” message.

/* Main SIP request routing logic
 * - processing of any incoming SIP request starts with this route
 * - note: this is the same as route { ... } */
request_route {
        xlog("I got a message");
        sl_reply("501", "Not Implemented");
}

So let’s break down the two functions we just used.

xlog(“”);

xlog is your friend.
Put simply xlog prints whatever you put inside the parenthesis to syslog.
You can use it to check to see if your messages are getting to the part of the config you want, check what pseudovariables are doing and many other things, but I’m getting ahead of myself. For now you just need to know xlog is like NoOp() in Asterisk, print() in Python, etc.

sl_reply();

sl_reply is stateless reply.
It takes two parameters, the SIP Response Code and the text to go with it, when called it sends the SIP response code and text back to the requester.
In this case we’re using SIP Response Code 501, which translates to Not Implemented, meaning the server does not support the functionality required to fulfill the request aka:

Putting it into Play

Now let’s restart Kamailio to make our config live, point a SIP endpoint at it and see what happens!

First we’ll restart Kamailio:

/etc/init.d/kamailio restart

All going well you’ll restart Kamailio and be good to go:

Now let’s fire some traffic at it and see what happens.
I’m using tcpdump to capture traffic on port 5060, and I’ve setup a SIP endpoint that’s going to try and register to our IP to see what we get:

So this is exciting, we now have a SIP server that can do nothing except let people know it can do nothing.

Let’s dig a bit deeper into the fundamentals and then we’ll have a good foundation to start building from, and get to work on stitching everything together to create something useful.

Link to Part 3 | Back to Part 1

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

Kamailio (formerly OpenSER) is an open source SIP server, but Kamailio is a bit difficult to grasp what “it is“, but once you understand it’s all very logical.

Over this series I’ll attempt to explain what Kamailio is (and isn’t), and through a series of examples, show you how to use Kamailio to build cool stuff.

I’ll try and make it accessible for people with a background / understanding of VoIP, specifically with an understanding of SIP.

There’s a lot of meticulous documentation out there on specific Kamailio modules, but not much I could find that gives an overview of how the platform works, so over this series of Tutorials, I’ll attempt to cover the basics of using Kamailio to solve problems, as together we build a basic PBX with Kamailio, touching upon some of the common modules and core concepts of Kamailio.

So what is Kamailio ?

Kamailio is a SIP Server.

It’s a bit confusing at the start, because Kamailio isn’t like FreeSWITCH, Asterisk, YATE, an SBC, a PBX or any of other telephony platforms you may have encountered before, because out of the box, Kamailio doesn’t really do anything.

You’ve got to tell Kamailio how to do everything.

Let’s take a SIP INVITE message, used to start a call (aka session) that we might send to a PBX with the domain name biloxi.example.com and a SIP endpoint registered as ‘101’:

INVITE sip:[email protected] SIP/2.0

If we sent this message to a generic PBX, the PBX would have the logic to know that it has an extension 101 and the PBX would ring extension 101.

Our generic PBX looks at the Request URI in the INVITE message it received and has the logic predefined to know that 101 is a device it has registered and that we want to connect to that device, so sends the call to the matching device.

If we sent the same INVITE to an Asterisk box, Asterisk would take a look at our SIP INVITE message, and see if there’s an entry in the dialplan under the current context for 101. Asterisk doesn’t assume if you have a user registered on SIP/101 and receive a SIP INVITE to 101 that you want to get to SIP/101, it’d need to be told this through the dialplan.

Kamailio takes this example even further.

If we want to dial 101 on Kamailio and have it ring the device registered on 101, you have to tell Kamailio what to do when it receives an INVITE message in the first place, lookup if that destination is in our AOR (we’ll get to that) table, and then forward the INVITE to the destination if it exists, and forward the provisional responses (1xx) and finally the final response (200 OK) from the remote end back to the originator. Plus we’ve got to think about how we handle a scenario where the destination doesn’t exist, or isn’t registered, of if the destination returns a 4xx response to the INVITE, how we handle provisional responses and CANCEL messages and finally the BYE message (if we’re record routing).

Phew. This seems like a lot to handle.

It all seems pretty daunting at first, calling from one SIP Endpoint to another seems like a pretty rudimentary thing in a telephony product, but by putting how the system thinks, routes and manipulates messages up to you, we open the doors to all the possibilities.

What if you want something to sit in front of your servers and only allow certain SIP User Agents? Or load balance between several soft-switches? Or route least-cost between connected carriers and seamlessly failover if one is lost? Rate limit dodgy traffic before it hits your environment? Manage hundreds of thousands of registrations?

Kamailio can do all of that.

Kamailio can do anything you can think of (to do with signaling).

And that’s the awesome part of Kamailio. It is, what you define it to be.

So let’s get started!

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