The post has been edited after publishing with updated content and Kamailio modules.
Kamailio® (successor of former OpenSER and SER) is an Open Source SIP Server released under GPLv2+, able to handle thousands of call setups per second. Kamailio can be used to build large platforms for VoIP and realtime communications – presence, WebRTC, Instant messaging and other applications. Moreover, it can be easily used for scaling up SIP-to-PSTN gateways, PBX systems or media servers like Asterisk™, FreeSWITCH™ or SEMS.
Kamailio follows RFC 3261 for SIP and can act as Registrar, Location server, Proxy, Redirect or event Application Server based on its configuration. The modular architecture of Kamailio enables extending the core functionality in various directions using modules.
There are over 150 modules in Kamailio dealing with add-on features that can be categorised into various functional areas such as
registrar and user location management
accounting, authorization and authentication
text and regular expression operations
stateless replying
stateful processing – SIP transaction management
Stateful
Stateless
stateful processing is per SIP transaction
Each SIP transaction will be kept in memory so that any replies, failures, or retransmissions can be recognized
Forwarding each msg in the dialog without any context.
Application understands the transactions , for example – recognize if a new INVITE message is a resend – know that 200 OK reponse belongs to the initial INVITE which it will be able to handle in an onreply_route[x] block.
it doesnt know that the call is on-going. However it can use callId to match INVITE and BYE.
Uses : manage call state , routing , call control like forward on busy, voicemail
Uses : Load distribution , proxying
SIP dialogs tracking – active calls management
instant messaging and presence extensions
RADIUS and LDAP support
SQL and no-SQL database connectors
MI and RPC transports
Enum, GeoIP API and CPL interpreter
topology hiding and NAT traversal
load balancing and least cost routing
asynchronous SIP request processing
interactive configuration file debugger
Lua, Perl, Python and Java SIP Servlet extensions
Routing a Call
A SIP server can either
direct the call and let the UA contact with each other directly or
force itself in the path by inserting a Route header in the SIP message (e record_route())
Kamailio provides a custom locking system its root element is a mutex semaphore, that can be set (locked) or unset (unlocked). The locking.h lib provides the functionality in C code.
A problem however with locks is that processes can eat a lot of CPU. Locking issues also occur when locks are set but not unset resulting in no more SIP messages being processed. Hence Kamailio uses gdb with PID and get backtraces to the lock that wasnt released .
Multliple processes run simultenously within kamailio server, hence it bears private and shared memeories to facailitate their working. One can increase shared memory using -m and private memory using -M command line option.
Private Memory
Shared Memory
Memeory is specific per process. No synchronization is needed to access structures allocated in it, such as varaibles not needed by other process or ones for temporary operations.
Private memory manager is accessed via mem/mem.h
The data stored in shared memeory is visible in all Kamailio modules such as, user location, TM structures for stateful processing, routing rules for the dispatcher etc.
Here locks are used to prvent race conditions.
Shared memeory can be acceses via mem/shm_mem.h.
pkg_malloc(…) pkg_free(…) pkg_realloc(…)
shm_malloc(…) shm_free(…) shm_realloc(…)
Problems in memory management can occur due to :
(-) Out of memory by allocating memory at runtime and not freeing it afterwards , called memory leaks
(-) writing more than allocated for that structure, called segmentation fault.
Since kamailio has a modular architecture with core components and modules to extend the functionality, this article will be discussing few of the essential modules in Kamailio. Specific modules Discussed in this Article :
UserLoc
Registrar
Dialog
UAC
XHTTP
Websocket
Few categories of modules discoverable via apt-cache search kamailio
kamailio – very fast and configurable SIP proxy
kamailio-autheph-modules – authentication using ephemeral credentials module for Kamailio
kamailio-berkeley-bin – Berkeley database module for Kamailio – helper program
kamailio-berkeley-modules – Berkeley database module for Kamailio
kamailio-carrierroute-modules – carrierroute module for Kamailio
kamailio-cnxcc-modules – cnxcc modules for Kamailio
kamailio-cpl-modules – CPL module (CPL interpreter engine) for Kamailio
kamailio-dbg – very fast and configurable SIP proxy [debug symbols]
kamailio-dnssec-modules – contains the dnssec module
kamailio-erlang-modules – earlang modules for Kamailio
kamailio-extra-modules – extra modules for Kamailio
kamailio-geoip-modules – contains the geoip module
kamailio-ims-modules – IMS module for Kamailio
kamailio-java-modules – contains the app_java module
kamailio-json-modules – Json parser and jsonrpc modules for Kamailio
kamailio-kazoo-modules – kazoo modules for Kamailio
kamailio-ldap-modules – LDAP modules for Kamailio
kamailio-lua-modules – contains the app_lua module
kamailio-memcached-modules – interface to memcached server
kamailio-mono-modules – contains the app_mono module
kamailio-mysql-modules – MySQL database connectivity module for Kamailio
kamailio-outbound-modules – Outbound module for Kamailio
kamailio-perl-modules – Perl extensions and database driver for Kamailio
kamailio-postgres-modules – PostgreSQL database connectivity module for Kamailio
kamailio-presence-modules – SIMPLE presence modules for Kamailio
kamailio-purple-modules – Provides the purple module, a multi-protocol IM gateway
kamailio-python-modules – contains the app_python module
kamailio-radius-modules – RADIUS modules for Kamailio
kamailio-redis-modules – Redis database connectivity module for Kamailio
kamailio-sctp-modules – sctp module for Kamailio
kamailio-snmpstats-modules – SNMP AgentX subagent module for Kamailio
kamailio-sqlite-modules – SQLite database connectivity module for Kamailio
kamailio-tls-modules – contains the TLS kamailio transport module
kamailio-unixodbc-modules – unixODBC database connectivity module for Kamailio
kamailio-utils-modules – Provides a set utility functions for Kamailio
kamailio-websocket-modules – Websocket module for kamailio
kamailio-xml-modules – XML based extensions for Kamailio’s Management Interface
kamailio-xmpp-modules – XMPP gateway module for Kamailio
The first set under explanation is Usrloc and Register module which take care of user persistance in Database and handling an incoming register request with authentication and validation.
The first set under explanation is Usrloc and Register module which take care of user persistance in Database and handling an incoming register request with authentication and validation.
We know that dialog represent the p2p relationship between 2 sip clients and contains sequence of transactions along with routing information and facilitate sequencing of more messages. Dialog module keeps track of current dialogs also provides API support. It can be loaded and used as
event_callback (str) – name of the function in the kemi configuration file (embedded scripting language such as Lua, Python, …) to be executed instead of event_route[…] blocks.
The callback function receives a string parameter with the name of the event, the values are: ‘dialog:start’, ‘dialog:end’, ‘dialog:failed’. It is also executed if ‘$dlg_ctx(timeout_route)’ is set
function ksr_dialog_event(evname)
KSR.info("===== dialog module triggered event: " .. evname .. "\n");
if (evname == "dialog:end") or (evname == "dialog:failed") then
logger.log("info", "in dialog event callback with event-name - " .. evname .. " start CDR process ")
if not cdrProcess.post() then
logger.log("err", "Failed")
else
logger.log("info", "successfully posted")
core.exit()
end
end
end
Provides basic HTTP/1.0 server functionality. SIP requires a Content-Length header for TCP transport. But most HTTP clients do not set the content length for normal GET requests. Therefore, the core must be configured to allow incoming requests without content length header:
tcp_accept_no_cl=yes
Parameters :
url_skip : if there is a match , event route is not executed modparam(“xhttp”, “url_skip”, “^/RPC2”)
url_match : if there is no match , event route is not executed modparam(“xhttp”, “url_match”, “^/sip/”)
event_Callback : function in the kemi configuration file (embedded scripting language such as Lua, Python) to be executed instead of event_route[xhttp:request] block
modparam("xhttp", "event_callback", "ksr_xhttp_event")
// and the event callback function implemented in Lua
function ksr_xhttp_event(evname)
KSR.info("===== xhttp module triggered event: " .. evname .. "\n");
return 1;
end
Function
xhttp_reply(code, reason, ctype, body) – Send back a reply with content-type and body.
This module provides websocket ( ws and wss) support to kamailio ( RFC 6455). Handles handshaking, management (including connection keep-alive), and framing for the SIP and MSRP WebSocket sub-protocols (RFC 7118 and RFC 7977).
Kamailio™ (former OpenSER) is an Open Source SIP Server released under GPL.
Kamailio primarily acts as a SIP server for VOIP and telecommunications platforms under various roles and can handle load of hight CPS ( Calls per second ) with custom call routing logic with the help of scripts.
Rich features set suiting to telephony domain that includes IMS extensions for VoLTE; ENUM; DID and least cost routing; load balancing; routing fail-over; Json and XMLRPC control interface, SNMP monitoring.
To integrate with a carrier grade telecom network as SBC / gateway / inbound/outbound proxy , it can act as IPv4-IPv6 gateway , UDP/TCP/SCTP/WS translator and even had NAT and anti DOS attack support .
If Kamailio is the central to the VoIP system it can also perform accounting with rich database extensions Mysql PostgreSQL UnixODBC Berkeley DB Oracle Redis, MongoDB Cassandra etc
Kamailio is SIP (RFC3261) compliant
It can work as Registrar or Location server. For SIP call logic it can become a Proxy or SIP Application server. Can also act like a Redirect, Dispatcher or simply a SIP over websocket server.
Customisable and Felxible
It can be embedded to devices as the binary file is small size. Additional modules can be appended for more functions with the same core.
Modular architecture – core, internal libraries , module interface and ability to extend functionality with scripts such as LUA, Kamailio can be readily integrated to a VOIP ecosystem.
Also NAT traversal support for SIP and RTP traffic ( suited to be WebRTC server ) . Read more about kamailio DNS subsystem management , load balancing , NAT and NAThelper modules in Kamailio DNS and NAT.
Among other features it offers load balancing with many distribution algorithms and failover support, flexible least cost routing , routing failover and replication for High Availability (HA).
Can be readily integrated with external databases, caches, notification system ( SNS , APNS , GCM ), VoIP monitors, CDR processors, API systems etc for efficient call processing.
Transport Layers supported
UDP, TCP, TLS and SCTP
IPv4 and IPv6
gateways via (IPv4 to IPv6, UDP to TLS, a.s.o.)
SCTP multi-homing and multi-streaming
WebSocket for WebRTC
Asynchronous TCP, UDP and SCTP
Asynchronous SIP message processing and inter-process message queues communication system
Secure Communication ( TLS + AAA)
Digest SIP User authentication
Authorization via ACL or group membership
IP and Network authentication
TLS support for SIP signaling
transparent handling of SRTP for secure audio
TLS domain name extension support
authentication and authorization against database (MySQL, PostgreSQL, UnixODBC, BerkeleyDB, Oracle, text files), RADIUS and DIAMETER
Kamailio Security here for snaity, ACL permission , firewall , flood detection , topology hiding and digests.
topology hiding – hide IP addresses in SIP headers to protect your network architecture
Accounting
Kamailio gives event based and configurable accounting data details. Can show multi-leg call accounting ( A leg to B leg ). It can store to database, Radius or Diameter based on module used . Has a prepaid engine.
External Interaction
text-based management interface via FIFO file, udp, xmlrpc and unix sockets.
RPC control interface – via XMLRPC, UDP or TCP
Rich Communication Services (RCS)
SIP SIMPLE Presence Server (rich presence)
Presence User Agent ( SUBSCRIBE , NOTIFY and PUBLSH)
XCAP client capabilities and Embedded XCAP Server
Presence DialogInfo support – SLA/BLA
Instant Messaging ( IM)
Embedded MSRP relay
Monitoring and Troubleshooting
Support for SNMP – interface to Simple Network Management Protocol. For Debugging it has config debugger , remote control via XMLRPC and error message logging system .Provides internal statistics exported via RPC and SNMP.
Extensibility APIs
The supported one are Perl , Java SIP Servlet Application Interface , Lua , Managed Code (C#) , Python.
(MySQL, PostgreSQL, SQLite, UnixODBC, BerkeleyDB, Oracle, text files) and other database types which have unixodbc drivers. ‘
It can have connections pool and different backends be used at same time (e.g., accounting to Oracle and authorization against MySQL).
Has connectors for Memcached, Redis , MongoDB and Cassandra no-SQL backends
Interconnectivity
Acts as SIP to PSTN gateway and gateway to sms or xmpp and other IM services. Has Interoperability with SIP enabled devices and applications such as SIP phones (Snom, Cisco, etc.), Media Servers (Asterisk, FreeSwitch, etc). More details on Kamailio as Inbound/Outbound proxy or Session Border Controller (SBC) here
Read RTP engine on kamailio SIP server which focuses on setting up sipwise rtpegine to proxy rtp traffic from kamailio app server. Also daemon and kernal modules. ,transcoding , in-kernel packet forwarding , ngcontrol protocol etc.
To validate and verify the location of kamillio use ‘which kamailio’ which returns /usr/sbin/kamailio
For Modules installation, check all avaible modules with command ‘apt search kamailio’and to install a new module such as websockt module use ‘apt install kamailio-websocket-modules’
Databaseaccess : After installaing kamailio , edit the kamailio.cfg file in /etc/kamailio to set the reachabe SIP domain, database engine, username/password etc to connect to databaseand enable the kamdbctl script to run and create users and tables, etc.
SIP_DOMAIN=kamailio.org
SIP_DOMAIN=17.3.4.5
chrooted directory
$CHROOT_DIR=”/path/to/chrooted/directory”
database type: MYSQL, PGSQL, ORACLE, DB_BERKELEY, DBTEXT, or SQLITE by default none is loaded
DBENGINE=MYSQL
Run kamdbctl to create users and database now
kamdbctl create
the database created is name kamailio and its tables are
The Kamailio configuration file for the control tools. Can set variables used in the kamctl and kamdbctl setup scripts. Per default all variables here are commented out, the control tools will use their internal default values. This file lets to edit SIP domain, the database engine, username/password/ to connect to database, etc.
## your SIP domain SIP_DOMAIN=1.1.1.1
## chrooted directory# $CHROOT_DIR="/path/to/chrooted/directory"## database type: MYSQL, PGSQL, ORACLE, DB_BERKELEY, DBTEXT, or SQLITE# by default none is loaded
# If you want to setup a database with kamdbctl, you must at least specify this parameter.
DBENGINE=MYSQL## database host# DBHOST=localhost# DBPORT=3306## database name (for ORACLE this is TNS name)# DBNAME=kamailio# database path used by dbtext, db_berkeley or sqlite# DB_PATH="/usr/local/etc/kamailio/dbtext"
database read/write user# DBRWUSER="kamailio"## password for database read/write user# DBRWPW="kamailiorw"
database read only user
# DBROUSER="kamailioro"## password for database read only user# DBROPW="kamailioro"## database access host (from where is kamctl used)# DBACCESSHOST=192.168.0.1
database super user (for ORACLE this is ‘scheme-creator’ user)
# DBROOTUSER="root"## password for database super user## - important: this is insecure, targeting the use only for automatic testing## - known to work for: mysql# DBROOTPW="dbrootpw"## database character set (used by MySQL when creating database)#CHARSET="latin1"## user name column# USERCOL="username"# SQL definitions# If you change this definitions here, then you must change them# in db/schema/entities.xml too.
# FIXME# FOREVER="2030-05-28 21:32:15"# DEFAULT_Q="1.0"# Program to calculate a message-digest fingerprint# MD5="md5sum"# awk tool# AWK="awk"# gdb tool# GDB="gdb"# If you use a system with a grep and egrep that is not 100% gnu grep compatible,# e.g. solaris, install the gnu grep (ggrep) and specify this below.grep tool# GREP="grep"# egrep tool# EGREP="egrep"# sed tool# SED="sed"# tail tool# LAST_LINE="tail -n 1"# expr tool# EXPR="expr"
Describe what additional tables to install. Valid values for the variables below are yes/no/ask. With ask (default) it will interactively ask the user for an answer, while yes/no allow for automated, unassisted installs.
#If to install tables for the modules in the EXTRA_MODULES variable.
# INSTALL_EXTRA_TABLES=ask# If to install presence related tables.# INSTALL_PRESENCE_TABLES=ask# If to install uid modules related tables.# INSTALL_DBUID_TABLES=ask
Define what module tables should be installed.
If you use the postgres database and want to change the installed tables, then you must also adjust the STANDARD_TABLES or EXTRA_TABLES variable accordingly in the kamdbctl.base script.
standard modules
# STANDARD_MODULES="
standard acc lcr domain group permissions registrar usrloc msiloalias_db uri_db speeddial avpops auth_db pdt dialog dispatcherdialplan"
extra modules
# EXTRA_MODULES="imc cpl siptrace domainpolicy carrierroute userblacklist htable purple sca"type of aliases used: DB - database aliases; UL - usrloc aliases- default: none , ALIASES_TYPE="DB"control engine: RPCFIFO
- default RPCFIFOCTLENGINE="RPCFIFO"## path to FIFO file for engine RPCFIFO# RPCFIFOPATH="/var/run/kamailio/kamailio_rpc_fifo"## check ACL names; default on (1); off (0)# VERIFY_ACL=1## ACL names-if VERIFY_ACL is set,only the ACL names from below list are accepted# ACL_GROUPS="local ld int voicemail free-pstn"## check if user exists (used by some commands such as acl);## - default on (1); off (0)# VERIFY_USER=1## verbose - debug purposes - default '0'# VERBOSE=1## do (1) or don't (0) store plaintext passwords## in the subscriber table - default '1'# STORE_PLAINTEXT_PW=0
Kamailio START Options
PID file path – default is: /var/run/kamailio/kamailio.pid
config files are used to customize and deploy SIP services since each and every SIP packet is route based on policies specified in conf file ( routing blocks ). Location when installed from source – /usr/local/etc/kamailio/kamailio.cfg , when installed from package – /etc/kamailio/kamailio.cfg
The features in config file :-
User authentication
Kamailio doesn’t have user authentication by default , so to enable it one must
#!define WITH_MYSQL
#!define WITH_AUTH
kamdbctl tool is to be used for creating and managing the database.
kamdbctl create
Kamctl is used for adding subscriber information and password.
kamctl add altanai1 123mysql: [Warning] Using a password on the command line interface can be insecure.MySQL password for user 'kamailio@localhost': mysql: [Warning] Using a password on the command line interface can be insecure.new user 'altanai1' added
More details in Tools section below .
IP authorization
accounting
registrar and location servicesTo have persisant location enabled so that records are not lost once kamailio are restarted , we need to save it to database and reload when restarting
#!define WITH_USRLOCDB
attacks detection and blocking (anti-flood protection)
NAT traversal
requires RTP proxy for RTP relay. NAT traversal support can be set by
#!define WITH_NAT
short dialing on server
multiple identities (aliases) for subscribers
multi-domain support
routing to a PSTN gateway
routing to a voicemail server
TLS encryption
instant messaging (pager mode with MESSAGE requests)
To enable IP authentication execute: enable mysql , enable authentication , define WITH_IPAUTH and add IP addresses with group id ‘1’ to ‘address’ table.
enable mysql
define WITH_MULTIDOMAIN
...
#!ifdef WITH_MULTIDOMAIN# - the value for 'use_domain' parameter
#!define MULTIDOMAIN 1
#!else
#!define MULTIDOMAIN 0
#!endif
To enable TLS support execute:
adjust CFGDIR/tls.cfg as needed
define WITH_TLS
To enable XMLRPC support :
define WITH_XMLRPC
adjust route[XMLRPC] for access policy
To enable anti-flood detection execute:
adjust pike and htable=>ipban settings as needed (default is block if more than 16 requests in 2 seconds and ban for 300 seconds)
define WITH_ANTIFLOOD
...
route[REQINIT] {
#!ifdef WITH_ANTIFLOOD
# flood detection from same IP and traffic ban
if(src_ip!=myself) {
if($sht(ipban=>$si)!=$null) {
# ip is already blocked
xdbg("request from blocked IP - $rm from $fu (IP:$si:$sp)\n");
exit;
}
if (!pike_check_req()) {
xlog("L_ALERT","ALERT: pike blocking $rm from $fu (IP:$si:$sp)\n");
$sht(ipban=>$si) = 1;
exit;
}
}
if($ua =~ "friendly-scanner") {
sl_send_reply("200", "OK");
exit;
}
#!endif
..
}
To block 3XX redirect replies execute:
define WITH_BLOCK3XX
To enable VoiceMail routing :
define WITH_VOICEMAIL
set the value of voicemail.srv_ip and adjust the value of voicemail.srv_port
ifdef WITH_VOICEMAIL
# VoiceMail Routing on offline, busy or no answer
# - by default Voicemail server IP is empty to avoid misrouting
voicemail.srv_ip = "" desc "VoiceMail IP Address"
voicemail.srv_port = "5060" desc "VoiceMail Port"
#!endif
To enhance accounting execute:
enable mysql
define WITH_ACCDB
add following columns to database
define WITH_MYSQL
define WITH_AUTH
define WITH_USRLOCDB
#!ifdef ACCDB_COMMENT
ALTER TABLE acc ADD COLUMN src_user VARCHAR(64) NOT NULL DEFAULT '';
ALTER TABLE acc ADD COLUMN src_domain VARCHAR(128) NOT NULL DEFAULT '';
ALTER TABLE acc ADD COLUMN src_ip varchar(64) NOT NULL default '';
ALTER TABLE acc ADD COLUMN dst_ouser VARCHAR(64) NOT NULL DEFAULT '';
ALTER TABLE acc ADD COLUMN dst_user VARCHAR(64) NOT NULL DEFAULT '';
ALTER TABLE acc ADD COLUMN dst_domain VARCHAR(128) NOT NULL DEFAULT '';
ALTER TABLE missed_calls ADD COLUMN src_user VARCHAR(64) NOT NULL DEFAULT '';
ALTER TABLE missed_calls ADD COLUMN src_domain VARCHAR(128) NOT NULL DEFAULT '';
ALTER TABLE missed_calls ADD COLUMN src_ip varchar(64) NOT NULL default '';
ALTER TABLE missed_calls ADD COLUMN dst_ouser VARCHAR(64) NOT NULL DEFAULT '';
ALTER TABLE missed_calls ADD COLUMN dst_user VARCHAR(64) NOT NULL DEFAULT '';
ALTER TABLE missed_calls ADD COLUMN dst_domain VARCHAR(128) NOT NULL DEFAULT '';
#!endif
Value defines – IDs used later in config #!ifdef WITH_MYSQL # – database URL – used to connect to database server by modules such # as: auth_db, acc, usrloc, a.s.o.
disable TCP (default on)
#disable_tcp=yes
enable_sctp = 0
disable the auto discovery of local aliases based on reverse DNS on IPs (default on)
#auto_aliases=no
add local domain aliases #alias=”sip.mydomain.com”
//port to listen
port=5060
#!ifdef WITH_TLS
enable_tls=yes
#!endif
Life time of TCP connection when there is no traffic – a bit higher than registration expires to cope with UA behind NAT
Modules Section
set paths to location of modules (to sources or installation folders)
----- mi_fifo params -----
#modparam("mi_fifo", "fifo_name", "/var/run/kamailio/kamailio_fifo")
----- ctl params -----
#modparam("ctl", "binrpc", "unix:/var/run/kamailio/kamailio_ctl")
----- tm params -----
# auto-discard branches from previous serial forking leg
modparam("tm", "failure_reply_mode", 3)
# default retransmission timeout: 30sec
modparam("tm", "fr_timer", 30000)
# default invite retransmission timeout after 1xx: 120sec
modparam("tm", "fr_inv_timer", 120000)
----- rr params -----
# set next param to 1 to add value to ;lr param (helps with some UAs)
modparam("rr", "enable_full_lr", 0)
# do not append from tag to the RR (no need for this script)
modparam("rr", "append_fromtag", 0)
registrar params
modparam("registrar", "method_filtering", 1)
/* uncomment the next line to disable parallel forking via location */
# modparam("registrar", "append_branches", 0)
/* uncomment the next line not to allow more than 10 contacts per AOR */
#modparam("registrar", "max_contacts", 10)
# max value for expires of registrations
modparam("registrar", "max_expires", 3600)
# set it to 1 to enable GRUU
modparam("registrar", "gruu_enabled", 0)
usrloc params – enable DB persistency for location entries
Note: leaving NAT pings turned off here as nathelper is <em>only</em> being used for WebSocket connections. NAT pings are not needed as WebSockets have their own keep-alives.
Routing Logic
Main SIP request routing logic processing of any incoming SIP request starts with this route . Read more on Kamailio Call routing and Control
request_route {
# per request initial checks
route(REQINIT);
#!ifdef WITH_WEBSOCKETS
if (nat_uac_test(64)) {
force_rport();
if (is_method("REGISTER")) {
fix_nated_register();
} else {
fix_nated_contact();
if (!add_contact_alias()) {
xlog("L_ERR", "Error aliasing contact \n");
sl_send_reply("400", "Bad Request");
exit;
}
}
}
#!endif
# NAT detection
route(NATDETECT);
# CANCEL processing
if (is_method("CANCEL")) {
if (t_check_trans()) {
route(RELAY);
}
exit;
}
# handle requests within SIP dialogs
route(WITHINDLG);
### only initial requests (no To tag)
# handle retransmissions
if(t_precheck_trans()) {
t_check_trans();
exit;
}
t_check_trans();
# authentication
route(AUTH);
# record routing for dialog forming requests (in case they are routed) - remove preloaded route headers
remove_hf("Route");
if (is_method("INVITE|SUBSCRIBE"))
record_route();
# account only INVITEs
if (is_method("INVITE")) {
setflag(FLT_ACC); # do accounting
}
# dispatch requests to foreign domains
route(SIPOUT);
### requests for my local domains
# handle presence related requests
route(PRESENCE);
# handle registrations
route(REGISTRAR);
if ($rU==$null) {
# request with no Username in RURI
sl_send_reply("484","Address Incomplete");
exit;
}
# dispatch destinations to PSTN
route(PSTN);
# user location service
route(LOCATION);
}
Wrapper for relaying requests
enable additional event routes for forwarded requests – serial forking, RTP relaying handling, a.s.o.
route[RELAY] {
if (is_method("INVITE|BYE|SUBSCRIBE|UPDATE")) {
if(!t_is_set("branch_route"))
t_on_branch("MANAGE_BRANCH");
}
if (is_method("INVITE|SUBSCRIBE|UPDATE")) {
if(!t_is_set("onreply_route"))
t_on_reply("MANAGE_REPLY");
}
if (is_method("INVITE")) {
if(!t_is_set("failure_route"))
t_on_failure("MANAGE_FAILURE");
}
if (!t_relay()) {
sl_reply_error();
}
exit;
}
Per SIP request initial checks
route[REQINIT] {
if (!mf_process_maxfwd_header("10")) {
sl_send_reply("483","Too Many Hops");
exit;
}
if(is_method("OPTIONS") && uri==myself &&; $rU==$null) {
sl_send_reply("200","Keepalive");
exit;
}
if(!sanity_check("1511", "7")) {
xlog("Malformed SIP message from $si:$sp\n");
exit;
}
}
Handle requests within SIP dialogs
sequential request withing a dialog should take the path determined by record-routing
route[WITHINDLG] {
if (!has_totag()) return;
if (has_totag()) {
if (loose_route()) {
#!ifdef WITH_WEBSOCKETS
if ($du == "") {
if (!handle_ruri_alias()) {
xlog("L_ERR", "Bad alias <$ru>\n");
sl_send_reply("400", "Bad Request");
exit;
}
}
#!endif
}
exit;
}
if (loose_route()) {
route(DLGURI);
if (is_method("BYE")) {
setflag(FLT_ACC); # do accounting ...
setflag(FLT_ACCFAILED); # ... even if the transaction fails
}
else if ( is_method("ACK") ) {
# ACK is forwarded statelessy
route(NATMANAGE);
}
else if ( is_method("NOTIFY") ) {
# Add Record-Route for in-dialog NOTIFY as per RFC 6665.
record_route();
}
route(RELAY);
exit;
}
if (is_method("SUBSCRIBE") && uri == myself) {
# in-dialog subscribe requests
route(PRESENCE);
exit;
}
if ( is_method("ACK") ) {
if ( t_check_trans() ) {
# no loose-route, but stateful ACK;
# must be an ACK after a 487
# or e.g. 404 from upstream server
route(RELAY);
exit;
} else {
# ACK without matching transaction ... ignore and discard
exit;
}
}
sl_send_reply("404","Not here");
exit;
}
Handle SIP registrations
tbd
User location service
route[LOCATION] {
#!ifdef WITH_SPEEDDIAL
# search for short dialing - 2-digit extension
if($rU=~"^[0-9][0-9]$")
if(sd_lookup("speed_dial"))
route(SIPOUT);
#!endif
#!ifdef WITH_ALIASDB
# search in DB-based aliases
if(alias_db_lookup("dbaliases"))
route(SIPOUT);
#!endif
$avp(oexten) = $rU;
if (!lookup("location")) {
$var(rc) = $rc;
route(TOVOICEMAIL);
t_newtran();
switch ($var(rc)) {
case -1:
case -3:
send_reply("404", "Not Found");
exit;
case -2:
send_reply("405", "Method Not Allowed");
exit;
}
}
# when routing via usrloc, log the missed calls also
if (is_method("INVITE")) {
setflag(FLT_ACCMISSED);
}
route(RELAY);
exit;
}
Presence processing
route[PRESENCE] {
if(!is_method("PUBLISH|SUBSCRIBE"))
return;
if(is_method("SUBSCRIBE") && $hdr(Event)=="message-summary") {
route(TOVOICEMAIL);
# returns here if no voicemail server is configured
sl_send_reply("404", "No voicemail service");
exit;
}
#!ifdef WITH_PRESENCE
if (!t_newtran()) {
sl_reply_error();
exit;
}
if(is_method("PUBLISH")) {
handle_publish();
t_release();
} else if(is_method("SUBSCRIBE")) {
handle_subscribe();
t_release();
}
exit;
#!endif
# if presence enabled, this part will not be executed
if (is_method("PUBLISH") || $rU==$null) {
sl_send_reply("404", "Not here");
exit;
}
return;
}
IP authorization and user authentication
route[AUTH] {
#!ifdef WITH_AUTH
#!ifdef WITH_IPAUTH
if((!is_method("REGISTER")) && allow_source_address()) {
# source IP allowed
return;
}
#!endif
if (is_method("REGISTER") || from_uri==myself)
{
# authenticate requests
if (!auth_check("$fd", "subscriber", "1")) {
auth_challenge("$fd", "0");
exit;
}
# user authenticated - remove auth header
if(!is_method("REGISTER|PUBLISH"))
consume_credentials();
}
# if caller is not local subscriber, then check if it calls
# a local destination, otherwise deny, not an open relay here
if (from_uri!=myself && uri!=myself) {
sl_send_reply("403","Not relaying");
exit;
}
#!endif
return;
}
failure_route[MANAGE_FAILURE] {
route(NATMANAGE);
if (t_is_canceled()) {
exit;
}
#!ifdef WITH_BLOCK3XX
# block call redirect based on 3xx replies.
if (t_check_status("3[0-9][0-9]")) {
t_reply("404","Not found");
exit;
}
#!endif
#!ifdef WITH_VOICEMAIL
# serial forking - route to voicemail on busy or no answer (timeout)
if (t_check_status("486|408")) {
$du = $null;
route(TOVOICEMAIL);
exit;
}
#!endif
}
Supports pseudo-variables to access and manage parts of the SIP messages and attributes specific to users and server. Transformations to modify existing pseudo-variables, accessing only the wanted parts of the information.
Already has over 1000 parameters, variables and functions exported to config file. Supports runtime update framework – to avoid restarting the SIP server when needing to change the config parameters.
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.
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.
Kamailio is a SIP server which does not play any role by itself in media transmission path. this behaviour leads to media packets having to attempt to stream peer to peer between caller and callee which in turn many a times causes them to get dropped in absence of NAT management
To ensure that media stream is proxied via an RTP proxy kamailio can use RTP proxy module combined with a RTP proxy.
This setup also provides other benefits such as controlling media media , security , Load balancing between many rtp proxies ,bridge signalling between multiple network interfaces etc.
RTP Proxy module
Used to proxy the media stream .
RTP proxies that can be used along with this module are:
rtpproxy_disable_tout – when rtp proxy is disabled then timeout till when it doesnt connect
rtpproxy_tout – timeout to wait for reply
rtpproxy_retr – num of retries after timeout
nortpproxy_str – sets the SDP attribute used by rtpproxy to mark the message’s SDP attachment with information that it have already been changed. Default value is
“a=nortpproxy:yes\r\n”
and others like
“a=sdpmangled:yes\r\n”
timeout_socket (string)
ice_candidate_priority_avp (string)
extra_id_pv (string)
db_url (string)
table_name (string)
rtp_inst_pvar (string)
Functions
set_rtp_proxy_set(setid) – Sets the Id of the rtpproxy set to be used for the next unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or rtpproxy_manage() command
rtpproxy_offer([flags [, ip_address]]) – to make the media pass through RTP the SDP is altered. Value of flag can be 1 – append first Via branch to Call-ID when sending command to rtpproxy. 2 – append second Via branch to Call-ID when sending command to rtpproxy. See flag ‘1’ for its meaning. 3 – behave like flag 1 is set for a request and like flag 2 is set for a reply a – flags that UA from which message is received doesn’t support symmetric RTP. (automatically sets the ‘r’ flag) b – append branch specific variable to Call-ID when sending command to rtpproxy l – force “lookup”, that is, only rewrite SDP when corresponding session already exists in the RTP proxy i, e – direction of the SIP message when rtpproxy is running in bridge mode. ‘i’ is internal network (LAN), ‘e’ is external network (WAN). Values ie , ei , ee and ii x – shortcut for using the “ie” or “ei”-flags, to do automatic bridging between IPv4 on the “internal network” and IPv6 on the “external network”. Differentiated by IP type in the SDP, e.g. a IPv4 Address will always call “ie” to the RTPProxy (IPv4(i) to IPv6(e)) and an IPv6Address will always call “ei” to the RTPProxy (IPv6(e) to IPv4(i)) f – instructs rtpproxy to ignore marks inserted by another rtpproxy in transit to indicate that the session is already gone through another proxy. Allows creating a chain of proxies r – IP address in SDP should be trusted. Without this flag, rtpproxy ignores address in the SDP and uses source address of the SIP message as media address which is passed to the RTP proxy o – flags that IP from the origin description (o=) should be also changed. c – flags to change the session-level SDP connection (c=) IP if media-description also includes connection information. w – flags that for the UA from which message is received, support symmetric RTP must be forced. zNN – perform re-packetization of RTP traffic coming from the UA which has sent the current message to increase or decrease payload size per each RTP packet forwarded if possible. The NN is the target payload size in ms, for the most codecs its value should be in 10ms increments, however for some codecs the increment could differ (e.g. 30ms for GSM or 20ms for G.723). ip_address denotes the address of new SDP
such as : rtpproxy_offer(“FRWOC+PS”) is rtpengine_offer(“force trust-address symmetric replace-origin replace-session-connection ICE=force RTP/SAVPF”);
route {
...
if (is_method("INVITE"))
{
if (has_body("application/sdp"))
{
if (rtpproxy_offer()) t_on_reply("1");
} else {
t_on_reply("2");
}
}
if (is_method("ACK") && has_body("application/sdp")) rtpproxy_answer();
...
}
onreply_route[1] {
if (has_body("application/sdp")) rtpproxy_answer();
}
onreply_route[2] {
if (has_body("application/sdp")) rtpproxy_offer();
}
rtpproxy_answer([flags [, ip_address]])- rewrite SDP to proxy media , it can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
rtpproxy_destroy([flags]) – tears down RTP proxy session for current call. Flags are , 1 – append first Via branch to Call-ID 2 – append second Via branch to Call-ID b – append branch specific variable to Call-ID t – do not include To tag to “delete” command to rtpproxy thus causing full call to be deleted
unforce_rtp_proxy()
rtpproxy_manage([flags [, ip_address]]) – Functionality is to use predfined logic for handling requests If INVITE with SDP, then do rtpproxy_offer() If INVITE with SDP, when the tm module is loaded, mark transaction with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for rtpproxy_answer() If ACK with SDP, then do rtpproxy_answer() If BYE or CANCEL, or called within a FAILURE_ROUTE[], then call unforce_rtpproxy(). If reply to INVITE with code >= 300 do unforce_rtpproxy() If reply with SDP to INVITE having code 1xx and 2xx, then do rtpproxy_answer() if the request had SDP or tm is not loaded, otherwise do rtpproxy_offer() This function can be used from ANY_ROUTE.
rtpproxy_stream2uac(prompt_name, count) – stream prompt/announcement pre-encoded with the makeann command. The uac/uas suffix selects who will hear the announcement relatively to the current transaction – UAC or UAS. Also used for music on hold (MOH). Params : prompt_name – path name of the prompt to stream count – number of times the prompt should be repeated. When count is -1, the streaming will be in loop indefinitely until the appropriate rtpproxy_stop_stream2xxx is issued. Example rtpproxy_stream2xxx usage
if (is_method("INVITE")) { rtpproxy_offer(); if (is_audio_on_hold()) { rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", "-1"); } else { rtpproxy_stop_stream2uas(); }; };
rtpproxy_stream2uas(prompt_name, count)
rtpproxy_stop_stream2uac()- Stop streaming of announcement/prompt/MOH
I hoped of making a SIP application Development environment a year back and worked towards it earnestly . Sadly I wasn’t able to complete the job yet I have decided to share a few things about it here .
Aim :
Develop a SCE ( Service Creation Environment ) to addresses all aspects of lifecycle of a Service, right from creation/development, orchestration, execution/delivery, Assurance and Migration/Upgrade of services.
Similar market products :
Open/cloud Rhino
Mobicents and Telestax
Limitations of open source/other market products:
Free versions of the Service Creation Environments do not offer High Availability.
High Cost of Deployment grade versions.
Solution Description
I propose a in-house Java based Service Creation Environment “SLC SCE”. The SLC SCE will enable creation of JAINSLEE based SIP services. It can be used to develop and deploy carrier-grade applications that use SS7 and IMS based protocols such as INAP, CAP, Diameter and SIP as well as IT / Web protocols such as HTTP and XML.
Benefits:
Service Agility
Significantly Lower price points
Open Standards eliminate Legacy SCP Lock-in
Timeline
Java-based service creation environment (SCE) – 1.5 Months
Graphical User Interface (GUI) and schematic representations to help in the design, maintenance and support of applications – 1.5 months
SIP Resource Adapter – 1 month
Architecture
Service Creation Environment (SCE) for SIP Applications
In essence it encompasses the idea of developing the following
SIP stack
Javascript API’s
Java Libraries for calling SIP stack
Eclipse plugin to work with the SIP application development process
Visual Interface to view the logic of application and possible errors / flaws
SDKs ( Service Development Kit) , which are development Environment themselves
Extra Effort required to put in to make the venture successful
Demo applications for basic SIP logic like Call screening , call rerouting .
tutorial to create , deploy and run application from scratch . Aimed at all sections ie web developer , telecom engineer , full stack developer etc .
Some opensource implementation on public repositories like Github , Google code , SourceForge
Perform active problem solving on Stackoverflow , CodeRanch , Google groups and other forums .
6. Build it with ant . For this go inside the application folder and run ant. Output will either be “failed to build “ or “build successfully” .
The ant command generates the war file from SIP servlet Web application .
7. Incase of successful build . Add the application to Weblogic web console install section and activate it.
I will demonstrate this process in step by step manner . First click on “ Lock and Edit “ Button on the left panel . Then goto Install button in the centre area and browser to the location of application war or sar we have build through ant ,
8. We can delete an application in exactly the same way . click on “ Lock and Edit “ Button on the left panel . Then goto the delete button after selecting the radio button alongside the application we want to delete.
8. For enhanced application building we can also refer to sample provided along with bea weblogic . file:///C:/bea/sipserver30/samples/sipserver/examples/src/index.html
It is supported on jdk1.5 hence the system’s environment variables must match. Otherwise in later stages deploying applications throw class version error.
We have already learned about Sip user agent and sip network server. SIP clients initiates a call and SIP server routes the call . Registrar is responsible for name resolution and user location. Sip proxy receives calls and send it to its destination or next hop.
Presence is user’s reachability and willingness to communicate its current status information . User subscribe to an event and receive notification . The components in presence are :
Sip was initially introduced as a signaling protocol but there were Lack of method to emulate constant communication and update status between entity Three more method was introduced namely – Publish , Subscribe and Notify
Subscribe request should be send by watchers to presence server. Presence agent should authenticate and send acknowledgement. State changes should be notified to subscriber. Agents should be able to allow or terminate subscription
Presence is a way to have sustained stateful communication. The SIP User agents can use presence service to know about others user’s online status . Presence deployment must confirm to security standards .
WebRTC is a disruptive techbology for the telephony and cloud based communication services . It will change the landscape and foster growth of new innovative VoIP services that will be device agnostic and future ready .
Role of SIP servers ?
SIP Server convert the SIP transport from WebSocket protocol to UDP, TCP or TLS which are supported by all legacy networks. It also facilitates the use of rich serves such as phonebook synchronisation , file sharing , oauth in client .
How does WebRTC Solution traverse through FireWalls ?
NAT traversal across Firewalls is achieved via TURN/STUN through ICE candidates gathering .Current ice_servers are : stun:stun.l.google.com:19302 and turn:user@numb.viagenie.ca
What audio and video codecs are supported by WebRTC client side alone ?
Without the role of Media Server WebRTC solution supports Opus , PCMA , PCMU for audio and VP8 for video call.
RTCBreaker if enabled provides a third party B2BUA agent that performs certain level of codec conversion to H.264, H.263, Theora or MP4V-ES for non WebRTC supported agents.
What video resolution is supported by WebRTC solution ?
The browser will try to find the best video size between max and min based on the camera capabilities.
We can also predefine the video size such as minWidth, minHeight, maxWidth, maxHeight.
What bandwidth is required to run WebRTC solution ?
We can set maximum audio and video bandwidth to use or use the browser’s ability to set it hy default at runtime . This will change the outgoing SDP to include a “b:AS=” attribute. Browser negotiates the right value using RTCP-REMB and congestion control.
List of Web based SIP clients
SIPML5 client by Dubango
Telestax WebRTC client
SIPJS with flash network support
JSSIP
MIT license
SIP phones in Ubuntu / Linux
SFL phone
Yate SIP phone
Linphone
There are ready made build of Linphone for Windows , Mac and Mobile
Aletrnatively one can also build the Linphone from source
[ 57%] Performing configure step for 'EP_ms2'
loading initial cache file /home/altanai/linphone-desktop/WORK/WORK/desktop//tmp/EP_ms2/EP_ms2-cache-RelWithDebInfo.cmake
CMake Error at CMakeLists.txt:322 (message):
Could not find a support sound driver API. Use -DENABLE_SOUND=NO if you
don't care about having sound.
Kamailio SIP server evolved from SER and OpenSER. Written in ANSI C , primarily it is an open source proxy SIP server. RFC 3261 compliant and has support for various Operating system to install and run on as alpine , centos , deb , fedora , freebsd , netbsd , obs , openbsd , opensuse , oracle , rhel , solaris so on .
With modular design it already has 150 + modules and can have third party addons like Databases , RTP engines etc. Anyone can contribute to extensions and modules read here. Also contains cmd line tool kamcmd , kamcli and Web management interface SIREMIS .
It has provisions for complex routing logic development through scripts and programming languages interpreter support.
Over the years kamailio as proven a key component of a “carrier-grade” SIP service delivery platform. Either as SBC interfacing internal softswitch with public internet and handling complex operation as NAT, auth , flood control, topology hiding etc or even as the core SIP Server handling RTP relay as well.
Module parameters For example considering for tm auto-discard branches from previous serial forking leg as failure_reply_mode ,30 sec as default retransmission timeout with 120 sec as invite retransmission timeout after 1xx
request_route {
route(REQINIT);
route(NATDETECT);
if (is_method("CANCEL"))
{
if (t_check_trans()) {
route(RELAY);
}
exit;
}
route(WITHINDLG);
t_check_trans();
route(AUTH);
if (is_method("INVITE|SUBSCRIBE"))
record_route();
route(SIPOUT);
route(PRESENCE);
route(REGISTRAR);
...
}
Custom event routes (callbacks/event handlers exposed by modules).
Code for programming languages and runtimes:
String transformations
Variables
Ephemeral/scratch-pad variables ($var(…))
Transaction-persistent variables ($avp(…)/$xavp(…)) , extended AVP like AVP ar attached to transactions and not messages .
Dialog-persistent variables ($dlg_var(…))
$var(rc) = $rc;
route(TOVOICEMAIL);
t_newtran();
switch ($var(rc)) {
case -1:
case -3:
send_reply("404", "Not Found");
exit;
case -2:
send_reply("405", "Method Not Allowed");
exit;
}
This article describes call routing config for Kamailio under following roles
SIP Proxy
Registrar
Accountant
Session border Controller
Kamailio as Proxy Server
Simple Kamailio configuration with basic features like alias , accounting , record routing , handling SIP requests like INVITE and its replies . Also failure and NAT handling . More samples of Kamailio config and call routing are at https://github.com/altanai/kamailioexamples
#!KAMAILIO
#Defined Values
!substdef "!MY_IP_ADDR!!g"
!substdef "!MY_EXTERNAL_IP!!g"
!substdef "!MY_UDP_PORT!!g"
!substdef "!MY_TCP_PORT!!g"
!substdef "!MY_UDP_ADDR!udp:MY_IP_ADDR:MY_UDP_PORT!g"
!substdef "!MY_TCP_ADDR!tcp:MY_IP_ADDR:MY_TCP_PORT!g"
!define MULTIDOMAIN 0
; - flags
; FLT_ - per transaction (message) flags
; FLB_ - per branch flags
!define FLT_ACC 1
!define FLT_ACCMISSED 2
!define FLT_ACCFAILED 3
!define FLT_NATS 5
!define FLB_NATB 6
!define FLB_NATSIPPING 7
# Global Parameters
; LOG Levels:3 = DBG, 2 = INFO, 1 = NOTICE, 0 = WARN, -1 = ERR
debug = 2
log_stderror = no
memdbg = 5
memlog = 5
log_facility = LOG_LOCAL0
log_prefix = "{$mt $hdr(CSeq) $ci} "
/* number of SIP routing processes */
children = 2
/* uncomment the next line to disable TCP (default on) */
disable_tcp = yes
/* uncomment the next line to disable the auto discovery of local aliases based on reverse DNS on IPs (default on) */
auto_aliases = no
/* add local domain aliases */
alias = "sip.mydomain.com"
/* listen addresses */
listen = udp:127.0.0.1:5060
listen = MY_UDP_ADDR advertise MY_EXTERNAL_IP:MY_UDP_PORT
listen = MY_TCP_ADDR advertise MY_EXTERNAL_IP:MY_TCP_PORT
# Modules Section
loadmodule "jsonrpcs.so"
loadmodule "kex.so"
loadmodule "corex.so"
loadmodule "tm.so"
loadmodule "tmx.so"
loadmodule "sl.so"
loadmodule "rr.so"
loadmodule "pv.so"
loadmodule "maxfwd.so"
loadmodule "textops.so"
loadmodule "siputils.so"
loadmodule "xlog.so"
loadmodule "sanity.so"
loadmodule "ctl.so"
loadmodule "cfg_rpc.so"
loadmodule "acc.so"
loadmodule "counters.so"
----------------- setting module-specific parameters --------------
----- jsonrpcs params -----
modparam("jsonrpcs", "pretty_format", 1)
/* set the path to RPC fifo control file */
modparam("jsonrpcs", "fifo_name", "/var/run/kamailio/kamailio_rpc.fifo")
/* set the path to RPC unix socket control file */
modparam("jsonrpcs", "dgram_socket", "/var/run/kamailio/kamailio_rpc.sock")
; ----- ctl params -----
/* set the path to RPC unix socket control file */
modparam("ctl", "binrpc", "unix:/var/run/kamailio/kamailio_ctl")
; ----- tm params -----
auto-discard branches from previous serial forking leg
modparam("tm", "failure_reply_mode", 3)
default retransmission timeout:30sec
modparam("tm", "fr_timer", 30000)
default invite retransmission timeout after 1xx:120sec
modparam("tm", "fr_inv_timer", 120000)
; ----- rr params -----
# set next param to 1 to add value to;lr param (helps with some UAs)
modparam("rr", "enable_full_lr", 0)
; do not append from tag to the RR (no need for this script)
modparam("rr", "append_fromtag", 0)
----- acc params -----
; /* what special events should be accounted ? / modparam("acc", "early_media", 0) modparam("acc", "report_ack", 0) modparam("acc", "report_cancels", 0) / by default ww do
; not adjust the direct of the sequential requests.
; if you enable this parameter, be sure the enable "append_fromtag"
; in "rr" module /
modparam("acc", "detect_direction", 0) / account triggers (flags) */
modparam("acc", "log_flag", FLT_ACC)
modparam("acc", "log_missed_flag", FLT_ACCMISSED)
modparam("acc", "log_extra",
"src_user=$fU;src_domain=$fd;src_ip=$si;"
"dst_ouser=$tU;dst_user=$rU;dst_domain=$rd")
modparam("acc", "failed_transaction_flag", FLT_ACCFAILED)
# Routing Logic
/* Main SIP request routing logic*/
request_route {
; per request initial checks
route(REQINIT);
; CANCEL processing
if (is_method("CANCEL")) {
if (t_check_trans()) {
route(RELAY);
}
exit;
}
; handle retransmissions
if (!is_method("ACK")) {
if (t_precheck_trans()) {
t_check_trans();
exit;
}
t_check_trans();
}
; handle requests within SIP dialogs
route(WITHINDLG);
; only initial requests (no To tag)
; record routing for dialog forming requests ( in case they are routed)
; - remove preloaded route headers
remove_hf("Route");
if (is_method("INVITE|SUBSCRIBE")) {
record_route();
}
; account only INVITEs
if (is_method("INVITE")) {
setflag(FLT_ACC); # do accounting
}
if ($rU==$null) {
# request with no Username in RURI
sl_send_reply("484", "Address Incomplete");
exit;
}
# update $du to set the destination address for proxying
$du = "sip:" + $rd + ":9";
route(RELAY);
exit;
}
# Wrapper for relaying requests
route[RELAY] {
if (is_method("INVITE|BYE|SUBSCRIBE|UPDATE")) {
if (!t_is_set("branch_route"))
t_on_branch("MANAGE_BRANCH");
}
if (is_method("INVITE|SUBSCRIBE|UPDATE")) {
if (!t_is_set("onreply_route"))
t_on_reply("MANAGE_REPLY");
}
if (is_method("INVITE")) {
if (!t_is_set("failure_route"))
t_on_failure("MANAGE_FAILURE");
}
if (!t_relay()) {
sl_reply_error();
}
exit;
}
#P er SIP request initial checks
route[REQINIT] {
if ($ua = ~ "friendly-scanner|sipcli|VaxSIPUserAgent") {
# sl_send_reply("200", "OK");
exit;
}
if (!mf_process_maxfwd_header("10")) {
sl_send_reply("483", "Too Many Hops");
exit;
}
if (is_method("OPTIONS") && uri==myself && $rU==$null) {
sl_send_reply("200", "Keepalive");
exit;
}
if (!sanity_check("1511", "7")) {
xlog("Malformed SIP message from $si:$sp\n");
exit;
}
}
# Handle requests within SIP dialogs
route[WITHINDLG] {
if (!has_totag())
return ;
if (loose_route()) {
if (is_method("BYE")) {
setflag(FLT_ACC); # do accounting ...
setflag(FLT_ACCFAILED); # ... even if the transaction fails
} else{
if (is_method("NOTIFY")) {
# Add Record-Route for in -dialog NOTIFY as per RFC 6665.
record_route();
}
route(RELAY);
exit;
}
}
if (is_method("ACK")) {
if (t_check_trans()) {
# no loose-route, but stateful ACK;
must be an ACK after a 487 or e.g. 404 from upstream server
route(RELAY);
exit;
} else {
# ACK without matching transaction, ignore and discard
exit;
}
}
sl_send_reply("404", "Not here"); exit;
#Manage outgoing branches
branch_route[MANAGE_BRANCH] {
xdbg("new branch [$T_branch_idx] to $ru\n");
}
--# Manage incoming replies
onreply_route[MANAGE_REPLY] {
xdbg("incoming reply\n");
}
--# Manage failure routing cases
failure_route[MANAGE_FAILURE] {
if (t_is_canceled()) exit;
}
creates the database support for many kamailio modules such as auth , location , dispatcher , permission etc
make sure you load a DB engine , during kamailio installation and configuration . It can be either done though make command or though modules.lst file
make include_modules="db_mysql" cfg
make all
make install
since json replaced all fifo command, ensure you do not get "json.h: No such file or directory” in server by install json either via libjson-c-dev or libjson-cpp-dev
apt-get install libjson-c-dev
For uuid/uuid.h: No such file or directory install
apt-get install uuid-dev
For libpq-fe.h: No such file or directory install
apt-get install libpq-dev
kamdbctl command list
kamdbctl create <db name or db_path, optional> ...(creates a new database)
kamdbctl drop <db name or db_path, optional> .....(!entirely deletes tables!)
kamdbctl reinit <db name or db_path, optional> ...(!entirely deletes and than re-creates tables!)
kamdbctl backup <file> ...........................(dumps current database to file)
kamdbctl restore <file> ..........................(restores tables from a file)
kamdbctl copy <new_db> ...........................(creates a new db from an existing one)
kamdbctl presence ................................(adds the presence related tables)
kamdbctl extra ...................................(adds the extra tables)
kamdbctl dbuid ...................................(adds the uid tables)
kamdbctl dbonly ..................................(creates empty database)
kamdbctl grant ...................................(grant privileges to database)
kamdbctl revoke ..................................(revoke privileges to database)
kamdbctl add-tables <gid> ........................(creates only tables groupped in gid)
if you want to manipulate database as other database user than
root, want to change database name from default value "kamailio",
or want to use other values for users and password, edit the
"config vars" section of the command kamdbctl.
kamdbctl pframework create .......................(creates a sample provisioning framework file)
For psql: received invalid response to SSL negotiation: [ ERROR: Creating database failed! errors . Remember for mysql the defaul port is 3306, but for psql it is 5432 . Hence make the change in /etc/kamailio/kamctlrc
database port
DBPORT=3306
DBPORT=5432
Kamctl
If kamctl isnt accessible from the machine installed with kamailio , just goto kamctl folder and compile it yourself . For example for me , I took the git pull of kamailio source code v 5.1.0 and went to util folder
cd /kamailio_source_code/utils/kamctl
make && make install
unix tool for interfacing with Kamailio using exported RPCs.
It uses binrpc (a proprietary protocol, designed for minimal packet size and
fast parsing) over a variety of transports (unix stream sockets, unix datagram
sockets, udp or tcp).
SIP is a widely adopted application layer protocol used in VoIP calls and confernecing applciations and in IMS architeture or pure packet switched networks .
Traditional SIP headers for Call setup are INVITE, ACK and teardown are CANCEL or BYE , however with more adoption newer methods specific to services were added such as :
MESSAGE Methods for Instant Message based services SUBSCRIBE, NOTIFY standardised by Event notification extension RFC 3856 PUBLISH to push presence information to the network
Outlining the SIP Requests and Responses in tables below,
Request Message
Request Message
Description
REGISTER
A Client use this message to register an address with a SIP server
INVITE
A User or Service use this message to let another user/service participate in a session. The body of this message would include a description of the session to which the callee is being invited.
ACK
This is used only for INVITE indicating that the client has received a final response to an INVITE request
CANCEL
This is used to cancel a pending request
BYE
A User Agent Client use this message to terminate the call
OPTIONS
This is used to query a server about its capabilities
Response Message
Code
Category
Description
1xx
Provisional
The request has been received and processing is continuing
2xx
Success
An ACK, to indicate that the action was successfully received, understood, and accepted.
3xx
Redirection
Further action is required to process this request
4xx
Client Error
The request contains bad syntax and cannot be fulfilled at this server
5xx
Server Error
The server failed to fulfill an apparently valid request
6xx
Global Failure
The request cannot be fulfilled at any server
SIP headers
Display names
From originators sipuri
CSeq or Command Sequence contains an integer and a method name. The CSeq number is incremented for each new request within a dialog and is a traditional sequence number.
Contact – SIP URI that represents a direct route to the originator usually composed of a username at a fully qualified domain name (FQDN) , also IP addresses are permitted. The Contact header field tells other elements where to send future requests.
Max-Forwards -to limit the number of hops a request can make on the way to its destination. It consists of an integer that is decremented by one at each hop.
Content-Length – an octet (byte) count of the message body.
Content-Disposition
describes how the message body or, for multipart messages, a message body part is to be interpreted by the UAC or UAS. It extends the MIME Content-Type
Disposition Types :
“session” – body part describes a session, for either calls or early (pre-call) media
“render” – body part should be displayed or otherwise rendered to the user.
“icon” – body part contains an image suitable as an iconic representation of the caller or callee
“alert” – body part contains information, such as an audio clip
Accept
Accept – acceptable formats like application/sdp or currency/dollars
Header field where proxy ACK BYE CAN INV OPT REG
Accept R - o - o m* o Accept 2xx - - - o m* o Accept 415 - c - c c c
An empty Accept header field means that no formats are acceptable.
Accept-Encoding
Accept-Encoding R - o - o o o Accept-Encoding 2xx - - - o m* o Accept-Encoding 415 - c - c c c
Accept-Language : languages for reason phrases, session descriptions, or status responses carried as message bodies in the response.
Accept-Language: da, en-gb;q=0.8, en;q=0.7
Accept-Language R - o - o o o
Accept-Language 2xx - - - o m* o
Accept-Language 415 - c - c c c
Tag globally unique and cryptographically random with at least 32 bits of randomness. identify a dialog, which is the combination of the Call-ID along with two tags ( from To and FROM headers )
Call-Id uniquely identify a session
contact – sip url alternative for direct routing
Encryption
Expires – when msg content is no longer valid
Mandatory SIP headers
INVITE sip:altanai@domain.comSIP/2.0
Via: SIP/2.0/UDP host.domain.com:5060
From: Bob
To: Altanai
Call-ID: 163784@host.domain.com
CSeq: 1 INVITE
Informational headers
Call-Info additional information for example, through a web page. The “card” parameter provides a business card, for example, in vCard [36] or LDIF [37] formats. Additional tokens can be registered using IANA
Priority indicates the urgency of the request as perceived by the client. can have the values “non-urgent”, “normal”, “urgent”, and “emergency”, but additional values can be defined elsewhere
Subject: A tornado is heading our way! Priority: emergency
or
Subject: Weekend plans Priority: non-urgent
Subject summary or indicates the nature of call
Subject: Need more boxes s: Tech Support
Supported enumerates all the extensions supported. can contain list of option tags, described
Supported: 100rel k: 100rel
Unsupported features not supported
Unsupported: foo
User-Agent information about the UAC originating the request.
User-Agent: Softphone Beta1.5
Organization conveys the name of the organization to which the SIP element issuing the request or response belongs.
Organization: AltanaiTelecom Co.
Warning additional information about the status of a response. List of warn-code
300 Incompatible network protocol:
301 Incompatible network address formats:
302 Incompatible transport protocol:
303 Incompatible bandwidth units:
304 Media type not available:
305 Incompatible media format:
306 Attribute not understood:
307 Session description parameter not understood:
330 Multicast not available:
331 Unicast not available:
370 Insufficient bandwidth:
399 Miscellaneous warning:
1xx and 2xx have been taken by HTTP/1.1.
Warning: 307 isi.edu “Session parameter ‘foo’ not understood” Warning: 301 isi.edu “Incompatible network address type ‘E.164′”
Authetication and Authorization related headers
Authentication-Info mutual authentication with HTTP Digest. A UAS MAY include this header field in a 2xx response to a request that was successfully authenticated using digest based on the Authorization header field.
limit the time period over which a stateful proxy must maintain state information. options
User agents must tear down the call after the expiration of the timer , or
aller can send re-INVITEs to refresh the timer, enabling a “keep alive” mechanism for SIP.
SDP (Session Description Protocol)
SIP can bear many kinds of MIME attachments , one such is SDP. It is a standard for protocol definition for exchange of media , metadata and other transport realted attributes between the particpants before establishing a VoIP call.
SDP session description is entirely textual using the ISO 10646 character set in UTF-8 encoding and described by application/SDP media type.
It should be noted that SDP itself does not incorporate a transport protocol and can be used with difference protocls like Session announcement proctols (SAP) , SIP , HTTP , Electronic MAIl MIME extension, RTSP etc.
In case of SIP SDP is encapsulated inside of SIP packet and use offer/answer model to convey information about media stream in multimedia session.
SDP body contains 2 parts : session based section starting with v= line and media bsesction starting with m= line Media and Transport Information can contain type of media like video, audio , transport protocol like RTP/UDP/IP, H.320 and format of the media such as H.261 video, MPEG video, etc.
Session Description in SDP
protocol version ( v= ) protocol version mostly version 0
sessionname ( s=) and session information ( i= ) session name is textual and can contain empty space or even s=- but must not be empty. Session infomration is optional textual information about the session
URI of description ( u = )
Email Address and Phone Number (“e=” and “p=”)
Both are optional free text string SHOULD be in the ISO-10646 character set with UTF-8 encoding
Nothe that if given the Phone numbers SHOULD follow international public telecommunication number specification ( ITU-T Recommendation E.164) and be preceded by a “+”. Spaces and hyphens may be used to split up a phone field to aid readability if desired.
Connection Data ( c= ) connection information — not required if included in all media in which media specific connecion data override overall session connection data
c= <net-type> <addr-type> <connection-address>
c=IN IP4 172.31.90.251
If the session is multicast, the connection address will be an IP multicast group address . TTL shoudl be present in IPv4 multicast address . If connection is unicast the address contains the unicast IP address of the expected data source or data relay or data sink .
Bandwidth ( b= ) interpreted as kilobits per second by default
b= <bwtype> : <bandwidth>
Encryption Keys ( k= ) Only is SDP is exchanged in secure and trusted channel, keys va be excahnged on this SDP field . Although this process is not recomended,
k= clear:< encryption key > k= base64:< encoded encryption key > k= uri:< URI to obtain key > k= prompt
Attributes ( a= )
extends the SDP with values like flags
a=inactive , a=sendonly , a=sendrecv , a=recvonly
Mapping the Encoder Spec from
a=rtpmap: < payload type > < encoding name >/ < clock rate > [/ ]
If the <stop-time> is set to zero, then the session is not bounded, though it will not become active until after the < start -time>. If the <start-time> is also zero, the session is regarded as permanent.
t=0 0
Repeat Times ( r= )
zero or more repeat times for scheduling a session
r= <repeat interval> <active duration> <offsets from start-time>
useful for scejduling session during transation to daylightv saving to standard time and vice versa
Media Description in SDP
For RTP, the default is that only the even-numbered ports are used for data with the corresponding one-higher odd ports used for the RTCP belonging to the RTP session
m= <media> <port> <proto> <fmt> …
m=audio 20098 RTP/AVP 0 101
will stream RTP on 20098 and RTCP on 20099
For multiple transport ports pairs of RTP , RTCP stream are specified
m= <media> <port>/ <number of ports> <proto> <fmt> …
m=audio 20098/2 RTP/AVP 0 101 will stream one pair on RTP 20098 , RTCP 20099 and RTP 20100 , RTCP 20101
If non-contiguous ports are required, they must be signalled using a separate attribute like example, “a=rtcp:”
Additioan SDP features : In addition to normal unicast sessions , SDP can also convery multicast group address for media on IP multicast session. Private (encryption of SDP ) or public session are not treated differently by SDP and they are entorely a function of implementing mechanism like SIP or SAP. Optiopnal SDP params include URI , Categorisation “a=cat:” , Internationalisation etc
Example 1 : Typical Audio call SIP INVITE showing SIP headers in blue and SDP in green below
INVITEnbspsip:01150259917040@x.x.x.x SIP/2.0
Via: SIP/2.0/UDP x.x.x.x:5060branch=z9hG4bK400fc6e6
From: "123456789" ltsip:123456789@x.x.x.xgttag=as42e2ecf6
To: ltsip:01150259917040@x.x.x.x.4gt
Contact: ltsip:123456789@x.x.x.x4gt
Call-ID: 2485823e63b290b47c042f20764d990a@x.x.x.x.x
CSeq: 102 INVITE
User-Agent:nbspMatrixSwitch
Date: Thu, 22 Dec 2005 18:38:28 GMT
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER
Content-Type: application/sdp
Content-Length: 268
v=0
o=root 14040 14040 IN IP4 x.x.x.x
s=session
c=IN IP4 x.x.x.x
t=0 0
m=audio 26784 RTP/AVP 0 8 18 101
a=rtpmap:0 PCMU/8000
a=rtpmap:8 PCMA/8000
a=rtpmap:18 G729/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=fmtp:18nbspannexb=no - - - -
c=* (connection information - optional if included at session-level)
b=* (bandwidth information)
a=* (zero or more media attribute lines)
The above SDP shows 4 supported media codecs on audio stream which are 0 PCMU , 8 PCMA , 18 G729 and finally 101 used for telephone events . It also shows RTP/AVP as RTP profile and does not contain any m=cideo line which shows that this endpoint does not want a video call , only an audio one.
Example 2 : Video Vall SIP invite from Linphone
SIP URI Params
Internet Assigned Number Authority (IANA) Universal Resource Identifier (URI) Parameter Registry defines URI params that can be sued along with SIP scheme
The aobve exmaple indicates that the request has to be compressed using SigComp
transport-param
SIP can use any network transport protocol. Parameter names are defined for UDP (RFC 768), TCP (RFC 761), and SCTP (RFC 2960). For a SIPS URI, the transport parameter MUST indicate a reliable transport.
The server address ( detsiantion address , port , transport ) to be contacted for this user, overriding any address derived from the host field.
Although discouraged , maddr URI param has been used as a simple form of loose source routing. It allows a URI to specify a proxy that must be traversed en-route to the destination.
ttl parameter determines the time-to-live value of the UDP multicast packet and MUST only be used if maddr is a multicast address and the transport protocol is UDP.
sip:alice@atlanta.com;maddr=239.255.255.1;ttl=15
cause param
“cause” EQUAL Status-Code ; 404 Unknown/Not available ; 486 User busy ; 408 No reply ; 302 Unconditional ; 487 Deflection during alerting ; 480 Deflection immediate response ; 503 Mobile subscriber not reachable ; 380 Service number translation RFC 8119 – Section 2
response that tells to its recipient that the associated request was received but result of the processing is not known yet which could be if the processing hasnt finished immediately. The sender must stop retransmitting the request upon reception of a provisional response.
100 Trying 180 Ringing : Triigers a local ringing at callers device 181 Call is Being Forwarded : Used before tranefering to another UA such as during forking or tranfer to voice mail Server
182 Queued
183 Session in Progress : conveys information . Headers field or SDP body has mor details about the call. Used in announcements and IVR + DTMF too by being followed by “Early media”.
199 Early Dialog Terminated
2xx—Successful Responses
final responses express result of the processing of the associated request and they terminate the transactions.
200 OK 202 Accepted 204 No Notification
3xx—Redirection Responses
Redirection response gives information about the user’s new location or an alternative service that the caller should try for the call. Used for cases when the server cant satisfy the call and wants the caller to try elsewhere . After this the caller is suppose to resend the request to the new location.
300 Multiple Choices 301 Moved Permanently 302 Moved Temporarily 305 Use Proxy 380 Alternative Service
4xx—Client Failure Responses
negative final responses indicating that the request couldn’t be processed due to callers fault , for reasons such as t contains bad syntax or cannot be fulfilled at that server.
400 Bad Request 401 Unauthorized 402 Payment Required 403 Forbidden 404 Not Found 405 Method Not Allowed 406 Not Acceptable 407 Proxy Authentication Required 408 Request Timeout 409 Conflict 410 Gone 411 Length Required 412 Conditional Request Failed 413 Request Entity Too Large 414 Request-URI Too Long 415 Unsupported Media Type 416 Unsupported URI Scheme 417 Unknown Resource-Priority 420 Bad Extension 421 Extension Required 422 Session Interval Too Small 423 Interval Too Brief 424 Bad Location Information 428 Use Identity Header 429 Provide Referrer Identity 430 Flow Failed 433 Anonymity Disallowed 436 Bad Identity-Info 437 Unsupported Certificate 438 Invalid Identity Header 439 First Hop Lacks Outbound Support 470 Consent Needed 480 Temporarily Unavailable 481 Call/Transaction Does Not Exist 482 Loop Detected. 483 Too Many Hops 484 Address Incomplete 485 Ambiguous 486 Busy Here 487 Request Terminated 488 Not Acceptable Here 489 Bad Event 491 Request Pending 493 Undecipherable 494 Security Agreement Required
5xx—Server Failure Responses
negative responses but indicating that fault is at server’s side for cases such as server cant or doesnt want to respond the the request.
500 Server Internal Error 501 Not Implemented 502 Bad Gateway 503 Service Unavailable 504 Server Time-out 505 Version Not Supported 513 Message Too Large 580 Precondition Failure
6xx—Global Failure Responses
request cannot be fulfilled at any server with definitive information
600 Busy Everywhere 603 Decline 604 Does Not Exist Anywhere 606 Not Acceptable
Mandatory SIP headers in SIP respone
SIP/2.0 200 OK
Via: SIP/2.0/UDP host.domain.com:5060
From: Bob<sip:bob@domain.com>
To: Altanai<sip:altanai@domain.com>
Call-ID: 163784@host.domain.com
CSeq: 1 INVITE
Via, From, To, Call-ID , and CSeq are copied exactly from request
3. UAS receives re-INVITE but waits for user intervention
UAS receives re-INVITE to add video , but instead of rejecting , it prompts user to permit.
So UAS provides a null IPaddress instead of setting the stream to ‘inactive’ because inactive streams still need to exchange RTP Control Protocol (RTCP) traffic
Later if user rejects the addition of the video stream. Consequently, the UAS sends an UPDATE request (6) setting the port of the video stream to zero in its offer.
Kamailio is basically only a transaction stateful proxy, without any dialog support built in. Here the TM module enables stateful processing of SIP transactions ( by maintaining state machine). State is a requirement for many complex logic such as accounting, forking, DNS resolution.
Although most of the Kamailio module related description is covered here, I wanted to keep a separate space to describe and explain how Kamailio handles transactions and in particular, the Transaction Module.
Note: This article has been updated many times to match v5.1 since v3.0 from when it was written, if u see and outdated content or deprecated functions, please point them out to me in the comments. If you are new to Kamailio, this post is probably not a good starting point for you, instead read more on Kamailio. It is a powerful open-source SIP server here and has a widespread application in telephony.
Kamailio can manage stateless replying as well as stateful processing – SIP transaction management. The difference between the two is below
Stateful
Stateless
stateful processing is per SIP transaction
Each SIP transaction will be kept in memory so that any replies, failures, or retransmissions can be recognized
Forwarding each msg in the dialog without any context.
Application understands the transactions , for example – recognize if a new INVITE message is a resend – know that 200 OK reponse belongs to the initial INVITE which it will be able to handle in an onreply_route[x] block.
it doesnt know that the call is on-going. However it can use callId to match INVITE and BYE.
Uses : manage call state , routing , call control like forward on busy, voicemail
Uses : Load distribution , proxying
Kamailio’s Transaction management
t_relay, t_relay_to_udp and t_relay_to_tcp are main functions to setup transaction state, absorb retransmissions from upstream, generate downstream retransmissions and correlate replies to requests in Kamailio.
Lifecycle of Transaction
Transactions lifecycle are controlled by various factors which includes reliable ( TCP) or non reliable transport, invite or non-invite transaction types etc. Transaction are terminated either by final response or when timers are fired, which control it.
ACK is considered part of INVITE trasnaction when non 2xx / negative final resposne is received , When 2xx final / positive response is recievd than ACK is not considered part of the transaction.
Memory Management in Transactions
Transaction Module copies clones of received SIP messages in shared memory. Non-TM functions operate over the received message in private memory. Therefore core operations ( like record_route) should not be called before settings the transaction state ( t_realy ) for state-fully processing a message.
An INVITE transaction will be kept in memory for maximum: max_inv_lifetime + fr_timer + wt_timer. While A non-INVITE transaction will be kept in memory for a maximum: max_noninv_lifetime + wt_timer.
Branches
A single SIP INVITE request may be forked to multiple destinations, all of which together is called destination sets and Individual elements within the destination sets are called branches. A transaction can have more than one branch. For example, during DNA failover, each failed DNS SRV destination can introduce a new branch.
Serial, Parallel and Combined Forking
By default Kamailio performs parallel forking sending msg to all destinations and waiting for a response, however it can also do serial ie send requests one by one and wait for response /timeout before sending next.
By use of priorities ( q value 0 – 1.0) , Kamailio can also intermix the forking technique ie describing priority oder for serial and same level for parallel . The destination uri are loaded using unctions t_load_contacts() and t_next_contacts().
modparam("tm", "contacts_avp", "tm_contacts");
modparam("tm", "contact_flows_avp", "tm_contact_flows");
request_route {
seturi("sip:a@example.com"); // lowest 0
append_branch("sip:b@example.com", "0.5"); // shoudl be in parallel with C
append_branch("sip:c@example.com", "0.5"); // shoudl be in parallel with B
append_branch("sip:d@example.com", "1.0"); // highest priority , should be tried first
t_load_contacts(); // load all branches as per q values, store them in AVP configured in modparam
t_next_contacts(); // takes AVP and extracts higher q value branch
t_relay();
break;
}
Code to terminate when no more branches are found ( -1 returned) and return the message upstream
failure_route["serial"]
{
if (!t_next_contacts()) {
exit;
}
t_on_failure("serial");
t_relay();
}
TM Module
t_relay, t_relay_to_udp and t_relay_to_tcp are main functions to setup transaction state, absorb retransmissions from upstream, generate downstream retransmissions and correlate replies to requests.
Memory
TM copies clones of received SIP messages in shared memory. non-TM functions operate over the received message in private memory. Therefore core operations ( like record_route) should ne called before settings the trasnaction state ( t_realy ) for statefully processing a message.
An INVITE transaction will be kept in memory for maximum: max_inv_lifetime + fr_timer + wt_timer. While A non-INVITE transaction will be kept in memory for a maximum: max_noninv_lifetime + wt_timer.
Parameters
Various parameters are used to fine tune how trsnactions are handled and timedout in kamailio. Note all timers are set in miliseconds notation.
fr_timer (integer) – timer hit when no final reply for a request or ACK for a negative INVITE reply arrives. Default 30000 ms (30 seconds).
fr_inv_timer (integer) – timer hit when no final reply for an INVITE arrives after a provisional message was received on branch. Default 120000 ms (120 seconds).
restart_fr_on_each_reply (integer) – restart fr_inv_timer fir INVITE transaction for each provisional reply. Otherwise it will be sreatred only for fisrt and then increasing provisonal replies. Turn it off in cases when dealing with bad UAs that continuously retransmit 180s, not allowing the transaction to timeout.
max_inv_lifetime (integer) – Maximum time an INVITE transaction is allowed to be active in a tansaction. It starts from the time trnsaction was created and after this timer is hit , transaction is moved to either wait state or in the final response retransmission state. Default 180000 ms (180 seconds )
max_noninv_lifetime (integer) – Maximum time a non-INVITE transaction is allowed to be active. default 32000 ms (32 seconds )
wt_timer (integer) – Time for which a transaction stays in memory to absorb delayed messages after it completed.
delete_timer (integer) – Time after which a to-be-deleted transaction currently ref-ed by a process will be tried to be deleted again. This is now obsolte and now transaction is deleted the moment it’s not referenced anymore.
Retry transmission timers
retr_timer1 (integer) – Initial retransmission period
retr_timer2 (integer) – Maximum retransmission period started increasingly from starts with retr_timer1 and stays constant after this
noisy_ctimer (integer) – if set, INVITE transactions that time-out (FR INV timer) will be always replied. Otherwise they will be quitely dropped without any 408 branch timeout resposne
auto_inv_100 (integer) – automatically send and 100 reply to INVITEs.
auto_inv_100_reason (string) – Set reason text of the automatically sent 100 to an INVITE.
aggregate_challenges (integer) – if more than one branch received a 401 or 407 as final response, then all the WWW-Authenticate and Proxy-Authenticate headers from all the 401 and 407 replies will be aggregated in a new final response.
Blacklist
blst_503 (integer) – reparse_invite=1.
blst_503_def_timeout (integer) – blacklist interval if no “Retry-After” header is present
blst_methods_add (unsigned integer) – Bitmap of method types that trigger blacklisting on transaction timeouts and by default INVITE triggers blacklisting only
blst_methods_lookup (unsigned integer) – Bitmap of method types that are looked-up in the blacklist before being forwarded statefully. For default only applied to BYE.
Reparse
reparse_invite (integer) – set if CANCEL and negative ACK requests are to be constructed from the INVITE message ( same record-set etc as INVITE ) which was sent out instead of building them from the received request.
reparse_on_dns_failover (integer) – SIP message after a DNS failover is constructed from the outgoing message buffer of the failed branch instead of from the received request.
ac_extra_hdrs (string) – Header fields prefixed by this parameter value are included in the CANCEL and negative ACK messages if they were present in the outgoing INVITE. Can be only used with reparse_invite=1.
on_sl_reply (string) – Sets reply route block, to which control is passed when a reply is received that has no associated transaction.
modparam("tm", "on_sl_reply", "stateless_replies")
...
onreply_route["stateless_replies"] {
// return 0 if do not allow stateless replies to be forwarded
return 1; // will pass to core for stateless forwading
}
xavp_contact (string) – name of XAVP storing the attributes per contact.
contacts_avp (string) – name of an XAVP that stores names of destination sets. Used by t_load_contacts() and t_next_contacts() for forking branches
contact_flows_avp (string) – name of an XAVP that were skipped
fr_timer_avp (string) – override teh value of fr_timer on per transactio basis , outdated
cancel_b_method (integer) – method to CANCEL an unreplied transaction branch. Params :
0 will immediately stop the request (INVITE) retransmission on the branch so that unrpelied branches will be terminated
1 will keep retransmitting the request on unreplied branches.
2 end and retransmit CANCEL even on unreplied branches, stopping the request retransmissions.
unmatched_cancel (string) – sets how to forward CANCELs that do not match any transaction. Params :
0 statefully
1 statelessly
2 dropping them
ruri_matching (integer) – try to match the request URI when doing SIP 1.0 transaction matching as older SIP didnt have via cookies as in RFC 3261
via1_matching (integer) – match the topmost “Via” header when doing SIP 1.0 transaction matching
callid_matching (integer) – match the callid when doing transaction matching.
pass_provisional_replies (integer)
default_code (integer) – Default response code sent by t_reply() ( 500 )
default_reason (string) – Default SIP reason phrase sent by t_reply() ( “Server Internal Error” )
disable_6xx_block (integer)- treat all the 6xx replies like normal replies. However according to RFC receiving a 6xx will cancel all the running parallel branches, will stop DNS failover and forking.
local_ack_mode (integer) – where locally generated ACKs for 2xx replies to local transactions are sent. Params :
0 – the ACK destination is choosen according next hop in contact and the route set and then DNS resolution is used on it
1 – the ACK is sent to the same address as the corresponding INVITE branch
2 – the ACK is sent to the source of the 2xx reply.
failure_reply_mode (integer) – how branches are managed and replies are selected for failure_route handling. Params :
0 – all branches are kept
1 – all branches are discarded
2 – only the branches of previous leg of serial forking are discarded
3 – all previous branches are discarded
if you dont want to drop all branches then use t_drop_replies() to sleectively drop
faked_reply_prio (integer) – how branch selection is done.
local_cancel_reason (boolean) – add reason headers for CANCELs generated due to receiving a final reply.
e2e_cancel_reason (boolean) – add reason headers for CANCELs generated due to receiving a CANCEL
remap_503_500 (boolean) – conversion of 503 response code to 500. RFC requirnment.
failure_exec_mode (boolean) – Add local failed branches in timer to be considered for failure routing blocks.
dns_reuse_rcv_socket (boolean) – reuse of the receive socket for additional branches added by DNS failover.
event_callback (str) – function in the kemi configuration file (embedded scripting language such as Lua, Python, …) to be executed instead of event_route[tm:local-request] block. The function recives a string param with name of the event.
modparam("tm", "event_callback", "ksr_tm_event")
...
function ksr_tm_event(evname)
KSR.info("===== TM module triggered event: " .. evname .. "\n");
return 1;
end
relay_100 (str) – whether or not a SIP 100 response is proxied. not valid behavior when operating in stateful mode and only useful when in stateless mode
rich_redirect (int) – to add branch info in 3xx class reply. Params : 0 – no extra info is added (default) 1 – include branch flags as contact header parameter 2 – include path as contact uri Route header
Functions
These functions are operational blocks and route handlers for trsnactions handling in kamailio
t_relay([host, port]) – Relay a message statefully. Exmaple to show if t_relay fails, atleast send a reply to UAC statelessly to not keep it waiting
if (!t_relay())
{
sl_reply_error();
break;
};
t_relay_to_udp([ip, port]) / t_relay_to_tcp([ip, port]) – same as above, relay a message statefully but using specific protocol
if (some_conditon)
t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
else
t_relay_to_tcp(); # relay to msg. uri, but over tcp
t_relay_to_tls([ip, port])
t_relay_to_sctp([ip, port])
t_on_failure(failure_route) – on route block for failure management on a branch when a negative reply is recived to transaction. here uri is reset to value which it had on relaying.
t_on_branch_failure(branch_failure_route) – controls when negative response come for a transacion. here uri is reset to value which it had on relaying.
t_on_reply(onreply_route) – gets control when a reply from transaction is received
t_on_branch(branch_route) – control is passed after forking (when a new branch is created)
t_newtran() – Creates a new transaction
t_reply(code, reason_phrase) – Sends a stateful reply after a transaction has been established.
t_send_reply(code, reason)
t_lookup_request() – Checks if a transaction exists
t_retransmit_reply()
t_release() – Remove transaction from memory
t_forward_nonack([ip, port]) – forward a non-ACK request statefully
t_set_fr(fr_inv_timeout [, fr_timeout]) – Sets the fr_inv_timeout
t_reset_fr()
t_set_max_lifetime(inv_lifetime, noninv_lifetime) – Sets the maximum lifetime for the current INVITE or non-INVITE transaction, or for transactions created during the same script invocation
t_reset_max_lifetime()
t_set_retr(retr_t1_interval, retr_t2_interval) – Sets the retr_t1_interval and retr_t2_interval for the current transaction
t_reset_retr()
t_set_auto_inv_100(0|1) – switch automatically sending 100 replies to INVITEs on/off on a per transaction basis
t_branch_timeout() – Returns true if the failure route is executed for a branch that did timeout.
t_branch_replied()
t_any_timeout()
t_any_replied()
t_grep_status(“code”)
t_is_canceled()
t_is_expired()
t_relay_cancel()
t_lookup_cancel([1])
t_drop_replies([mode])
t_save_lumps()
t_load_contacts()
t_next_contacts()
t_next_contact_flow()
t_check_status(re)
t_check_trans() – check if a message belongs or is related to a transaction.
t_set_disable_6xx(0|1)
t_set_disable_failover(0|1)
t_set_disable_internal_reply(0|1)
t_replicate([params]) – Replicate the SIP request to a specific address.
t_relay_to(proxy, flags) – KSR.tm.t_relay()
t_set_no_e2e_cancel_reason(0|1)
t_is_set(target) – KEMI – KSR.tm.t_is_set() Return true if the attribute specified by ‘target’ is set for transaction. Target can be branch_route , failure_route and onreply_route.
if not(KSR.tm.t_is_set("branch_route")>0) then
core.set_branch_route("ksr_branch_manage");
end
if not(KSR.tm.t_is_set("onreply_route")>0) then
core.set_reply_route("ksr_onreply_manage");
end
if not(KSR.tm.t_is_set("failure_route")>0) and (req_method == "INVITE") then
core.set_failure_route("ksr_failure_manage");
end
t_get_status_code() – Return the status code for transaction or -1 in case of error or no status code was set.
Snippetto demo stateful handling of trsansactions
Yhis program is designed to accept all Register with 200 OK and create a new transaction. Does a check for username altanai. After the check cutom message hello is replied and any other username is printed a different rejection reply.
# ------------------ module loading ----------------------------------
loadmodule "tm.so"
route{
# for testing purposes, simply okay all REGISTERs
if (method=="REGISTER") {
log("REGISTER");
sl_send_reply("200", "ok");
break;
};
# create transaction state with t_newtran(); abort if error occurred
if (t_newtran()){
log("New Transaction created");
}
else {
sl_reply_error();
break;
};
log(1, "New Transaction Arrived\n");
# add a check for matching username to print a cutom message with t_reply()
if (uri=~"altanai@") {
if (!t_reply("409", "Well , hello altanai !")) {
sl_reply_error();
};
} else {
if (!t_reply("699", "Do not proceed with this one")) {
sl_reply_error();
};
};
}
For the past few weeks, I’ve been trying to find the answer to this one. After much information gathering, I understood that majority of communication platform provider’s mostly OTT such as iMessage from apple, RBM(RCS Business Messaging) already supports these features. And it is partially a term coined by Google to bring smart communication features in Android and other smartphones. In essence, RCSe is a part of the broader IMS architecture published by GSMA.
Update: after 2019 plenty of carriers also already provide RCSe as a replacement for SMS. OEM providers like Samsung also have RCS feature inbuild in phones.
Rich Communications should be viewed as technology upgrade that will transition SMS and voice capabilities from Circuit Switched technologies into the all-IP world, including VoLTE. RCS and VoLTE are build over IMS technology. The RCS wil benifit from Standardization of the technical environment, shared by all industry players, to offer these services on a wide range of handsets
The Rich Communication Services programme is a global initiative to deploy inter-operator services within an industry ecosystem. Marketed by the GSMA under the brand name joyn, RCS is an upgrade that marks the transition of messaging and voice capabilities from Circuit Switched technology to an all-IP world.Wider and large scale IMS deployment, interoperability between different terminal vendor RCS clients and RCS service interworking between operators are the key aims of the RCS Initiative.
In the face of new and innovative over the top messaging applications, mobile operators are experiencing declining SMS usage. With the launch of WiFi and VoIP enabled voice calling applications, similar declines in voice revenues are increasing, RCS presents and opportunity for telecom providers to rebrand their messaging solutions as a better product to compete against the growing influence of “Over-The-Top” (OTT) communications services providers.
Enhanced Phonebook: service capabilities and enhanced contacts information such as presence and service discovery.
Enhanced Messaging: enables a large variety of messaging options including chat, emoticons, location share and file sharing.
Enriched Calls: enables multimedia content sharing during a voice call, video call and video sharing (see what I see).
Rich Communication Suite (RCS) and RCS-e aim to seamlessly unify the communications experience by integrating traditional mobile telephony with new interactive services such as presence, instant messaging and content sharing enabled by the enhanced address book of the mobile phone. RCS leverages the 3GPP IMS architecture and uses SIP signalling to establish sessions to exchange instant messages, presence information, video and files
Five releases of the RCS specifications have been made to date. Each release expanded the scope of its predecessor.
Release 1 : Offered the first definitions for the enrichment of voice and chat with content sharing, driven from an RCS enhanced address book.
Release 2 : Added broadband access to RCS features: enhancing the messaging and enabling sharing of files.
Release3: Focused on the broadband device as a primary device.
Release4: Included support for LTE.
Release5: The most recent release, global interoperability is a key aspect of these specifications.
As the team developed a web client for making and receiving SIP calls over websockets through a proxy SIP server , I felt its an achievement big enough. To integrate it with RCS ( Rich Communication Suite ) stack appeared as a very complicated job .
I began by adding RCS specific standards modules one by one instead of importing the whole stack / library all together. The modules for XCAP for buddylist, MSRP for file transfer, geolocation mapping , cloud sync of phonebook and message book have begun taking shape . In essence following features set are expected out of a RCS enabled Client ( short outline ) Provisioning
OAUTH integration with operator customer portal
RCS HTTP Auto-Configuration
Manual IMS credentials, typically reserved for testing / troubleshooting
Pblished under Joyn in GSMS RDC Developer documents. There are many individual RCS APIs available. Brief details are as follows.
1. Log user in and out of the RCS server : Allows address book contacts to receive periodic updates of user availability for chat, file transfer and other services. This is essential for use of the RCS services.
2. Subscribe application to server-originated notifications :This is one of the most important aspects of RCS as events are asynchronous; the notifications channel is used by your application to know how an API call is proceeding and to receive updates from other users such as messages, files and status updates. You can subscribe to certain types of notifications if your application is focused on particular RCS services.
3. Network address book access and management : RCS provides each registered user with a server managed address book. Though the other APIs are not restricted to contacts in the network address book this makes it much more convenient to connect with other users. The network address book can have contacts added, removed, attributes changed, and is available to any application the user signs in to.
4. Chat API : Unlike SMS, which is broadly a ‘fire and forget’ service, the RCS chat services allow much more sophisticated messaging services to be built. Depending on user configuration you can check out whether the user has received the message, and displayed it.
RCS chat also allows feedback to other parties when a user is composing a message. There are also group chat services allowing multiple parties to collaboratively message. RCS provides API features for setting up a group chat session, adding or removing chat participants.
5. File Transfer : These APIs allow applications to send content between users – whether this is a picture or a document, and whether it is stored originally on the user’s device or elsewhere located on the Internet. They allow the recipient to receive information about the file separately from the file itself so the recipient can choose whether or not to accept the file.
6. User capabilities API : Enables the application to retrieve and amend system managed common capabilities of the user.
At this stage I will also put in a bit more about RCSe.
RCS-enhanced (RCS-e) is the currently available version of RCS, developed to speed time to market. It offers enhanced features such as instant messaging, live video sharing, and file transfer across any device on any network operator
Focus on advanced communication chat , file transfer , video sharing
Easy to Use zero touch from end user perspective minimal setup for subscribers Interoperability across devices , infrastructure components and service providers
Low barrier to entry / simplify networks Capability discovery using SIP OPTIONS Less impact on network elements and handset battery Lack of presence server reduces cost and time to market
Universal Allows implementation in lower range devices One common device specification
RCS-e (1.2.2) : RCS-e defined the initial IM/Chat functionality, File transfer, Image Share and Video share functionality over mobile packet switched networks, trusted and untrusted broadband networks. It has gained wide acceptance in Europe as an initial deployment to be followed by future deployment phases.
RCS 5.0 is completely backward compatible with V1.2.2 specifications and adds new features such as best efforts IP video calls, Geo-location exchange, Social Presence, Standalone Messaging, and a network based blacklist. Global interoperability is a key aspect of these specifications, and as a result this version supports both OMA CPM and OMA SIMPLE IM, which are more widely requested in North America.
RCS 5.1 is also backward compatible with the V1.2.2 and 5.0 specifications. It introduces additional new features such as Group Chat Store & Forward, File Transfer in Group Chat, File Transfer Store & Forward, and Best Effort Voice Call.
WebRTC Communication Client can meet the requiremnets of RCS and serve as a telco based platform for using TSP backened network to provide call and messaging to web users.
REST and SOAP Based Client Integration with RCS features like MSRP, XCAP Cloud Hosted Solution Technical Expertise in HTML5,J2EE,SIP,WebRTC & IMS
Integrated charging: Users already have mobile service. WebRTC with session-based charging can be added onto existing service plans.
Bundling: Messaging APIs can augment WebRTC apps with RCS and other messaging services developers Already know and implement.
Reliability: QoS can provide assurance to users and priority services (enterprise, emergency, law enforcement, eHealth) that a WebRTC service will work as well as they need it to.
RCS solution is required to bear its Net-Net session border controller (SBC) deployed at the access border of the SIP or IMS service network. SBC should provide critical control functions to deliver interactive communications services—voice, video and multimedia sessions—over the IP 3G RAN.
RCS oenapi ( GSMA ) – registered with developer license to use the non commercially API’s , attempts to run the same http://rcs.oneapi-gw.gsma.com/
Challenges in RCS intergration There are technical challenges and requirements for RCS IP interactive communications:
Service reach: Deliver service to handsets and clients on networks with differing or conflicting network characteristics such as IP addresses, signalling and transport protocols and encryption.
Security: Protect network resources from attack and overloads and ensure the privacy of communications.
Revenue and cost optimization: Protect against theft and abuse of service and capture session data for billing, traffic management and planning.
Regulatory compliance: Enable emergency service routing and lawful intercept to comply with government regulations for VoIP and interactive communications.
SLA assurance: Handle latency-sensitive traffic with high priority and maintain service availability during abnormal busy periods.
Standards-based network services, such as GSMA OneAPI and Rich Communications Suite (RCS), along with service provider’s OSS/BSS “back-end” capabilities enables numerous features that gives application developers the ability to monetize communications, context, commerce and control. They can deliver their services more intelligently, by providing them with real-time information such as Data Connection type, tariff, roaming status, and device capabilities integrate innovative API such as integral Payments Engine.
RealTime Notifications: RCS gives choice of notifications such as sms, email, and push notification messages via Android, Apple or MS notification service. Device-level ad targeting can be by •Geo-Location •Time of Day •Frequency Capping •Direction of Travel
The suite of rich communication services with context-based capabilities have numerous applications too. For example integrating directly into business applications such as Field Service Management. The advantages of contextual commnication communciations is that it interact more intelligently and effectively with their customers, for example delivering targeted, contextually relevant marketing promotions, offers and coupons. Some application of RCS from user front is that it allows the user to describe issues in detail by allowing multimedia formats in tickets or complaina or even request higher Quality of Service temporarily for the delivery of, for example, High-Definition video content.
One of the possible applications using RCS-based advanced communication features can be smart self-care. This can include platform support and API integration to check real-time consumption, validity alerts, payment history, check available promo/discounted plans & period as well as Pay-online using sms/MMS. Self-care is a popular concept among many service/product providers and is developed for mobile applications on smartphones, and web portals on the internet. This is similarly integrable via SMS or Toll-Free number using IVR/USSD.
Realted Terms
MSRP
File Transfer using MSRP (or Message Session Relay Protocol) is an instant messaging or chat protocol, defined by the IETF in RFC4975. MSRP is a text-based, connection-oriented protocol for exchanging arbitrary (binary) MIME content, especially instant messages.
There is a strong evolution being seen in CSP space. Now operators are looking forward to implement the open standard for intelligent networks. It reduces their dependency on proprietary platforms and on vendor’s road maps. Open –source platform gives operator flexibility to develop their own applications without being dependent on vendor. An open, standards based, service logic execution environment (SLEE) that integrates with current and future networks is the key to providing innovative and revenue generating services. Providing one (standards based) carrier grade execution environment that integrates SS7, SIP, OSA/Parlay, OSS/BSS and J2EE environments offers significant benefits to operator.
Business benefits of SIP JAINSLEE based platform
Network Independence: The JAIN SLEE framework is independent of any particular network protocol, API or network topology. This is supported through the resource adaptor architecture
Portable Services: Application components can be developed and then deployed on JAIN SLEE compliant platforms from different vendors without recompilation or source code modification.
Supports Complex Applications: JAIN SLEE application components can have state, can be composed from other components, can create and destroy other application components, can invoke other application components both synchronously and asynchronously, and can invoke resource adaptors.
Industry Standard: JAIN SLEE is specified via the Java Community Process which allows multiple companies and individuals to collaborate in developing Java technology specifications.
In order to reduce the operating cost of legacy infrastructure more and more operators are investing and implementing open source platform. These new platforms bring agility and new service delivery capability to CSP.
The JAINSLEE based platform can be used to develop and deploy carrier-grade applications that use SS7-based protocols such as INAP and CAP, IP protocols such as SIP and Diameter, and IT / Web protocols, such as HTTP Servlet, XML and Service Orientated Architectures (SOA).
Fundamental Concepts :
Application can be written once and run on many different implementations of JAIN SLEE.
Applications can access resources and protocols across multiple networks from within the JAIN SLEE environment.
Follows the ACID transaction .
component model for structuring the application logic of communications applications as a collection of reusable
object-orientated components, and for composing these components into higher level and more sophisticated services.
SLEE specification also defines the management interfaces used to administer the application environment and also
defines set of standard Facilities (such as the Timer Facility, Trace Facility, and Alarm Facility so on )
Extension framework to allow new external protocols and systems (such as MSCs, MMSCs, SMSCs, Softswitchs, CSCFs, HLRs) to be integrated.
Characteristics of SLEE specification
• Event based model, asynchronous, support for composition
• Container manages component state
• Container manages garbage collection of components
• Transaction boundaries for demarcation and semantics of state replication
• Management of lifecycle of Server, Services, Provisioned state
• Versioned services, upgrade of services, existing activities stay on existing service instances, new activities are directed to instances of upgraded services
• Independent of network technology/ protocols/elements through resource adaptor architecture
Entities :
Service
A service in JAIN SLEE terminology is a managed field replaceable unit.
The system administrator of a JAIN SLEE controls the life cycle (including deployment, undeployment and on-line upgrade) of a service. The program code can include Java classes Profiles, and Service Building Blocks.
Profile
A JAIN SLEE Profi le contains provisioned service or subscriber data.
Service Building Blocks running inside the JAINSLEE may access profiles as part of their application logic.
Service Building Block
The element of re-use defined by JAINSLEE is the Service Building Block (SBB).
An SBB is a software component that sends and receives events and performs computational logic based on the receipt of events and its current state. SBBs are stateful.
The program code for an SBB is comprised of Java classes.
Event
An event represents an occurrence that may require application processing.
An event may originate from a number of different sources, for example, an external resource such as a communications protocol stack, from the SLEE itself, or from application components within the SLEE.
Resources and Resource ADAPTERS
Resources are external entities that interact with other systems outside of the SLEE, such as network elements (HLR, MSC, etc), protocol stacks, directories and databases.
A Resource Adaptor implements the interfacing of a Resource into the JAINSLEE environment.
– signalling at the protocol level (such as SIP, MGCP and SS7)
•For telephony, data and wireless communications networks, the Java APIs defined through.
– service portability
– network independence
– open development
•A Service Logic Execution Environment (SLEE) is high-throughput, low-latency, event-processing application environment.
•JAIN SLEE is designed specifically to allow implementations of a standard to meet the stringent requirements of communications applications (such as network-signaling applications).
Goals of JAIN SLEE are:
– Portable services and network independence.
– Hosting on an extensible platform.
– services and SLEE platform available from many vendors.
Key Features are :
•Industry standard :- JSLEE is the industry-agreed standard for an application server that meets the specific needs of telecommunications networks.
•Network independence:-The JSLEE programming model enables network independence for the application developer. The model is independent of any particular network protocol, API or network topology.
•Converged services:- JSLEE provides the means to create genuinely converged services, which can run across multiple network technologies.
•Network migrations :-As JSLEE provides a generic, horizontal platform across many protocols, independent of the network technology, it provides the ideal enabler technology for smooth transition between networks.
•Global market—global services:-JSLEE-compliant applications, hosted on a JSLEE application server are network agnostic. A single platform can be used across disparate networks
•Robust and reliable:- As with the enterprise application server space, deploying applications on a standard application server that has been tested and deployed in many other networks reduces logic errors, and produces more reliable applications
A VOIP/CPaaS solution is designed to accommodate both signalling and media. It integrates with various external endpoints. These include SIP phones like desktop, softphones, and webRTC. It also involves telecom carriers, different VoIP network providers, and enterprise applications such as Skype and Microsoft Lync. Additionally, it connects with Trunks.
A sufficiently capable SIP platform should have
Audio calls ( optionally video ) service using SIP gateways
Media services (such as recording , conferencing, voicemail, and IVR )
Messaging and presence ( could be using SIP SIMPLE, SMS , messahing service from third parties)
Interconnectivity with other IP multimedia systems, VoLTE ( optional interconnection with other types of communications networks as GSM or PSTN/ISDN).
support for VoIP signalling protocols (SIP, H,323, SCCP, MGCP, IAX) and telephony signalling protocols ( ISDN/SS7, FXS/FXO, Sigtran ) either internally via pluggable modules or externally via gateways .
Performance factors :
Security considerations :
High availability using redundant servers in standby Load balancing IPv4 and IPv6 network layer support TCP , UDP , SCTP transport layer protocol support DNS lookups and hop by hop connectivity
authentication, authorization, and accounting (AAA) Digest authentication and credentials fetched from backend Media Encryption TLS and SRTP support Topology hiding to prevent disclosing IP form internal components in via and route headers Firewalls , blacklist, filters , peak detectors to prevent Dos and Ddos attacks
The article only outlines SIP system architecture from 3 viewpoints :
A SIP server can be molded to take up any role based on the libraries and programs that run on it such as gateway server, call manager, load balancer etc. This in turn defines its placement in overall VoIP communication architecture. For example
stateless proxy servers are placed on the border,
application and B2BUA server at the core
SIP platform components
SIP Gateways
A SIP gateway is an application that interfaces a SIP network to a network utilising another signalling protocol. In terms of the SIP protocol, a gateway is just a special type of user agent, where the user agent acts on behalf of another protocol rather than a human. A gateway terminates the signalling path and can also terminate the media path .
To PSTN for telephony inter-working To H.323 for IP Telephony inter-working Client – originates message Server – responds to or forwards message
Logical SIP entities are:
User Agent Client (UAC): Initiates SIP requests ….
User Agent Server (UAS): Returns SIP responses ….
Network Servers ….
Registrar Server
A registrar server accepts SIP REGISTER requests; all other requests receive a 501 Not Implemented response. The contact information from the request is then made available to other SIP servers within the same administrative domain, such as proxies and redirect servers. In a registration request, the To header field contains the name of the resource being registered, and the Contact header fields contain the contact or device URIs.
Proxy Server
A SIP proxy server receives a SIP request from a user agent or another proxy and acts on behalf of the user agent in forwarding or responding to the request. Just as a router forwards IP packets at the IP layer, a SIP proxy forwards SIP messages at the application layer.
Typically proxy server ( inbound or outbound) have no media capabilities and ignore the SDP . They are mostly bypassed once dialog is established but can add a record-route .
A proxy server usually also has access to a database or a location service to aid it in processing the request (determining the next hop).
1. Stateless Proxy Server A proxy server can be either stateless or stateful. A stateless proxy server processes each SIP request or response based solely on the message contents. Once the message has been parsed, processed, and forwarded or responded to, no information (such as dialog information) about the message is stored. A stateless proxy never retransmits a message, and does not use any SIP timers
2. Stateful Proxy Server A stateful proxy server keeps track of requests and responses received in the past, and uses that information in processing future requests and responses. For example, a stateful proxy server starts a timer when a request is forwarded. If no response to the request is received within the timer period, the proxy will retransmit the request, relieving the user agent of this task.
3 . Forking Proxy Server A proxy server that receives an INVITE request, then forwards it to a number of locations at the same time, or forks the request. This forking proxy server keeps track of each of the outstanding requests and the response. This is useful if the location service or database lookup returns multiple possible locations for the called party that need to be tried.
Redirect Server
A redirect server is a type of SIP server that responds to, but does not forward, requests. Like a proxy server, a redirect server uses a database or location service to lookup a user. The location information, however, is sent back to the caller in a redirection class response (3xx), which, after the ACK, concludes the transaction. Contact header in response indicates where request should be tried .
Application Server
The heart of all call routing setup. It loads and executes scripts for call handling at runtime and maintains transaction states and dialogs for all ongoing calls . Usually the one to rewrite SIP packets adding media relay servers, NAT . Also connects external services like Accounting , CDR , stats to calls .
Media processing is usually provided by media servers in accordance to the SIP signalling. Bridges, call recording, Voicemail, audio conferencing, and interactive voice response (IVR) are commonly used. Read more about Media Architecture here
RFC 6230 Media Control Channel Framework decribes framework and protocol for application deployment where the application programming logic and media processing are distributed.
Any one such service could be a combination of many smaller services within such as Voicemail is a combination of prompt playback, runtime controls, Dual-Tone Multi-Frequency (DTMF) collection, and media recording. RFC 6231 Interactive Voice Response (IVR) Control Package for the Media Control Channel Framework.
Inband – With Inband digits are passed along just like the rest of your voice as normal audio tones with no special coding or markers using the same codec as your voice does and are generated by your phone.
Outband – Incoming stream delivers DTMF signals out-of-audio using either SIP-INFO or RFC-2833 mechanism, independently of codecs – in this case, the DTMF signals are sent separately from the actual audio stream.
TTS ( Text to Speech )
Alexa Text-to-Speech (TTS) + Amazon Polly
Ivona – multiple language text to speech converter with ssml scripts such as below
<speak><p><s><prosody rate="slow">IVONA</prosody> means highest quality speech
synthesis in various languages.</s><s>It offers both male and female radio quality voices <break/> at a
sampling rate of 22 kHz <break/> which makes the IVONA voices a
perfect tool for professional use or individual needs.</s></p></speak>
check ivona status
service ivona-tts-http status
tail -f /var/log/tts.log
SIP defines basic methods such as INVITE, ACK and BYE which can pretty much handle simple call routing with some more advanced processoes too like call forwarding/redirection, call hold with optional Music on hold, call parking, forking, barge etc.
Extending SIP headers
Newer SIP headers defined by more updated SIP RFC’s contains INFO, PRACK, PUBLISH, SUBSCRIBE, NOTIFY, MESSAGE, REFER, UPDATE. But more methods or headers can be added to baseline SIP packets for customization specific to a particular service provider. In case where a unrecognized SIP header is found on a SIP proxy which it either does not support or doesn’t understand, it will simply forward it to the specified endpoint.
Call routing Scripts
Interfaces for programming SIP call routing include :
– Call Processing Language—SIP CPL,
– Common Gateway Interface—SIP CGI,
– SIP Servlets,
– Java API for Integrated Networks—JAIN APIs etc .
Some known SIP stacks :
SailFin – SIP servlet container uses GlassFish open source enterprise Application Server platform (GPLv2), obsolete since merger from Sun Java to Oracle.
Mobicents – supports both JSLEE 1.1 and SIP Servlets 1.1 (GPLv2)
Cipango – extension of SIP Servlets to the Jetty HTTP Servlet engine thus compliant with both SIP Servlets 1.1 and HTTP Servlets 2.5 standards.
WeSIP – SIP and HTTP ( J2EE) converged application server build on OpenSER SIP platform
Additionally SIP stacks are supported on almost all popular SIP programming lanaguges which can be imported as lib and used for building call routing scripts to be mounted on SIP servers or endpoints such as :
PJSIP in C
JSSIP Javascript
Sofia in kamailio , Freswitch
Some popular SIP server also have proprietary scripting language such as – Asterisk Gateway Interface (AGI) , application interface for extending the dialplan with your functionality in the language you choose – PHP, Perl, C, Java, Unix Shell and others
A sufficiently capable SIP platform shoudl consist of following features :
Performance factors :
High availability using redundant servers in standby
Load balancing
IPv4 and IPv6 support
Security considerations :
digest authentication and credentials fetched from backend
Media Encryption
TLS and SRTP support
Topology hiding to prevent disclosing IP form internal components in via and route headers
Firewalls , blacklist, filters , peak detectors to prevent Dos and Ddos attacks .
Collecting and Processing PCAPS
VoIP monitor – network packet sniffer with commercial fronted for SIP RTP RTCP SKINNY(SCCP) MGCP WebRTC VoIP protocols
it uses a passive network sniffer (like tcpdump or wireshark) to analyse packets in realtime and transforms all SIP calls with associated RTP streams into database CDR record which is sent over the TCP to MySQL server (remote or local). If enabled saving SIP / RTP packets the sniffer stores each VoIP call into separate files in native pcap format (to local storage).
To adapt SIP to modern IP networks with inter network traversal ICE, far and near-end NAT traversal solutions are used. Network Address traversal is crtical to traffic flow between private public network and from behind firewalls and policy controlled networks
One can use any of the VOVIDA-based STUN server, mySTUN , TurnServer, reStund , CoTURN , NATH (PJSIP NAT Helper), ReTURN, or ice4j
Near-end NAT traversal
STUN (session traversal utilities for NAT) – UA itself detect presence of a NAT and learn the public IP address and port assigned using Nating. Then it replaces device local private IP address with it in the SIP and SDP headers. Implemented via STUN, TURN, and ICE. limitations are that STUN doesnt work for symmetric NAT (single connection has a different mapping with a different/randomly generated port) and also with situations when there are multiple addresses of a end point.
TURN (traversal using relay around NAT) or STUN relay – UA learns the public IP address of the TURN server and asks it to relay incoming packets. Limitatiosn since it handled all incoming and outgong traffic, it must scale to meet traffic requirments and should not become the bottle neck junction or single point of failure.
ICE (interactive connectivity establishment) – UA gathers “candidates of communication” with priorities offered by the remote party. After this client pairs local candidates with received peer candidates and performs offer-answer negotiating by trying connectivity of all pairs, therefore maximising success. The types of candidates : – host candidate who represents clients’ IP addresses, – server reflexive candidate for the address that has been resolved from STUN – and a relayed candidate for the address which has been allocated from a TURN relay by the client.
Far-end NAT traversal
UA is not concerned about NAT at all and communicated using its local IP port. The border controller implies a NAT handling components such as an application layer gateway (ALG) or universal plug and play (UPnP) etc which resolves the private and public network address mapping by act as a back to back user agent (B2BUA). Far end NAT can also be enabled by deploying a public SIP server which performs media relay (RTP Proxy/Media proxy).
Limitations of this approach (-) security risks as they are operating in the public network (-) enabling reverse traffic from UAS to UAC behind NAT.
A keep-alive mechanism is used to keep NAT translations of communications between SIP endpoint and its serving SIP servers opened , so that this NAT translation can be reused for routing. It contains client-to-server “ping” keep-alive and corresponding server-to-client “pong” messages. The 2 keep-alive mechanisms: a CRLF keep-alive and a STUN keep-alive message exchange.
The 3 types of SIP URIs,
address of record (AOR)
fully qualified domain name (FQDN)
globally routable user agent (UA) URI
SIP uniform resource identifiers (URIs) are identified based on DNS resolution since the URI after @ symbol contains hostname , port and protocl for the next hop.
Adding record route headers for locating the correct SIP server for a SIP message can be done by : – DNS service record (DNS SRV) – naming authority pointer (NAPTR) DNS resource record
Steps for SIP endpoints locating SIP server
From SIP packet get the NAPTR record to get the protocl to be used
Inspect SRV record to fetch port to use
Inspect A/AAA record to get IPv4 or IPv6 addresses ref : RFC 3263 – Locating SIP Servers Can use BIND9 server for DNS resolution supports NAPTR/SRV, ENUM, DNSSEC, multidomains, and private trees or public trees.
CDR store call detail records along with proof of call with tiemstamps, origination, destination, duration, rate etc. At the end of month or any other term, the aggregated CDR are cumulatively processed to generate the bill for a user. This heavy data stream needs to be accurately processed and this can be achived by using data-pipelines like AWS kinesis or Kafka eventstore.
The prime requirnment for the system is to handle enormous amount of call records data in relatime , cater to a number of producers and consumers.
For security the data is obfuscated into blob using base 64 encoding. For good consistency only a single shard should be responsible to process one user account’s bill.
Data Streams for billing service
AWSKinesis – Kinesis Data Streams is sued for for rapid and continuous data intake and aggregation. The type of data used can include IT infrastructure log data, application logs, social media, market data feeds, and web clickstream data. It supports data sharding (ie number of call records grouped) and uses a partition Key ( string MD5 hash) to determine which shard the record goes to.
(+) This system can handle high volume of data in realtime and produce call uuid specfic results which can be consumed by consumers waiting for the processed results
(-) If not consumed with a pre-specified time duration the processed results expire and are irretrivable . Self implement publisher to store teh processed reults from kisesis stream to data stores like Redis / RDBMS or other storge locations like s3 , dynamo DB. If pieline crashes during operation , data is lost
(-) Data stream should have low latency ingesting continuous data from producer and presenting data to consumer.
Call Rate and Accounting
Generally data streams processing are used for critical and voluminous service usage like for – metering/billing – server activity, – website clicks, – geo-location of devices, people, and physical goods
Call Rates are very crticial for billing and charging the calls . Any updates from the customer or carriers or individuals need to propagate automatically and quickly to avoid discrpencies and neagtive margins. CDRs need to be processed sequentially and incrementally on a record-by-record basis or over sliding time windows, and used for a wide variety of analytics including correlations, aggregations, filtering, and sampling.
To acheieve this the follow setup is ideal to use the new input rate sheet values via web UI console or POST API and propagate it quickly to main DB via AWS SQS which is a queing service and AWS lamda which is a serverless trigger based system . This ensures that any new input rates are updates in realtime and maintin fallback values in s3 bucket too
Call Rate and Accounting using task pipes , lambda serverless and qiueing service
It is an advantage to plan for ahead for connection with IMS such as openIMS, support for Voip signalling protocols (SIP, H,323, SCCP, MGCP, IAX) and telephony signalling protocls ( ISDN/SS7, FXS/FXO, Sigtran ) either internally via pluggable modules or externally via gateways or for SIP trunking integration via OTT providers/ cloud telephony.
Adhere to Standard
The obvious starting milestone before making a full-scale carrier-grade, SIP-based VoIP system is to start by building a PBX for intra-enterprise communication. There are readily available solutions to make an IP telephony PBX Kamailio, FreeSWITCH, asterisk, Elastix, SipXecs. It is important to use the standard protocol and widely acceptable media formats and codecs to ensure interoperability and reduce compute and delay involved in protocol or media transcoding.
Database Integration
Need backend , cache , databse integration to npt only store routing rules with temporary varaible values but also aNeed backend, cache, database integration to not only store routing rules with temporary variable values but also account details, call records details, access control lists etc. Should therefore extend integration with text-based DB, Redis, MySQL, PostgreSQL, OpenLDAP, and OpenRadius.
Consistency of Call Records and duplicated charging records at various endpoints
In current Voip scenarios a call may be passing thorugh various telco providers , ISP and cloud telephony serviIn current VoIP scenarios, a call may be passing through various telco providers, ISP and cloud telephony service providers where each system maintains its own call records and billing. This in my opinion is duplication and can be avoided by sharing a consistent data store possible in the blockchain. This is an experimental idea that I have further explored in this article
There are other external components to setup a VOIP solution apart from Core voice Servers and gateways like the ones listed below, I will try to either add a detailed overall architecture diagram here or write about them in an separate article. Keep watching this space for updates
Payment Gateways
Billing and Invoice
Fraud Prevention
Contacts Integration
Call Analytics
API services
Admin Module
Number Management ( DIDs ) and porting
Call Tracking
Single Sign On and User Account Management with Oauth and SAML
Telecom R & D 
