Best of New in Kamailio 3.1.0 - #4: Embedded XCAP Server

SIP SIMPLE extensions get slowly into IM & Presence market, however, they are more visible lately than few years ago. One of the key components in XCAP server - an XML storage engine that uses HTTP for transport.
Kamailio 3.1.0 is first open source SIP server that includes an embedded XCAP server - functionality provided by xcap_server module. That means a very tight integration with the SIMPLE Presence server offered by Kamailio for quite some time.

Although XCAP specs specify HTTP as transport protocol, the implementation in Kamailio can work fine with XCAP documents transferred with SIP (over TCP, TLS and even SCTP or UDP).

All these together make the implementation of a SIP SIMPLE server simpler than anytime before. You get a compact solution, within a single application. However, worth to mention that Kamailio can be used as a stand-alone XCAP server, with other SIP application servers.

There is a complete tutorial about how to deploy Kamailio with embedded XCAP server, using SIP Communicator as softphone. You will discover that the additions to default Kamailio config file are pretty minimal, straightforward and independent of SIP routing logic - see the tutorial at:

• http://kb.asipto.com/kamailio:presence:k31-made-simple
  

For further references, you can browse xcap_server module documentation:

• http://kamailio.org/docs/modules/3.1.x/modules_k/xcap_server.html
  

Best of New in Kamailio 3.1.0 - #3: Embedded HTTP Server

There is no doubt that SIP and HTTP integration brings lot of benefits for servicing VoIP, IM and Presence.

Being able to request information directly from SIP server via HTTP, without the need to develop intermediate layers and APIs, opens the doors for tighter integration between web and realtime voice, im & presence.

Kamailio 3.1.0 introduces a new module, named xhttp, that extends its capabilities with the ability of handling HTTP requests.

Usage is straightforward, you have to load the module and define a special route called event_route[xhttp:request]. Every time an HTTP request is received, the actions in this event route are executed. You can authenticate the HTTP requests, using same username and passwords like for SIP accounts, being sure that only local subscribers can access HTTP resources exported by SIP server.

Next is a simple route that welcomes visitors over HTTP and prints their IP address and port:

event_route[xhttp:request] {
  if (!www_authorize("kamailio.org", "subscriber"))
  {
    www_challenge("kamailio.org", "0");
    exit;
  }
  xdbg("===== xhttp: request [$rv:$au] $rm => $hu\n");
  $var(html) = "Welcome " + $au + "! Your address is [" + $si + ":" + $sp + "]";
  xhttp_reply("200", "OK", "text/html", "$var(html)");
}

The above example intercepts all HTTP requests sent to SIP server, no matter the URL, but you can offer different replies based on HTTP URL - its value is available in config variable $hu:

switch ($hu) {
  case "/mycontacts":
    # send back the online contacts of authenticated user
    ...
  break;
  case "/myaccount":
    # send back the contacts of authenticated user
    ...
  break;
  default:
    # invalid resource - page not found
    send_reply("404", "Page not found");
    exit;
}

In HTTP event route, you can use any function exported by Kamailio core and modules, access its database and memory. Also, you can use embedded languages such as Lua or Perl to build the HTTP reply, having full language tools to construct rich HTML documents.

You can browse the documentation of xhttp module at:

• http://kamailio.org/docs/modules/devel/modules/xhttp.html
  

Best of New in Kamailio 3.1.0 - #2: Embedded Lua

Lua is a small, fast and easy to embed programming language (http://www.lua.org). It is a good choice to implement the routing logic for complex requirements in a SIP Server.

A new module in 3.1.0, named app_lua, provides the functionality to execute Lua code and scripts in your configuration file.

The readme and the API are available at:

• http://kamailio.org/docs/modules/3.1.x/modules/app_lua.html
• http://sip-router.org/wiki/api/lua/devel
  

Lua language is small and fast, therefore fits very well in a sip proxy environment, it has a lot of extensions, so when you cannot do something with existing cfg functions, check Lua documentation. The interpreter is embedded in app_lua module, so it is executed within Kamailio context.

Inside the Lua scripts, you get access to SIP message and functions from Kamailio core and modules. I did a presentation at Amoocon 2010 showing a practical example: how to use Lua to send notifications to Twitter from your SIP server, see the slides at:

• http://www.amoocon.de/talks/101

Here is an example of sending a SIP reply through Lua:

lua_dostring("sr.sl.send_reply(200, [[Lua says is ok]])");

This is execution of Lua code provided within the string parameter of lua_dostring(). Also, you can execute a Lua script by providing the path in the parameter of lua_dofile():

lua_dofile("/path/to/yourscript.lua"); 

Other options to run Lua code are provide by the new module, like to load a script at startup and execute functions from it at runtime.

Best of New in Kamailio 3.1.0 - #1: Interactive Config Debugger

Version 3.1.0 is just to be released, proposed date being October 6, 2010, that means about one week and a half since today. So it's time for the blog series to show what are the best of the new features to be introduced by this major release. Backed up by the biggest development team in the history of the project, 3.1.0 comes with a large set of new features, along with tighter integration between Kamailio (OpenSER) and SIP Express Router (SER) - the sip-router.org development project.

Let the show begin ...

One of the topics gathering complaints in the past was the complexity of debugging the config file. xlog module did the heavy work so far to help administrators understand how the processing of SIP traffic is going through the config file (I still consider xlog the best friend of config file writers, and it has some new goodies I will talk about them later).

Well, I guess this new features will make happy a lot of people: version 3.1.0 brings a new module, named debugger, providing an interactive configuration file debugger and printing of execution trace.

It allows to execute step by step the configuration file, discover which actions are involved in routing a particular SIP message and evaluate pseudo-variables in the context of that message. For those familiar with gdb tool, you can make a similar association. Tools like sercmd (command line tool, installed by default in the same location as Kamailio binary) or siremis (web management interface available at http://siremis.asipto.com) can be used to control the module with RPC, from same host or remotely.

How it works? You can tell Kamailio to stop before executing first line of config when a SIP message is received (also, you can set breakpoints at certain lines of your config). Then, via RPC commands, you can instruct to execute next action, evaluate a config variable or to execute all next actions. External applications such as sipsak or sipp can be used to inject a SIP message that is problematic, in order to debug it.

Let's look at an example: if calls set to you by a particular peering partner originating traffic from 10.0.0.10 are not routed properly, you can add at beginning for main routing route next lines:

if($si=="10.0.0.10")
dbg_breakpoint("1"); 

Then, when a call is sent from there, kamailio stops to execute the actions after dbg_breackpoint("1"); line. You connect with sercmd and see which kamailio process read it and issue dbg.pb next commands, walking step-by-step through the actions of config file.

You can see an example in the readme of debugger module, some snippets pasted next:

sercmd> dbg.bp show 6402
at bkp [/etc/kamailio/debugger.cfg:369] a=6 n=route

sercmd> dbg.bp next 6402
exec [/etc/kamailio/debugger.cfg:369] a=6 n=route

sercmd> dbg.bp eval 6402 $fu
$fu : t=str v=sip:test@kamailio.org 

You will see each executed action for it and at each step you can print any config variable, helping to understand where is the problem in routing logic or content of SIP message.

Another useful feature of debugger module is printing execution trace. Unlike break-pointing, execution trace functionality does not stop the SIP message processing, but writes log messages with informative details about executed actions, such as config file name, line and action name. Here is an example:

9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=501 a=17 n=if
9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=470 a=25 n=has_totag
9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=386 a=17 n=if
9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=379 a=26 n=is_method
9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=386 a=25 n=t_check_trans
9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=389 a=6 n=route
9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=643 a=3 n=return
9(6285) ERROR: *** cfgtrace: c=[/etc/kamailio/debugger.cfg] l=393 a=26 n=remove_hf 

This is quick and easy way to see the config actions execution path, from start to end.

Printing execution trace can be controlled at runtime, via RPC commands, without need to restart the SIP server, the admins being able to enable or disable it globally or per process.

Stay tuned for new posts of this series in the next days...

Siremis v1.0.1 Released

A new version of SIREMIS Web Management Interface for Kamailio (former OpenSER) and SIP Router is available as v1.0.1.

Siremis enables straightforward management of subscriber profiles, least cost routing and load balancing rules, communication at runtime with the SIP server, displays monitoring charts. You find detailed list of feature at:

http://siremis.asipto.com

v1.0.1 is a minor release, fixing issues discovered since releasing last version:

• replaced deprecated PHP functions such as split() and ereg()
• added missing column in LCR gateways
• set default page to home.php instead of login.php
• set default path to XMLRPC commands in configuration

Download and installation steps:

http://siremis.asipto.com/install/

Some screenshots specific for this version:
http://www.asipto.com/gallery/v/siremis/siremis_22.png.html
http://www.asipto.com/gallery/v/siremis/siremis_23.png.html
http://www.asipto.com/gallery/v/siremis/siremis_24.png.html

More screenshots:

http://www.asipto.com/gallery/v/siremis/

Demo site (it works on a database with random data, username: admin, password: admin):

http://siremis.asipto.com/demo/

A piece of history: 9 years SER

Today are 9 years since first source code commit of SIP Express Router (aka SER) happened. It started with following three commits reported by git-log:

git log --pretty=format:"%h%x09%an%x09%ad%x09%s" --reverse | head -3

512dcd9 Andrei Pelinescu-Onciul Mon Sep 3 21:27:11 2001 +0000 Initial revision
888ca09 Andrei Pelinescu-Onciul Tue Sep 4 01:41:39 2001 +0000 parser seems to work
e60a972 Andrei Pelinescu-Onciul Tue Sep 4 20:55:41 2001 +0000 First working release

Today, 3286 days later, it counts 14 200 commits only in development branch, estimated development cost over $8,000,000.

Some statistics about project evolution and development were made available on web site – click here to see them!

There are interesting facts about most productive time frames (i.e., hour, day, …), evolution of default configuration files, command line parameters, … IPv6 support is there since 2002, but no convenient public network to use it yet.

Enjoy and enhance the content as you have interesting aspects of history to add…

… and, VERY important, do not forget to start testing 3.1.0, we are in pre-release phase, there are a lot of new features you surely want on your production system:

http://sip-router.org/wiki/features/new-in-devel