$Revision: 1.3.2.1 $
$Date: 2005/06/22 23:12:08 $
User's Guide
Overview
TM module enables stateful processing of &sip; transactions. The main
use of stateful logic, which is costly in terms of memory and CPU, is
some services inherently need state. For example, transaction-based accounting (module
acc) needs to process transaction state as opposed to individual messages, and any kinds
of forking must be implemented statefully. Other use of stateful processing is it trading
CPU caused by retransmission processing for memory. That makes
however only sense if CPU consumption per request is huge. For
example, if you want to avoid costly DNS resolution for every
retransmission of a request to an unresolvable destination, use stateful mode. Then,
only the initial message burdens server by DNS queries, subsequent
retransmissions will be dropped and will not result in more processes blocked by
DNS resolution. The price is more memory consumption and higher
processing latency.
From user's perspective, there are these major functions : t_relay, t_relay_to_udp
and t_relay_to_tcp. All of them
setup transaction state, absorb retransmissions from upstream, generate downstream
retransmissions and correlate replies to requests. t_relay forwards to current &uri; (be
it original request's &uri; or a &uri; changed by some of &uri;-modifying functions,
such as sethost). t_relay_to_udp and t_relay_to_tcp forward to a specific address
over UDP or TCP respectively.
In general, if TM is used, it copies clones of received &sip;
messages in shared memory. That costs the memory and also CPU time
(memcpys, lookups, shmem locks, etc.) Note that non-TM functions
operate over the received message in private memory, that means that any core operations
will have no effect on statefully processed messages after creating the transactional
state. For example, calling record_route after t_relay is pretty
useless, as the RR is added to privately held message whereas its
TM clone is being forwarded.
TM is quite big and uneasy to program--lot of mutexes, shared memory
access, malloc & free, timers--you really need to be careful when you do anything. To
simplify TM programming, there is the instrument of callbacks. The
callback mechanisms allow programmers to register their functions to specific event. See
t_hooks.h for a list of possible events.
Other things programmers may want to know is &uac;--it is a very simplistic code which
allows you to generate your own transactions. Particularly useful for things like
NOTIFYs or IM gateways. The &uac; takes care of all the transaction
machinery: retransmissions , FR timeouts, forking, etc. See t_uac prototype in uac.h
for more details. Who wants to see the transaction result may register for a callback.
Dependencies
&ser; Modules
The following modules must be loaded before this module:
No dependencies on other &ser; modules.
External Libraries or Applications
The following libraries or applications must be installed before running
&ser; with this module loaded:
None.
Exported Parameters
<varname>fr_timer</varname> (integer)
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.
Set <varname>fr_timer</varname> parameter
...
modparam("tm", "fr_timer", 10)
...
<varname>fr_inv_timer</varname> (integer)
Timer which hits if no final reply for an INVITE arrives after a provisional message
was received (in seconds).
Default value is 120 seconds.
Set <varname>fr_inv_timer</varname> parameter
...
modparam("tm", "fr_inv_timer", 200)
...
<varname>wt_timer</varname> (integer)
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).
Default value is 5 seconds.
Set <varname>wt_timer</varname> parameter
...
modparam("tm", "wt_timer", 10)
...
<varname>delete_timer</varname> (integer)
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.
Set <varname>delete_timer</varname> parameter
...
modparam("tm", "delete_timer", 5)
...
<varname>retr_timer1p1</varname> (integer)
Retransmission period.
Default value is 1 second.
Set <varname>retr_timer1p1</varname> parameter
...
modparam("tm", "retr_timer1p1", 2)
...
<varname>retr_timer1p2</varname> (integer)
Retransmission period.
Default value is 2 * retr_timer1p1 second.
Set <varname>retr_timer1p2</varname> parameter
...
modparam("tm", "retr_timer1p2", 4)
...
<varname>retr_timer1p3</varname> (integer)
Retransmission period.
Default value is 4 * retr_timer1p1 second.
Set <varname>retr_timer1p4</varname> parameter
...
modparam("tm", "retr_timer1p3", 8)
...
<varname>retr_timer2</varname> (integer)
Maximum retransmission period.
Default value is 4 seconds.
Set <varname>retr_timer2</varname> parameter
...
modparam("tm", "retr_timer2", 8)
...
<varname>noisy_ctimer</varname> (integer)
If set, on FR timer INVITE transactions will be explicitly canceled if possible,
silently dropped otherwise. Preferably, it is turned off to allow very long ringing.
This behavior is overridden if a request is forked, or some functionality
explicitly turned it off for a transaction (like acc does to avoid unaccounted
transactions due to expired timer).
Default value is 0 (false).
Set <varname>noisy_ctimer</varname> parameter
...
modparam("tm", "noisy_ctimer", 1)
...
<varname>ruri_matching</varname> (integer)
The parameter controls whether the Request-URI should be
included in pre-RFC3261 transaction maching. When set 1 then
the Request-URI will be included, when set to 0 then it will be
not included.
Default value is 1 (include Request-URI).
<varname>via1_matching</varname> (integer)
The parameter controls whether the topmost Via header field
should be included in pre-RFC3261 transaction maching. When set
1 then the topmost Via header field will be included, when set
to 0 then it will be not included.
Default value is 1 (include topmost Via header field).
<varname>uac_from</varname> (string)
This parameter allows to configure the URI that will be put in
the From header field of SIP request generated localy by the
UAC in tm module. This parameter is currently not used.
Default value is "sip:foo@foo.bar".
<varname>unix_tx_timeout</varname> (integer)
Maximum timeout in seconds for the request sent over the unix
domain socket interface (using t_write_unix function). The
function will indicate failure if it does not manage to send
all the data within the interval configured by this parameter.
Default value is 2 seconds.
<varname>restart_fr_on_each_reply</varname> (integer)
The parameter controls whether the FR timer will be restarted on
each provisional reply received.
Default value is 1 (yes).
<varname>fr_timer_avp</varname> (string)
This parameter makes it possible to override the value of FR
(final reply) timer on per-transaction basis. TM module can
pick the value of the timer from an AVP. The name or ID of the
AVP can be configured by this parameter. If there is no such
AVP then the default value configured through fr_timer
parameter will be used.
Default value is "callee_fr_timer".
<varname>fr_inv_timer_avp</varname> (string)
This parameter makes it possible to override the value of FR
Invite (final response for INVITE transactions) timer on
per-transaction basis. TM module can pick the value of the
timer from an AVP. The name or ID of the AVP can be configured
by this parameter. If there is no such AVP then the default
value configured through fr_inv_timer parameter will be used.
Default value is "callee_fr_inv_timer".
<varname>tw_append</varname> (string)
This parameter configures additional information that can be
passed over the FIFO or unix domain socket interfaces by TM
module to another application. TM module can pass values of
AVPs, SIP message header fields, or the message body. Syntax of
the parameter is as follows:
tw_append = name ':' element ( ';' element ) *
element = [ title '=' ] ( avp_val | hdr_val )
element = title '=' body_val
avp_val = "avp" '[' avp_spec ']'
hdr_val = "hdr" '[' hdr_name ']'
body_val = "msg[body]"
Default value is "".
Set <varname>tw_append</varname> parameter
Pass the value of callee_fr_timer AVP, the contents of
Subject header field, and the whole SIP message body to the
application over FIFO or unix domain socket interface.
...
modparam("tm", "tw_append", "params:avp[callee_fr_timer];hdr[Subject];body=msg[body]")
...
Exported Functions
<function moreinfo="none">t_relay_to_udp(ip, port)</function>,
<function moreinfo="none">t_relay_to_tcp(ip, port)</function>,
<function moreinfo="none">t_relay_to_tls(ip, port)</function>
Relay a message statefully to a fixed destination. This along with t_relay is the function most users want to use--all
other are mostly for programming. Programmers interested in writing
TM logic should review how t_relay is implemented in tm.c and
how TM callbacks work.
Meaning of the parameters is as follows:
ip - &ip address where the message should be sent.
port - Port number.
<function>t_relay_to_udp</function> usage
...
t_relay_to_udp("1.2.3.4", "5060");
...
<function moreinfo="none">t_relay()</function>
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.
<function>t_relay</function> usage
...
if (!t_relay()) { sl_reply_error(); break; };
...
<function moreinfo="none">t_on_failure(reply_route)</function>
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
). Note that the set of command which are usable within reply_routes
is strictly limited to rewriting &uri;, initiating new branches, logging, and
sending stateful replies (t_reply). Any other commands may
result in unpredictable behavior and possible server failure. Note that whenever
reply_route is entered, uri is reset to value which it had on relaying. If it
temporarily changed during a reply_route processing, subsequent reply_route will
ignore the changed value and use again the original one.
Meaning of the parameters is as follows:
reply_route - Reply route block to be called.
<function>t_on_failure</function> usage
...
route {
t_on_failure("1");
t_relay();
}
failure_route[1] {
revert_uri();
setuser("voicemail");
append_branch();
}
...
See test/onr.cfg for a more complex example of combination
of serial with parallel forking.
<function moreinfo="none">t_on_failure(reply_route)</function>
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
). Note that the set of command which are usable within reply_routes
is strictly limited to rewriting &uri;, initiating new branches, logging, and
sending stateful replies (t_reply). Any other commands may
result in unpredictable behavior and possible server failure. Note that whenever
reply_route is entered, uri is reset to value which it had on relaying. If it
temporarily changed during a reply_route processing, subsequent reply_route will
ignore the changed value and use again the original one.
Meaning of the parameters is as follows:
reply_route - Reply route block to be called.
<function>t_on_failure</function> usage
...
route {
t_on_failure("1");
t_relay();
}
failure_route[1] {
revert_uri();
setuser("voicemail");
append_branch();
}
...
See test/onr.cfg for a more complex example of combination
of serial with parallel forking.
<function moreinfo="none">t_on_failure(reply_route)</function>
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
). Note that the set of command which are usable within reply_routes
is strictly limited to rewriting &uri;, initiating new branches, logging, and
sending stateful replies (t_reply). Any other commands may
result in unpredictable behavior and possible server failure. Note that whenever
reply_route is entered, uri is reset to value which it had on relaying. If it
temporarily changed during a reply_route processing, subsequent reply_route will
ignore the changed value and use again the original one.
Meaning of the parameters is as follows:
reply_route - Reply route block to be called.
<function>t_on_failure</function> usage
...
route {
t_on_failure("1");
t_relay();
}
failure_route[1] {
revert_uri();
setuser("voicemail");
append_branch();
}
...
See test/onr.cfg for a more complex example of combination
of serial with parallel forking.
<function moreinfo="none">t_on_reply(onreply_route)</function>
Sets reply routing block, to which control is passed when a
reply is received from one of downstream branches. Only a
limited set of functions is available in onreply_route
blocks. The routing block will be called for every reply
received from downstream. A typical use for onreply_route
blocks would be rewriting contacts with private IP addresses in
200 OK replies by nathelper module.
Meaning of the parameters is as follows:
onreply_route - Reply route block to be called.
<function>t_on_reply</function> usage
...
route {
t_on_reply("1");
t_relay();
}
onreply_route[1] {
fix_nated_contact();
force_rtp_proxy();
}
...
<function moreinfo="none">t_check_status(regex)</function>
This function can be used to check the status code in replies
from failure_route and onreply_route blocks. It allows to
differentiate processing based on the status code received.
Meaning of the parameters is as follows:
regex - Regular expression to be
matched agains the status code.
<function>t_check_status</function> usage
...
failure_route[1] {
if (t_check_status("486")) {
# Busy
t_relay_to_udp("1.2.3.4", "5060");
};
}
...
<function moreinfo="none">t_write_req(fifo, application)</function>
Send the request ove the FIFO interface to another application,
such as SEMS.
Meaning of the parameters is as follows:
fifo - Name of the FIFO interface.
application - Name of the application.
<function moreinfo="none">t_write_unix(socket, application)</function>
Send the request ove the unix domain socket interface to another application,
such as SEMS.
Meaning of the parameters is as follows:
socket - Filename of the unix
domain socket.
application - Name of the application.
<function moreinfo="none">append_branch()</function>
Similarly to t_fork_to, it extends destination set by a new
entry. The difference is that current &uri; is taken as new entry.
<function>append_branch</function> usage
...
set_user("john");
t_fork();
set_user("alice");
t_fork();
t_relay();
...
<function moreinfo="none">t_newtran()</function>
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;.
<function>t_newtran</function> usage
...
if (t_newtran()) {
log("UAS logic");
t_reply("999","hello");
} else sl_reply_error();
...
See test/uas.cfg for more examples.
<function moreinfo="none">t_reply(code, reason_phrase)</function>
Sends a stateful reply after a transaction has been established. See
t_newtran for usage.
Meaning of the parameters is as follows:
code - Reply code number.
reason_phrase - Reason string.
<function>t_reply</function> usage
...
t_reply("404", "Not found");
...
<function moreinfo="none">t_lookup_request()</function>
Checks if a transaction exists. Returns a positive value if so, negative otherwise.
Most likely you will not want to use it, as a typical application of a looku-up is
to introduce a new transaction if none was found. However this is safely
(atomically) done using t_newtran.
<function>t_lookup_request</function> usage
...
if (t_lookup_request()) {
...
};
...
<function moreinfo="none">t_retransmit_reply()</function>
Retransmits a reply sent previously by &uas; transaction.
<function>t_retransmit_reply</function> usage
...
t_retransmit_reply();
...
<function moreinfo="none">t_release()</function>
Remove transaction from memory (it will be first put on a wait timer to absorb
delayed messages).
<function>t_release</function> usage
...
t_release();
...
<function moreinfo="none">t_replicate(ip, port)</function>,
<function moreinfo="none">t_replicate_udp(ip, port)</function>,
<function moreinfo="none">t_replicate_tcp(ip, port)</function>,
<function moreinfo="none">t_replicate_tls(ip, port)</function>
Replicate a message to another server. Functions with "_tls"
suffix are only available with additional TLS package.
Meaning of the parameters is as follows:
ip - &ip address where the message should be sent.
port - Port number.
<function moreinfo="none">t_forward_nonack(ip,
port)</function>,
<function moreinfo="none">t_forward_nonack_uri()</function>,
<function moreinfo="none">t_forward_nonack_udp(ip,
port)</function>,
<function moreinfo="none">t_forward_nonack_tcp(ip,
port)</function>,
<function moreinfo="none">t_forward_nonack_tls(ip, port)</function>
mainly for internal usage--forward a non-ACK request
statefully. t_forward_nonack_tls is only available with
additional TLS package.
Meaning of the parameters is as follows:
ip - &ip address where the message should be sent.
port - Port number.
<function>t_forward_nonack</function> usage
...
t_forward_nonack("1.2.3.4", "5060");
...
External Usage of <acronym>TM</acronym>
There are applications which would like to generate &sip; transactions without too
big involvement in &sip; stack, transaction management, etc. An example of such an
application is sending instant messages from a website. To address needs of such
apps, &ser; accepts requests for new transactions via fifo pipes too. If you want to
enable this feature, start FIFO server with configuration option.
fifo=/tmp/ser_fifo
Then, an application can easily launch a new transaction by writing a transaction
request to this named pipe. The request must follow very simple format, which is
:t_uac_from:[<file_name>]\n
<method>\n
<sender's uri>\n
<dst uri>\n
<CR_separated_headers>\n
<body>\n
.\n
\n
(Filename is to where a report will be dumped. ser assumes /tmp
as file's directory.)
Note the the request write must be atomic, otherwise it might get intermixed with
writes from other writers. You can easily use it via Unix command-line tools, see
the following example:
[jiri@bat jiri]$ cat > /tmp/ser_fifo
:t_uac_from:xxx
MESSAGE
sip:sender@iptel.org
sip:mrx@iptel.org
header:value
foo:bar
bznk:hjhjk
p_header: p_value
body body body
yet body
end of body
.
or cat test/transaction.fifo > /tmp/ser_fifo
Known Issues
We don't have authentication merging on forking.
Local ACK/CANCELs copy'n'pastes Route and ignores deleted
Routes.
6xx should be delayed.
Possibly, performance could be improved by not parsing non-INVITEs, as they
do not be replied with 100, and do not result in ACK/CANCELs, and other
things which take parsing. However, we need to rethink whether we don't need
parsed headers later for something else. Remember, when we now conserver a
request in sh_mem, we can't apply any pkg_mem operations to it any
more. (that might be redesigned too).
Another performance improvement may be achieved by not parsing
CSeq in replies until reply branch matches branch of an INVITE/CANCEL
in transaction table.
t_replicate should be done more cleanly--Vias, Routes,
etc. should be removed from a message prior to replicating it (well, does
not matter any longer so much as there is a new replication module).
SNMP support (as nobody cares about
SNMP, in particular for TM, I will drop this item soon).