1. TM Module

Jiri Kuthan

   FhG FOKUS

   Copyright  2003 FhG FOKUS
   Revision History
   Revision $Revision: 1.12.2.3 $ $Date: 2008/06/20 17:37:22 $
     __________________________________________________________________

   1.1. Overview
   1.2. Known Issues
   1.3. Parameters

        1.3.1. fr_timer (integer)
        1.3.2. fr_inv_timer (integer)
        1.3.3. wt_timer (integer)
        1.3.4. delete_timer (integer)
        1.3.5. retr_timer1 (integer)
        1.3.6. retr_timer2 (integer)
        1.3.7. noisy_ctimer (integer)
        1.3.8. restart_fr_on_each_reply (integer)
        1.3.9. unix_tx_timeout (integer)
        1.3.10. aggregate_challenges (integer)
        1.3.11. blst_methods_add (unsigned integer)
        1.3.12. blst_methods_lookup (unsigned integer)

   1.4. Functions

        1.4.1. t_relay_to_udp(ip, port), t_relay_to_tcp(ip, port)
        1.4.2. t_relay()
        1.4.3. t_on_failure(failure_route)
        1.4.4. t_on_reply(onreply_route)
        1.4.5. t_on_branch(branch_route)
        1.4.6. append_branch()
        1.4.7. t_newtran()
        1.4.8. t_reply(code, reason_phrase)
        1.4.9. t_lookup_request()
        1.4.10. t_retransmit_reply()
        1.4.11. t_release()
        1.4.12. t_forward_nonack(ip, port)
        1.4.13. t_set_fr(fr_inv_timeout [, fr_timeout])
        1.4.14. t_branch_timeout()
        1.4.15. t_branch_replied()
        1.4.16. t_any_timeout()
        1.4.17. t_any_replied()
        1.4.18. t_is_canceled()

   1.5. TM Module API

        1.5.1. Defines
        1.5.2. Functions

              1.5.2.1. register_tmcb(cb_type, cb_func)
              1.5.2.2. load_tm(*import_structure)

1.1. 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 and 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.

1.2. Known Issues

     * Local ACK/CANCELs copy'n'pastes Route and ignores deleted Routes
       (solved in ser 2.1).
     * 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).

1.3. Parameters

   Revision History
   Revision $Revision: 1.12.2.3 $ $Date: 2008/06/20 17:37:22 $

1.3.1. fr_timer (integer)

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

   Default value is 30000 ms (30 seconds).

   See also: t_set_fr().

   Example 1. Set fr_timer parameter
...
modparam("tm", "fr_timer", 10000)
...

1.3.2. fr_inv_timer (integer)

   Timer which hits if no final reply for an INVITE arrives after a
   provisional message was received (in milliseconds).

   Note: this timer can be restarted when a provisional response is
   received. For more details see restart_fr_on_each_reply.

   Default value is 120000 ms (120 seconds).

   See also: t_set_fr().

   Example 2. Set fr_inv_timer parameter
...
modparam("tm", "fr_inv_timer", 180000)
...

1.3.3. wt_timer (integer)

   Time for which a transaction stays in memory to absorb delayed messages
   after it completed (in milliseconds); 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 5000 ms (5 seconds).

   Example 3. Set wt_timer parameter
...
modparam("tm", "wt_timer", 1000)
...

1.3.4. delete_timer (integer)

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

   Default value is 200 milliseconds.

   Example 4. Set delete_timer parameter
...
modparam("tm", "delete_timer", 100)
...

1.3.5. retr_timer1 (integer)

   Initial retransmission period (in milliseconds).

   Default value is 500 milliseconds.

   Example 5. Set retr_timer1 parameter
...
modparam("tm", "retr_timer1", 1000)
...

1.3.6. retr_timer2 (integer)

   Maximum retransmission period (in milliseconds). The retransmission
   interval starts with retr_timer1 and increases until it reaches this
   value. After this it stays constant at retr_timer2.

   Default value is 4000 milliseconds.

   Example 6. Set retr_timer2 parameter
...
modparam("tm", "retr_timer2", 2000)
...

1.3.7. noisy_ctimer (integer)

   If set, INVITE transactions that time-out (FR INV timer) will be always
   replied. If it's not set, the transaction has only one branch and no
   response was ever received on this branch, it will be silently dropped
   (no 408 reply will be generated) This behavior is overridden if a
   request is forked, the transaction has a failure route or callback, or
   some functionality explicitly turned it on for a transaction (like acc
   does to avoid unaccounted transactions due to expired timer). Turn this
   off only if you know the client UACs will timeout and their timeout
   interval for INVITEs is lower or equal than tm's fr_inv_timer.

   Default value is 0 (false).

   Example 7. Set noisy_ctimer parameter
...
modparam("tm", "noisy_ctimer", 1)
...

1.3.8. restart_fr_on_each_reply (integer)

   If set (default), the fr_inv_timer for an INVITE transaction will be
   restarted for each provisional reply received (rfc3261 mandated
   behaviour). If not set, the fr_inv_timer will be restarted only for the
   first provisional replies and for increasing replies greater or equal
   180 (e.g. 180, 181, 182, 185, ...).

   Setting it to 0 is especially useful when dealing with bad UAs that
   continuously retransmit 180s, not allowing the transaction to timeout
   (and thus making impossible the implementation of certain services,
   like automatic voicemail after x seconds).

   Default value is 1 (on).

   See also: fr_inv_timer.

   Example 8. Set restart_fr_on_each_reply parameter
...
modparam("tm", "restart_fr_on_each_reply", 0)
...

1.3.9. unix_tx_timeout (integer)

   Unix socket transmission timeout, in milliseconds.

   If unix sockets are used (e.g.: to communicate with sems) and sending a
   message on a unix socket takes longer then unix_tx_timeout, the send
   will fail.

   The default value is 500 milliseconds.

   Example 9. Set unix_tx_timeout parameter
...
modparam("tm", "unix_tx_timeout", 250)
...

1.3.10. aggregate_challenges (integer)

   If set (default), the final reply is a 401 or a 407 and more then one
   branch received a 401 or 407, then all the WWW-Authenticate and
   Proxy-Authenticate headers from all the 401 and 407 replies will be
   aggregated in a new final reply. If only one branch received the
   winning 401 or 407 then this reply will be forwarded (no new one will
   be built). If 0 only the first 401, or if no 401 was received the first
   407, will be forwarded (no header aggregation).

   Default value is 1 (required by rfc3261).

   Example 10. Set aggregate_challenges parameter
...
modparam("tm", "aggregate_challenges", 0)
...

1.3.11. blst_methods_add (unsigned integer)

   Bitmap of method types that trigger blacklisting on transaction
   timeouts. (This setting has no effect on blacklisting because of send
   failures.)

   The following values are associated to the request methods: INVITE=1,
   CANCEL=2, ACK=4 (not retransmitted, thus, never times-out), BYE=8,
   INFO=16, REGISTER=32, SUBSCRIBE=64, NOTIFY=126, OTHER=256 (all the
   unknown types). Check parser/msg_parser.h for farther details.

   Change the value carefully, because requests not having provisional
   response (everything but INVITE) can easily cause the next hop to be
   inserted into the blacklist by mistake. For exmaple the next hop is a
   proxy, it is alive, but waiting for the response of the UAS, and has
   higher fr_timer value.

   The default value is 1, only INVITEs trigger blacklisting

   Example 11. Set blst_methods_add parameter
...
# INVITEs and REGISTERs trigger blacklisting
modparam("tm", "blst_methods_add", 33)
...

1.3.12. blst_methods_lookup (unsigned integer)

   Bitmap of method types that are looked-up in the blacklist before
   statefull forwarding. See also blst_methods_add

   The default value is 4294967287, every method type except BYE. (We try
   to deliver BYEs no matter what)

   Example 12. Set blst_methods_lookup parameter
...
# lookup only INVITEs
modparam("tm", "blst_methods_lookup", 1)
...

1.4. Functions

   Revision History
   Revision $Revision: 1.12.2.3 $ $Date: 2008/06/20 17:37:22 $

1.4.1.  t_relay_to_udp(ip, port), t_relay_to_tcp(ip, port)

   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.

   Example 13. t_relay_to_udp usage
...
t_relay_to_udp("1.2.3.4", "5060");
...

1.4.2.  t_relay()

   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.

   Example 14. t_relay usage
...
if (!t_relay())
{
    sl_reply_error();
    break;
};
...

1.4.3.  t_on_failure(failure_route)

   Sets failure 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 commands which are usable within failure_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 failure_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:
     * failure_route - Failure route block to be called.

   Example 15. t_on_failure 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.

1.4.4.  t_on_reply(onreply_route)

   Sets the reply routing block, to which control is passed when a reply
   for the current transaction is received. Note that the set of commands
   which are usable within onreply_routes is limited.

   Meaning of the parameters is as follows:
     * onreply_route - Onreply route block to be called.

   Example 16. t_on_reply usage
...
loadmodule "/usr/local/lib/ser/modules/nathelper.so"
...
route {
        /* if natted */
        t_on_reply("1");
        t_relay();
}

onreply_route[1] {
        if (status=~ "(183)|2[0-9][0-9]"){
                force_rtp_proxy();
                search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=y
es');
        }
        if (nat_uac_test("1")){
                fix_nated_contact();
        }
}

1.4.5.  t_on_branch(branch_route)

   Sets the branch routing block, to which control is passed after forking
   (when a new branch is created). For now branch routes are intended only
   for last minute changes of the SIP messages (like adding new headers).
   Note that the set of commands which are usable within branch_routes is
   very limited. It is not possible to drop a message or generate a reply.

   Meaning of the parameters is as follows:
     * branch_route - branch route block to be called.

   Example 17. t_on_branch usage
...
route {
        t_on_branch("1");
        t_relay();
}

branch_route[1] {
        if (uri=~"sip:[0-9]+"){
                append_hf("P-Warn: numeric uri\r\n");
        }
}

1.4.6.  append_branch()

   Similarly to t_fork_to, it extends destination set by a new entry. The
   difference is that current URI is taken as new entry.

   Example 18. append_branch usage
...
set_user("john");
t_fork();
set_user("alice");
t_fork();
t_relay();
...

1.4.7.  t_newtran()

   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.

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

   See test/uas.cfg for more examples.

1.4.8.  t_reply(code, reason_phrase)

   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.

   Example 20. t_reply usage
...
t_reply("404", "Not found");
...

1.4.9.  t_lookup_request()

   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.

   Example 21. t_lookup_request usage
...
if (t_lookup_request()) {
    ...
};
...

1.4.10.  t_retransmit_reply()

   Retransmits a reply sent previously by UAS transaction.

   Example 22. t_retransmit_reply usage
...
t_retransmit_reply();
...

1.4.11.  t_release()

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

   Example 23. t_release usage
...
t_release();
...

1.4.12.  t_forward_nonack(ip, port)

   mainly for internal usage--forward a non-ACK request statefully.

   Meaning of the parameters is as follows:
     * ip - IP address where the message should be sent.
     * port - Port number.

   Example 24. t_forward_nonack usage
...
t_forward_nonack("1.2.3.4", "5060");
...

1.4.13.  t_set_fr(fr_inv_timeout [, fr_timeout])

   Sets the fr_inv_timeout and optionally fr_timeout for the current
   transaction. If the transaction is already created (e.g called after
   t_relay() or in an onreply_route) all the branches will have their
   final response timeout updated on-the-fly. If one of the parameters is
   0, its value won't be changed.

   Meaning of the parameters is as follows:
     * fr_inv_timeout - new final response timeout (in milliseconds) for
       INVITEs. See also fr_inv_timer.
       fr_timeout - new final response timeout (in milliseconds) for
       non-INVITE transaction, or INVITEs which haven't received yet a
       provisional response. See also fr_timer.

   See also: fr_timer, fr_inv_timer.

   Example 25. t_set_fr usage
...
route {
        t_set_fr(10000); # set only fr invite timeout to 10s
        t_on_branch("1");
        t_relay();
}

branch_route[1] {
        # if we are calling the pstn, extend the invite timeout to 50s
        # for all the branches, and set the no-reply-received timeout to 2s
        if (uri=~"sip:[0-9]+"){
                t_set_fr(50000, 2000);
        }
}

1.4.14.  t_branch_timeout()

   Returns true if the failure route is executed for a branch that did
   timeout. It can be used only from the failure_route.

   Example 26. t_branch_timeout usage
...
failure_route[0]{
        if (t_branch_timeout()){
                log("timeout\n");
                # ...
        }
}

1.4.15.  t_branch_replied()

   Returns true if the failure route is executed for a branch that did
   receive at least one reply in the past (the "current" reply is not
   taken into account). It can be used only from the failure_route.

   Example 27. t_branch_replied usage
...
failure_route[0]{
        if (t_branch_timeout()){
                if (t_branch_replied())
                        log("timeout after receiving a reply (no answer?)\n");
                else
                        log("timeout, remote side seems to be down\n");
                # ...
        }
}

1.4.16.  t_any_timeout()

   Returns true if at least one of the current transactions branches did
   timeout.

   Example 28. t_any_timeout usage
...
failure_route[0]{
        if (!t_branch_timeout()){
                if (t_any_timeout()){
                        log("one branch did timeout\n");
                        sl_send_reply("408", "Timeout");
                }
        }
}

1.4.17.  t_any_replied()

   Returns true if at least one of the current transactions branches did
   receive some reply in the past. If called from a failure or onreply
   route, the "current" reply is not taken into account.

   Example 29. t_any_replied usage
...
onreply_route[0]{
        if (!t_any_replied()){
                log("first reply received\n");
                # ...
        }
}

1.4.18.  t_is_canceled()

   Returns true if the current transaction was canceled.

   Example 30. t_is_canceled usage
...
failure_route[0]{
        if (t_is_canceled()){
                log("transaction canceled\n");
                # ...
        }
}

1.5. TM Module API

   Revision History
   Revision $Revision: 1.12.2.3 $ $Date: 2008/06/20 17:37:22 $

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

1.5.1. Defines

     * ACK_TAG enables stricter matching of acknowledgments including
       to-tags. Without it, to-tags are ignored. It is disabled by default
       for two reasons:
          + It eliminates an unlikely race condition in which
            transaction's to-tag is being rewritten by a 200 OK whereas an
            ACK is being looked up by to-tag.
          + It makes UACs happy who set wrong to-tags.
       It should not make a difference, as there may be only one negative
       reply sent upstream and 200/ACKs are not matched as they constitute
       another transaction. It will make no difference at all when the new
       magic cookie matching is enabled anyway.
     * CANCEL_TAG similarly enables strict matching of CANCELs including
       to-tags--act of mercy to UACs, who screw up the to-tags (however,
       it still depends on how forgiving the downstream UAS is). Like with
       ACK_TAG, all this complex transactions matching goes with RFC3261's
       magic cookie away anyway.

1.5.2. Functions

1.5.2.1.  register_tmcb(cb_type, cb_func)

   For programmatic use only--register a function to be called back on an
   event. See t_hooks.h for more details.

   Meaning of the parameters is as follows:
     * cb_type - Callback type.
     * cb_func - Callback function.

1.5.2.2.  load_tm(*import_structure)

   For programmatic use only--import exported TM functions. See the acc
   module for an example of use.

   Meaning of the parameters is as follows:
     * import_structure - Pointer to the import structure.
