User Tools
Sidebar
This is an old revision of the document!
Table of Contents
Kamailio - Getting Started Guide
A collection of guidelines and useful links to smoothen the understanding and deploying of Kamailio for newbies.
Feel free to add new content here.
The first version of the tutorial was written for Kamailio v4.3.x.
Prerequisites
SIP
The initial name of the project was SIP Express Router (aka SER) and that says it all: Kamailio is a SIP router at the core. It means that it works at the lower layer of SIP packets, routing each and every SIP message that it receives based on the policies specified in the configuration file.
It is important to understand that it is not a telephony engine at its core, a VoIP call is seen as a sequence of SIP messages sharing the same attributes for caller, callee and signaling tokens such as Call-ID, From tag and To tag.
Given the above, a good understanding of SIP is critical to get faster familiar with Kamailio, especially with its configuration file routing rules.
Session Initiation Protocol (SIP) is specified by IETF (www.ietf.org), with the core specification in the RFC 3261:
Many other RFCs add to the core specifications, look at what is published by the IETF Working Groups for SIP and SIMPLE.
IETF RFC documents are a bit dry to read, with particular language suitable for technical specifications, therefore trying to learn SIP directly from RFCs could be not that easy. Fortunately there are plenty of free online resources, tutorials or blogs, as well as books, that can help understanding SIP faster.
A SIP Introduction tutorial was written by SER/Kamailio developers quite some time ago. It is available inside source tree of Kamailio, in the folder doc/sip/. It is docbook xml format, the html version can be read online at:
Other online SIP learning resources:
SIP Books:
Logical Programming
Kamailio configuration file is not just a set of 'parameter=value' line. It has active components for runtime, named routing blocks. A routing block is a group of actions that specify what should be done for each SIP message.
The actions are exported by Kamailio core or modules and are like functions exported by a library. Those actions can be combined in conditional statements like IF and SWITCH or in loops like WHILE. Modularity is provided by the ability to execute a routing block from another routing block.
Therefore, understanding logical programming is important as well. Be sure you are familiar with concepts such as functions, variables, conditions or loops.
IF, SWITCH and WHILE are pretty similar to other imperative languages such as C, Perl, Python or Java. Even Shell/Bash programming is useful to get into Kamailio configuration structure.
Linux/Unix
Being developed for Unix/Linux, managing a Kamailio instance, from installation to runtime and maintenance involves operations specific for Linux administration, like running command line applications from terminal, configure network and firewall to allow sending/receiving SIP and RTP packets, a.s.o.
Troubleshooting Kamailio and SIP requires knowledge of various tools for reading and searching log files (e.g., grep, awk), sniffing the network (e.g., ngrep, tcpdump, wireshark). Of course, knowing to work with text editor, especially the ones for terminal if the server is remote, is quite obvious (e.g., vim, joe, nano, pico, emacs, etc.).
Initial Installation
From Sources
Install current stable version:
Install development version (master branch):
Debian
Kamailio is part of latest official stable Debian distribution (and its Ubuntu cousin), but might be an older version.
To use most recent Kamailio release, you can use the APT repositories hosted by Kamailio project, see details at:
Then, the typical way of installing packages can be used:
apt-get update apt-get install kamailio
Various modules are packaged separately, you can search the repository to see what is available:
apt-cache search kamailio
Install the other packages of the modules you may need, like mysql or tls modules – they can be installed with:
apt-get install kamailio-mysql-modules kamailio-tls-modules
CentoOS
Configuration File
Overview
Default Configuration File
Tools
kamctl
Kamctl is part of Kamailio project (in the same source tree) and installed by default.
It has a configuration file named kamctlrc, located in the same folder with kamailio.cfg. You have to edit it to set your SIP domain, the database engine, username/password/… to connect to database, etc.
This is the tool to manage kamailio from command line, providing lots of operations, such as adding/removing/updating SIP users, controlling the ACL for users, managing the records for LCR or load balancing, viewing registered users and internal statistics, etc.
When needed to interact with Kamailio, it does it via FIFO file created by mi_fifo module. Operations to the database are done by connecting directly to the database server.
kamdbctl
Kamctl is part of Kamailio project (in the same source tree) and installed by default.
It uses the same configuration file like kamctl, respectively the kamctlrc.
The tool can be used to create and manage the database structure needed by Kamailio, therefore it should be immediately after Kamailio installation, in case you plan to run Kamailio with a database backend.
It is not used for managing the records inside the database tables, just for database structure and access to the database (e.g., granting/revoking access to database server). For managing the records inside database table, kamctl is the tool.
kamcmd
Kamctl is part of Kamailio project (in the same source tree) and installed by default.
This is an application that can send RPC commands to Kamailio from command line. It requires that the ctl module is loaded by Kamailio.
siremis
It is a web management interface for Kamailio, written in PHP – more at:
kamcli
It is a command line application write in Python, more or less an alternative to kamctl. It has a modular architecture, allowing to extend it by writing new plugins.
See more at:
Typical Use Cases
NAT Traversal
VoIP Provider
Load Balancing
Least Cost Routing
IMS/VoLTE
Instant Messaging and Presence
WebRTC
Useful Resources
Kamailio Books
Kamailio Online Tutorials
