htable(k): fix non-init act. ctx in event route execution
[sip-router] / modules / tm / README
1 1. TM Module
2
3 Jiri Kuthan
4
5    FhG FOKUS
6
7 Juha Heinanen
8
9    <jh@tutpro.com>
10
11    Copyright © 2003 FhG FOKUS
12
13    Copyright © 2008 Juha Heinanen
14    Revision History
15    Revision $Revision$ $Date$
16      __________________________________________________________________
17
18 1.1. Overview
19
20    TM module enables stateful processing of SIP transactions. The main use
21    of stateful logic, which is costly in terms of memory and CPU, is some
22    services inherently need state. For example, transaction-based
23    accounting (module acc) needs to process transaction state as opposed
24    to individual messages, and any kinds of forking must be implemented
25    statefully. Other use of stateful processing is it trading CPU caused
26    by retransmission processing for memory. That makes however only sense
27    if CPU consumption per request is huge. For example, if you want to
28    avoid costly DNS resolution for every retransmission of a request to an
29    unresolvable destination, use stateful mode. Then, only the initial
30    message burdens server by DNS queries, subsequent retransmissions will
31    be dropped and will not result in more processes blocked by DNS
32    resolution. The price is more memory consumption and higher processing
33    latency.
34
35    From user's perspective, there are these major functions : t_relay,
36    t_relay_to_udp and t_relay_to_tcp. All of them setup transaction state,
37    absorb retransmissions from upstream, generate downstream
38    retransmissions and correlate replies to requests. t_relay forwards to
39    current URI (be it original request's URI or a URI changed by some of
40    URI-modifying functions, such as sethost). t_relay_to_udp and
41    t_relay_to_tcp forward to a specific address over UDP or TCP
42    respectively.
43
44    In general, if TM is used, it copies clones of received SIP messages in
45    shared memory. That costs the memory and also CPU time (memcpys,
46    lookups, shmem locks, etc.) Note that non-TM functions operate over the
47    received message in private memory, that means that any core operations
48    will have no effect on statefully processed messages after creating the
49    transactional state. For example, calling record_route after t_relay is
50    pretty useless, as the RR is added to privately held message whereas
51    its TM clone is being forwarded.
52
53    TM is quite big and uneasy to program--lot of mutexes, shared memory
54    access, malloc and free, timers--you really need to be careful when you
55    do anything. To simplify TM programming, there is the instrument of
56    callbacks. The callback mechanisms allow programmers to register their
57    functions to specific event. See t_hooks.h for a list of possible
58    events.
59
60    Other things programmers may want to know is UAC--it is a very
61    simplistic code which allows you to generate your own transactions.
62    Particularly useful for things like NOTIFYs or IM gateways. The UAC
63    takes care of all the transaction machinery: retransmissions , FR
64    timeouts, forking, etc. See t_uac prototype in uac.h for more details.
65    Who wants to see the transaction result may register for a callback.
66
67 Note
68
69    Several Kamailio (OpenSER) TM module functionalities are now
70    implemented in the TMX module: "modules_k/tmx". Check it to see if what
71    you are looking for is there.
72
73 1.2. Serial Forking Based on Q Value
74
75    A single SIP INVITE request may be forked to multiple destinations. We
76    call the set of all such destinations a destination set. Individual
77    elements within the destination sets are called branches. The script
78    writer can add URIs to the destination set from the configuration file,
79    or they can be loaded from the user location database, each registered
80    contact then becomes one branch in the destination set.
81
82    The default behavior of the tm module, if it encounters a SIP message
83    with multiple branches in the destination set, it to forward the SIP
84    message to all the branches in parallel. That means it sends the
85    message to all the branch destinations before it waits for replies from
86    any of them. This is the default behavior if you call t_relay() and
87    similar functions without anything else.
88
89    Another approach of handling multiple branches in a destination set it
90    serial forking. When configured to do serial forking, the server takes
91    the first branch out of the destination set, forwards the message to
92    its destination and waits for a reply or timeout. Only after a reply
93    has been received or the timeout occurred, the server takes another
94    destination from the destination set and tries again, until it receives
95    a positive final reply or until all branches from the destination set
96    have been tried.
97
98    Yet another, more sophisticated, way of handling multiple branches is
99    combined serial/parallel forking, where individual branches within the
100    destination set are assigned priorities. The order in which individual
101    branches are tried is then determined by their relative priority within
102    the destination set. Branches can be tried sequentially in the
103    descending priority order and all branches that have the same priority
104    can be tried in parallel. Such combined serial/parallel forking can be
105    achieved in the tm module with the help of functions t_load_contacts()
106    and t_next_contacts().
107
108    Every branch in the destination set is assigned a priority number, also
109    known as the q value. The q value is a floating point number in a range
110    0 to 1.0. The higher the q value number, the more priority is the
111    particular branch in the destination set is given. Branches with q
112    value 1.0 have maximum priority, such branches should be always tried
113    first in serial forking. Branches with q value 0 have the lowest
114    priority and they should by tried after all other branches with higher
115    priority in the destination set.
116
117    As an example, consider the following simple configuration file. When
118    the server receives an INVITE, it creates four branches for it with
119    usernames A through D and then forwards the request using t_relay():
120 route {
121   seturi("sip:a@example.com");
122   append_branch("sip:b@example.com");
123   append_branch("sip:c@example.com");
124   append_branch("sip:d@example.com");
125
126   t_relay();
127   break;
128 }
129
130    With this configuratin the server forwards the request to all four
131    branches at once, performing parallel forking described above. We did
132    not set the q value for individual branches in this example but we can
133    do that by slightly modifying the arguments given to append_branch():
134 route {
135   seturi("sip:a@example.com");
136   append_branch("sip:b@example.com", "0.5");
137   append_branch("sip:c@example.com", "0.5");
138   append_branch("sip:d@example.com", "1.0");
139
140   t_relay();
141   break;
142 }
143
144    Here we assigned q value 0.5 to branches B and C and q value 1.0 to
145    branch D. We did not specify any q value for branch A and in that case
146    it is assumed that its q value is the lowest from all branches within
147    the destination set. If you try to run this example again, you will
148    figure out that nothing changed, t_relay() still forward the message to
149    all branches in parallel.
150
151    We now want to implement the combined serial/parallel forking. Branch D
152    should be tried first, because its q value is 1.0. Branches B and C
153    should be tried in parallel, but only after D finishes. Branch A should
154    be tried after B and C finished, because its q value (the default) is
155    the lowest of all. To do that, we need to introduce two new functions
156    into our example and one tm module parameter:
157 modparam("tm", "contacts_avp", "tm_contacts");
158
159 route {
160   seturi("sip:a@example.com");
161   append_branch("sip:b@example.com", "0.5");
162   append_branch("sip:c@example.com", "0.5");
163   append_branch("sip:d@example.com", "1.0");
164
165   t_load_contacts();
166
167   t_next_contacts();
168   t_relay();
169   break;
170 }
171
172    First of all, the tm module parameter is mandatory if the two new
173    functions are used. Function t_load_contacts() takes all branches from
174    the destination set, sorts them according to their q values and stores
175    them in the AVP configured in the modparam. The function also clears
176    the destination set, which means that it removes all branches
177    configured before with seturi() and append_branch().
178
179    Function t_next_contacts() takes the AVP created by the previous
180    function and extract the branches with highest q values from it. In our
181    example it is branch D. That branch is then put back into the
182    destination set and when the script finally reaches t_relay(), the
183    destination set only contains branch D and the request will be
184    forwarded there.
185
186    We achieved the first step of serial forking, but this is not
187    sufficient. Now we also need to forward to other branches with lower
188    priority values when branch D finishes. To do that, we need to extend
189    the configuration file again and introduce a failure_route section:
190 modparam("tm", "contacts_avp", "tm_contacts");
191
192 route {
193   seturi("sip:a@example.com");
194   append_branch("sip:b@example.com", "0.5");
195   append_branch("sip:c@example.com", "0.5");
196   append_branch("sip:d@example.com", "1.0");
197
198   t_load_contacts();
199
200   t_next_contacts();
201   t_on_failure("serial");
202   t_relay();
203   break;
204 }
205
206 failure_route["serial"]
207 {
208   if (!t_next_contacts()) {
209     exit;
210   }
211
212   t_on_failure("serial");
213   t_relay();
214 }
215
216    The failure_route section will be executed when branch D finishes. It
217    executes t_next_contacts() again and this time the function retrieves
218    branches B and C from the AVP and adds them to the destination set.
219    Here we need to check the return value of the function, because a
220    negative value indicates that there were no more branches, in that case
221    the failure_route should just terminate and forward the response from
222    branch D upstream.
223
224    If t_next_contact() returns a positive value then we have more new
225    branches to try and we need to setup the failure_route again and call
226    t_relay(). In our example the request will now be forwarded to branches
227    B and C in paralell, because they were both added to the destination
228    set by t_next_contacts() at the same time.
229
230    When branches B and C finish, the failure_route block is executed
231    again, this time t_next_contacts() puts the final branch A into the
232    destination set and t_relay() forwards the request there.
233
234    And that's the whole example, we achieved combined serial/parallel
235    forking based on the q value of individual branches. In real-world
236    configuration files the script writer would need to check the return
237    value of all functions and also configure some additional parameters,
238    such as fr_inv_timer_next and restart_fr_on_each_reply. Also the
239    destination set would not be configured directly in the configuration
240    file, but can be retrieved from the user location database, for
241    example. In that case registered contacts will be stored in the
242    destination set as branches and their q values (provided by UAs) will
243    be used.
244
245 1.3. Known Issues
246
247      * Possibly, performance could be improved by not parsing non-INVITEs,
248        as they do not be replied with 100, and do not result in
249        ACK/CANCELs, and other things which take parsing. However, we need
250        to rethink whether we don't need parsed headers later for something
251        else. Remember, when we now conserver a request in sh_mem, we can't
252        apply any pkg_mem operations to it any more. (that might be
253        redesigned too).
254      * Another performance improvement may be achieved by not parsing CSeq
255        in replies until reply branch matches branch of an INVITE/CANCEL in
256        transaction table.
257      * t_replicate should be done more cleanly--Vias, Routes, etc. should
258        be removed from a message prior to replicating it (well, does not
259        matter any longer so much as there is a new replication module).
260      * Function t_next_contacts should restore the value of timer
261        fr_inv_timer when there are no more branches to be processed
262        serially. The function can restore the timer properly if it has
263        been configured through an AVP or with the config framework, but
264        may fail to restore timer values configured for individual
265        transactions with t_set_fr.
266
267 1.4. Parameters
268
269    Revision History
270    Revision $Revision$ $Date$
271
272 1.4.1. fr_timer (integer)
273
274    Timer which hits if no final reply for a request or ACK for a negative
275    INVITE reply arrives (in milliseconds).
276
277    Default value is 30000 ms (30 seconds).
278
279    See also: t_set_fr(), max_noninv_lifetime.
280
281    Example 1. Set fr_timer parameter
282 ...
283 modparam("tm", "fr_timer", 10000)
284 ...
285
286 1.4.2. fr_inv_timer (integer)
287
288    Timer which hits if no final reply for an INVITE arrives after a
289    provisional message was received (in milliseconds).
290
291    Note: this timer can be restarted when a provisional response is
292    received. For more details see restart_fr_on_each_reply.
293
294    Default value is 120000 ms (120 seconds).
295
296    See also: t_set_fr(), max_inv_lifetime.
297
298    Example 2. Set fr_inv_timer parameter
299 ...
300 modparam("tm", "fr_inv_timer", 180000)
301 ...
302
303 1.4.3. max_inv_lifetime (integer)
304
305    Maximum time an INVITE transaction is allowed to be active (in
306    milliseconds). After this interval has passed from the transaction
307    creation, the transaction will be either moved into the wait state or
308    in the final response retransmission state, irrespective of the
309    transaction fr_inv_timer and fr_timer values.
310
311    An INVITE transaction will be kept in memory for maximum:
312    max_inv_lifetime+fr_timer(from the ack to the final reply
313    wait)+wt_timer.
314
315    The main difference between this timer and fr_inv_timer is that the
316    fr_inv_timer is per branch, while max_inv_lifetime is per the whole
317    transaction. Even on a per branch basis fr_inv_timer could be
318    restarted. For example, by default if restart_fr_on_each_reply is not
319    cleared, the fr_inv_timer will be restarted for each received
320    provisional reply. Even if restart_fr_on_each_reply is not set the
321    fr_inv_timer will still be restarted for each increasing reply (e.g.
322    180, 181, 182, ...). Another example when a transaction can live
323    substantially more then its fr_inv_timer and where max_inv_lifetime
324    will help is when dns failover is used (each failed dns destination can
325    introduce a new branch).
326
327    The default value is 180000 ms (180 seconds - the rfc3261 timer C
328    value).
329
330    See also: max_noninv_lifetime, t_set_max_lifetime() (allows changing
331    max_inv_lifetime on a per transaction basis), t_reset_max_lifetime
332    fr_timer, wt_timer, restart_fr_on_each_reply.
333
334    Example 3. Set max_inv_lifetime parameter
335 ...
336 modparam("tm", "max_inv_lifetime", 150000)
337 ...
338
339 1.4.4. max_noninv_lifetime (integer)
340
341    Maximum time a non-INVITE transaction is allowed to be active (in
342    milliseconds). After this interval has passed from the transaction
343    creation, the transaction will be either moved into the wait state or
344    in the final response retransmission state, irrespective of the
345    transaction fr_timer value. It's the same as max_inv_lifetime, but for
346    non-INVITEs.
347
348    A non-INVITE transaction will be kept in memory for maximum:
349    max_noninv_lifetime+wt_timer.
350
351    The main difference between this timer and fr_timer is that the
352    fr_timer is per branch, while max_noninv_lifetime is per the whole
353    transaction. An example when a transaction can live substantially more
354    then its fr_timer and where max_noninv_lifetime will help is when dns
355    failover is used (each failed dns destination can introduce a new
356    branch).
357
358    The default value is 32000 ms (32 seconds - the rfc3261 timer F value).
359
360    See also: max_inv_lifetime, t_set_max_lifetime() (allows changing
361    max_noninv_lifetime on a per transaction basis), t_reset_max_lifetime
362    fr_timer, wt_timer.
363
364    Example 4. Set max_noninv_lifetime parameter
365 ...
366 modparam("tm", "max_inv_lifetime", 30000)
367 ...
368
369 1.4.5. wt_timer (integer)
370
371    Time for which a transaction stays in memory to absorb delayed messages
372    after it completed (in milliseconds); also, when this timer hits,
373    retransmission of local cancels is stopped (a puristic but complex
374    behavior would be not to enter wait state until local branches are
375    finished by a final reply or FR timer--we simplified).
376
377    Default value is 5000 ms (5 seconds).
378
379    Example 5. Set wt_timer parameter
380 ...
381 modparam("tm", "wt_timer", 1000)
382 ...
383
384 1.4.6. delete_timer (integer)
385
386    Time after which a to-be-deleted transaction currently ref-ed by a
387    process will be tried to be deleted again (in milliseconds).
388
389    Note: this parameter is obsolete for ser 2.1 (in 2.1 the transaction is
390    deleted the moment it's not referenced anymore).
391
392    Default value is 200 milliseconds.
393
394    Example 6. Set delete_timer parameter
395 ...
396 modparam("tm", "delete_timer", 100)
397 ...
398
399 1.4.7. retr_timer1 (integer)
400
401    Initial retransmission period (in milliseconds).
402
403    Default value is 500 milliseconds.
404
405    Example 7. Set retr_timer1 parameter
406 ...
407 modparam("tm", "retr_timer1", 1000)
408 ...
409
410 1.4.8. retr_timer2 (integer)
411
412    Maximum retransmission period (in milliseconds). The retransmission
413    interval starts with retr_timer1 and increases until it reaches this
414    value. After this it stays constant at retr_timer2.
415
416    Default value is 4000 milliseconds.
417
418    Example 8. Set retr_timer2 parameter
419 ...
420 modparam("tm", "retr_timer2", 2000)
421 ...
422
423 1.4.9. noisy_ctimer (integer)
424
425    If set, INVITE transactions that time-out (FR INV timer) will be always
426    replied. If it's not set, the transaction has only one branch and no
427    response was ever received on this branch, it will be silently dropped
428    (no 408 reply will be generated) This behavior is overridden if a
429    request is forked, the transaction has a failure route or callback, or
430    some functionality explicitly turned it on for a transaction (like acc
431    does to avoid unaccounted transactions due to expired timer). Turn this
432    off only if you know the client UACs will timeout and their timeout
433    interval for INVITEs is lower or equal than tm's fr_inv_timer.
434
435    Default value is 1 (on).
436
437    Example 9. Set noisy_ctimer parameter
438 ...
439 modparam("tm", "noisy_ctimer", 1)
440 ...
441
442 1.4.10. restart_fr_on_each_reply (integer)
443
444    If set (default), the fr_inv_timer for an INVITE transaction will be
445    restarted for each provisional reply received (rfc3261 mandated
446    behaviour). If not set, the fr_inv_timer will be restarted only for the
447    first provisional replies and for increasing replies greater or equal
448    180 (e.g. 180, 181, 182, 185, ...).
449
450    Setting it to 0 is especially useful when dealing with bad UAs that
451    continuously retransmit 180s, not allowing the transaction to timeout
452    (and thus making impossible the implementation of certain services,
453    like automatic voicemail after x seconds).
454
455    Default value is 1 (on).
456
457    See also: fr_inv_timer, max_inv_lifetime.
458
459    Example 10. Set restart_fr_on_each_reply parameter
460 ...
461 modparam("tm", "restart_fr_on_each_reply", 0)
462 ...
463
464 1.4.11. auto_inv_100 (integer)
465
466    If set (default) tm will automatically send and 100 reply to INVITEs.
467
468    Setting it to 0 one can be used to enable doing first some tests or
469    pre-processing on the INVITE and only if some conditions are met
470    manually send a 100 (using t_reply()). Note however that in this case
471    all the 100s have to be sent "by hand". t_set_auto_inv_100() might help
472    to selectively turn off this feature only for some specific
473    transactions.
474
475    Default value is 1 (on).
476
477    See also: t_set_auto_inv_100() auto_inv_100_reason.
478
479    Example 11. Set auto_inv_100 parameter
480 ...
481 modparam("tm", "auto_inv_100", 0)
482 ...
483
484 1.4.12. auto_inv_100_reason (string)
485
486    Set reason text of the automatically send 100 to an INVITE.
487
488    Default value is "trying -- your call is important to us".
489
490    See also: auto_inv_100.
491
492    Example 12. Set auto_inv_100_reason parameter
493 ...
494 modparam("tm", "auto_inv_100_reason", "Trying")
495 ...
496
497 1.4.13. unix_tx_timeout (integer)
498
499    Unix socket transmission timeout, in milliseconds.
500
501    If unix sockets are used (e.g.: to communicate with sems) and sending a
502    message on a unix socket takes longer then unix_tx_timeout, the send
503    will fail.
504
505    The default value is 500 milliseconds.
506
507    Example 13. Set unix_tx_timeout parameter
508 ...
509 modparam("tm", "unix_tx_timeout", 250)
510 ...
511
512 1.4.14. aggregate_challenges (integer)
513
514    If set (default), the final reply is a 401 or a 407 and more then one
515    branch received a 401 or 407, then all the WWW-Authenticate and
516    Proxy-Authenticate headers from all the 401 and 407 replies will be
517    aggregated in a new final reply. If only one branch received the
518    winning 401 or 407 then this reply will be forwarded (no new one will
519    be built). If 0 only the first 401, or if no 401 was received the first
520    407, will be forwarded (no header aggregation).
521
522    Default value is 1 (required by rfc3261).
523
524    Example 14. Set aggregate_challenges parameter
525 ...
526 modparam("tm", "aggregate_challenges", 0)
527 ...
528
529 1.4.15. reparse_invite (integer)
530
531    If set (default), the CANCEL and negative ACK requests are constructed
532    from the INVITE message which was sent out instead of building them
533    from the received request. The disadvantage is that the outgoing INVITE
534    has to be partially re-parsed, the advantage is that the CANCEL/ACK is
535    always RFC 3261-compliant, it always contains the same route-set as the
536    INVITE message. Do not disable the INVITE re-parsing for example in the
537    following cases:
538
539    - The INVITE contains a preloaded route-set, and SER forwards the
540    message to the next hop according to the Route header. The Route header
541    is not removed in the CANCEL without reparse_invite=1.
542
543    - SER record-routes, thus an in-dialog INVITE contains a Route header
544    which is removed during loose routing. If the in-dialog INVITE is
545    rejected, the negative ACK still contains the Route header without
546    reparse_invite=1.
547
548    Default value is 1.
549
550    Example 15. Set reparse_invite parameter
551 ...
552 modparam("tm", "reparse_invite", 0)
553 ...
554
555 1.4.16. ac_extra_hdrs (string)
556
557    Header fields prefixed by this parameter value are included in the
558    CANCEL and negative ACK messages if they were present in the outgoing
559    INVITE.
560
561    Note, that the parameter value effects only those headers which are not
562    covered by RFC-3261 (which are neither mandatory nor prohibited in
563    CANCEL and ACK), and the parameter can be used only together with
564    reparse_invite=1.
565
566    Default value is "".
567
568    Example 16. Set ac_extra_hdrs parameter
569 ...
570 modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
571 ...
572
573 1.4.17. blst_503 (integer)
574
575    If set and the blacklist support is enabled, every 503 reply source is
576    added to the blacklist. The initial blacklist timeout (or ttl) depends
577    on the presence of a Retry-After header in the reply and the values of
578    the following tm parameters: blst_503_def_timeout, blst_503_min_timeout
579    and blst_503_max_timeout.
580
581    WARNING:blindly allowing 503 blacklisting could be very easily
582    exploited for DOS attacks in most network setups.
583
584    The default value is 0 (disabled due to the reasons above).
585
586    Example 17. Set blst_503 parameter
587 ...
588 modparam("tm", "blst_503", 1)
589 ...
590
591 1.4.18. blst_503_def_timeout (integer)
592
593    Blacklist interval in seconds for a 503 reply with no Retry-After
594    header. See also blst_503, blst_503_min_timeout and
595    blst_503_max_timeout.
596
597    The default value is 0, which means that if no Retry-After header is
598    present, the 503 reply source will not be blacklisted (rfc conformant
599    behaviour).
600
601    Example 18. Set blst_503_def_timeout parameter
602 ...
603 modparam("tm", "blst_503_def_timeout", 120)
604 ...
605
606 1.4.19. blst_503_min_timeout (integer)
607
608    Minimum blacklist interval in seconds for a 503 reply with a
609    Retry-After header. It will be used if the Retry-After value is
610    smaller. See also blst_503, blst_503_def_timeout and
611    blst_503_max_timeout.
612
613    The default value is 0
614
615    Example 19. Set blst_503_min_timeout parameter
616 ...
617 modparam("tm", "blst_503_min_timeout", 30)
618 ...
619
620 1.4.20. blst_503_max_timeout (integer)
621
622    Maximum blacklist interval in seconds for a 503 reply with a
623    Retry-After header. It will be used if the Retry-After value is
624    greater. See also blst_503, blst_503_def_timeout and
625    blst_503_min_timeout.
626
627    The default value is 3600
628
629    Example 20. Set blst_503_max_timeout parameter
630 ...
631 modparam("tm", "blst_503_max_timeout", 604800)
632 ...
633
634 1.4.21. blst_methods_add (unsigned integer)
635
636    Bitmap of method types that trigger blacklisting on transaction
637    timeouts. (This setting has no effect on blacklisting because of send
638    failures.)
639
640    The following values are associated to the request methods: INVITE=1,
641    CANCEL=2, ACK=4 (not retransmitted, thus, never times-out), BYE=8,
642    INFO=16, REGISTER=32, SUBSCRIBE=64, NOTIFY=126, OTHER=256 (all the
643    unknown types). Check parser/msg_parser.h for farther details.
644
645    Change the value carefully, because requests not having provisional
646    response (everything but INVITE) can easily cause the next hop to be
647    inserted into the blacklist by mistake. For exmaple the next hop is a
648    proxy, it is alive, but waiting for the response of the UAS, and has
649    higher fr_timer value.
650
651    The default value is 1, only INVITEs trigger blacklisting
652
653    Example 21. Set blst_methods_add parameter
654 ...
655 # INVITEs and REGISTERs trigger blacklisting
656 modparam("tm", "blst_methods_add", 33)
657 ...
658
659 1.4.22. blst_methods_lookup (unsigned integer)
660
661    Bitmap of method types that are looked-up in the blacklist before
662    statefull forwarding. See also blst_methods_add
663
664    The default value is 4294967287, every method type except BYE. (We try
665    to deliver BYEs no matter what)
666
667    Example 22. Set blst_methods_lookup parameter
668 ...
669 # lookup only INVITEs
670 modparam("tm", "blst_methods_lookup", 1)
671 ...
672
673 1.4.23. cancel_b_method (integer)
674
675    Method used when attempting to CANCEL an unreplied transaction branch
676    (a branch where no reply greater the 99 was received). The possible
677    values are 0, 1, and 2.
678
679    0 will immediately stop the request (INVITE) retransmission on the
680    branch and it will behave as if the branch was immediately replied with
681    a 487 (a fake internal 487 reply). The advantage is the unreplied
682    branches will be terminated immediately. However it introduces a race
683    risk with a possible slightly delayed 2xx reply. In this case we could
684    have an UA receiving a 2xx after a 487. Moreover this risk is greatly
685    amplified by packet loss (e.g. if an 180 is lost the branch will look
686    as unreplied and a CANCEL will silently drop the branch, but a 2xx can
687    still come at a later time). This is the behaviour for ser versions
688    older then 2.1.
689
690    1 will keep retransmitting the request on unreplied branches. If a
691    provisional answer is later received a CANCEL will be immediately sent
692    back (attempting to quickly trigger a 487). This approach is race free
693    and avoids the 2xx after 487 problem, but it's more resource intensive:
694    faced with a branch towards and UA that doesn't answer, a CANCEL
695    attempt will keep the transaction alive for the whole timeout interval
696    (fr_timer).
697
698    2 will send and retransmit CANCEL even on unreplied branches, stopping
699    the request retransmissions. This has the same advantages as 1 and also
700    avoids the extra roundtrip in the case of the provisional reply, but
701    it's not RFC 3261 conforming (the RFC allows sending CANCELs only on
702    pending branches).
703
704    The default value is 1.
705
706    Example 23. Set cancel_b_method parameter
707 ...
708 modparam("tm", "cancel_b_method", 1)
709 ...
710
711 1.4.24. reparse_on_dns_failover (integer)
712
713    If set to 1, the SIP message after a DNS failover is constructed from
714    the outgoing message buffer of the failed branch instead of from the
715    received request.
716
717    It must be set if multiple branches are installed, the SIP message is
718    modified differently in them, and at least one of them can result in
719    DNS failover. If the parameter is not set the per-branch modifications
720    are lost after the failover.
721
722    Note: If the parameter is set, branch route block and
723    TMCB_REQUEST_FWDED callback are not called in case of the failover.
724
725    Disadvantage: only the via header is replaced in the message buffer, so
726    the outgoing socket address is not corrected in any other part of the
727    message. It is dangerous on multihomed hosts: when the new SIP request
728    after the DNS failover is sent via different interface than the first
729    request, the message can contain incorrect ip address in the
730    Record-Route header for instance.
731
732    Default value is 1.
733
734    Example 24. Set reparse_on_dns_failover parameter
735 ...
736 modparam("tm", "reparse_on_dns_failover", 0)
737 ...
738
739 1.4.25. on_sl_reply (string)
740
741    Sets reply route block, to which control is passed when a reply is
742    received that has no associated transaction. The reply is passed to the
743    core for stateless forwarding after the route block execution unless it
744    returns 0.
745
746    Example 25. Set on_sl_reply parameter
747 ...
748 modparam("tm", "on_sl_reply", "stateless_replies")
749 ...
750
751 onreply_route["stateless_replies"] {
752         # do not allow stateless replies to be forwarded
753         return 0;
754 }
755
756 1.4.26. fr_inv_timer_next (integer)
757
758    This parameter can be used to configure an alternative value for the
759    fr_inv_timer timer. This alternative value is used in place of
760    fr_inv_timer when serial forking takes place. It is used for all
761    branches during serial forking except the last one. The last branch (or
762    a set of parallel branches) use the original value from fr_inv_timer
763    again.
764
765    The purpose of the timer is to allow an administrator to configure a
766    shorter version of fr_inv_timer that is used only when serial forking
767    takes place. Forwarding branches one after another is much more time
768    consuming, because every serial branch has to wait for the result of
769    the previous one. That can take up to the value of fr_inv_timer and
770    this timer is configured to two minutes by default. Hence, if you have
771    three serial branches then completing the transaction can take six
772    minutes with default timer values.
773
774    In practise, the transaction will be terminated sooner, because the
775    timer max_inv_lifetime hits after three minutes. Thus, some of the
776    serial branches might not be forwarded at all. And this is exactly what
777    fr_inv_timer_next is for. You can configure the timer to a shorter
778    value to ensure that all serial branches are tried before the timer
779    max_inv_lifetime hits.
780
781    Note that if there is only one branch or if the current serial branch
782    is the last one (i.e. no more serial forking takes place after this
783    branch is finished) then fr_inv_timer_next is not used, instead the
784    branch uses the longer fr_inv_timer.
785
786    Function t_next_contacts() sets fr_inv_timer to fr_inv_timer_next if
787    serial forking takes place and there is more than one serial branch.
788
789    The administrator can configure the value of this timer using the
790    configuration framework on the fly. But unlike fr_inv_timer, it is not
791    possible to configure the value of this timer on per-transaction basis.
792
793    The value of this timer is to be specified in milliseconds. The default
794    value is 30000ms.
795
796    Example 26. Set fr_inv_timer_next parameter
797 ...
798 modparam("tm", "fr_inv_timer_next", 10000)
799 ...
800
801 1.4.27. contacts_avp (string)
802
803    This is the name or Id of an AVP that t_load_contacts() function uses
804    to store contacts of the destination set and that t_next_contacts()
805    function uses to restore those contacts.
806
807    Default value is "NULL" (t_load_contacts()/t_next_contacts() functions
808    are disabled).
809
810    Example 27. Set contacts_avp parameter
811 ...
812 modparam("tm", "contacts_avp", "$avp(i:25)")
813 ...
814
815 1.4.28. fr_timer_avp (string)
816
817    The value of fr_timer timer can be overriden on per-transaction basis.
818    The administrator can provide a value to be used for a particular
819    transaction in an AVP. This parameter contains the name of the AVP that
820    will be checked. If the AVP exists then its value will be used for the
821    fr_timer timer, effectively overriding the value configured in fr_timer
822    parameter for the current transaction.
823
824    The value of this parameter is the the name of the AVP to be checked,
825    without the $ character or "$avp" prefix.
826
827 Note
828
829    The value of the AVP is expected to be expressed in seconds and not
830    milliseconds (unlike the rest of the timers).
831
832    This parameter is kept for backwards compatibility (hence its value
833    expressed in seconds instead of milliseconds and its arcane way of
834    specifying the avps). The recommended replacement is using t_set_fr()
835    on a per transaction basis.
836
837    See also: t_set_fr(), fr_timer.
838
839    Example 28. Set fr_timer_avp parameter
840 ...
841 modparam("tm", "fr_timer_avp", "i:708")
842 ...
843
844 1.4.29. fr_inv_timer_avp (string)
845
846    The value of fr_inv_timer timer can be overriden on per-transaction
847    basis. The administrator can provide a value to be used for a
848    particular transaction in an AVP. This parameter contains the name of
849    the AVP that will be checked. If the AVP exists, is non-empty and
850    non-zero then its value will be used for the fr_inv_timer timer,
851    effectively overriding the value configured in fr_inv_timer parameter
852    for the current transaction.
853
854    The value of this parameter is the the name of the AVP to be checked,
855    without the $ character or "$avp" prefix.
856
857 Note
858
859    The value of the AVP is expected to be expressed in seconds and not
860    milliseconds (unlike the rest of the timers).
861
862    This parameter is kept for backwards compatibility (hence its value
863    expressed in seconds instead of milliseconds and its arcane way of
864    specifying the avps). The recommended replacement is using t_set_fr()
865    on a per transaction basis.
866
867    See also: t_set_fr(), fr_inv_timer.
868
869    Example 29. Set fr_inv_timer_avp parameter
870 ...
871 modparam("tm", "fr_inv_timer_avp", "my_fr_inv_timer")
872 ...
873
874 1.4.30. unmatched_cancel (string)
875
876    This parameter selects between forwarding CANCELs that do not match any
877    transaction statefully (0, default value), statelessly (1) or dropping
878    them (2). Note that the statefull forwarding has an additional hidden
879    advantage: tm will be able to recognize INVITEs that arrive after their
880    CANCEL. Note also that this feature could be used to try a memory
881    exhaustion DOS attack against a proxy that authenticates all requests,
882    by continuously flooding the victim with CANCELs to random destinations
883    (since the CANCEL cannot be authenticated, each received bogus CANCEL
884    will create a new transaction that will live by default 30s).
885
886    Default value is 0.
887
888    Example 30. Set unmatched_cancel parameter
889 ...
890 modparam("tm", "unmatched_cancel", "2")
891 ...
892
893 1.4.31. ruri_matching (integer)
894
895    If set it will also try to match the request uri when doing pre-3261
896    transaction matching (the via branch parameter does not contain the
897    3261 cookie).
898
899    The only reason to have it not set is for interoperability with old,
900    broken implementations.
901
902    Default value is 1 (on).
903
904    Can be set at runtime, e.g.:
905         $ sercmd cfg.set_now_int tm ruri_matching 0
906
907    Example 31. Set ruri_matching parameter
908 ...
909 modparam("tm", "ruri_matching", 1)
910 ...
911
912 1.4.32. via1_matching (integer)
913
914    If set it will also try to match the topmost via when doing pre-3261
915    transaction matching (the via branch parameter does not contain the
916    3261 cookie).
917
918    The only reason to have it not set is for interoperability with old,
919    broken implementations.
920
921    Default value is 1 (on).
922
923    Can be set at runtime, e.g.:
924         $ sercmd cfg.set_now_int tm via1_matching 0
925
926    Example 32. Set via1_matching parameter
927 ...
928 modparam("tm", "via1_matching", 1)
929 ...
930
931 1.4.33. pass_provisional_replies (integer)
932
933    If set, TMCB_LOCAL_REPONSE_OUT tm registered callbacks will be called
934    also for provisional replies.
935
936    Default value is 0 (off).
937
938    Can be set at runtime, e.g.:
939         $ sercmd cfg.set_now_int tm pass_provisional_replies 1
940
941    Example 33. Set pass_provisional_replies parameter
942 ...
943 modparam("tm", "pass_provisional_replies", 1)
944 ...
945
946 1.4.34. default_code (integer)
947
948    Default response code sent by t_reply() if it cannot retrieve its
949    parameters (e.g. inexistent avp). Valid values are between 400 and 699.
950
951    Default value is 500.
952
953    Can be set at runtime, e.g.:
954         $ sercmd cfg.set_now_int tm default_code 505
955
956    Example 34. Set default_code parameter
957 ...
958 modparam("tm", "default_code", 501)
959 ...
960
961 1.4.35. default_reason (string)
962
963    Default SIP reason phrase sent by t_reply() if it cannot retrieve its
964    parameters (e.g. inexistent avp).
965
966    Default value is "Server Internal Error".
967
968    Can be set at runtime, e.g.:
969         $ sercmd cfg.set_now_string tm default_reason "Unknown error"
970
971    Example 35. Set default_reason parameter
972 ...
973 modparam("tm", "default_reason", "Unknown reason")
974 ...
975
976 1.4.36. disable_6xx_block (integer)
977
978    If set tm will treat all the 6xx replies like normal replies (warning:
979    this would be non-rfc conformant behaviour).
980
981    If not set (default) receiving a 6xx will cancel all the running
982    parallel branches, will stop dns failover and forking. However serial
983    forking using append_branch() in the failure_route will still work.
984
985    It can be overwritten on a per transaction basis using
986    t_set_disable_6xx().
987
988    Default value is 0 (off, rfc conformant behaviour).
989
990    Can be set at runtime, e.g.:
991         $ sercmd cfg.set_now_int tm disable_6xx_block 0
992
993    See also: t_set_disable_6xx().
994
995    Example 36. Set disable_6xx_block parameter
996 ...
997 modparam("tm", "disable_6xx_block", 1)
998 ...
999
1000 1.5. Functions
1001
1002    Revision History
1003    Revision $Revision$ $Date$
1004
1005 1.5.1.  t_relay_to_udp(ip, port), t_relay_to_udp(), t_relay_to_tcp(ip, port)
1006 t_relay_to_tcp() t_relay_to_tls(ip, port) t_relay_to_tls()
1007 t_relay_to_sctp(ip, port) t_relay_to_sctp()
1008
1009    Relay a message statefully using a fixed protocol either to the
1010    specified fixed destination or to a destination derived from the
1011    message uri (if the host address and port are not specified). These
1012    along with t_relay are the functions most users want to use--all other
1013    are mostly for programming. Programmers interested in writing TM logic
1014    should review how t_relay is implemented in tm.c and how TM callbacks
1015    work.
1016
1017    Meaning of the parameters is as follows:
1018      * ip - IP address where the message should be sent.
1019      * port - Port number.
1020
1021    If no parameters are specified the message is sent to a destination
1022    derived from the message uri (using sip sepcific DNS lookups), but with
1023    the protocol corresponding to the function name.
1024
1025    Example 37. t_relay_to_udp usage
1026 ...
1027 if (src_ip==10.0.0.0/8)
1028         t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
1029 else
1030         t_relay_to_tcp(); # relay to msg. uri, but over tcp
1031 ...
1032
1033 1.5.2.  t_relay() t_relay(host, port)
1034
1035    Relay a message statefully either to the destination indicated in the
1036    current URI (if called without any parameters) or to the specified host
1037    and port. In the later case (host and port specified) the protocol used
1038    is the same protocol on which the message was received.
1039
1040    t_relay() is the statefull version for forward(uri:host, uri:port)
1041    while t_relay(host, port) is similar to forward(host, port).
1042
1043    In the forward to uri case (t_relay()), if the original URI was
1044    rewritten (by UsrLoc, RR, strip/prefix, etc.) the new URI will be
1045    taken). The destination (including the protocol) is determined from the
1046    uri, using SIP specific DNS resolving if needed (NAPTR, SRV a.s.o
1047    depending also on the dns options).
1048
1049    Returns a negative value on failure--you may still want to send a
1050    negative reply upstream statelessly not to leave upstream UAC in lurch.
1051
1052    Example 38. t_relay usage
1053 ...
1054 if (!t_relay())
1055 {
1056     sl_reply_error();
1057     break;
1058 };
1059 ...
1060
1061 1.5.3.  t_on_failure(failure_route)
1062
1063    Sets failure routing block, to which control is passed after a
1064    transaction completed with a negative result but before sending a final
1065    reply. In the referred block, you can either start a new branch (good
1066    for services such as forward_on_no_reply) or send a final reply on your
1067    own (good for example for message silo, which received a negative reply
1068    from upstream and wants to tell upstream "202 I will take care of it").
1069    Note that the set of commands which are usable within failure_routes is
1070    strictly limited to rewriting URI, initiating new branches, logging,
1071    and sending stateful replies (t_reply). Any other commands may result
1072    in unpredictable behavior and possible server failure. Note that
1073    whenever failure_route is entered, uri is reset to value which it had
1074    on relaying. If it temporarily changed during a reply_route processing,
1075    subsequent reply_route will ignore the changed value and use again the
1076    original one.
1077
1078    Meaning of the parameters is as follows:
1079      * failure_route - Failure route block to be called.
1080
1081    Example 39. t_on_failure usage
1082 ...
1083 route {
1084     t_on_failure("1");
1085     t_relay();
1086 }
1087
1088 failure_route[1] {
1089     revert_uri();
1090     setuser("voicemail");
1091     append_branch();
1092 }
1093 ...
1094
1095    See test/onr.cfg for a more complex example of combination of serial
1096    with parallel forking.
1097
1098 1.5.4.  t_on_reply(onreply_route)
1099
1100    Sets the reply routing block, to which control is passed when a reply
1101    for the current transaction is received. Note that the set of commands
1102    which are usable within onreply_routes is limited.
1103
1104    Meaning of the parameters is as follows:
1105      * onreply_route - Onreply route block to be called.
1106
1107    Example 40. t_on_reply usage
1108 ...
1109 loadmodule "/usr/local/lib/ser/modules/nathelper.so"
1110 ...
1111 route {
1112         /* if natted */
1113         t_on_reply("1");
1114         t_relay();
1115 }
1116
1117 onreply_route[1] {
1118         if (status=~ "(183)|2[0-9][0-9]"){
1119                 force_rtp_proxy();
1120                 search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=y
1121 es');
1122         }
1123         if (nat_uac_test("1")){
1124                 fix_nated_contact();
1125         }
1126 }
1127
1128 1.5.5.  t_on_branch(branch_route)
1129
1130    Sets the branch routing block, to which control is passed after forking
1131    (when a new branch is created). For now branch routes are intended only
1132    for last minute changes of the SIP messages (like adding new headers).
1133    Note that the set of commands which are usable within branch_routes is
1134    very limited. It is not possible to drop a message or generate a reply.
1135
1136    Meaning of the parameters is as follows:
1137      * branch_route - branch route block to be called.
1138
1139    Example 41. t_on_branch usage
1140 ...
1141 route {
1142         t_on_branch("1");
1143         t_relay();
1144 }
1145
1146 branch_route[1] {
1147         if (uri=~"sip:[0-9]+"){
1148                 append_hf("P-Warn: numeric uri\r\n");
1149         }
1150 }
1151
1152 1.5.6.  append_branch()
1153
1154    Similarly to t_fork_to, it extends destination set by a new entry. The
1155    difference is that current URI is taken as new entry.
1156
1157    Example 42. append_branch usage
1158 ...
1159 set_user("john");
1160 t_fork();
1161 set_user("alice");
1162 t_fork();
1163 t_relay();
1164 ...
1165
1166 1.5.7.  t_newtran()
1167
1168    Creates a new transaction, returns a negative value on error. This is
1169    the only way a script can add a new transaction in an atomic way.
1170    Typically, it is used to deploy a UAS.
1171
1172    Example 43. t_newtran usage
1173 ...
1174 if (t_newtran()) {
1175     log("UAS logic");
1176     t_reply("999","hello");
1177 } else sl_reply_error();
1178 ...
1179
1180    See test/uas.cfg for more examples.
1181
1182 1.5.8.  t_reply(code, reason_phrase)
1183
1184    Sends a stateful reply after a transaction has been established. See
1185    t_newtran for usage.
1186
1187    Meaning of the parameters is as follows:
1188      * code - Reply code number.
1189      * reason_phrase - Reason string.
1190
1191    Example 44. t_reply usage
1192 ...
1193 t_reply("404", "Not found");
1194 ...
1195
1196 1.5.9.  t_lookup_request()
1197
1198    Checks if a transaction exists. Returns a positive value if so,
1199    negative otherwise. Most likely you will not want to use it, as a
1200    typical application of a look-up is to introduce a new transaction if
1201    none was found. However this is safely (atomically) done using
1202    t_newtran.
1203
1204    Example 45. t_lookup_request usage
1205 ...
1206 if (t_lookup_request()) {
1207     ...
1208 };
1209 ...
1210
1211 1.5.10.  t_retransmit_reply()
1212
1213    Retransmits a reply sent previously by UAS transaction.
1214
1215    Example 46. t_retransmit_reply usage
1216 ...
1217 t_retransmit_reply();
1218 ...
1219
1220 1.5.11.  t_release()
1221
1222    Remove transaction from memory (it will be first put on a wait timer to
1223    absorb delayed messages).
1224
1225    Example 47. t_release usage
1226 ...
1227 t_release();
1228 ...
1229
1230 1.5.12.  t_forward_nonack() t_forward_nonack(ip, port)
1231 t_forward_nonack_udp(ip, port) t_forward_nonack_tcp(ip, port)
1232 t_forward_nonack_tls(ip, port) t_forward_nonack_sctp(ip, port)
1233
1234    mainly for internal usage--forward a non-ACK request statefully.
1235
1236    Meaning of the parameters is as follows:
1237      * ip - IP address where the message should be sent.
1238      * port - Port number.
1239
1240    Example 48. t_forward_nonack usage
1241 ...
1242 t_forward_nonack("1.2.3.4", "5060");
1243 ...
1244
1245 1.5.13.  t_set_fr(fr_inv_timeout [, fr_timeout])
1246
1247    Sets the fr_inv_timeout and optionally fr_timeout for the current
1248    transaction or for transactions created during the same script
1249    invocation, after calling this function. If the transaction is already
1250    created (e.g called after t_relay() or in an onreply_route) all the
1251    branches will have their final response timeout updated on-the-fly. If
1252    one of the parameters is 0, its value won't be changed.
1253
1254    Meaning of the parameters is as follows:
1255      * fr_inv_timeout - new final response timeout (in milliseconds) for
1256        INVITEs. See also fr_inv_timer.
1257        fr_timeout - new final response timeout (in milliseconds) for
1258        non-INVITE transaction, or INVITEs which haven't received yet a
1259        provisional response. See also fr_timer.
1260
1261    See also: fr_timer, fr_inv_timer, t_reset_fr().
1262
1263    Example 49. t_set_fr usage
1264 ...
1265 route {
1266         t_set_fr(10000); # set only fr invite timeout to 10s
1267         t_on_branch("1");
1268         t_relay();
1269 }
1270
1271 branch_route[1] {
1272         # if we are calling the pstn, extend the invite timeout to 50s
1273         # for all the branches, and set the no-reply-received timeout to 2s
1274         if (uri=~"sip:[0-9]+"){
1275                 t_set_fr(50000, 2000);
1276         }
1277 }
1278
1279 1.5.14.  t_reset_fr()
1280
1281    Resets the fr_inv_timer and fr_timer for the current transaction to the
1282    default values (set using the tm module parameters fr_inv_timer and
1283    fr_timer).
1284
1285    It will effectively cancel any previous calls to t_set_fr for the same
1286    transaction.
1287
1288    See also: fr_timer, fr_inv_timer, t_set_fr.
1289
1290    Example 50. t_reset_fr usage
1291 ...
1292 route {
1293 ...
1294                 t_reset_fr();
1295 ...
1296 }
1297
1298 1.5.15.  t_set_max_lifetime(inv_lifetime, noninv_lifetime)
1299
1300    Sets the maximum lifetime for the current INVITE or non-INVITE
1301    transaction, or for transactions created during the same script
1302    invocation, after calling this function (that's why it takes values for
1303    both INVITE and non-INVITE). If one of the parameters is 0, its value
1304    won't be changed.
1305
1306    It works as a per transaction max_inv_lifetime or max_noninv_lifetime.
1307
1308    Meaning of the parameters is as follows:
1309      * inv_lifetime - maximum INVITE transaction lifetime (in
1310        milliseconds). See also max_inv_lifetime.
1311        noninv_lifetime - maximum non-INVITE transaction lifetime (in
1312        milliseconds). See also max_noninv_lifetime.
1313
1314    See also: max_inv_lifetime, max_noninv_lifetime, t_reset_max_lifetime.
1315
1316    Example 51. t_set_max_lifetime usage
1317 ...
1318 route {
1319     if (src_ip=1.2.3.4)
1320         t_set_max_lifetime(120000, 0); # set only max_inv_lifetime to 120s
1321     else
1322         t_set_max_lifetime(90000, 15000); # set the maximum lifetime to 90s if
1323                                           # the current transaction is an
1324                                           # INVITE and to 15s if not
1325 }
1326
1327 1.5.16.  t_reset_max_lifetime()
1328
1329    Resets the the maximum lifetime for the current INVITE or non-INVITE
1330    transaction to the default value (set using the tm module parameter
1331    max_inv_lifetime or max_noninv_lifetime).
1332
1333    It will effectively cancel any previous calls to t_set_max_lifetime for
1334    the same transaction.
1335
1336    See also: max_inv_lifetime, max_noninv_lifetime, t_set_max_lifetime.
1337
1338    Example 52. t_reset_max_lifetime usage
1339 ...
1340 route {
1341 ...
1342                 t_reset_max_lifetime();
1343 ...
1344 }
1345
1346 1.5.17.  t_set_retr(retr_t1_interval, retr_t2_interval)
1347
1348    Sets the retr_t1_interval and retr_t2_interval for the current
1349    transaction or for transactions created during the same script
1350    invocation, after calling this function. If one of the parameters is 0,
1351    it's value won't be changed. If the transaction is already created (e.g
1352    called after t_relay() or in an onreply_route) all the existing
1353    branches will have their retransmissions intervals updated on-the-fly:
1354    if the retransmission interval for the branch has not yet reached T2
1355    the interval will be reset to retr_t1_interval, else to
1356    retr_t2_interval. Note that the change will happen after the current
1357    interval expires (after the next retransmission, the next-next
1358    retransmission will take place at retr_t1_interval or
1359    retr_t2_interval). All new branches of the same transaction will start
1360    with the new values. This function will work even if it's called in the
1361    script before a transaction creating function (e.g.: t_set_retr(500,
1362    4000); t_relay()). All new transaction created after this function
1363    call, during the same script invocation will use the new values. Note
1364    that this function will work only if tm is compile with
1365    -DTM_DIFF_RT_TIMEOUT (which increases every transaction size with 4
1366    bytes).
1367
1368    Meaning of the parameters is as follows:
1369      * retr_t1_interval - new T1 retransmission interval (in
1370        milliseconds). See also retr_t1_timeout.
1371        retr_t2_interval - new T2 (or maximum) retransmission interval (in
1372        milliseconds). See also retr_t2_timeout.
1373
1374    See also: retr_timer1, retr_timer2, t_reset_retr().
1375
1376    Example 53. t_set_retr usage
1377 ...
1378 route {
1379         t_set_retr(250, 0); # set only T1 to 250 ms
1380         t_on_branch("1");
1381         t_relay();
1382 }
1383
1384 branch_route[1] {
1385         # if we are calling the a remote pstn, extend T1 and decrease T2
1386         # for all the branches
1387         if (uri=~"sip:[0-9]+"){
1388                 t_set_retr(500, 2000);
1389         }
1390 }
1391
1392 1.5.18.  t_reset_retr()
1393
1394    Resets the retr_timer1 and retr_timer2 for the current transaction to
1395    the default values (set using the tm module parameters retr_timer1 and
1396    retr_timer2).
1397
1398    It will effectively cancel any previous calls to t_set_retr for the
1399    same transaction.
1400
1401    See also: retr_timer1, retr_timer2, t_set_retr.
1402
1403    Example 54. t_reset_retr usage
1404 ...
1405 route {
1406 ...
1407                 t_reset_retr();
1408 ...
1409 }
1410
1411 1.5.19.  t_set_auto_inv_100(0|1)
1412
1413    Switch automatically sending 100 replies to INVITEs on/off on a per
1414    transaction basis. It overrides the auto_inv_100 value for the current
1415    transaction.
1416
1417    See also: auto_inv_100.
1418
1419    Example 55. t_set_auto_inv_100 usage
1420 ...
1421 route {
1422 ...
1423         if (src_ip==1.2.3.0/24)
1424                 t_set_auto_inv_100(0); # turn off automatic 100 replies
1425 ...
1426 }
1427
1428 1.5.20.  t_branch_timeout()
1429
1430    Returns true if the failure route is executed for a branch that did
1431    timeout. It can be used only from the failure_route.
1432
1433    Example 56. t_branch_timeout usage
1434 ...
1435 failure_route[0]{
1436         if (t_branch_timeout()){
1437                 log("timeout\n");
1438                 # ...
1439         }
1440 }
1441
1442 1.5.21.  t_branch_replied()
1443
1444    Returns true if the failure route is executed for a branch that did
1445    receive at least one reply in the past (the "current" reply is not
1446    taken into account). It can be used only from the failure_route.
1447
1448    Example 57. t_branch_replied usage
1449 ...
1450 failure_route[0]{
1451         if (t_branch_timeout()){
1452                 if (t_branch_replied())
1453                         log("timeout after receiving a reply (no answer?)\n");
1454                 else
1455                         log("timeout, remote side seems to be down\n");
1456                 # ...
1457         }
1458 }
1459
1460 1.5.22.  t_any_timeout()
1461
1462    Returns true if at least one of the current transactions branches did
1463    timeout.
1464
1465    Example 58. t_any_timeout usage
1466 ...
1467 failure_route[0]{
1468         if (!t_branch_timeout()){
1469                 if (t_any_timeout()){
1470                         log("one branch did timeout\n");
1471                         sl_send_reply("408", "Timeout");
1472                 }
1473         }
1474 }
1475
1476 1.5.23.  t_any_replied()
1477
1478    Returns true if at least one of the current transactions branches did
1479    receive some reply in the past. If called from a failure or onreply
1480    route, the "current" reply is not taken into account.
1481
1482    Example 59. t_any_replied usage
1483 ...
1484 onreply_route[0]{
1485         if (!t_any_replied()){
1486                 log("first reply received\n");
1487                 # ...
1488         }
1489 }
1490
1491 1.5.24.  t_grep_status("code")
1492
1493    Returns true if "code" is the final reply received (or locally
1494    generated) in at least one of the current transactions branches.
1495
1496    Example 60. t_grep_status usage
1497 ...
1498 onreply_route[0]{
1499         if (t_grep_status("486")){
1500                 /* force a 486 reply, even if this is not the winning branch */
1501                 t_reply("486", "Busy");
1502         }
1503 }
1504
1505 1.5.25.  t_is_canceled()
1506
1507    Returns true if the current transaction was canceled.
1508
1509    Example 61. t_is_canceled usage
1510 ...
1511 failure_route[0]{
1512         if (t_is_canceled()){
1513                 log("transaction canceled\n");
1514                 # ...
1515         }
1516 }
1517
1518 1.5.26.  t_is_expired()
1519
1520    Returns true if the current transaction has already been expired, i.e.
1521    the max_inv_lifetime/max_noninv_lifetime interval has already elapsed.
1522
1523    Example 62. t_is_expired usage
1524 ...
1525 failure_route[0]{
1526         if (t_is_expired()){
1527                 log("transaction expired\n");
1528                 # There is no point in adding a new branch.
1529         }
1530 }
1531
1532 1.5.27.  t_relay_cancel()
1533
1534    Forwards the CANCEL if the corresponding INVITE transaction exists. The
1535    function is supposed to be used at the very beginning of the script,
1536    because the CANCELs can be caught and the rest of the script can be
1537    bypassed this way. Do not disable reparse_invite module parameter, and
1538    call t_relay_cancel() right after the sanity tests.
1539
1540    Return value is 0 (drop) if the corresponding INVITE was found and the
1541    CANCELs were successfully sent to the pending branches, true if the
1542    INVITE was not found, and false in case of any error.
1543
1544    Example 63. t_relay_cancel usage
1545 if (method == CANCEL) {
1546         if (!t_relay_cancel()) {  # implicit drop if relaying was successful,
1547                                   # nothing to do
1548
1549                 # corresponding INVITE transaction found but error occurred
1550                 sl_reply("500", "Internal Server Error");
1551                 drop;
1552         }
1553         # bad luck, corresponding INVITE transaction is missing,
1554         # do the same as for INVITEs
1555 }
1556
1557 1.5.28.  t_lookup_cancel(), t_lookup_cancel(1)
1558
1559    Returns true if the corresponding INVITE transaction exists for a
1560    CANCEL request. The function can be called at the beginning of the
1561    script to check whether or not the CANCEL can be immediately forwarded
1562    bypassing the rest of the script. Note however that t_relay_cancel
1563    includes t_lookup_cancel as well, therefore it is not needed to
1564    explicitly call this function unless something has to be logged for
1565    example.
1566
1567    If the function parameter (optional) is set to 1, the message flags are
1568    overwritten with the flags of the INVITE. isflagset() can be used to
1569    check the flags of the previously forwarded INVITE in this case.
1570
1571    Example 64. t_lookup_cancel usage
1572 if (method == CANCEL) {
1573         if (t_lookup_cancel()) {
1574                 log("INVITE transaction exists");
1575                 if (!t_relay_cancel()) {  # implicit drop if
1576                                           # relaying was successful,
1577                                           # nothing to do
1578
1579                         # corresponding INVITE transaction found
1580                         # but error occurred
1581                         sl_reply("500", "Internal Server Error");
1582                         drop;
1583                 }
1584         }
1585         # bad luck, corresponding INVITE transaction is missing,
1586         # do the same as for INVITEs
1587 }
1588
1589 1.5.29.  t_drop_replies()
1590
1591    Drops all the previously received replies in failure_route block to
1592    make sure that none of them is picked up again. Works only if a new
1593    branch is added to the transaction, or it is explicitly replied in the
1594    script!
1595
1596    Example 65. t_drop_replies() usage
1597 ...
1598 failure_route[0]{
1599         if (t_check_status("5[0-9][0-9]")){
1600                 # I do not like the 5xx responses,
1601                 # so I give another chance to "foobar.com",
1602                 # and I drop all the replies to make sure that
1603                 # they are not forwarded to the caller.
1604                 t_drop_replies();
1605
1606                 rewritehostport("foobar.com");
1607                 append_branch();
1608                 t_relay();
1609         }
1610 }
1611
1612 1.5.30.  t_save_lumps()
1613
1614    Forces the modifications of the processed SIP message to be saved in
1615    shared memory before t_relay() is called. The new branches which are
1616    created in failure_route will contain the same modifications, and any
1617    other modification after t_save_lumps() will be lost.
1618
1619    Note that t_relay() automatically saves the modifications when it is
1620    called the first time, there is no need for t_save_lumps() unless
1621    message changes between t_save_lumps() and t_relay() must not be
1622    propagated to failure_route.
1623
1624    The transaction must be created by t_newtran() before calling
1625    t_save_lumps().
1626
1627    Example 66. t_save_lumps() usage
1628 route {
1629         ...
1630         t_newtran();
1631         append_hf("hf1: my first header\r\n");
1632         ...
1633         t_save_lumps();
1634         append_hf("hf2: my second header\r\n");
1635         ...
1636         t_on_failure("1");
1637         t_relay();
1638 }
1639
1640 failure_route[1] {
1641         append_branch();
1642         append_hf("hf3: my third header\r\n");
1643         #
1644         # This branch contains hf1 and hf3, but does
1645         # not contain hf2 header.
1646         # hf2 would be also present here without
1647         # t_save_lumps().
1648         ...
1649         t_relay();
1650 }
1651
1652 1.5.31.  t_load_contacts()
1653
1654    This is the first of the two functions that can be used to implement
1655    serial/parallel forking based on the q value of individual branches in
1656    a destination set.
1657
1658    The function t_load_contacts() takes all branches from the current
1659    destination set and encodes them into the AVP whose name or ID is
1660    configured with the parameter contacts_avp. Note that you have to
1661    configure this parameter before you can use the function, the parameter
1662    is set to NULL by default, which disables the function.
1663
1664    If the destination set contains only one branch (the Request-URI) or if
1665    all branches have the same q value then the function does nothing to
1666    minimize performance impact. In such case all branches should be tried
1667    in parallel and that is the default mode of operation of functions like
1668    t_relay(), so there is no need to create the AVP or sort the branches.
1669
1670    If the current destination set contains more than one branch and not
1671    all branches have the same q value then the function sorts them
1672    according to the increasing value of the q parameter. The resulting
1673    sorted list of branches is then encoded into the AVP.
1674
1675    The q parameter contains a value from a range of 0 to 1.0 and it
1676    expresses relative preferrence of the branch among all branches in the
1677    destination set. The higher the q value the more preferrence the user
1678    agent gave to the branch. Branches with higher q values will be tried
1679    first when serial forking takes place.
1680
1681    After that the function clears all branches and you have to call
1682    t_next_contacts to retrieve them sorted according to their q value.
1683    Note that if you use t_load_contacts then you also have to use
1684    t_next_contacts before calling t_relay.
1685
1686    The AVP created by the function may contain multiple values, with one
1687    encoded branch per value. The first value will contain the branch with
1688    the highest q value. Each value contains the Request-URI, the
1689    destination URI, the path vector, the outgoing socket description and
1690    branch flags. All these fields are delimited with the LF character.
1691
1692    The function returns 1 if loading of contacts succeeded or there was
1693    nothing to do. Returns -1 on error (see syslog).
1694
1695    This function can be used from REQUEST_ROUTE.
1696
1697    Example 67. t_load_contacts usage
1698 ...
1699 if (!t_load_contacts()) {
1700         sl_send_reply("500", "Server Internal Error - Cannot load contacts");
1701         exit;
1702 };
1703 ...
1704
1705 1.5.32.  t_next_contacts()
1706
1707    The function t_next_contacts is the second of the two functions that
1708    can be used to implement serial/parallel forking based on the q value
1709    of individual branches in a destination set.
1710
1711    This function takes the AVP created by t_load_contacts and extracts
1712    branches with highest q value from it into the destination set when
1713    called for the first time. When you call the function second time it
1714    extracts branches with lower q value, and so on until all branches have
1715    been extracted.
1716
1717    If no transaction exist when t_next_contacts() is called, this usually
1718    happens when you call the function from a request route block before
1719    you call t_relay, it replaces the Request-URI with the first
1720    contacts_avp value, adds the remaining contacts_avp values with the
1721    same q value as branches, and destroys those AVPs.
1722
1723    If transaction does exist when t_next_contacts() is called, it adds the
1724    first contacts_avp value and all following contacts_avp values with the
1725    same q value as new branches to request and destroys those AVPs.
1726
1727    When you call the function repeatedly from a failure_route branch, it
1728    looks for more AVP values each time and adds branches that have same q
1729    value from the AVP as additional destination set branches. It always
1730    stops when it reaches a branch that has a lower q value. Used AVP
1731    values are always destroyed.,
1732
1733    The function does nothing if there are no contact_avp values.
1734
1735    The function returns 1 if there were no errors and -1 if an error
1736    occurred (see syslog). This function can be used from REQUEST_ROUTE and
1737    FAILURE_ROUTE.
1738
1739    Note that if use use t_load_contacts and t_next_contacts functions then
1740    you should also set the value of restart_fr_on_each_reply parameter to
1741    0. If you do not do that then it can happen that a broken user agent
1742    that retransmits 180 periodically will keep resetting the fr_inv_timer
1743    value and serial forking never happens.
1744
1745    Also make sure that you configured fr_inv_timer_next with lower value,
1746    especially if you expect to have many serially forked branches. See the
1747    documentation of that parameter for more details.
1748
1749    Example 68. t_next_contacts usage
1750 ...
1751 # First call after t_load_contacts() when transaction does not exist yet
1752 # and contacts should be available
1753 if (!t_next_contacts()) {
1754         sl_send_reply("500", "Server Internal Error - Cannot get contacts");
1755 } else {
1756         t_relay();
1757 };
1758 ...
1759 # Following call, when transaction exists and there may or may not be
1760 # contacts left
1761 if (!t_next_contacts()) {
1762         t_reply("408", "Request Timeout");
1763 } else {
1764         t_relay();
1765 };
1766 ...
1767
1768 1.5.33.  t_check_trans()
1769
1770    t_check_trans() can be used to quickly check if a message belongs or is
1771    related to a transaction. It behaves differently for different types of
1772    messages:
1773      * For a SIP Reply it returns true if the reply belongs to an existing
1774        transaction and false otherwise.
1775      * For a CANCEL it behaves exactly as t_lookup_cancel(): returns true
1776        if a corresponding INVITE transaction exists for the CANCEL and
1777        false otherwise.
1778      * For ACKs to negative replies or for ACKs to local transactions it
1779        will terminate the script if the ACK belongs to a transaction (it
1780        would make very little sense to process an ACK to a negative reply
1781        for an existing transaction in some other way then to simply pass
1782        it to tm) or return false if not.
1783      * For end-to-end ACKs (ACKs to 2xx responses for forwarded INVITE
1784        transactions) it will return true if the corresponding INVITE
1785        transaction is found and still active and false if not.
1786
1787 Note
1788        Note that the e2e ACK matching is more of a hint then a certainty.
1789        A delayed e2e ACK might arrive after the transaction wait time
1790        elapses, when the INVITE transaction no longer exists and thus
1791        would not match anything. There are also cases when tm would not
1792        keep all the information needed for e2e ACK matching (since this is
1793        not needed for a statefull proxy and it requires additional memory,
1794        tm will not keep this information unless needed by some other
1795        module or callbacks).
1796      * For other requests (non ACKs and non CANCELs), it will terminate
1797        the script for retransmissions and return false for new requests
1798        (for which no transaction exists yet).
1799
1800 Note
1801
1802    An important difference from kamailio version is that for an ACK to
1803    negative reply or for a local transaction, the script execution will be
1804    immediately stopped and the message handled by tm, instead of returning
1805    true.
1806
1807    t_check_trans() functionality for requests, except for the e2e ACK
1808    matching, can be replicated in the script using t_lookup_cancel() and
1809    t_lookup_request().
1810
1811    See also: t_lookup_request(), t_lookup_cancel().
1812
1813    Example 69. t_check_trans usage
1814 if ( method == "CANCEL" && !t_check_trans())
1815         sl_reply("403", "cancel out of the blue forbidden");
1816 # note: in this example t_check_trans() can be replaced by t_lookup_cancel()
1817
1818 1.5.34.  t_set_disable_6xx(0|1)
1819
1820    Turn off/on 6xx replies special rfc conformant handling on a per
1821    transaction basis. If turned off (t_set_disable_6xx("1")) 6XXs will be
1822    treated like normal replies.
1823
1824    It overrides the disable_6xx_block value for the current transaction.
1825
1826    See also: disable_6xx_block.
1827
1828    Example 70. t_set_disable_6xx usage
1829 ...
1830 route {
1831 ...
1832         if (src_ip==1.2.3.4) # bad user agent that sends 603
1833                 t_set_disable_6xx(1); # turn off 6xx special handling
1834 ...
1835 }
1836
1837 1.5.35.  t_set_disable_failover(0|1)
1838
1839    Turn off/on dns failover on a per transaction basis.
1840
1841    See also: use_dns_failover.
1842
1843    Example 71. t_set_disable_failover usage
1844 ...
1845 route {
1846 ...
1847         if (uri=~"@foo.bar$")
1848                 t_set_disable_failover(1); # turn off dns failover
1849 ...
1850 }
1851
1852 1.6. TM Module API
1853
1854    Revision History
1855    Revision $Revision$ $Date$
1856
1857    There are applications which would like to generate SIP transactions
1858    without too big involvement in SIP stack, transaction management, etc.
1859    An example of such an application is sending instant messages from a
1860    website. To address needs of such apps, SER accepts requests for new
1861    transactions via fifo pipes too. If you want to enable this feature,
1862    start FIFO server with configuration option.
1863
1864    fifo="/tmp/ser_fifo"
1865
1866    Then, an application can easily launch a new transaction by writing a
1867    transaction request to this named pipe. The request must follow very
1868    simple format, which is
1869  :t_uac_from:[<file_name>]\n
1870  <method>\n
1871  <sender's uri>\n
1872  <dst uri>\n
1873  <CR_separated_headers>\n
1874  <body>\n
1875  .\n
1876  \n
1877
1878    (Filename is to where a report will be dumped. ser assumes /tmp as
1879    file's directory.)
1880
1881    Note the request write must be atomic, otherwise it might get
1882    intermixed with writes from other writers. You can easily use it via
1883    Unix command-line tools, see the following example:
1884 [jiri@bat jiri]$ cat > /tmp/ser_fifo
1885 :t_uac_from:xxx
1886 MESSAGE
1887 sip:sender@iptel.org
1888 sip:mrx@iptel.org
1889 header:value
1890 foo:bar
1891 bznk:hjhjk
1892 p_header: p_value
1893
1894 body body body
1895 yet body
1896 end of body
1897 .
1898
1899    or cat test/transaction.fifo > /tmp/ser_fifo
1900
1901 1.6.1. Defines
1902
1903      * ACK_TAG enables stricter matching of acknowledgments including
1904        to-tags. Without it, to-tags are ignored. It is disabled by default
1905        for two reasons:
1906           + It eliminates an unlikely race condition in which
1907             transaction's to-tag is being rewritten by a 200 OK whereas an
1908             ACK is being looked up by to-tag.
1909           + It makes UACs happy who set wrong to-tags.
1910        It should not make a difference, as there may be only one negative
1911        reply sent upstream and 200/ACKs are not matched as they constitute
1912        another transaction. It will make no difference at all when the new
1913        magic cookie matching is enabled anyway.
1914      * CANCEL_TAG similarly enables strict matching of CANCELs including
1915        to-tags--act of mercy to UACs, who screw up the to-tags (however,
1916        it still depends on how forgiving the downstream UAS is). Like with
1917        ACK_TAG, all this complex transactions matching goes with RFC3261's
1918        magic cookie away anyway.
1919
1920 1.6.2. Functions
1921
1922 1.6.2.1.  register_tmcb(cb_type, cb_func)
1923
1924    For programmatic use only--register a function to be called back on an
1925    event. See t_hooks.h for more details.
1926
1927    Meaning of the parameters is as follows:
1928      * cb_type - Callback type.
1929      * cb_func - Callback function.
1930
1931 1.6.2.2.  load_tm(*import_structure)
1932
1933    For programmatic use only--import exported TM functions. See the acc
1934    module for an example of use.
1935
1936    Meaning of the parameters is as follows:
1937      * import_structure - Pointer to the import structure.
1938
1939 1.6.2.3.  int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
1940 unsigned int *label)
1941
1942    For programmatic use only. This function together with t_continue() can
1943    be used to implement asynchronous actions: t_suspend() saves the
1944    transaction, returns its identifiers, and t_continue() continues the
1945    SIP request processing. (The request processing does not continue from
1946    the same point in the script, a separate route block defined by the
1947    parameter of t_continue() is executed instead. The reply lock is held
1948    during the route block execution.) FR timer is ticking while the
1949    transaction is suspended, and the transaction's failure route is
1950    executed if t_continue() is not called in time.
1951
1952    Missing: message lumps are saved by t_suspend() and are not updated by
1953    the subsequent t_relay(). This means that the modifications made
1954    between them are lost.
1955
1956    Meaning of the parameters is as follows:
1957      * msg - SIP message pointer.
1958      * hash_index - transaction identifier.
1959      * label - transaction identifier.
1960
1961    Return value: 0 - success, <0 - error.
1962
1963    Usage: Allocate a memory block for storing the transaction identifiers
1964    (hash_index and label), and for storing also any variable related to
1965    the async query. Before calling t_suspend(), register for the following
1966    callbacks, and pass the pointer to the allocated shared memory as a
1967    parameter: TMCB_ON_FAILURE, TMCB_DESTROY, and TMCB_E2ECANCEL_IN (in
1968    case of INVITE transaction). The async operation can be cancelled, if
1969    it is still pending, when TMCB_ON_FAILURE or TMCB_E2ECANCEL_IN is
1970    called. TMCB_DESTROY is suitable to free the shared memory allocated
1971    for the async and SIP transaction identifiers. Once the async query
1972    result is available call t_continue(), see below. The SIP transaction
1973    must exist before calling t_suspend(), and the module function calling
1974    t_suspend() should return 0 to make sure that the script processing
1975    does not continue.
1976
1977 1.6.2.4.  int t_continue(unsigned int hash_index, unsigned int label, struct
1978 action *route)
1979
1980    For programmatic use only. This function is the pair of t_suspend(),
1981    and is supposed to be called when the asynchronous query result is
1982    available. The function executes a route block with the saved SIP
1983    message. It is possible to add more branches to the transaction, or
1984    send a reply from the route block.
1985
1986    Meaning of the parameters is as follows:
1987      * hash_index - transaction identifier.
1988      * label - transaction identifier.
1989      * route - route block to execute.
1990
1991    Return value: 0 - success, <0 - error.