Kamailio Transaction Module

Although most of 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 , Transaction Module .

Note : This article has been updated many time 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 comments.

If you are new to kamailio , this post os not for you , instead read more on kamailio as a powerful sip server here or its application in telephony domain here .

Kamailio is basically only a transaction stateful proxy, without any dialog support build 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 .

we know that SIP is a transactional protocol and every request and its response goes within a transaction. more on SIP as protocol is here

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.

Lifecycle of Transaction

Transactions lifecycle are controlled by various factors which includes coming from 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.

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 setse and Individual elements within the destination sets are called branches.

Serial , Parallel and Combined Forking – By default kamailio performs parallel forking sending msg to all destinations and waiting for response , however it can also do serail ie send request one by one and wait for reposne /timeout before sending next . By use of priorities ( q valaue 0 – 1.0), Kamailio can also intermix the forking technique ie decreasing priority oder for serial and same level for parallel . The destination uri are loaded using unctions t_load_contacts() and t_next_contacts().

parallel forking exmaple

request_route {
  seturi("sip:a@example.com");
  append_branch("sip:b@example.com");
  append_branch("sip:c@example.com");
  append_branch("sip:d@example.com");

  t_relay();
  break;
}

mixed forking exmaple

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();
 }
 ``

Transaction Module 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.

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.

unix_tx_timeout (integer) – nix socket transmission timeout,

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.

blst_503 (integer) – reparse_invite=1.

blst_503_def_timeout (integer) – blacklist interval if no “Retry-After” header is present

blst_503_min_timeout / blst_503_max_timeout (integer) – minimum and maximun blacklist interval respectively

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_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.

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.

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.

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

fr_inv_timer_avp (string) – same as abovel , 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

Telecom Solution startup’s strategy

I have been contemplating points that make for a successful developer  to develop solutions and services for a  Telecom Application Server.  The trend has shown many variations from pure IN programs like VPN , Prepaid billing logic to SIP servlets for call parking , call completion. From SIP servlets to JAISNLEE open standard based communication.

I can assert with confidence that Telephony is eventually going to be integrated with Internet to provide a new breed of communication in future aka Internet Telephony.

I have assembled some points here that make for a successful startup   in logic building domain of telecom core network .

1. Product Innovation 

Envisions a multiple network technologies, that provides ability to build over new innovative cutting edge technologies in the market. It should deliver platform to launch newer  services like WebRTC and RCS .

innovation

2. Competitive Pricing

Cutting down the spiraling cost of Development of the new technologies platform with improvement in the usage of Data rather than voice by integrating new features like File sharing and MSRP messaging. An evolutionary architecture to reduce the effort and cost through high re-use of NGN Platform and Services.

Pictures2

3. Lower Servicing costs 

Introduce uniform service experience across different platforms which helps CSP’s to reduce Time Cycles and Costs for handling enhancements requests and the annual OPEX appreciably.

Pictures1

4.Flexibility

Interworking among the services from  legacy IN solution and IMS /IT. Allow the Operators to extend their basic offering with added  services via low cost software and increases the ARPU for subscribers.

5. Develop on webRTC

Make a WebRTC solution that offers a plug in free, device agnostic, network agnostic web based communication tool along with the server side implementation.

webrtc

6. Media solutions

CSP’s are looking into Long term growth and profitability from new online services media streaming services . Make use-cases around IPTV and VOD ( Video On Demand) . Also Voicemails , IVR , DTMF, TTS( text to speech ) , Speech recognition etc

Picture1

7. Social Media Integration

Integration of the services with social media/networking enables new monetizing benefits to CSPs especially in terms on advertising and gaining popularity , inviting new customers etc.

resources

Enterprises are looking forward to reach customers with ennoblement of Telco in their present landscape which was impossible to reach before. Telco not only plays an instrumental role in increasing the customers base which results into increase in enterprise’s revenue but also offers the value addition in their present product/service delivery model.  Hence it is high-time when developers can aggregate , use open-standard services / technologies ( GSMA , SIP , WebRTC )  and develop high end solutions for Telecom Domain .


E-Learning

True that the number of teacher today are not enough to teach the number of kids . For example even in India there is often 1 teacher for a class of 60 students in one subject. Also the experience and output of learning from a human teacher cannot be ever replaced by a software or ebook or application no matter how user-friendly or informative it is .

In this post I am going to describe an e-learning platform which harness the power of Internet for the purpose of distance education and where students around the world volunteer to teach each other any subject they wish to. This will be made possible through a combination of real time communication technologies like WebRTC and plethora of knowledge repositories.

Aim :

Platform to connect volunteers ( children ) teach each other a subject in a stipulated time through Web based Real Time Communication.

Working :

A student enrolls himself for a subject or a course it could be anything from arithmetic to french language . Another student who know French language for example find this in portal and sign up to be teacher for that child. They can anytime connect with each other in audio , video , message , file sharing , screen sharing session through WebRTC and learn the subject. The students earn reward points .

e-leaning service on WebRTC
e-leaning service on WebRTC

Technologies  :

  • WebRTC for communication
  • MySQL for data storage
  • Apache Tomcat as Webserver
  • HTML5
  • CSS
  • JavaScript

Conclusion :

By encouraging a child to take responsibility and teach another child , we will not only encourage friendship between them but also give them a sense of accomplishment .