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