Kamailio Advanced Training
Click here for more details!

Learn how to build RTC services with Kamailio!

Monday, December 28, 2009

Best of New in Kamailio 3.0.0 - #9: event_route

The event_route is offering a framework for developers to give script writers more control when special events happen. Unlike the other routing blocks which were designed to process SIP messages, the event_route can be triggered by a non-SIP-related event as well.

An example is event_route[htable:mod-init] which is executed by htable module when it is initialized. Practically, the event_route is executed once, when Kamailio (OpenSER) starts. The main goal for event_route[htable:mod-init] is to allow initializations at startup -- can be variables from htable or other modules.
...  
event_route[htable:mod-init] {
$sht(a=>x) = 1;
$shv(counter) = 0;
sql_query("insert into restarts (start_time) values ('$Tf')");
}
...

Another event_route is exported by tm module: event_route[tm:local-request] - which is executed when tm generates internally and sends a SIP request. Such cases are:
  • SIP messages sent by msilo module
  • SIP messages sent by presence server
  • SIP messages sent by dialog module
  • SIP messages sent via MI or CTL interfaces
Examples of usage:
  • log details about local request
  • account the local request
  • apply filters to local generated requests
...  
event_route[tm:local-request] {
xlog("request [$rm] from [$fu] to [$ru]\n");
}
...
Among the benefits of event_route:
  • new events can be exported and fired by any module
  • no need to extend the config grammar when adding a new event
  • various variables can be made available when the event is fired to be used inside the event_route
  • no need to have SIP message to be processed
For the future I expect several events to be added, for example:
  • when a location contact expires
  • timer-based events (rtimer module to migrate from using route to using event_route blocks)
  • when dialog module sends BYE on timeout
Next episode to be about: topology hiding module.

Wednesday, December 23, 2009

Best of New in Kamailio 3.0.0 - #8: onsend_route

Kamailio (OpenSER) 3.0.0 provides two new routing block types:
  • onsend_route - executed when a SIP request is sent to network
  • event_route - will be presented in the next post of this series
R-URI or routing headers might have domain names and the DNS resolver is hidden behind functions like t_relay() or forward(). Moreover, there is pretty quite complexity in selecting the next hop by strict or loose routing, outbound proxy address and R-URI address which tied with DNS failover made the options to get the destination address in config impossible with older versions.

The newly introduced onsend_route comes to fill the gap. The actions in this routing block are executed just before sending the message to network, meaning:
  • you get access to the buffer with the version of the SIP request that is sent
  • you get access to all attributes of destination address: address family, transport protocol, ip address and port.
A new set of pseudo-variables and keywords are made available:
  • $snd(name), where 'name' can be 'ip', 'af', 'port' or 'proto'- get access via PV to destination's ip address, address family, port or transport protocol. In addition to details of destination address, when name is 'buf' or 'len' you get access to content of output buffer and its length.
  • snd_ip, snd_af, snd_port, snd_proto - same as above about destination address, but implemented as config keywords
Not all functions exported by core or modules are available in onsend_route, however, you can drop the request, access message flags, use transformations over the output buffer and more. msg:len keyword returns the length of the message to be sent, not the length of original message.

The typical usage is to implement outgoing filtering, a good option to protect against DNS poisoning and malicious DNS records:
onsend_route {
if(isflagset(2) && $snd(ip)=="10.10.10.10"){
drop;
}
}

Tuesday, December 22, 2009

VUC Dec 2009: Kamailio - Asterisk

Alex Balashov of Evariste Systems, active community member and contributor of Kamailio (OpenSER), running a VoIP consultancy business in USA, leads a VoIP User Conference about Kamailio, the role of Asterisk, SER and media gateways, etc.

Among topics: relationship of Kamailio to OpenSER project history, what is Kamailio (OpenSER), SIP server (for certain purposes, such as registrar, presence user agent, etc.), common uses of Kamailio, service delivery platform engineering and Asterisk scaling using Kamailio, some discussion of sip-router.org initiative.

Almost 2 hours of recording, going from overview to deep technical concepts, I can even say, a great tutorial about Kamailio in some aspects.

Evariste Systems comes with a big bag of expertise about SIP and SIP Proxy, Kamailio (OpenSER) in particular, being one of the nominations for Kamailio (OpenSER) 2008 Awards and good candidate for 2009.

More details and the podcast available at:

http://www.voipusersconference.org/2009/asterisk-kamaillio/

Monday, December 21, 2009

Best of New in Kamailio 3.0.0 - #7: tls

The most important change, comparing to Kamailio (OpenSER) 1.5.x (or older), in regard to TLS is a new internal architecture - the core is no longer dependent of SSL libraries.

If in older versions, enabling TLS means to recompile everything, with TLS=1 flag for Makefile, in Kamailio (OpenSER) 3.0.0 TLS implementation is provided by a module, named tls.
  • no more two tarballs with sources of Kamailio
  • no more two sets of packages with Kamailio binaries
  • no more need to recompile everything every time when switching between no-TLS and TLS configs
  • compilation of TLS support as simple as compilation of any other module: make modules modules=modules/tls
Yes, now enabling TLS is as simple as just loading a module and configure it via modparam:
...
loadmodule "tls.so"
...
modparam("tls", "certificate", "/etc/kamailio/certificate.pem")
...

Coming as well with support for server name extension, another feature that worth to mention is the option for a dedicated config file for TLS parameters.

...
modparam("tls", "config", "etc/kamailio/tls.cfg")
...

Sample TLS config file:

[server:default]
method = TLSv1
verify_certificate = no
require_certificate = no
private_key = kamailio_key.pem
certificate = kamailio_cert.pem
ca_list = kamailio_ca.pem

[client:default]
verify_certificate = yes
require_certificate = yes

[server:10.0.0.10:5061]
method = SSLv23
verify_certificate = yes
require_certificate = no
private_key = privatenet_key.pem
certificate = privatenet_cert.pem
verify_depth = 3
ca_list = privatenet_ca.pem

[client:10.0.0.11:5061]
verify_certificate = no
certificate = peer_11_client.pem
private_key = peer_11_key.pem
ca_list = peer_11_ca.pem
Check the full list of available parameters for TLS module at:
http://kamailio.org/docs/modules/3.0.x/modules/tls.html

Moreover, the new architecture offers far better performances, as it is reusing lot of TCP enhancements, getting to tens of thousands TLS connections in a single SIP server is easier than ever.

Note that TLS was not updated to work in asynchronous mode, therefore when using TLS configure TCP in non-asynchronous mode (feature planned for next major release).

Next in this series: onsend_route.

Sunday, December 20, 2009

Best of New in Kamailio 3.0.0 - #6: asynchronous tcp

With increasing of instant messaging and presence traffic, ability to handle in a reliable and fast fashion the TCP processing in SIP networks became mandatory.

Thanks to Andrei Pelinescu-Onciul, the one that wrote the first (and the second, and the third, ...) line of code for SIP Express Router (SER) (of course that extends to Kamailio (OpenSER) or other variants), Kamailio 3.0.0 introduces asynchronous TCP processing, via sip-router.org core framework.

You can control synchronous/asynchronous TCP behaviour via global parameter tcp_async:
http://www.kamailio.org/dokuwiki/doku.php/core-cookbook:3.0.x#tcp_async

Shortly, asynchronous TCP means that Kamailio worker processes will not block in attempt to open a TCP connection or send a SIP message over a TCP connection. The TCP operations are pooled and handled by special processes, the SIP worker processes moving forward to deal with next SIP messages.

This is not the only improvement to TCP, practically TCP has been refurbished if you compare it with Kamailio 1.5.x or older. A lot of new parameters that help you tune TCP processing performances that came along with a better internal architecture:
http://www.kamailio.org/dokuwiki/doku.php/core-cookbook:3.0.x#tcp_parameters

Next post in this series will be about TLS improvements.

Saturday, December 19, 2009

Best of New in Kamailio 3.0.0 - #5: sercmd

Along with Kamailio (OpenSER) 3.0.0 you will get a command line interface: sercmd. Installed on same directory as kamailio binary, sercmd enables admins to connect to running instance of Kamailio, either on same or remote system.

First, you have to load the ctl module in your config, see module's readme:
http://kamailio.org/docs/modules/3.0.x/modules/ctl.html

If you use default configuration in the ctl module and sercmd, with kamailio on the same system, then just launch sercmd.

Among features:
  • command history
  • connection or single command mode
  • tab completion
  • double tab to list available options
  • execute all MI commands from Kamailio core and modules (module mi_rpc must be loaded)
  • execute RPC commands (core, tm and other modules)
  • over one hundred commands available from core and modules
  • change config variables during runtime (module cfg_rpc must be loaded)
  • option to format the output
  • connection to Kamailio via udp, tcp or unix sockets
  • help message for each command
For command line options, run: sercmd -h

Screenshots:
  • show available commands


  • list registered phones via MI


  • list TCP options via RPC



Next post to be about asynchronous tcp.

Friday, December 18, 2009

Best of New in Kamailio 3.0.0 - #4: cfg variables reload framework

Inherited from SIP Express Router (SER) via sip-router.org project, the cfg variables framework can be used by Kamailio 3.0.0 core and by the modules, to get and set internal variables on-the-fly, eliminating Kamailio restarts whenever it is possible. Such variables can be global or module parameters.

The operations with cfg variables can be done at any time without performance overhead. The framework makes sure that the variables do not change during the SIP message processing, the child processes see a snapshot of the variables with constant values. The variable that is changed will be automatically replaced by the framework the next time a SIP message is started to be processed.

The drivers can change the values of all the variables by names with or without the need of commit. That means a kind of transaction support, the framework can keep track of the changes (per driver) until they are committed or rolled-back.

New configuration values can be declared in the script, with following syntax :

group_name.var_name = value ['descr' description]

The values can be accessed via select calls:

@cfg_get.group_name.var_name

Example:

gateway.destination = "127.0.0.1" descr "IP addr of the gateway"
gateway.enabled = 1 descr "enable/disable the gateway"

route {
...
if (@cfg_get.gateway.enabled == 1) {
$du = "sip:"+ $sel(cfg_get.gateway.destination);
} else {
send_reply("404", "No gateway");
exit;
}


The cfg variables can be changed via control interface (e.g., xmlrpc) or using the new command line interface application (cli): sercmd.
sercmd cfg.set_now_int gateway enabled 0
Examples of what can be tuned via cfg variables framework:
  • tcp parameters (connect_timeout, send_timeout, connection_lifetime, asynchronous mode, keepalive, ...)
  • sctp parameters (autoclose, send_ttl, send_retries, ...)
  • dns parameters (dns_retr_time, dns_retr_no, ...)
  • other global parameters (debug, log_facility, memlog, force_rport, udp_mtu, ...) - see the cookbook for all tcp, sctp, dns and other global parameters
  • TM module parameters (fr_timer, fr_inv_timer, fr_inv_timer_next, auto_inv_100, auto_inv_100_reason, a.s.o.)
By using the cfg_db or cfg_rpc modules, values for those variables can be loaded from database or set via RPC control interface:

http://kamailio.org/docs/modules/3.0.x/modules/cfg_db.html
http://kamailio.org/docs/modules/3.0.x/modules/cfg_rpc.html

Next episode will be about sercmd.

Thursday, December 17, 2009

Best of New in Kamailio 3.0.0 - #3: route blocks with names

So far, the routing blocks defined in Kamailio (OpenSER) configuration file could get only integer IDs, for example:

route[10] {
$du = "sip:10.10.10.10";
t_relay();
exit;
}
That could make the big configs hard to understand after a while, when was need for troubleshooting or enhancements. It was a nightmare to check what route[24] was intended to do when you encountered the execution of it in another route.

In version 3.0.0, along with integer IDs, you can give string IDs to name the routes:

route[TO_ASTERISK] {
$du = "sip:10.10.10.10";
t_relay();
exit;
}
Previously, many people, including myself, used a text preprocessor like M4 to have string IDs for route names, but with some disadvantages: more files to manage (at least two m4 and one cfg), you had to edit all the time the m4 file, compile it with m4 in cfg, then the errors were reported by Kamailio relative to cfg file, resulting in mismatch of error's line number and the place you had to edit for fix.

However, the new embedded features with string names for routing blocks eliminates the restriction of up to 60 (40 in older versions) route blocks where the IDs must be in between 1 and 59. Instead of static array, the routing blocks are now in a hash table, allowing as many routing blocks as you need, with no constraints in naming.

Moreover, the string IDs can be used for any kind of routing block: route, failure_route, onreply_route, branch_route, ...

To call a route block, use the string name instead of integer ID:

route {
...
route(TO_ASTERISK);
...
}
The default configuration for Kamailio 3.0.0 uses this new feature: see it online .

Worth to mention that you can define now names for SIP message flags as well:

flags
FLAG_ACC : 1, # log in acc
FLAG_MISSED : 2; # log in missed_calls

...
route {
...
setflag(FLAG_ACC);
...
}
Next writing will be about new config parameters framework.

Wednesday, December 16, 2009

Best of New in Kamailio 3.0.0 - #2: define

The need of switching on or off features in Kamailio (OpenSER) 3.0.0 config file became more handy by addition of #!define directives support. There are five pre-processor directives:

#!define ID - define the ID
#!ifdef ID - test if ID is defined
#!ifndef ID - test if ID is not defined
#!else - create an else branch for ifdef/ifndef tests
#!endif - end an ifdef/ifndef block
Combining them, you can make parts of configuration file to be ignored at start time. For example, you can have in config a lot of xlog lines to help you troubleshooting, but you do not want them in a normal production environment. In your config you can have:

#!ifdef DEBUG_MODE
xlog("sip message from IP: $si and port $sp\r\n");
#!endif
To run in debug mode, add next line at the top of configuration file and then restart:

#!define DEBUG_MODE
For more examples, see Kamailio 3.0.0 default config file - authentication, NAT traversal, presence functionality, ... can be enabled or disabled via #!define.

Next to write about is route blocks with names.

Tuesday, December 15, 2009

Best of New in Kamailio 3.0.0 - #1: include file

I'm starting a series of posts, to highlight the best new features in Kamailio (OpenSER) 3.0.0, of course, from my point of view, hoping to cover most of them before full 3.0.0 is out (RC3 was done yesterday).

First one to write about is the include_file support. Over the time, with addition of new features, the config file got bigger and bigger. Being in consultancy business, I have hundreds of config files and deployments to maintain. In terms of structure, there are some parts repeating in most of configs, like:
  • sanity checks
  • authentication
  • nat traversal
  • presence handling, a.s.0.
Every time I did an improvement, I had to update in all configs. Now, using the include_file, maintenance is much easier. Practically, you can break down the config in many files and have the master config just including them. For example, split of sanity checks:

kamailio-sanity.cfg:

if (!mf_process_maxfwd_header("10")) {
sl_send_reply("483","Too Many Hops");
exit;
}
if ( msg:len >= 8192 ) {
sl_send_reply("513", "Message too big");
exit;
}
if ( is_method("NOTIFY") && uri==myself
&& $hdr(Event) =~ "keep-alive" )
{
sl_send_reply("200", "OK - keepalive");
exit;
}

Now, at the top of main route block in each config, I include the 'kamailio-sanity.cfg' file:

kamailio.cfg:

...
route {
include_file "kamailio-sanity.cfg"
...
}
...
Note that you can use include_file anywhere in your config file - included file must contain valid config statements for the part where is included (e.g., global parameters, modules loading, module parameters, routing actions, etc.).

Next is going to be about #!define support, which completes perfectly the include_file feature to ease the maintenance, troubleshooting and development of config files.

Monday, December 14, 2009

Kamailio v3.0.0-RC3

Kamailio v3.0.0-RC3 is out - last release candidate before full 3.0.0 major version - the tarball with sources of Kamailio 3.0.0 RC3 is available at:

http://www.kamailio.org/pub/kamailio/3.0.0-rc3/src/kamailio-3.0.0-rc3_src.tar.gz

Kamailio Logo

Lot of fixes to packaging, code and documentation have been committed since RC1, Kamailio 3.0.0-RC3 becoming ready for pre-production phase.

If you like to work with source, then use the tutorial guiding the installation of Kamailio 3.0 branch from GIT repository:
http://www.kamailio.org/dokuwiki/doku.php/install:kamailio-3.0.x-from-git

Two wiki pages were created to collect what is new in Kamailio 3.0 and how to migrate to this version:

http://www.kamailio.org/dokuwiki/doku.php/features:new-in-3.0.x

http://www.kamailio.org/dokuwiki/doku.php/install:1.5.x-to-3.0.0

Feel free to contribute to wiki pages, helping to build migration tutorials.

This is the last RC before full 3.0.0 relase. Please report any issue you find to sr-dev at lists.sip-router.org.

Wednesday, December 2, 2009

Daily tarballs for 3.0 branches

Thanks to Andrei, daily snapshots of sr_3.0, kamailio_3.0 and sr master branches can be downloaded from:

http://sip-router.org/tarballs/sr/

Note that new tarballs are generated only if there are changes for the corresponding branch (so if you don’t see a tarball with today’s date it means there was no change from the previous one).

The tarballs are generated via make tar, which makes sure the correct repository version will be included in the compiled binary (make tar generates first autover.h before creating the archive).