Kamailio by example - Introduction

Intro

Note: Read the official docs to get the most updated information.

Now that we have resources to learn about Kamailio and a lab ready to test it, let’s do our Hello, World!

hello

loadmodule "sl"

request_route {
  sl_send_reply(200, "Hello, World!");
}

This is our kamailio.cfg.

Kamailio will read it from the default location, which is /etc/kamailio/ for package installations and /usr/local/etc/kamailio/ when building from source. However, this file path can be specified with a -f <path>.

This hello example is simply:

• Loading the sl module: loadmodule "sl".
  • This module is responsible for stateless requests handling and is needed because we are using its sl_send_reply() function.
• Defining the request_route.
  • The only mandatory routing block is request_route, which contains the actions for deciding the routing for SIP requests.
• Sending a stateless reply.
  • A 200 Hello, World! reply is sent using the sl_send_reply() function.

If you are not familiar with stateless/stateful proxies, check SIP Concepts.

Config

Kamailio uses its own configuration file language (native scripting). The structure can be splited in three parts:

• global parameters
• modules settings
• routing blocks

Characteristics

• Lines with instructions have to end with a semicolon ;. Global parameters do not need it, unless values are defined in multiple lines.
• Comments start with # or // if single line or /* comment */ for multi-line

Global Parameters

This is the first part of the configuration file, containing the parameters for the core and custom global settings. Typically, this is formed by directives of the form name=value. We don’t have global parameters, so let’s add some:

#!defenvs KAMA_LISTEN
listen=KAMA_LISTEN
auto_aliases=no

• defenvs defines an ID to the value of an env variable, that will be used by listen.
  • This #! means a pre-processing directive, that we will learn in another article.
• listen defines the address to listen to instead of listening on all available addresses.
• auto_aliases setting it to no, to disable the reverse DNS lookup and make the startup faster.

You can find the full list of core parameters in the Core Cookbook.

Modules Settings

This section contains the directives to load modules (loadmodule) and set their parameters (modparam).

loadmodule "sl"
modparam("sl", "bind_tm", 0)

We are adding this modparam setting to disable the bind to the tm module, that we do not use or load, thus removing the warning we see in the logs.

You can find the full list of modules in the Modules Documentation.

Routing Blocks

The routing blocks are similar to functions, which can be executed many times at runtime and contain the routing logic for SIP traffic.

request_route {
  sl_send_reply(200, "Hello, World!");
}

The only mandatory routing block is request_route, which contains the actions for deciding the routing for SIP requests.

Route blocks can also be executed on timer events (e.g., retransmission timeout) or particular events specific to modules.

This is a small introduction to a configuration, but we will get into more detail in the next sections.

How to test

Check the kamalab to prepare your lab.

# kamalab ❯
./kamalab
# select 0.2.1-hello.cfg
# Listening on
#              udp: 127.0.0.2 [127.0.0.2]:5060
#              tcp: 127.0.0.2 [127.0.0.2]:5060
# Aliases:

In another terminal let’s send OPTIONS to the server:

# >
sipexer 127.0.0.2
# ...
# OPTIONS sip:127.0.0.2:5060 SIP/2.0
# ...
# SIP/2.0 200 Hello, World!
# ...

We can see the response to our request: 200 Hello, World!

Resources

• Wiki Core Cookbook