tm Module

First what is the idea with the branch concept: branch route is a route to be execute separately for each branch before being sent out - changes in that route should reflect only on that branch.

There are several types of flags in Kamailio :

For example: I have a call parallel forking to GW and to a user. And I would like to know from which branch I will get the final negative reply (if so). I will set a branch route before relaying the calls (with the 2 branches). The branch route will be separately executed for each branch; in the branch going to GW (I can identified it by looking to RURI), I will set a branch flag. This flag will appear only in the onreply route run for replied from GW. It will be also be visible in failure route if the final elected reply belongs to the GW branch. This flags will not be visible in the other branch (in routes executing replies from the other branch).

For how to define branch flags and use via script, see Section 1.4.15, “ t_on_branch(branch_route) ” and the setbflag(), resetbflag() and isbflagset() script functions.

Also, modules may set branch flags before transaction creation. The REGISTRAR module was the first to use this type of flags. The NAT flag is pushed in branch flags instead in message flags.

Timers can be used to trigger failover behavior. E.g. if we send a call a gateway and the gateway does not send a provisional response within 3 seconds, we want to cancel this call and send the call to another gateway. Another example is to ring a SIP client only for 30 seconds and then redirect the call to the voicemail.

There are two timers in Kamailio :

For example: You want to have failover if there is no provisional response after 3 seconds, but you want to ring for 60 seconds. Thuse, set the fr_timer to 3 and fr_inv_timer to 60.

DNS based failover can be use when relaying stateful requests. According to RFC 3263, DNS failover should be done on transport level or transaction level. TM module supports them both.

Failover at transport level may be triggered by a failure of sending out the request message. A failure occurs if the corresponding interface was found for sending the request, if the TCP connection was refused or if a generic internal error happened during send. There is no ICMP error report support.

Failover at transaction level may be triggered when the transaction completed either with a 503 reply, either with a timeout without any received reply. In such a case, automatically, a new branch will be forked if any other destination IPs can be used to deliver the requests. The new branch will be a clone of the winning branch.

The set of destinations IPs is step-by-step build (on demand) based on the NAPTR, SRV and A records available for the destination domain.

DNS-based failover is by default applied excepting when this failover is globally disabled (see the core parameter disable_dns_failover) or when the relay flag (per transaction) is set (see the t_relay() function).

The following modules must be loaded before this module:

The following libraries or applications must be installed before running Kamailio with this module loaded:

Timer which hits if no final reply for a request or ACK for a negative INVITE reply arrives (in seconds).

Default value is 30 seconds.

...
modparam("tm", "fr_timer", 10)
...

Timer which hits if no final reply for an INVITE arrives after a provisional message was received (in seconds). This timer is started after the first provisional response. Thus, fast failover (no 100 trying from gateway) can be achieved by setting fr_timer to low values. See example below

Default value is 120 seconds.

...
modparam("tm", "fr_inv_timer", 200)
...

Time for which a transaction stays in memory to absorb delayed messages after it completed; also, when this timer hits, retransmission of local cancels is stopped (a puristic but complex behavior would be not to enter wait state until local branches are finished by a final reply or FR timer--we simplified).

For non-INVITE transaction this timer relates to timer J of RFC 3261 section 17.2.2. According to the RFC this timer should be 64*T1 (= 32 seconds). But this would increase memory usage as the transactions are kept in memory very long.

Default value is 5 seconds.

...
modparam("tm", "wt_timer", 10)
...

Time after which a to-be-deleted transaction currently ref-ed by a process will be tried to be deleted again.

Default value is 2 seconds.

...
modparam("tm", "delete_timer", 5)
...

Retransmission T1 period, in milliseconds.

Default value is 500 milliseconds.

...
modparam("tm", "T1_timer", 700)
...

Maximum retransmission period, in milliseconds.

Default value is 4000 milliseconds.

...
modparam("tm", "T2_timer", 8000)
...

Should be request-uri matching used as a part of pre-3261 transaction matching as the standard wants us to do so? Turn only off for better interaction with devices that are broken and send different r-uri in CANCEL/ACK than in original INVITE.

Default value is 1 (true).

...
modparam("tm", "ruri_matching", 0)
...

Should be top most VIA matching used as a part of pre-3261 transaction matching as the standard wants us to do so? Turn only off for better interaction with devices that are broken and send different top most VIA in CANCEL/ACK than in original INVITE.

Default value is 1 (true).

...
modparam("tm", "via1_matching", 0)
...

Send timeout to be used by function which use UNIX sockets (as t_write_unix).

Default value is 2 seconds.

...
modparam("tm", "unix_tx_timeout", 5)
...

If true (non null value), the final response timer will be re-triggered for each received provisional reply. In this case, final response timeout may occure after a time longer than fr_inv_timer (if UAS keeps sending provisional replies).

Default value is 1 (true).

...
modparam("tm", "restart_fr_on_each_reply", 0)
...

Full specification (NAME, ID, Alias) of an AVP which contains a final response timeout value. If present, this value will override the static fr_timer parameter.

If you set the AVP to an empty string, the whole mechanism for variable timeout will be disabled, falling back to the static value. Note that if you set this parameter to an empty string, a value of zero will be used.

Default value is "NULL" (feature disabled).

...
modparam("tm", "fr_timer_avp", "$avp(i:24)")
...

Full specification (NAME, ID, Alias) of an AVP which contains a final INVITE response timeout value. If present, this value will override the static fr_inv_timer parameter.

If set the AVP to an to empty string, the whole mechanism for variable timeout will be disabled, falling back to the static value. Note that if you set this parameter to an empty string, a value of zero will be used.

Default value is "NULL" (feature disabled).

...
modparam("tm", "fr_inv_timer_avp", "$avp(i:25)")
...

List of additional information to be appended by t_write_req and t_write_unix functions.

Default value is null string.

Syntax of the parameter is:

The full list of supported pseudo-variables in Kamailio is available at: http://kamailio.org/docs/pseudo-variables-1.1.x.html

Each element will be appended per line in “name: value” format. Element “$rb (message body)” is the only one which does not accept name; the body it will be printed all the time at the end, disregarding its position in the definition string.

...
modparam("tm", "tw_append",
   "test: ua=$hdr(User-Agent) ;avp=$avp(i:10);$rb;time=$Ts")
...

If the module should generate and export statistics to the core manager. A zero value means disabled.

The TM module provides statistics about how many transaction were created (splitted per code classes), how many transaction are currently in use and some other values.

Default value is 1 (enabled).

modparam("tm", "enable_stats", 0)

Enable/disable passing of provisional replies to FIFO applications.

Default value is 0.

...
modparam("tm", "pass_provisional_replies", 1)
...

Enable/disable the usage of stateful synonym branch IDs in the generated Via headers. They are faster but not reboot-safe.

Default value is 1 (use synonym branches).

...
modparam("tm", "syn_branch", 0)
...

Describes how the AVPs should be handled in reply route:

In mode 1, you can see the AVPs you set in request route, branch route or failure route. The side efect is performance as more locking is required in order to keep the AVP's list integrity.

Default value is 0.

...
modparam("tm", "onreply_avp_mode", 1)
...

Tells how the 6xx replies should be internally handled:

Default value is 0.

...
modparam("tm", "disable_6xx_block", 1)
...

Value of the Final Response timeout for INVITE transactions to be used during serial forwarding:

Function t_next_contacts() sets fr_inv_timer to fr_inv_timer_next value if, after t_next_contacts() is called, there are still lower qvalue contacts available, and to fr_inv_timer value if there are not.

Default value is 30.

...
modparam("tm", "fr_inv_timer_next", 10)
...

Internal AVP that t_load_contacts() function uses to store contacts of the destination set and that t_next_contacts() function uses to restore those contacts.

Default value is "NULL" (t_load_contacts()/t_next_contacts() functions are disabled).

...
modparam("tm", "contacts_avp", "$avp(i:25)")
...

When enabled Kamailio behaves according to draft-sparks-sip-invfix so received replies matching no transaction are dropped instead of stateless forwarded. This avoids spoofed replies from attackers.

Default value is 0.

...
modparam("tm", "drop_stateless_replies", 1)
...
			

Set the reason phrase for 100 replies generated by tm module.

Default value is "Giving a Try".

...
modparam("tm", "auto_inv_100_reason", "Trying")
...
			

Creates a new transaction, returns a negative value on error. This is the only way a script can add a new transaction in an atomic way. Typically, it is used to deploy a UAS.

This function can be used from REQUEST_ROUTE.

...
if (t_newtran()) { 
	log("UAS logic"); 
	t_reply("999","hello"); 
} else sl_reply_error();
...

Relay a message statefully to destination indicated in current URI. (If the original URI was rewritten by UsrLoc, RR, strip/prefix, etc., the new URI will be taken). Returns a negative value on failure--you may still want to send a negative reply upstream statelessly not to leave upstream UAC in lurch.

The coresponding transaction may or may not be already created. If not yet created, the function will automatically create it.

The function may take as parameter an optional set of flags for controlling the internal behaviour. The flags may be given in decimal or hexa format; supported flags are:

In case of error, the function returns the following codes:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

...
if (!t_relay()) {
    sl_reply_error();
    exit;
}
...

Relay a message statefully to a fixed destination. The destination is specified as “[proto:]host[:port]”. If a destination URI “$du” for this message was set before the function is called then this value will be used as destination instead of the function parameter.

The function may take as parameter an optional set of flags for controlling the internal behaviour - for details see the above “t_relay([flags])” function.

This functions can be used from REQUEST_ROUTE, FAILURE_ROUTE.

NOTE: the first parameter can take only static values. If you need to set next hop (proxy) destination via some script variable, set the value of destination URI variable: $du. $du takes as value a SIP URI, so “proto:host:port” translates in: “sip:host:port;transport=proto”. Once you set the $du use t_relay() without proxy address parameter.

...
t_relay("tcp:192.168.1.10:5060");
t_relay("mydomain.com:5070","0x1");
t_relay("udp:mydomain.com");
...

Sends a stateful reply after a transaction has been established. See t_newtran for usage.

Meaning of the parameters is as follows:

Both parameters accept any kind of pseudo-variables.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

...
t_reply("404", "Use $rU not found");
...

Replicates a request to another destination. No information due the replicated request (like reply code) will be forwarded to the original SIP UAC.

The destination is specified by a SIP URI. If multiple destinations are to be used, the additional SIP URIs have to be set as branches.

The function may take as parameter an optional set of flags for controlling the internal behaviour - for description see the above “t_relay([flags])” function. Note that only 0x4 is applicable here.

This functions can be used from REQUEST_ROUTE.

...
t_replicate("sip:1.2.3.4:5060");
t_replicate("sip:1.2.3.4:5060;transport=tcp");
t_replicate("sip:1.2.3.4","0x4");
...

Remove transaction from memory (it will be first put on a wait timer to absorb delayed messages).

This function can be used from REQUEST_ROUTE.

...
t_release();
...

Returns true if the regualr expresion “re” match the reply code of the response message as follows:

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE .

...
if (t_check_status("(487)|(408)")) {
    log("487 or 408 negative reply\n");
}
...

Flush the flags from current request into the already created transaction. It make sense only in routing block if the transaction was created via t_newtran() and the flags have been altered since.

This function can be used from REQUEST_ROUTE and BRANCH_ROUTE .

...
t_flush_flags();
...

Returns true if all or last (depending of the parameter) reply(es) were local generated (and not received).

Parameter may be “all” or “last”.

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, FAILURE_ROUTE and ONREPLY_ROUTE.

...
if (t_local_replied("all")) {
	log ("no reply received\n");
}
...

Write via FIFO interface or UNIX socket a lot of information regarding the request. Which information should be written may be control via the “tw_append” parameter.

This functions can be used from REQUEST_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE.

...
modparam("tm","tw_append","append1:Email=avp[i:12];UA=hdr[User-Agent]")
modparam("tm","tw_append","append2:body=msg[body]")
...
t_write_req("voicemail/append1","/tmp/appx_fifo");
...
t_write_unix("logger/append2","/var/run/logger.sock");
...

Returns true if the current SIP message is associated to a transaction. The relationship between the SIP request and transaction is defined as follow:

For SIP reply processing, the function returns:

Note: To detect retransmissions using this function you have to make sure that the initial request has already created a transaction, e.g. by using t_relay(). If the processing of requests may take long time (e.g. DB lookups) and the retransmission arrives before t_relay() is called, you can use the t_newtran() function to manually create a transaction.

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and ONREPLY_ROUTE.

...
if ( is_method("CANCEL") ) {
	if ( t_check_trans() )
		t_relay();
	exit;
}
...

Retuns true if called for an INVITE transaction that was explicitly cancelled by UAC side via a CANCEL request.

This function can be used from ONREPLY_ROUTE, FAILURE_ROUTE.

...
if (t_was_cancelled()) {
    log("transaction was cancelled by UAC\n");
}
...

Sets reply routing block, to which control is passed after a transaction completed with a negative result but before sending a final reply. In the referred block, you can either start a new branch (good for services such as forward_on_no_reply) or send a final reply on your own (good for example for message silo, which received a negative reply from upstream and wants to tell upstream “202 I will take care of it”).

As not all functions are available from failure route, please check the documentation for each function to see the permissions. Any other commands may result in unpredictable behavior and possible server failure.

Only one failure_route can be armed for a request. If you use many times t_on_failure(), only the last one has effect.

Note that whenever failure_route is entered, RURI is set to value of the winning branch.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE and FAILURE_ROUTE.

...
route { 
	t_on_failure("1"); 
	t_relay();
} 

failure_route[1] {
	seturi("sip:user@voicemail");
	append_branch();
	t_relay();
}
...

Sets reply routing block, to which control is passed each time a reply (provisional or final) for the transaction is received. The route is not called for local generated replies! In the referred block, you can inspect the reply and perform text operations on it.

As not all functions are available from this type of route, please check the documentation for each function to see the permissions. Any other commands may result in unpredictable behavior and possible server failure.

Only one onreply_route can be armed for a request. If you use many times t_on_reply(), only the last one has effect.

If the processed reply is provisionla reply (1xx code), by calling the drop() function (exported by core), the execution of the route will end and the reply will not be forwarded further.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE and FAILURE_ROUTE.

...
route { 
	t_on_reply("1"); 
	t_relay();
} 

onreply_route[1] {
	if (t_check_status("1[0-9][0-9]")) {
		setflag(1);
		log("provisional reply received\n");
		if (t_check_status("183"))
			drop;
	}
}
...

Sets a branch route to be execute separately for each branch of the transaction before being sent out - changes in that route should reflect only on that branch.

As not all functions are available from this type of route, please check the documentation for each function to see the permissions. Any other commands may result in unpredictable behavior and possible server failure.

Only one branch_route can be armed for a request. If you use many time t_on_branch(), only the last one has effect.

By calling the drop() function (exported by core), the execution of the branch route will end and the branch will not be forwarded further.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE and FAILURE_ROUTE.

...
route { 
	t_on_branch("1"); 
	t_relay();
} 

branch_route[1] {
	if (uri=~"bad_uri") {
		xlog("dropping branch $ru \n");
		drop;
	}
	if (uri=~"GW_uri") {
		append_rpid();
	}
}
...

Loads contacts in destination set in increasing qvalue order as values of contacts_avp. If all contacts in the destination set have the same qvalue, t_load_contacts() does not do anything thus minimizing performance impact of serial forking capability when it is not needed. Returns 1 if loading of contacts succeeded or there was nothing to do. Returns -1 on error (see syslog).

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

...
if (!t_load_contacts()) {
        sl_send_reply("500", "Server Internal Error - Cannot load contacts");
        exit;
};
...

If transaction does not exist when t_next_contacts() is called, replaces Request-URI with the first contacts_avp value, adds the remaining contacts_avp values with the same qvalue as branches, and destroys those AVPs. It does nothing if there are no contacts_avp values. Returns 1 if there were no errors and -1 if an error occurred (see syslog).

If transaction does exist when t_next_contacts() is called, adds the first contacts_avp value and all following contacts_avp values with the same qvalue as new branches to request and destroys those AVPs. Returns 1 if new branches were successfully added and -1 on error (see syslog) or if there were no more contacts_avp values.

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

...
# First call after t_load_contacts() when transaction does not exist yet
# and contacts should be available
if (!t_next_contacts()) {
        sl_send_reply("500", "Server Internal Error - Cannot get contacts");
} else {
        t_relay();
};
...
# Following call, when transaction exists and there may or may not be
# contacts left
if (!t_next_contacts()) {
        t_reply("408", "Request Timeout");
} else {
        t_relay();
};
...

Cancel branches of an active SIP transaction. The function can be called for a SIP reply that will identify the current branch.

Parameter can be:.

This function can be used in ONREPLY_ROUTE.

...
if (t_cancel_branches("all")) {
	xlog("cancelled all branches\n");
}
...

Generates and sends a local SIP request.

Parameters:

Generates and sends a CANCEL for an existing local SIP request.

Parameters:

Gets information about the load of TM internal hash table.

Parameters:

Generates and sends a reply for an existing inbound SIP transaction.

Parameters:

Total number of total replies received by TM module.

Total number of replies received and relayed by TM module.

Total number of replies local generated by TM module.

Total number of transactions created by received requests.

Total number of transactions created by local generated requests.

Total number of transactions completed with 2xx replies.

Total number of transactions completed with 3xx replies.

Total number of transactions completed with 4xx replies.

Total number of transactions completed with 5xx replies.

Total number of transactions completed with 6xx replies.

Number of transactions existing in memory at current time.

For programmatic use only--import the TM API. See the cpl-c, acc or jabber modules to see how it works.

Meaning of the parameters is as follows: