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