Debian Codegraph @

src/modules/tm/README

raw
1 TM Module
2
3 Jiri Kuthan
4
5 FhG FOKUS
6
7 Juha Heinanen
8
9 <[email protected]>
10
11 Daniel-Constantin Mierla
12
13 <[email protected]>
14
15 Copyright © 2003 FhG FOKUS
16
17 Copyright © 2008 Juha Heinanen
18
19 Copyright © 2016 Daniel-Constantin Mierla
20 __________________________________________________________________
21
22 Table of Contents
23
24 1. Admin Guide
25
26 1. Overview
27 2. Serial Forking Based on Q Value
28 3. Parameters
29
30 3.1. fr_timer (integer)
31 3.2. fr_inv_timer (integer)
32 3.3. max_inv_lifetime (integer)
33 3.4. max_noninv_lifetime (integer)
34 3.5. wt_timer (integer)
35 3.6. retr_timer1 (integer)
36 3.7. retr_timer2 (integer)
37 3.8. noisy_ctimer (integer)
38 3.9. restart_fr_on_each_reply (integer)
39 3.10. auto_inv_100 (integer)
40 3.11. auto_inv_100_reason (string)
41 3.12. unix_tx_timeout (integer)
42 3.13. aggregate_challenges (integer)
43 3.14. reparse_invite (integer)
44 3.15. ac_extra_hdrs (string)
45 3.16. blst_503 (integer)
46 3.17. blst_503_def_timeout (integer)
47 3.18. blst_503_min_timeout (integer)
48 3.19. blst_503_max_timeout (integer)
49 3.20. blst_methods_add (unsigned integer)
50 3.21. blst_methods_lookup (unsigned integer)
51 3.22. cancel_b_method (integer)
52 3.23. reparse_on_dns_failover (integer)
53 3.24. on_sl_reply (string)
54 3.25. contacts_avp (string)
55 3.26. contact_flows_avp (string)
56 3.27. fr_timer_avp (string)
57 3.28. fr_inv_timer_avp (string)
58 3.29. unmatched_cancel (integer)
59 3.30. ruri_matching (integer)
60 3.31. via1_matching (integer)
61 3.32. callid_matching (integer)
62 3.33. callid_cseq_matching (int)
63 3.34. pass_provisional_replies (integer)
64 3.35. default_code (integer)
65 3.36. default_reason (string)
66 3.37. disable_6xx_block (integer)
67 3.38. local_ack_mode (integer)
68 3.39. local_ack_branch_mode (integer)
69 3.40. failure_reply_mode (integer)
70 3.41. faked_reply_prio (integer)
71 3.42. local_cancel_reason (boolean)
72 3.43. e2e_cancel_reason (boolean)
73 3.44. e2e_cancel_hop_by_hop (int)
74 3.45. headers_mode (int)
75 3.46. remap_503_500 (boolean)
76 3.47. failure_exec_mode (boolean)
77 3.48. dns_reuse_rcv_socket (boolean)
78 3.49. xavp_contact (string)
79 3.50. event_callback (str)
80 3.51. event_callback_lres_sent (str)
81 3.52. evcb_local_ack_sent (str)
82 3.53. relay_100 (str)
83 3.54. rich_redirect (int)
84 3.55. exec_time_check (int)
85 3.56. reply_relay_mode (int)
86 3.57. enable_uac_fr (int)
87 3.58. failover_reply_codes (string)
88 3.59. reply_408_code (int)
89 3.60. reply_408_reason (str)
90 3.61. delayed_reply (int)
91 3.62. evlreq_mode (int)
92
93 4. Functions
94
95 4.1. t_relay([host, port])
96 4.2. t_relay_to_udp([ip, port])
97 4.3. t_relay_to_tcp([ip, port])
98 4.4. t_relay_to_tls([ip, port])
99 4.5. t_relay_to_sctp([ip, port])
100 4.6. t_on_failure(failure_route)
101 4.7. t_on_branch_failure(branch_failure_route)
102 4.8. t_on_reply(onreply_route)
103 4.9. t_on_branch(branch_route)
104 4.10. t_newtran()
105 4.11. t_reply(code, reason_phrase)
106 4.12. t_reply_error()
107 4.13. t_send_reply(code, reason)
108 4.14. t_lookup_request()
109 4.15. t_retransmit_reply()
110 4.16. t_release()
111 4.17. t_forward_nonack([ip, port])
112 4.18. t_forward_nonack_udp(ip, port)
113 4.19. t_forward_nonack_tcp(ip, port)
114 4.20. t_forward_nonack_tls(ip, port)
115 4.21. t_forward_nonack_sctp(ip, port)
116 4.22. t_set_fr(fr_inv_timeout [, fr_timeout])
117 4.23. t_reset_fr()
118 4.24. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
119 4.25. t_reset_max_lifetime()
120 4.26. t_set_retr(retr_t1_interval, retr_t2_interval)
121 4.27. t_reset_retr()
122 4.28. t_set_auto_inv_100(0|1)
123 4.29. t_branch_timeout()
124 4.30. t_branch_replied()
125 4.31. t_any_timeout()
126 4.32. t_any_replied()
127 4.33. t_grep_status("code")
128 4.34. t_is_canceled()
129 4.35. t_is_expired()
130 4.36. t_relay_cancel()
131 4.37. t_lookup_cancel([1])
132 4.38. t_drop_replies([mode])
133 4.39. t_save_lumps()
134 4.40. t_load_contacts([mode])
135 4.41. t_next_contacts()
136 4.42. t_next_contact_flow()
137 4.43. t_check_status(re)
138 4.44. t_check_trans()
139 4.45. t_set_disable_6xx(0|1)
140 4.46. t_set_disable_failover(0|1)
141 4.47. t_set_disable_internal_reply(0|1)
142 4.48. t_set_no_auto_ack(0|1)
143 4.49. t_replicate([params])
144 4.50. t_relay_to(proxy, flags)
145 4.51. t_relay_to_proxy(proxy [, flags])
146 4.52. t_set_no_e2e_cancel_reason(0|1)
147 4.53. t_is_set(target)
148 4.54. t_use_uac_headers()
149 4.55. t_is_retr_async_reply()
150 4.56. t_uac_send(method, ruri, nexthop, socket, headers,
151 body)
152
153 4.57. t_get_status_code()
154 4.58. t_clean()
155 4.59. t_exists()
156 4.60. t_cell_append_branches(tindex, tlabel)
157 4.61. t_msg_apply_changes()
158
159 5. RPC Commands
160
161 5.1. tm.list
162 5.2. tm.t_uac_start
163 5.3. tm.t_uac_start_hex
164 5.4. tm.t_uac_wait
165 5.5. tm.t_uac_wait_hex
166 5.6. tm.t_uac_wait_block
167 5.7. tm.t_uac_wait_block_hex
168 5.8. tm.t_uac_start_noack
169 5.9. tm.t_uac_start_noack_hex
170 5.10. tm.t_uac_wait_noack
171 5.11. tm.t_uac_wait_noack_hex
172 5.12. tm.t_uac_wait_block_noack
173 5.13. tm.t_uac_wait_block_noack_hex
174 5.14. tm.t_uac_attrs
175 5.15. tm.cancel
176 5.16. tm.hash_stats
177 5.17. tm.reply
178 5.18. tm.reply_callid
179 5.19. tm.retransmit_reply
180 5.20. tm.retransmit_reply_callid
181 5.21. tm.clean
182 5.22. tm.stats
183
184 6. Event Routes
185
186 6.1. event_route[tm:branch-failure:id]
187 6.2. event_route[tm:local-request]
188 6.3. event_route[tm:local-response]
189 6.4. event_route[tm:local-ack-sent]
190
191 7. TM Module API
192
193 7.1. Defines
194 7.2. Functions
195
196 7.2.1. register_tmcb(cb_type, cb_func)
197 7.2.2. load_tm(*import_structure)
198 7.2.3. int t_suspend(struct sip_msg *msg, unsigned int
199 *hash_index, unsigned int *label)
200
201 7.2.4. int t_continue(unsigned int hash_index,
202 unsigned int label, struct action *route)
203
204 7.2.5. int t_cancel_suspend(unsigned int hash_index,
205 unsigned int label)
206
207 8. Known Issues
208
209 List of Examples
210
211 1.1. Set fr_timer parameter
212 1.2. Set fr_inv_timer parameter
213 1.3. Set max_inv_lifetime parameter
214 1.4. Set max_noninv_lifetime parameter
215 1.5. Set wt_timer parameter
216 1.6. Set retr_timer1 parameter
217 1.7. Set retr_timer2 parameter
218 1.8. Set noisy_ctimer parameter
219 1.9. Set restart_fr_on_each_reply parameter
220 1.10. Set auto_inv_100 parameter
221 1.11. Set auto_inv_100_reason parameter
222 1.12. Set unix_tx_timeout parameter
223 1.13. Set aggregate_challenges parameter
224 1.14. Set reparse_invite parameter
225 1.15. Set ac_extra_hdrs parameter
226 1.16. Set blst_503 parameter
227 1.17. Set blst_503_def_timeout parameter
228 1.18. Set blst_503_min_timeout parameter
229 1.19. Set blst_503_max_timeout parameter
230 1.20. Set blst_methods_add parameter
231 1.21. Set blst_methods_lookup parameter
232 1.22. Set cancel_b_method parameter
233 1.23. Set reparse_on_dns_failover parameter
234 1.24. Set on_sl_reply parameter
235 1.25. Set on_sl_reply parameter (KEMI javascript)
236 1.26. Set contacts_avp parameter
237 1.27. Set contact_flows_avp parameter
238 1.28. Set fr_timer_avp parameter
239 1.29. Set fr_inv_timer_avp parameter
240 1.30. Set unmatched_cancel parameter
241 1.31. Set ruri_matching parameter
242 1.32. Set via1_matching parameter
243 1.33. Set callid_matching parameter
244 1.34. Set callid_cseq_matching parameter
245 1.35. Set pass_provisional_replies parameter
246 1.36. Set default_code parameter
247 1.37. Set default_reason parameter
248 1.38. Set disable_6xx_block parameter
249 1.39. Set local_ack_mode parameter
250 1.40. Set local_ack_branch_mode parameter
251 1.41. Set failure_reply_mode parameter
252 1.42. Set faked_reply_prio parameter
253 1.43. Set local_cancel_reason parameter
254 1.44. Set e2e_cancel_reason parameter
255 1.45. Set e2e_cancel_hop_by_hop parameter
256 1.46. Set headers_mode parameter
257 1.47. Set remap_503_500 parameter
258 1.48. Set failure_exec_mode parameter
259 1.49. Set dns_reuse_rcv_socket parameter
260 1.50. Set xavp_contact parameter
261 1.51. Set event_callback parameter
262 1.52. Set event_callback_lres_sent parameter
263 1.53. Set evcb_local_ack_sent parameter
264 1.54. Set relay_100 parameter
265 1.55. rich_redirect example
266 1.56. Set exec_time_check parameter
267 1.57. Set reply_relay_mode parameter
268 1.58. enable_uac_fr example
269 1.59. Set the “failover_reply_codes” parameter
270 1.60. reply_408_code example
271 1.61. reply_408_reason example
272 1.62. delayed_reply example
273 1.63. evlreq_mode example
274 1.64. t_relay usage
275 1.65. t_relay_to_udp usage
276 1.66. t_on_failure usage
277 1.67. t_on_branch_failure usage
278 1.68. t_on_reply usage
279 1.69. t_on_branch usage
280 1.70. t_newtran usage
281 1.71. t_reply usage
282 1.72. t_reply_error usage
283 1.73. t_send_reply usage
284 1.74. t_lookup_request usage
285 1.75. t_retransmit_reply usage
286 1.76. t_release usage
287 1.77. t_forward_nonack usage
288 1.78. t_set_fr usage
289 1.79. t_reset_fr usage
290 1.80. t_set_max_lifetime usage
291 1.81. t_reset_max_lifetime usage
292 1.82. t_set_retr usage
293 1.83. t_reset_retr usage
294 1.84. t_set_auto_inv_100 usage
295 1.85. t_branch_timeout usage
296 1.86. t_branch_replied usage
297 1.87. t_any_timeout usage
298 1.88. t_any_replied usage
299 1.89. t_grep_status usage
300 1.90. t_is_canceled usage
301 1.91. t_is_expired usage
302 1.92. t_relay_cancel usage
303 1.93. t_lookup_cancel usage
304 1.94. t_drop_replies() usage
305 1.95. t_save_lumps() usage
306 1.96. t_load_contacts usage
307 1.97. t_next_contacts usage
308 1.98. t_next_contact_flow usage
309 1.99. t_check_status usage
310 1.100. t_check_trans usage
311 1.101. t_set_disable_6xx usage
312 1.102. t_set_disable_failover usage
313 1.103. t_set_disable_internal_reply usage
314 1.104. t_set_no_auto_ack usage
315 1.105. t_replicate usage
316 1.106. t_relay_to usage
317 1.107. t_relay_to_proxy usage
318 1.108. t_set_no_e2e_cancel_reason usage
319 1.109. t_replicate usage
320 1.110. t_use_uac_headers usage
321 1.111. t_is_retr_async_reply usage
322 1.112. t_uac_send usage
323 1.113. t_get_status_code usage
324 1.114. t_clean usage
325 1.115. t_exists usage
326 1.116. t_cell_append_branches usage
327 1.117. t_msg_apply_changes usage
328 1.118. Using “tm.t_uac_attrs”
329 1.119. Using “tm.retransmit_reply”
330 1.120. Using “tm.retransmit_reply_callid”
331 1.121. event_route[tm:branch-failure:id] usage
332 1.122. event_route[tm:local-request] usage
333 1.123. event_route[tm:local-response] usage
334 1.124. event_route[tm:local-ack-sent] usage
335
336 Chapter 1. Admin Guide
337
338 Table of Contents
339
340 1. Overview
341 2. Serial Forking Based on Q Value
342 3. Parameters
343
344 3.1. fr_timer (integer)
345 3.2. fr_inv_timer (integer)
346 3.3. max_inv_lifetime (integer)
347 3.4. max_noninv_lifetime (integer)
348 3.5. wt_timer (integer)
349 3.6. retr_timer1 (integer)
350 3.7. retr_timer2 (integer)
351 3.8. noisy_ctimer (integer)
352 3.9. restart_fr_on_each_reply (integer)
353 3.10. auto_inv_100 (integer)
354 3.11. auto_inv_100_reason (string)
355 3.12. unix_tx_timeout (integer)
356 3.13. aggregate_challenges (integer)
357 3.14. reparse_invite (integer)
358 3.15. ac_extra_hdrs (string)
359 3.16. blst_503 (integer)
360 3.17. blst_503_def_timeout (integer)
361 3.18. blst_503_min_timeout (integer)
362 3.19. blst_503_max_timeout (integer)
363 3.20. blst_methods_add (unsigned integer)
364 3.21. blst_methods_lookup (unsigned integer)
365 3.22. cancel_b_method (integer)
366 3.23. reparse_on_dns_failover (integer)
367 3.24. on_sl_reply (string)
368 3.25. contacts_avp (string)
369 3.26. contact_flows_avp (string)
370 3.27. fr_timer_avp (string)
371 3.28. fr_inv_timer_avp (string)
372 3.29. unmatched_cancel (integer)
373 3.30. ruri_matching (integer)
374 3.31. via1_matching (integer)
375 3.32. callid_matching (integer)
376 3.33. callid_cseq_matching (int)
377 3.34. pass_provisional_replies (integer)
378 3.35. default_code (integer)
379 3.36. default_reason (string)
380 3.37. disable_6xx_block (integer)
381 3.38. local_ack_mode (integer)
382 3.39. local_ack_branch_mode (integer)
383 3.40. failure_reply_mode (integer)
384 3.41. faked_reply_prio (integer)
385 3.42. local_cancel_reason (boolean)
386 3.43. e2e_cancel_reason (boolean)
387 3.44. e2e_cancel_hop_by_hop (int)
388 3.45. headers_mode (int)
389 3.46. remap_503_500 (boolean)
390 3.47. failure_exec_mode (boolean)
391 3.48. dns_reuse_rcv_socket (boolean)
392 3.49. xavp_contact (string)
393 3.50. event_callback (str)
394 3.51. event_callback_lres_sent (str)
395 3.52. evcb_local_ack_sent (str)
396 3.53. relay_100 (str)
397 3.54. rich_redirect (int)
398 3.55. exec_time_check (int)
399 3.56. reply_relay_mode (int)
400 3.57. enable_uac_fr (int)
401 3.58. failover_reply_codes (string)
402 3.59. reply_408_code (int)
403 3.60. reply_408_reason (str)
404 3.61. delayed_reply (int)
405 3.62. evlreq_mode (int)
406
407 4. Functions
408
409 4.1. t_relay([host, port])
410 4.2. t_relay_to_udp([ip, port])
411 4.3. t_relay_to_tcp([ip, port])
412 4.4. t_relay_to_tls([ip, port])
413 4.5. t_relay_to_sctp([ip, port])
414 4.6. t_on_failure(failure_route)
415 4.7. t_on_branch_failure(branch_failure_route)
416 4.8. t_on_reply(onreply_route)
417 4.9. t_on_branch(branch_route)
418 4.10. t_newtran()
419 4.11. t_reply(code, reason_phrase)
420 4.12. t_reply_error()
421 4.13. t_send_reply(code, reason)
422 4.14. t_lookup_request()
423 4.15. t_retransmit_reply()
424 4.16. t_release()
425 4.17. t_forward_nonack([ip, port])
426 4.18. t_forward_nonack_udp(ip, port)
427 4.19. t_forward_nonack_tcp(ip, port)
428 4.20. t_forward_nonack_tls(ip, port)
429 4.21. t_forward_nonack_sctp(ip, port)
430 4.22. t_set_fr(fr_inv_timeout [, fr_timeout])
431 4.23. t_reset_fr()
432 4.24. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
433 4.25. t_reset_max_lifetime()
434 4.26. t_set_retr(retr_t1_interval, retr_t2_interval)
435 4.27. t_reset_retr()
436 4.28. t_set_auto_inv_100(0|1)
437 4.29. t_branch_timeout()
438 4.30. t_branch_replied()
439 4.31. t_any_timeout()
440 4.32. t_any_replied()
441 4.33. t_grep_status("code")
442 4.34. t_is_canceled()
443 4.35. t_is_expired()
444 4.36. t_relay_cancel()
445 4.37. t_lookup_cancel([1])
446 4.38. t_drop_replies([mode])
447 4.39. t_save_lumps()
448 4.40. t_load_contacts([mode])
449 4.41. t_next_contacts()
450 4.42. t_next_contact_flow()
451 4.43. t_check_status(re)
452 4.44. t_check_trans()
453 4.45. t_set_disable_6xx(0|1)
454 4.46. t_set_disable_failover(0|1)
455 4.47. t_set_disable_internal_reply(0|1)
456 4.48. t_set_no_auto_ack(0|1)
457 4.49. t_replicate([params])
458 4.50. t_relay_to(proxy, flags)
459 4.51. t_relay_to_proxy(proxy [, flags])
460 4.52. t_set_no_e2e_cancel_reason(0|1)
461 4.53. t_is_set(target)
462 4.54. t_use_uac_headers()
463 4.55. t_is_retr_async_reply()
464 4.56. t_uac_send(method, ruri, nexthop, socket, headers, body)
465 4.57. t_get_status_code()
466 4.58. t_clean()
467 4.59. t_exists()
468 4.60. t_cell_append_branches(tindex, tlabel)
469 4.61. t_msg_apply_changes()
470
471 5. RPC Commands
472
473 5.1. tm.list
474 5.2. tm.t_uac_start
475 5.3. tm.t_uac_start_hex
476 5.4. tm.t_uac_wait
477 5.5. tm.t_uac_wait_hex
478 5.6. tm.t_uac_wait_block
479 5.7. tm.t_uac_wait_block_hex
480 5.8. tm.t_uac_start_noack
481 5.9. tm.t_uac_start_noack_hex
482 5.10. tm.t_uac_wait_noack
483 5.11. tm.t_uac_wait_noack_hex
484 5.12. tm.t_uac_wait_block_noack
485 5.13. tm.t_uac_wait_block_noack_hex
486 5.14. tm.t_uac_attrs
487 5.15. tm.cancel
488 5.16. tm.hash_stats
489 5.17. tm.reply
490 5.18. tm.reply_callid
491 5.19. tm.retransmit_reply
492 5.20. tm.retransmit_reply_callid
493 5.21. tm.clean
494 5.22. tm.stats
495
496 6. Event Routes
497
498 6.1. event_route[tm:branch-failure:id]
499 6.2. event_route[tm:local-request]
500 6.3. event_route[tm:local-response]
501 6.4. event_route[tm:local-ack-sent]
502
503 7. TM Module API
504
505 7.1. Defines
506 7.2. Functions
507
508 7.2.1. register_tmcb(cb_type, cb_func)
509 7.2.2. load_tm(*import_structure)
510 7.2.3. int t_suspend(struct sip_msg *msg, unsigned int
511 *hash_index, unsigned int *label)
512
513 7.2.4. int t_continue(unsigned int hash_index, unsigned int
514 label, struct action *route)
515
516 7.2.5. int t_cancel_suspend(unsigned int hash_index,
517 unsigned int label)
518
519 8. Known Issues
520
521 1. Overview
522
523 The TM module enables stateful processing of SIP transactions. Stateful
524 logic is costly in terms of memory and CPU. The main use is services
525 that inherently need state. For example, transaction-based accounting
526 (module acc) needs to process transaction state as opposed to
527 individual messages. Any kind of forking must be implemented
528 transaction statefully. By using transaction states you trade CPU
529 caused by retransmission processing for memory. That only makes sense
530 if CPU consumption per request is huge. For example, if you want to
531 avoid costly DNS resolution for every retransmission of a request to an
532 unresolvable destination, use stateful mode. Then, only the initial
533 message burdens server by DNS queries, subsequent retransmissions will
534 be dropped and will not result in more processes blocked by DNS
535 resolution. The price is more memory consumption and higher processing
536 latency.
537
538 From the admin's perspective, these are the major functions : t_relay,
539 t_relay_to_udp and t_relay_to_tcp. All of them set up transaction
540 state, absorb retransmissions from upstream, generate downstream
541 retransmissions and correlate replies to requests. t_relay forwards to
542 current URI (be it original request's URI or a URI changed by some of
543 URI-modifying functions, such as sethost). t_relay_to_udp and
544 t_relay_to_tcp forward to a specific address over UDP or TCP
545 respectively.
546
547 In general, if TM is used, it copies clones of received SIP messages in
548 shared memory. That costs memory and also CPU time (memcpys, lookups,
549 shmem locks, etc.) Note that non-TM functions operate over the received
550 message in private memory, that means that any core operations will
551 have no effect on statefully processed messages after creating the
552 transactional state. For example, calling record_route after t_relay is
553 pretty useless, as the RR is added to privately held message whereas
554 its TM clone is being forwarded.
555
556 The TM module is quite big and uneasy to program --lots of mutexes,
557 shared memory access, malloc and free, timers--you really need to be
558 careful when you do anything. To simplify TM programming, there is the
559 instrument of callbacks. The callback mechanisms allow programmers to
560 register their functions to a specific event. See t_hooks.h for a list
561 of possible events.
562
563 Other things programmers may want to know is UAC--it is a very
564 simplistic code which allows you to generate your own transactions.
565 Particularly useful for things like NOTIFYs or IM gateways. The UAC
566 takes care of all the transaction machinery: retransmissions, FR
567 timeouts, forking, etc. See t_uac prototype in uac.h for more details.
568 If you want to see the transaction result the code can register for a
569 callback.
570
571 Note
572
573 Several Kamailio TM module functions are now implemented in the TMX
574 module. Check it to see if what you are looking for is there.
575
576 2. Serial Forking Based on Q Value
577
578 A single SIP INVITE request may be forked to multiple destinations. We
579 call the set of all such destinations a “destination set”. Individual
580 elements within the destination sets are called branches. The script
581 writer can add URIs to the destination set from the configuration file,
582 or they can be loaded from the user location database. Each registered
583 contact then becomes one branch in the destination set.
584
585 The default behavior of the TM module, if it encounters a SIP message
586 with multiple branches in the destination set, is to forward the SIP
587 message to all the branches in parallel. That means it sends the
588 message to all the branch destinations before it waits for replies from
589 any of them. This is the default behavior if you call t_relay() and
590 similar functions without any other arguments.
591
592 Another approach of handling multiple branches in a destination set is
593 serial forking. When configured to do serial forking, the server takes
594 the first branch out of the destination set, forwards the message to
595 its destination and waits for a reply or timeout. Only after a reply
596 has been received or a timeout occurred, the server takes another
597 destination from the destination set and tries again, until it receives
598 a positive final reply or until all branches from the destination set
599 have been tried.
600
601 Yet another, more sophisticated, way of handling multiple branches is
602 combined serial/parallel forking, where individual branches within the
603 destination set are assigned priorities. The order in which individual
604 branches are tried is then determined by their relative priority within
605 the destination set. Branches can be tried sequentially in the
606 descending priority order and all branches that have the same priority
607 can be tried in parallel. Such combined serial/parallel forking can be
608 achieved in the TM module with the help of functions t_load_contacts()
609 and t_next_contacts().
610
611 Every branch in the destination set is assigned a priority number, also
612 known as the “q value”. The q value is a floating point number in a
613 range 0 to 1.0. The higher the q value number, the more priority is
614 given to the particular branch in the destination set. Branches with q
615 value 1.0 have maximum priority, such branches should always be tried
616 first in serial forking. Branches with q value 0 have the lowest
617 priority and they should by tried after all other branches with higher
618 priority in the destination set.
619
620 As an example, consider the following simple configuration file. When
621 the server receives an INVITE, it creates four branches with usernames
622 A through D and then forwards the request using t_relay():
623 request_route {
624 seturi("sip:[email protected]");
625 append_branch("sip:[email protected]");
626 append_branch("sip:[email protected]");
627 append_branch("sip:[email protected]");
628
629 t_relay();
630 break;
631 }
632
633 With this configuration the server forwards the request to all four
634 branches at once, performing parallel forking as described above. We
635 did not set the q value for individual branches in this example but we
636 can do that by slightly modifying the arguments given to
637 append_branch():
638 request_route {
639 seturi("sip:[email protected]");
640 append_branch("sip:[email protected]", "0.5");
641 append_branch("sip:[email protected]", "0.5");
642 append_branch("sip:[email protected]", "1.0");
643
644 t_relay();
645 break;
646 }
647
648 Here we assigned q value 0.5 to branches B and C and q value 1.0 to
649 branch D. We did not specify any q value for branch A and in that case
650 it is assumed that its q value is the lowest from all branches within
651 the destination set. If you try to run this example again, you will
652 figure out that nothing changed, t_relay() still forward the message to
653 all branches in parallel.
654
655 We now want to implement the combined serial/parallel forking. Branch D
656 should be tried first, because its q value is 1.0. Branches B and C
657 should be tried in parallel, but only after D finishes. Branch A should
658 be tried after B and C finished, because its q value (the default) is
659 the lowest of all. To do that, we need to introduce two new functions
660 into our example and two tm module parameters:
661 modparam("tm", "contacts_avp", "tm_contacts");
662 modparam("tm", "contact_flows_avp", "tm_contact_flows");
663
664 request_route {
665 seturi("sip:[email protected]");
666 append_branch("sip:[email protected]", "0.5");
667 append_branch("sip:[email protected]", "0.5");
668 append_branch("sip:[email protected]", "1.0");
669
670 t_load_contacts();
671
672 t_next_contacts();
673 t_relay();
674 break;
675 }
676
677 First of all, the tm module parameters are mandatory if the two new
678 functions are used. Function t_load_contacts() takes all branches from
679 the destination set, sorts them according to their q values and stores
680 them in the AVP configured in the modparam. The function also clears
681 the destination set, which means that it removes all branches
682 configured before with seturi() and append_branch().
683
684 Function t_next_contacts() takes the AVP created by the previous
685 function and extracts the branches with highest q values from it. In
686 our example it is branch D. That branch is then put back into the
687 destination set and when the script finally reaches t_relay(), the
688 destination set only contains branch D and the request will be
689 forwarded there.
690
691 We achieved the first step of serial forking, but this is not
692 sufficient. Now we also need to forward to other branches with lower
693 priority values when branch D finishes. To do that, we need to extend
694 the configuration file again and introduce a failure_route section:
695 modparam("tm", "contacts_avp", "tm_contacts");
696
697 request_route {
698 seturi("sip:[email protected]");
699 append_branch("sip:[email protected]", "0.5");
700 append_branch("sip:[email protected]", "0.5");
701 append_branch("sip:[email protected]", "1.0");
702
703 t_load_contacts();
704
705 t_next_contacts();
706 t_on_failure("serial");
707 t_relay();
708 break;
709 }
710
711 failure_route["serial"]
712 {
713 if (!t_next_contacts()) {
714 exit;
715 }
716
717 t_on_failure("serial");
718 t_relay();
719 }
720
721 The failure_route section will be executed when branch D finishes. It
722 executes t_next_contacts() again and this time the function retrieves
723 branches B and C from the AVP and adds them to the destination set.
724 Here we need to check the return value of the function, because a
725 negative value indicates that there were no more branches, in that case
726 the failure_route should just terminate and forward the response from
727 branch D upstream.
728
729 If t_next_contact() returns a positive value then we have more new
730 branches to try and we need to set up the failure_route again and call
731 t_relay(). In our example the request will now be forwarded to branches
732 B and C in parallel, because they were both added to the destination
733 set by t_next_contacts() at the same time.
734
735 When branches B and C finish, the failure_route block is executed
736 again, this time t_next_contacts() puts the final branch A into the
737 destination set and t_relay() forwards the request there.
738
739 And that's the whole example, we achieved combined serial/parallel
740 forking based on the q value of individual branches. In real-world
741 configuration files the script writer would need to check the return
742 value of all functions and restart_fr_on_each_reply. The destination
743 set would not be configured directly in the configuration file, but can
744 be retrieved from the user location database. In that case registered
745 contacts will be stored in the destination set as branches and their q
746 values (provided by UAs) will be used.
747
748 3. Parameters
749
750 3.1. fr_timer (integer)
751 3.2. fr_inv_timer (integer)
752 3.3. max_inv_lifetime (integer)
753 3.4. max_noninv_lifetime (integer)
754 3.5. wt_timer (integer)
755 3.6. retr_timer1 (integer)
756 3.7. retr_timer2 (integer)
757 3.8. noisy_ctimer (integer)
758 3.9. restart_fr_on_each_reply (integer)
759 3.10. auto_inv_100 (integer)
760 3.11. auto_inv_100_reason (string)
761 3.12. unix_tx_timeout (integer)
762 3.13. aggregate_challenges (integer)
763 3.14. reparse_invite (integer)
764 3.15. ac_extra_hdrs (string)
765 3.16. blst_503 (integer)
766 3.17. blst_503_def_timeout (integer)
767 3.18. blst_503_min_timeout (integer)
768 3.19. blst_503_max_timeout (integer)
769 3.20. blst_methods_add (unsigned integer)
770 3.21. blst_methods_lookup (unsigned integer)
771 3.22. cancel_b_method (integer)
772 3.23. reparse_on_dns_failover (integer)
773 3.24. on_sl_reply (string)
774 3.25. contacts_avp (string)
775 3.26. contact_flows_avp (string)
776 3.27. fr_timer_avp (string)
777 3.28. fr_inv_timer_avp (string)
778 3.29. unmatched_cancel (integer)
779 3.30. ruri_matching (integer)
780 3.31. via1_matching (integer)
781 3.32. callid_matching (integer)
782 3.33. callid_cseq_matching (int)
783 3.34. pass_provisional_replies (integer)
784 3.35. default_code (integer)
785 3.36. default_reason (string)
786 3.37. disable_6xx_block (integer)
787 3.38. local_ack_mode (integer)
788 3.39. local_ack_branch_mode (integer)
789 3.40. failure_reply_mode (integer)
790 3.41. faked_reply_prio (integer)
791 3.42. local_cancel_reason (boolean)
792 3.43. e2e_cancel_reason (boolean)
793 3.44. e2e_cancel_hop_by_hop (int)
794 3.45. headers_mode (int)
795 3.46. remap_503_500 (boolean)
796 3.47. failure_exec_mode (boolean)
797 3.48. dns_reuse_rcv_socket (boolean)
798 3.49. xavp_contact (string)
799 3.50. event_callback (str)
800 3.51. event_callback_lres_sent (str)
801 3.52. evcb_local_ack_sent (str)
802 3.53. relay_100 (str)
803 3.54. rich_redirect (int)
804 3.55. exec_time_check (int)
805 3.56. reply_relay_mode (int)
806 3.57. enable_uac_fr (int)
807 3.58. failover_reply_codes (string)
808 3.59. reply_408_code (int)
809 3.60. reply_408_reason (str)
810 3.61. delayed_reply (int)
811 3.62. evlreq_mode (int)
812
813 3.1. fr_timer (integer)
814
815 This timer is used for all SIP requests. It hits if no reply for an
816 request INVITE request or other request has been received within (F in
817 milliseconds). If a provisional reply is received for an INVITE (any
818 1xx), then the fr_inv_timer will be used instead. And if no replies (at
819 all) for an INVITE are received before fr_timer hits, the transaction
820 is terminated with a 408 in failure route.
821
822 Default value is 30000 ms (30 seconds).
823
824 See also: t_set_fr(), max_noninv_lifetime.
825
826 Example 1.1. Set fr_timer parameter
827 ...
828 modparam("tm", "fr_timer", 10000)
829 ...
830
831 3.2. fr_inv_timer (integer)
832
833 Timer which hits if no final reply for an INVITE arrives after a
834 provisional message was received (in milliseconds).
835
836 Note: This timer can be restarted when a provisional response is
837 received. For more details see restart_fr_on_each_reply.
838
839 Default value is 120000 ms (120 seconds).
840
841 See also: t_set_fr(), max_inv_lifetime.
842
843 Example 1.2. Set fr_inv_timer parameter
844 ...
845 modparam("tm", "fr_inv_timer", 180000)
846 ...
847
848 3.3. max_inv_lifetime (integer)
849
850 Maximum time an INVITE transaction is allowed to be active (in
851 milliseconds). After this interval has passed from the transaction
852 creation, the transaction will be either moved into the wait state or
853 in the final response retransmission state, irrespective of the
854 transaction fr_inv_timer and fr_timer values.
855
856 An INVITE transaction will be kept in memory for maximum:
857 max_inv_lifetime+fr_timer(from the ACK to the final reply
858 wait)+wt_timer.
859
860 The main difference between this timer and fr_inv_timer is that the
861 fr_inv_timer is per branch, while max_inv_lifetime is per the whole
862 transaction. Even on a per branch basis fr_inv_timer could be
863 restarted. For example, by default if restart_fr_on_each_reply is not
864 cleared, the fr_inv_timer will be restarted for each received
865 provisional reply. Even if restart_fr_on_each_reply is not set the
866 fr_inv_timer will still be restarted for each increasing reply (e.g.
867 180, 181, 182, ...). Another example when a transaction can live
868 substantially more than its fr_inv_timer and where max_inv_lifetime
869 will help is when DNS failover is used (each failed DNS destination can
870 introduce a new branch).
871
872 The default value is 180000 ms (180 seconds - the rfc3261 timer C
873 value).
874
875 See also: max_noninv_lifetime, t_set_max_lifetime() (allows changing
876 max_inv_lifetime on a per transaction basis), t_reset_max_lifetime
877 fr_timer, wt_timer, restart_fr_on_each_reply.
878
879 Example 1.3. Set max_inv_lifetime parameter
880 ...
881 modparam("tm", "max_inv_lifetime", 150000)
882 ...
883
884 3.4. max_noninv_lifetime (integer)
885
886 Maximum time a non-INVITE transaction is allowed to be active (in
887 milliseconds). After this interval has passed from the transaction
888 creation, the transaction will be either moved into the wait state or
889 in the final response retransmission state, irrespective of the
890 transaction fr_timer value. It's the same as max_inv_lifetime, but for
891 non-INVITEs.
892
893 A non-INVITE transaction will be kept in memory for a maximum of:
894 max_noninv_lifetime+wt_timer.
895
896 The main difference between this timer and fr_timer is that the
897 fr_timer is per branch, while max_noninv_lifetime is per the whole
898 transaction. An example when a transaction can live substantially more
899 than its fr_timer and where max_noninv_lifetime will help is when DNS
900 failover is used (each failed DNS SRV destination can introduce a new
901 branch).
902
903 The default value is 32000 ms (32 seconds - the RFC3261 timer F value).
904
905 See also: max_inv_lifetime, t_set_max_lifetime() (allows changing
906 max_noninv_lifetime on a per transaction basis), t_reset_max_lifetime
907 fr_timer, wt_timer.
908
909 Example 1.4. Set max_noninv_lifetime parameter
910 ...
911 modparam("tm", "max_noninv_lifetime", 30000)
912 ...
913
914 3.5. wt_timer (integer)
915
916 Time for which a transaction stays in memory to absorb delayed messages
917 after it completed (in milliseconds); also, when this timer hits,
918 retransmission of local CANCEL requests is stopped (a puristic but
919 complex behavior would be not to enter wait state until local branches
920 are finished by a final reply or FR timer--we simplified).
921
922 Default value is 5000 ms (5 seconds).
923
924 Example 1.5. Set wt_timer parameter
925 ...
926 modparam("tm", "wt_timer", 1000)
927 ...
928
929 3.6. retr_timer1 (integer)
930
931 Initial retransmission period (in milliseconds).
932
933 Default value is 500 milliseconds.
934
935 Example 1.6. Set retr_timer1 parameter
936 ...
937 modparam("tm", "retr_timer1", 1000)
938 ...
939
940 3.7. retr_timer2 (integer)
941
942 Maximum retransmission period (in milliseconds). The retransmission
943 interval starts with retr_timer1 and increases until it reaches this
944 value. After this it stays constant at retr_timer2.
945
946 Default value is 4000 milliseconds.
947
948 Example 1.7. Set retr_timer2 parameter
949 ...
950 modparam("tm", "retr_timer2", 2000)
951 ...
952
953 3.8. noisy_ctimer (integer)
954
955 If set, INVITE transactions that time-out (FR INV timer) will be always
956 replied. If it's not set, the transaction has only one branch and no
957 response was ever received on this branch, it will be silently dropped
958 (no 408 reply will be generated) This behavior is overridden if a
959 request is forked, the transaction has a failure route or callback, or
960 some functionality explicitly turned it on for a transaction (like the
961 ACC module does to avoid unaccounted transactions due to expired
962 timer). Turn this off only if you know the client UACs will timeout and
963 their timeout interval for INVITEs is lower or equal than tm's
964 fr_inv_timer.
965
966 Default value is 1 (on).
967
968 Example 1.8. Set noisy_ctimer parameter
969 ...
970 modparam("tm", "noisy_ctimer", 1)
971 ...
972
973 3.9. restart_fr_on_each_reply (integer)
974
975 If set (default), the fr_inv_timer for an INVITE transaction will be
976 restarted for each provisional reply received (rfc3261 mandated
977 behaviour). If not set, the fr_inv_timer will be restarted only for the
978 first provisional replies and for increasing replies greater or equal
979 180 (e.g. 180, 181, 182, 185, ...).
980
981 Setting it to 0 is especially useful when dealing with bad UAs that
982 continuously retransmit 180s, not allowing the transaction to timeout
983 (and thus making impossible the implementation of certain services,
984 like automatic voicemail after x seconds).
985
986 Default value is 1 (on).
987
988 See also: fr_inv_timer, max_inv_lifetime.
989
990 Example 1.9. Set restart_fr_on_each_reply parameter
991 ...
992 modparam("tm", "restart_fr_on_each_reply", 0)
993 ...
994
995 3.10. auto_inv_100 (integer)
996
997 If set (default) tm will automatically send a 100 reply to INVITEs.
998
999 Setting it to 0 can be used to enable first running some tests or
1000 pre-processing on the INVITE and only if some conditions are met
1001 manually send a 100 (using t_reply()). Note however that in this case
1002 all the 100s have to be sent "by hand". t_set_auto_inv_100() might help
1003 to selectively turn off this feature only for some specific
1004 transactions.
1005
1006 Default value is 1 (on).
1007
1008 See also: t_set_auto_inv_100() auto_inv_100_reason.
1009
1010 Example 1.10. Set auto_inv_100 parameter
1011 ...
1012 modparam("tm", "auto_inv_100", 0)
1013 ...
1014
1015 3.11. auto_inv_100_reason (string)
1016
1017 Set reason text of the automatically sent 100 to an INVITE.
1018
1019 Default value is "trying -- your call is important to us".
1020
1021 See also: auto_inv_100.
1022
1023 Example 1.11. Set auto_inv_100_reason parameter
1024 ...
1025 modparam("tm", "auto_inv_100_reason", "Trying")
1026 ...
1027
1028 3.12. unix_tx_timeout (integer)
1029
1030 Unix socket transmission timeout, in milliseconds.
1031
1032 If UNIX sockets are used (e.g.: to communicate with sems) and sending a
1033 message on a UNIX socket takes longer than unix_tx_timeout, the send
1034 will fail.
1035
1036 The default value is 500 milliseconds.
1037
1038 Example 1.12. Set unix_tx_timeout parameter
1039 ...
1040 modparam("tm", "unix_tx_timeout", 250)
1041 ...
1042
1043 3.13. aggregate_challenges (integer)
1044
1045 If set (default), the final response is a 401 or a 407 and more than
1046 one branch received a 401 or 407, then all the WWW-Authenticate and
1047 Proxy-Authenticate headers from all the 401 and 407 replies will be
1048 aggregated in a new final response. If only one branch received the
1049 winning 401 or 407 then this reply will be forwarded (no new one will
1050 be built).
1051
1052 If disabled (set to 0) only the first 401, or if no 401 was received
1053 the first 407, will be forwarded (no header aggregation).
1054
1055 Default value is 1 (required by RFC 3261).
1056
1057 Example 1.13. Set aggregate_challenges parameter
1058 ...
1059 modparam("tm", "aggregate_challenges", 0)
1060 ...
1061
1062 3.14. reparse_invite (integer)
1063
1064 If set (default), the CANCEL and negative ACK requests are constructed
1065 from the INVITE message which was sent out instead of building them
1066 from the received request. The disadvantage is that the outgoing INVITE
1067 has to be partially re-parsed, the advantage is that the CANCEL/ACK is
1068 always RFC 3261-compliant, it always contains the same route-set as the
1069 INVITE message. Do not disable the INVITE re-parsing for example in the
1070 following cases:
1071
1072 - The INVITE contains a preloaded route-set, and Kamailio forwards the
1073 message to the next hop according to the "Route" header. The "Route"
1074 header is not removed in the CANCEL without reparse_invite=1.
1075
1076 - Kamailio record-routes, thus an in-dialog INVITE contains a "Route"
1077 header which is removed during loose routing. If the in-dialog INVITE
1078 is rejected, the negative ACK still contains the "Route" header without
1079 reparse_invite=1.
1080
1081 Default value is 1.
1082
1083 Example 1.14. Set reparse_invite parameter
1084 ...
1085 modparam("tm", "reparse_invite", 0)
1086 ...
1087
1088 3.15. ac_extra_hdrs (string)
1089
1090 Header fields prefixed by this parameter value are included in the
1091 CANCEL and negative ACK messages if they were present in the outgoing
1092 INVITE.
1093
1094 Note, that the parameter value effects only those headers which are not
1095 covered by RFC 3261 (which are neither mandatory nor prohibited in
1096 CANCEL and ACK), and the parameter can be used only together with
1097 reparse_invite=1.
1098
1099 Default value is "".
1100
1101 Example 1.15. Set ac_extra_hdrs parameter
1102 ...
1103 modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
1104 ...
1105
1106 3.16. blst_503 (integer)
1107
1108 If set and the Kamailio blocklist support is enabled, every 503 reply
1109 source is added to the blocklist. The initial blocklist timeout (or
1110 ttl) depends on the presence of a "Retry-After" header in the reply and
1111 the values of the following tm parameters: blst_503_def_timeout,
1112 blst_503_min_timeout and blst_503_max_timeout.
1113
1114 WARNING:blindly allowing 503 blocklisting could be very easily
1115 exploited for DOS attacks in most network setups.
1116
1117 The default value is 0 (disabled due to the reasons above).
1118
1119 Example 1.16. Set blst_503 parameter
1120 ...
1121 modparam("tm", "blst_503", 1)
1122 ...
1123
1124 3.17. blst_503_def_timeout (integer)
1125
1126 Blocklist interval in seconds for a 503 reply with no "Retry-After"
1127 header. See also blst_503, blst_503_min_timeout and
1128 blst_503_max_timeout.
1129
1130 The default value is 0, which means that if no "Retry-After" header is
1131 present, the 503 reply source will not be blocklisted (RFC 3261
1132 conformant behaviour).
1133
1134 Example 1.17. Set blst_503_def_timeout parameter
1135 ...
1136 modparam("tm", "blst_503_def_timeout", 120)
1137 ...
1138
1139 3.18. blst_503_min_timeout (integer)
1140
1141 Minimum blocklist interval in seconds for a 503 reply with a
1142 "Retry-After" header. It will be used if the "Retry-After" value is
1143 smaller than this value.
1144
1145 See also blst_503, blst_503_def_timeout and blst_503_max_timeout.
1146
1147 The default value is 0
1148
1149 Example 1.18. Set blst_503_min_timeout parameter
1150 ...
1151 modparam("tm", "blst_503_min_timeout", 30)
1152 ...
1153
1154 3.19. blst_503_max_timeout (integer)
1155
1156 Maximum blocklist interval in seconds for a 503 reply with a
1157 "Retry-After header". It will be used if the "Retry-After" value is
1158 greater than this limit.
1159
1160 See also blst_503, blst_503_def_timeout and blst_503_min_timeout.
1161
1162 The default value is 3600
1163
1164 Example 1.19. Set blst_503_max_timeout parameter
1165 ...
1166 modparam("tm", "blst_503_max_timeout", 604800)
1167 ...
1168
1169 3.20. blst_methods_add (unsigned integer)
1170
1171 Bitmap of method types that trigger blocklisting on transaction
1172 timeouts. (This setting has no effect on blocklisting because of send
1173 failures.)
1174
1175 The following values are associated to the request methods: INVITE=1,
1176 CANCEL=2, ACK=4 (not retransmitted, thus, never times-out), BYE=8,
1177 INFO=16, REGISTER=32, SUBSCRIBE=64, NOTIFY=126, OTHER=256 (all the
1178 unknown types). Check parser/msg_parser.h for farther details.
1179
1180 Change the value carefully, because requests that don't get a
1181 provisional response (everything but INVITE) can easily cause the next
1182 hop to be inserted into the blocklist by mistake. For example the next
1183 hop is a proxy, it is alive, but waiting for the response of the UAS,
1184 and has higher fr_timer value.
1185
1186 The default value is 1, only INVITEs trigger blocklisting
1187
1188 Example 1.20. Set blst_methods_add parameter
1189 ...
1190 # INVITEs and REGISTERs trigger blocklisting
1191 modparam("tm", "blst_methods_add", 33)
1192 ...
1193
1194 3.21. blst_methods_lookup (unsigned integer)
1195
1196 Bitmap of method types that are looked-up in the blocklist before being
1197 forwarded statefully. See also blst_methods_add
1198
1199 The default value is 4294967287, every method type except BYE. (We try
1200 to deliver BYEs no matter what)
1201
1202 Example 1.21. Set blst_methods_lookup parameter
1203 ...
1204 # lookup only INVITEs
1205 modparam("tm", "blst_methods_lookup", 1)
1206 ...
1207
1208 3.22. cancel_b_method (integer)
1209
1210 Method used when attempting to CANCEL an unreplied transaction branch
1211 (a branch where no response was received). The possible values are 0,
1212 1, and 2.
1213
1214 - 0 will immediately stop the request (INVITE) retransmission on the
1215 branch and it will behave as if the branch was immediately replied with
1216 a 487 (a fake internal 487 reply). The advantage is the unreplied
1217 branches will be terminated immediately. However it introduces a race
1218 risk with a possible slightly delayed 2xx reply. In this case we could
1219 have an UA receiving a 2xx after a 487. Moreover this risk is greatly
1220 amplified by packet loss (e.g. if an 180 is lost the branch will look
1221 as unreplied and a CANCEL will silently drop the branch, but a 2xx can
1222 still come at a later time). This is the behaviour for SER versions
1223 older than 2.1.
1224
1225 - 1 will keep retransmitting the request on unreplied branches. If a
1226 provisional answer is received a CANCEL will be immediately sent back
1227 (attempting to quickly trigger a 487). This approach is race free and
1228 avoids the 2xx after 487 problem, but it's more resource intensive:
1229 faced with a branch towards and UA that doesn't answer, a CANCEL
1230 attempt will keep the transaction alive for the whole timeout interval
1231 (fr_timer).
1232
1233 - 2 will send and retransmit CANCEL even on unreplied branches,
1234 stopping the request retransmissions. This has the same advantages as 1
1235 and also avoids the extra roundtrip in the case of the provisional
1236 reply, but it's not RFC 3261 conforming (the RFC allows sending CANCELs
1237 only on pending branches).
1238
1239 The default value is 1.
1240
1241 Example 1.22. Set cancel_b_method parameter
1242 ...
1243 modparam("tm", "cancel_b_method", 1)
1244 ...
1245
1246 3.23. reparse_on_dns_failover (integer)
1247
1248 If set to 1, the SIP message after a DNS failover is constructed from
1249 the outgoing message buffer of the failed branch instead of from the
1250 received request.
1251
1252 It must be set if multiple branches are installed, the SIP message is
1253 modified differently in them, and at least one of them can result in
1254 DNS failover. If the parameter is not set the per-branch modifications
1255 are lost after the failover.
1256
1257 Note: If the parameter is set, branch route block and
1258 TMCB_REQUEST_FWDED callback are not called in case of the failover.
1259
1260 Disadvantage: only the via header is replaced in the message buffer, so
1261 the outgoing socket address is not corrected in any other part of the
1262 message. It is dangerous on multihomed hosts: when the new SIP request
1263 after the DNS failover is sent via different interface than the first
1264 request, the message can contain incorrect IP address in the
1265 Record-Route header.
1266
1267 Default value is 1.
1268
1269 Example 1.23. Set reparse_on_dns_failover parameter
1270 ...
1271 modparam("tm", "reparse_on_dns_failover", 0)
1272 ...
1273
1274 3.24. on_sl_reply (string)
1275
1276 Sets reply route block, to which control is passed when a reply is
1277 received that has no associated transaction. The reply is passed to the
1278 core for stateless forwarding after the route block execution unless
1279 drop is executed (or it returns 0).
1280
1281 If KEMI is used, the parameter has to be the KEMI function name, which
1282 receives a string parameter with the event name, respectively
1283 "on_sl_reply".
1284
1285 Example 1.24. Set on_sl_reply parameter
1286 ...
1287 modparam("tm", "on_sl_reply", "stateless_replies")
1288 ...
1289
1290 onreply_route["stateless_replies"] {
1291 # do not allow stateless replies to be forwarded
1292 return 0;
1293 }
1294
1295 Example 1.25. Set on_sl_reply parameter (KEMI javascript)
1296 ...
1297 modparam("tm", "on_sl_reply", "ksr_slreply")
1298 ...
1299 -- event callback function implemented in javascript
1300 function ksr_slreply(evname) {
1301 # the evname is set to "on_sl_reply"
1302 # do not allow stateless replies to be forwarded
1303 KSR.x.drop();
1304 }
1305
1306 3.25. contacts_avp (string)
1307
1308 This is the name of an XAVP that the t_load_contacts() function uses to
1309 store contacts of the destination set and that t_next_contacts()
1310 function uses to restore those contacts.
1311
1312 Default value is "NULL" (t_load_contacts()/t_next_contacts() functions
1313 are disabled).
1314
1315 Example 1.26. Set contacts_avp parameter
1316 ...
1317 modparam("tm", "contacts_avp", "tm_contacts")
1318 ...
1319
1320 3.26. contact_flows_avp (string)
1321
1322 This is the name of an XAVP that the t_next_contacts() function uses to
1323 store contacts (if any) that it skipped, because they contained same
1324 +sip.instance value than some other contact, and that
1325 t_next_contact_flows() function uses to restore those contacts.
1326
1327 Default value is "NULL". This parameter MUST be set if variable
1328 contacts_avp is set.
1329
1330 Example 1.27. Set contact_flows_avp parameter
1331 ...
1332 modparam("tm", "contact_flows_avp", "tm_contact_flows")
1333 ...
1334
1335 3.27. fr_timer_avp (string)
1336
1337 The value of fr_timer timer can be overridden on per-transaction basis.
1338 The administrator can provide a value to be used for a particular
1339 transaction in an AVP. This parameter contains the name of the AVP that
1340 will be checked. If the AVP exists then its value will be used for the
1341 fr_timer timer, effectively overriding the value configured in fr_timer
1342 parameter for the current transaction.
1343
1344 Note
1345
1346 The value of the AVP is expected to be expressed in seconds and not
1347 milliseconds (unlike the rest of the timers).
1348
1349 This parameter is kept for backwards compatibility (hence its value
1350 expressed in seconds instead of milliseconds and its arcane way of
1351 specifying the avps). The recommended replacement is using t_set_fr()
1352 on a per transaction basis.
1353
1354 See also: t_set_fr(), fr_timer.
1355
1356 In Kamailio compatibility mode (defined by #!KAMAILIO, which is
1357 default), the value of the parameter must be the name of an AVP in
1358 pseudo-variable format: $avp(name). In SER compatibility mode (defined
1359 by #!SER) it must be just AVP name.
1360
1361 Example 1.28. Set fr_timer_avp parameter
1362 ...
1363 # default Kamailio compatibility mode
1364 modparam("tm", "fr_timer_avp", "$avp(frtimer)")
1365 # old SER compatibility mode
1366 modparam("tm", "fr_timer_avp", "frtimer")
1367 ...
1368
1369 3.28. fr_inv_timer_avp (string)
1370
1371 The value of fr_inv_timer timer can be overridden on per-transaction
1372 basis. The administrator can provide a value to be used for a
1373 particular transaction in an AVP. This parameter contains the name of
1374 the AVP that will be checked. If the AVP exists, is non-empty and
1375 non-zero then its value will be used for the fr_inv_timer timer,
1376 effectively overriding the value configured in fr_inv_timer parameter
1377 for the current transaction.
1378
1379 Note
1380
1381 The value of the AVP is expected to be expressed in seconds and not
1382 milliseconds (unlike the rest of the timers).
1383
1384 This parameter is kept for backwards compatibility (hence its value
1385 expressed in seconds instead of milliseconds and its arcane way of
1386 specifying the avps). The recommended replacement is using t_set_fr()
1387 on a per transaction basis.
1388
1389 See also: t_set_fr(), fr_inv_timer.
1390
1391 In Kamailio compatibility mode (defined by #!KAMAILIO, which is
1392 default), the value of the parameter must be the name of an AVP in
1393 pseudo-variable format: $avp(name). In SER compatibility mode (defined
1394 by #!SER) it must by just AVP name.
1395
1396 Example 1.29. Set fr_inv_timer_avp parameter
1397 ...
1398 # Kamailio compatibility mode
1399 modparam("tm", "fr_inv_timer_avp", "$avp(my_fr_inv_timer)")
1400 # old SER compatibility mode
1401 modparam("tm", "fr_inv_timer_avp", "my_fr_inv_timer")
1402 ...
1403
1404 3.29. unmatched_cancel (integer)
1405
1406 This parameter selects between forwarding CANCELs that do not match any
1407 transaction statefully (0, default value), statelessly (1) or dropping
1408 them (2). Note that the stateful forwarding has an additional hidden
1409 advantage: the tm module will be able to recognize INVITEs that arrive
1410 after their CANCEL. Note also that this feature could be used to try a
1411 memory exhaustion DOS attack against a proxy that authenticates all
1412 requests, by continuously flooding the victim with CANCELs to random
1413 destinations (since the CANCEL cannot be authenticated, each received
1414 bogus CANCEL will create a new transaction that will live by default
1415 30s).
1416
1417 Default value is 0.
1418
1419 Example 1.30. Set unmatched_cancel parameter
1420 ...
1421 modparam("tm", "unmatched_cancel", 2)
1422 ...
1423
1424 3.30. ruri_matching (integer)
1425
1426 If set the TM module will try to match the request URI when doing SIP
1427 1.0 (pre-RFC 3261) transaction matching (the "Via" header branch
1428 parameter does not contain the 3261 cookie).
1429
1430 The only reason to have it not set is for interoperability with old,
1431 broken implementations.
1432
1433 Default value is 1 (on).
1434
1435 Can be set at runtime, e.g.:
1436 $ kamcmd cfg.set_now_int tm ruri_matching 0
1437
1438 Example 1.31. Set ruri_matching parameter
1439 ...
1440 modparam("tm", "ruri_matching", 1)
1441 ...
1442
1443 3.31. via1_matching (integer)
1444
1445 If set the TM module will try to match the topmost "Via" header when
1446 doing SIP 1.0 (pre-RFC 3261) transaction matching (the "Via" header
1447 branch parameter does not contain the 3261 cookie).
1448
1449 The only reason to have it not set is for interoperability with old,
1450 broken implementations.
1451
1452 Default value is 1 (on).
1453
1454 Can be set at runtime, e.g.:
1455 $ kamcmd cfg.set_now_int tm via1_matching 0
1456
1457 Example 1.32. Set via1_matching parameter
1458 ...
1459 modparam("tm", "via1_matching", 1)
1460 ...
1461
1462 3.32. callid_matching (integer)
1463
1464 If set the TM module will try to match the callid when doing
1465 transaction matching.
1466
1467 Turn on if you don't want replies/requests from broken clients who send
1468 a mangled Call-ID to match the transaction. For example when the other
1469 side won't recognise the response anyway because of a changed Call-ID,
1470 this setting will prevent accounting records to be created or
1471 failure_route to be skipped.
1472
1473 Default value is 0 (off).
1474
1475 Can be set at runtime, e.g.:
1476 $ kamcmd cfg.set_now_int tm callid_matching 0
1477
1478 Example 1.33. Set callid_matching parameter
1479 ...
1480 modparam("tm", "callid_matching", 1)
1481 ...
1482
1483 3.33. callid_cseq_matching (int)
1484
1485 If set to something other than 0, will do transaction matching using
1486 callid and cseq header values instead of via branch md5 value. Note
1487 that this behavior is non-RFC conpliant!
1488
1489 Default value is 0.
1490
1491 Example 1.34. Set callid_cseq_matching parameter
1492 ...
1493 modparam("tm", "callid_cseq_matching", 0)
1494 ...
1495
1496 kamctl rpc cfg.set_now_int tm callid_cseq_matching 1
1497
1498 3.34. pass_provisional_replies (integer)
1499
1500 If set, TMCB_LOCAL_RESPONSE_OUT tm registered callbacks will be called
1501 also for provisional replies.
1502
1503 Default value is 0 (off).
1504
1505 Can be set at runtime, e.g.:
1506 $ kamcmd cfg.set_now_int tm pass_provisional_replies 1
1507
1508 Example 1.35. Set pass_provisional_replies parameter
1509 ...
1510 modparam("tm", "pass_provisional_replies", 1)
1511 ...
1512
1513 3.35. default_code (integer)
1514
1515 Default response code sent by t_reply() if it cannot retrieve its
1516 parameters (e.g. inexistent avp). Valid values are between 400 and 699.
1517
1518 Default value is 500.
1519
1520 Can be set at runtime, e.g.:
1521 $ kamcmd cfg.set_now_int tm default_code 505
1522
1523 Example 1.36. Set default_code parameter
1524 ...
1525 modparam("tm", "default_code", 501)
1526 ...
1527
1528 3.36. default_reason (string)
1529
1530 Default SIP reason phrase sent by t_reply() if it cannot retrieve its
1531 parameters (e.g. inexistent avp).
1532
1533 Default value is "Server Internal Error".
1534
1535 Can be set at runtime, e.g.:
1536 $ kamcmd cfg.set_now_string tm default_reason "Unknown error"
1537
1538 Example 1.37. Set default_reason parameter
1539 ...
1540 modparam("tm", "default_reason", "Unknown reason")
1541 ...
1542
1543 3.37. disable_6xx_block (integer)
1544
1545 If set the TM module will treat all the 6xx replies like normal replies
1546 (warning: this would be non-RFC conformant behaviour).
1547
1548 If not set (default) receiving a 6xx will cancel all the running
1549 parallel branches, will stop DNS failover and forking. However serial
1550 forking using append_branch() in the failure_route will still work.
1551
1552 It can be overwritten on a per transaction basis using
1553 t_set_disable_6xx().
1554
1555 Default value is 0 (off, rfc conformant behaviour).
1556
1557 Can be set at runtime, e.g.:
1558 $ kamcmd cfg.set_now_int tm disable_6xx_block 0
1559
1560 See also: t_set_disable_6xx().
1561
1562 Example 1.38. Set disable_6xx_block parameter
1563 ...
1564 modparam("tm", "disable_6xx_block", 1)
1565 ...
1566
1567 3.38. local_ack_mode (integer)
1568
1569 This setting controls where locally generated ACKs for 2xx replies to
1570 local transactions (transactions created via t_uac*() either through
1571 the TM api or via RPC/mi/fifo) are sent.
1572
1573 It has 3 possible values:
1574 * 0 - the ACK destination is choosen according to the RFC: the next
1575 hop is found using the contact and the route set and then DNS
1576 resolution is used on it.
1577 * 1 - the ACK is sent to the same address as the corresponding INVITE
1578 branch.
1579 * 2 - the ACK is sent to the source of the 2xx reply.
1580
1581 Note
1582
1583 Modes 1 and 2 do not follow RFC 3261, but are useful to deal with some
1584 simple UAs behind a NAT (no different routing for the ACK and the
1585 contact contains an address behind the NAT).
1586
1587 The default value is 0 (RFC conformant behaviour).
1588
1589 Can be set at runtime, e.g.:
1590 $ kamcmd cfg.set_now_int tm local_ack_mode 0
1591
1592 Example 1.39. Set local_ack_mode parameter
1593 ...
1594 modparam("tm", "local_ack_mode", 1)
1595 ...
1596
1597 3.39. local_ack_branch_mode (integer)
1598
1599 If set to 1, the Via branch value of the ACK for 200ok of a local
1600 INVITE has a slightly different value than the corresponding local
1601 INVITE. If set to 2, a new Via branch is attempted to be created.
1602
1603 Default 0.
1604
1605 Example 1.40. Set local_ack_branch_mode parameter
1606 ...
1607 modparam("tm", "local_ack_branch_mode", 1)
1608 ...
1609
1610 3.40. failure_reply_mode (integer)
1611
1612 This parameter controls how branches are managed and replies are
1613 selected for failure_route handling: keep all, drop all, drop last
1614 branches in SIP serial forking handling.
1615
1616 To control per transaction see t_drop_replies().
1617
1618 It has 4 possible values:
1619 * 0 - all branches are kept, no matter a new leg of serial forking
1620 has been started. Beware that if the new leg fails, you may get in
1621 failure_route a reply code from a branch of previous serial forking
1622 legs (e.g., if in first leg you got a 3xx, then you handled the
1623 redirection in failure route, sent to a new destination and this
1624 one timeout, you will get again the 3xx). Use t_drop_replies() on
1625 per transaction fashion to control the behavior you want. It is the
1626 default behaviour coming from SER 2.1.x.
1627 * 1 - all branches are discarded by default. You can still overwrite
1628 the behaviour via t_drop_replies()
1629 * 2 - by default only the branches of previous leg of serial forking
1630 are discarded
1631 * 3 - all previous branches are discarded if there is a new serial
1632 forking leg. This is the default behaviour coming from Kamailio
1633 1.5.x. Use this mode if you don't want to handle in a per
1634 transaction fashion with t_drop_replies(). It ensures that you will
1635 get the winning reply from the branches of last serial forking step
1636 (e.g., if in first step you get 3xx, then you forward to a new
1637 destination, you will get in failure_route the reply coming from
1638 that destination or a local timeout).
1639
1640 The default value is 3.
1641
1642 Example 1.41. Set failure_reply_mode parameter
1643 ...
1644 modparam("tm", "failure_reply_mode", 0)
1645 ...
1646
1647 3.41. faked_reply_prio (integer)
1648
1649 It controls how branch selection is done. It allows to give a penalty
1650 to faked replies such as the infamous 408 on branch timeout.
1651
1652 Internally, every reply is assigned a priority between 0 (high prio)
1653 and 32000 (low prio). With this parameter the priority of fake replies
1654 can be adjusted.
1655 * 0 - disabled (default)
1656 * < 0 - priority is increased by given amount.
1657 * > 0 - priority is decreased by given amount. Do not make it higher
1658 than 10000 or faked replies will even loose from 1xx class replies.
1659
1660 The default value is 0.
1661
1662 To let received replies win from a locally generated 408, set this
1663 value to 2000.
1664
1665 Example 1.42. Set faked_reply_prio parameter
1666 ...
1667 modparam("tm", "faked_reply_prio", 2000)
1668 ...
1669
1670 3.42. local_cancel_reason (boolean)
1671
1672 Enables/disables adding reason headers (RFC 3326) for CANCELs generated
1673 due to receiving a final reply. The reason header added will look like:
1674 "Reason: SIP;cause=<final_reply_code>".
1675
1676 Default value is 1 (enabled).
1677
1678 Can be set at runtime, e.g.:
1679 $ kamcmd cfg.set_now_int tm local_cancel_reason 0
1680
1681 See also: e2e_cancel_reason.
1682
1683 Example 1.43. Set local_cancel_reason parameter
1684 ...
1685 modparam("tm", "local_cancel_reason", 0)
1686 ...
1687
1688 3.43. e2e_cancel_reason (boolean)
1689
1690 Enables/disables adding reason headers (RFC 3326) for CANCELs generated
1691 due to a received CANCEL. If enabled the reason headers from received
1692 CANCELs will be copied into the generated hop-by-hop CANCELs.
1693
1694 Default value is 1 (enabled).
1695
1696 Can be changed at runtime, e.g.:
1697 $ kamcmd cfg.set_now_int tm e2e_cancel_reason 0
1698
1699 See also: t_set_no_e2e_cancel_reason() and local_cancel_reason.
1700
1701 Example 1.44. Set e2e_cancel_reason parameter
1702 ...
1703 modparam("tm", "e2e_cancel_reason", 0)
1704 ...
1705
1706 3.44. e2e_cancel_hop_by_hop (int)
1707
1708 Enable/disable sending CANCEL in hop-by-hop mode.
1709
1710 Default value: 1 (hop-by-hop mode).
1711
1712 Example 1.45. Set e2e_cancel_hop_by_hop parameter
1713 ...
1714 modparam("tm", "e2e_cancel_hop_by_hop", 0)
1715 ...
1716
1717 3.45. headers_mode (int)
1718
1719 Control how headers from incoming CANCEL should be propagated to
1720 hop-by-hop generated CANCEL. If bit (flag) 1 is set (value 1),
1721 propagate the headers that are not branch specific (e.g., From, To). If
1722 bit (flag) 2 is set, in case processing ends in stateless forwarding by
1723 tm, forward CANCEL with a single Via header (the one added by
1724 Kamailio).
1725
1726 Default value: 0 (do not propagate).
1727
1728 Example 1.46. Set headers_mode parameter
1729 ...
1730 modparam("tm", "headers_mode", 1)
1731 ...
1732
1733 3.46. remap_503_500 (boolean)
1734
1735 Enables/disables conversion of 503 response code to 500. By default it
1736 is enabled, based on the SIP RFC requirement. This is global setting
1737 for all received replies handled by TM. To do it per transaction basis,
1738 let this option disabled, set a failure route and then do
1739 t_reply("500", "...") inside it.
1740
1741 Default value is 1 (enabled).
1742
1743 Example 1.47. Set remap_503_500 parameter
1744 ...
1745 modparam("tm", "remap_503_500", 0)
1746 ...
1747
1748 3.47. failure_exec_mode (boolean)
1749
1750 Add local failed branches in timer to be considered for failure routing
1751 blocks. If disabled, relay functions will return false in case the
1752 branch could not be forwarded (default behaviour before v4.1.0).
1753
1754 Default value is 0 (disabled).
1755
1756 Example 1.48. Set failure_exec_mode parameter
1757 ...
1758 modparam("tm", "failure_exec_mode", 1)
1759 ...
1760
1761 3.48. dns_reuse_rcv_socket (boolean)
1762
1763 Control reuse of the receive socket for additional branches added by
1764 DNS failover. If set to 1, the receive socket is used for sending out
1765 the new branches, unless the socket is forced explicitely in
1766 configuration file. If set to 0, selected socket is done depending on
1767 value of global parameter "mhomed" (if mhomed=0, then the first listen
1768 socket is used, otherwise the socket is selected based on routing
1769 rules).
1770
1771 Do enable it with caution, it might create troubles on DNS results with
1772 different transport layer. Better let it be disabled and enable
1773 "mhomed".
1774
1775 Default value is 0 (disabled).
1776
1777 Example 1.49. Set dns_reuse_rcv_socket parameter
1778 ...
1779 modparam("tm", "dns_reuse_rcv_socket", 1)
1780 ...
1781
1782 3.49. xavp_contact (string)
1783
1784 The name of XAVP storing the attributes per contact. This must be the
1785 same as the usrloc parameter xavp_contact.
1786
1787 Default value is “NULL”.
1788
1789 Example 1.50. Set xavp_contact parameter
1790 ...
1791 modparam("tm|usrloc", "xavp_contact", "ulattrs")
1792 ...
1793
1794 3.50. event_callback (str)
1795
1796 The name of the function in the kemi configuration file (embedded
1797 scripting language such as Lua, Python, ...) to be executed instead of
1798 event_route[tm:local-request] block. The function receives a string
1799 parameter with the name of the event, respectively "tm:local-request".
1800
1801 Default value is 'empty' (no function is executed for events).
1802
1803 Example 1.51. Set event_callback parameter
1804 ...
1805 modparam("tm", "event_callback", "ksr_tm_event")
1806 ...
1807 -- event callback function implemented in Lua
1808 function ksr_tm_event(evname)
1809 KSR.info("===== tm module triggered event: " .. evname .. "\n");
1810 return 1;
1811 end
1812 ...
1813
1814 3.51. event_callback_lres_sent (str)
1815
1816 The name of the function in the kemi configuration file (embedded
1817 scripting language such as Lua, Python, ...) to be executed instead of
1818 event_route[tm:local-response] block. The function receives a string
1819 parameter with the name of the event, respectively "tm:local-response".
1820
1821 Default value is 'empty' (no function is executed for events).
1822
1823 Example 1.52. Set event_callback_lres_sent parameter
1824 ...
1825 modparam("tm", "event_callback_lres_sent", "ksr_tm_event_response_sent")
1826 ...
1827 -- event callback function implemented in Lua
1828 function ksr_tm_event_response_sent(evname)
1829 KSR.info("===== tm module triggered event: " .. evname .. "\n");
1830 return 1;
1831 end
1832 ...
1833
1834 3.52. evcb_local_ack_sent (str)
1835
1836 The name of the function in the kemi configuration file (embedded
1837 scripting language such as Lua, Python, ...) to be executed instead of
1838 event_route[tm:local-ack-sent] block. The function receives a string
1839 parameter with the name of the event, respectively "tm:local-ack-sent".
1840
1841 Default value is 'empty' (no function is executed for events).
1842
1843 Example 1.53. Set evcb_local_ack_sent parameter
1844 ...
1845 modparam("tm", "evcb_local_ack_sent", "ksr_tm_event_local_ack_sent")
1846 ...
1847 -- event callback function implemented in Lua
1848 function ksr_tm_event_local_ack_sent(evname)
1849 KSR.info("===== tm module triggered event: " .. evname .. "\n");
1850 return 1;
1851 end
1852 ...
1853
1854 3.53. relay_100 (str)
1855
1856 This parameter controls whether or not a SIP 100 response is proxied.
1857 Note that this is not valid behavior when operating in stateful mode
1858 per RFC 3261 Section 21.1.1, and therefore is useful only when
1859 operating as a stateless proxy. When using this feature, it is possible
1860 to control which 100 responses are proxied and which are not by
1861 detecting whether they are part of an existing transaction and setting
1862 up the appropriate logic in onreply_route.
1863
1864 Default value is 0 (disabled).
1865
1866 Example 1.54. Set relay_100 parameter
1867 ...
1868 modparam("tm", "relay_100", 1)
1869 ...
1870
1871 3.54. rich_redirect (int)
1872
1873 When sending a 3xx class reply, include additional branch info to the
1874 contacts such as path vector and branch flags.
1875 * 0 - no extra info is added (default)
1876 * 1 - include branch flags as contact header parameter
1877 * 2 - include path as contact uri Route header
1878
1879 Values may be combined (added).
1880
1881 Example 1.55. rich_redirect example
1882 ...
1883 modparam("tm", "rich_redirect", 3)
1884 ....
1885
1886 3.55. exec_time_check (int)
1887
1888 Duration in milliseconds for executing transaction failure callbacks
1889 and failure_route block after which to do a safety check if transaction
1890 is still active.
1891
1892 Set it to 0 in order to disable this check.
1893
1894 Default value is 5000 (5 seconds).
1895
1896 Example 1.56. Set exec_time_check parameter
1897 ...
1898 modparam("tm", "exec_time_check", 0)
1899 ...
1900
1901 3.56. reply_relay_mode (int)
1902
1903 If set to 1, a received 200 OK response that was suspended is no longer
1904 forwarded in the transactional context if another final response was
1905 forwarded while 200 OK was suspended. Forwarding the 200 OK, even it
1906 was received first, results in overwriting the transaction response
1907 buffer that can impact matching of incoming ACKs.
1908
1909 Set it to 0 in order to disable this behaviour and attempt to forward
1910 suspended 200 OK in the transaction context. This was the behaviour
1911 before the commit 18410da0.
1912
1913 Default value is 1.
1914
1915 Example 1.57. Set reply_relay_mode parameter
1916 ...
1917 modparam("tm", "reply_relay_mode", 0)
1918 ...
1919
1920 3.57. enable_uac_fr (int)
1921
1922 Enable failure route trigger, for uac. This will copy the tm uac into
1923 uas. Thus, failure route can be triggered even for uac messages. The
1924 default is 0 (disabled).
1925
1926 Example 1.58. enable_uac_fr example
1927 ...
1928 modparam("tm", "enable_uac_fr", 1)
1929 ....
1930
1931 3.58. failover_reply_codes (string)
1932
1933 This parameter defines the response codes (only codes >= 300 and class
1934 >= 3), which enable dns failover to continue to try next ips when
1935 previous one fail. It is a list separated by colons, where you may
1936 define either a single code (e.g. "code=408" would accept 408 as an
1937 additional response code) or a class of responses, you want to accept
1938 (e.g. "class=3" would accept everything from 300 to 999 as valid
1939 response). (with default behaviour only 503 code or no response from
1940 previous one will try next ip).
1941
1942 Default value is “”
1943
1944 Example 1.59. Set the “failover_reply_codes” parameter
1945 ...
1946 modparam("tm", "failover_reply_codes", "code=403;code=488;class=5")
1947 ...
1948
1949 3.59. reply_408_code (int)
1950
1951 Status code for internally generated timeout responses.
1952 Default value is “408”.
1953
1954 Example 1.60. reply_408_code example
1955 ...
1956 modparam("tm", "reply_408_code", 410)
1957 ....
1958
1959 3.60. reply_408_reason (str)
1960
1961 Reason phrase for internally generated timeout responses.
1962 Default value is “Request Timeout”.
1963
1964 Example 1.61. reply_408_reason example
1965 ...
1966 modparam("tm", "reply_408_reason", "Gone")
1967 ....
1968
1969 3.61. delayed_reply (int)
1970
1971 If set to 1, the reply generation in case of request
1972 processing/forwarding error is delayed till the config script execution
1973 ends. This allows the script writer to send its own error reply. If set
1974 to 0, the transaction is replied and killed immediately.
1975 Default value is “1”.
1976
1977 Example 1.62. delayed_reply example
1978 ...
1979 modparam("tm", "delayed_reply", 0)
1980 ....
1981
1982 3.62. evlreq_mode (int)
1983
1984 If bit 1 is set (value 1), the event_route[tm:local-request] is also
1985 executed for hop-by-hop CANCEL requests (for received INVITEs, not only
1986 for local generated ones).
1987 Default value is “0”.
1988
1989 Example 1.63. evlreq_mode example
1990 ...
1991 modparam("tm", "evlreq_mode", 1)
1992 ....
1993
1994 4. Functions
1995
1996 4.1. t_relay([host, port])
1997 4.2. t_relay_to_udp([ip, port])
1998 4.3. t_relay_to_tcp([ip, port])
1999 4.4. t_relay_to_tls([ip, port])
2000 4.5. t_relay_to_sctp([ip, port])
2001 4.6. t_on_failure(failure_route)
2002 4.7. t_on_branch_failure(branch_failure_route)
2003 4.8. t_on_reply(onreply_route)
2004 4.9. t_on_branch(branch_route)
2005 4.10. t_newtran()
2006 4.11. t_reply(code, reason_phrase)
2007 4.12. t_reply_error()
2008 4.13. t_send_reply(code, reason)
2009 4.14. t_lookup_request()
2010 4.15. t_retransmit_reply()
2011 4.16. t_release()
2012 4.17. t_forward_nonack([ip, port])
2013 4.18. t_forward_nonack_udp(ip, port)
2014 4.19. t_forward_nonack_tcp(ip, port)
2015 4.20. t_forward_nonack_tls(ip, port)
2016 4.21. t_forward_nonack_sctp(ip, port)
2017 4.22. t_set_fr(fr_inv_timeout [, fr_timeout])
2018 4.23. t_reset_fr()
2019 4.24. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
2020 4.25. t_reset_max_lifetime()
2021 4.26. t_set_retr(retr_t1_interval, retr_t2_interval)
2022 4.27. t_reset_retr()
2023 4.28. t_set_auto_inv_100(0|1)
2024 4.29. t_branch_timeout()
2025 4.30. t_branch_replied()
2026 4.31. t_any_timeout()
2027 4.32. t_any_replied()
2028 4.33. t_grep_status("code")
2029 4.34. t_is_canceled()
2030 4.35. t_is_expired()
2031 4.36. t_relay_cancel()
2032 4.37. t_lookup_cancel([1])
2033 4.38. t_drop_replies([mode])
2034 4.39. t_save_lumps()
2035 4.40. t_load_contacts([mode])
2036 4.41. t_next_contacts()
2037 4.42. t_next_contact_flow()
2038 4.43. t_check_status(re)
2039 4.44. t_check_trans()
2040 4.45. t_set_disable_6xx(0|1)
2041 4.46. t_set_disable_failover(0|1)
2042 4.47. t_set_disable_internal_reply(0|1)
2043 4.48. t_set_no_auto_ack(0|1)
2044 4.49. t_replicate([params])
2045 4.50. t_relay_to(proxy, flags)
2046 4.51. t_relay_to_proxy(proxy [, flags])
2047 4.52. t_set_no_e2e_cancel_reason(0|1)
2048 4.53. t_is_set(target)
2049 4.54. t_use_uac_headers()
2050 4.55. t_is_retr_async_reply()
2051 4.56. t_uac_send(method, ruri, nexthop, socket, headers, body)
2052 4.57. t_get_status_code()
2053 4.58. t_clean()
2054 4.59. t_exists()
2055 4.60. t_cell_append_branches(tindex, tlabel)
2056 4.61. t_msg_apply_changes()
2057
2058 4.1. t_relay([host, port])
2059
2060 Relay a SIP request statefully either to the destination indicated in
2061 the current URI (if called without any parameters) or to the specified
2062 host and port. In the later case (host and port specified) the protocol
2063 used is the same protocol on which the message was received. It creates
2064 the SIP transaction, if none was created before (e.g., with
2065 t_newtran()).
2066
2067 t_relay() is the stateful version for forward() while t_relay(host,
2068 port) is similar to forward(host, port).
2069
2070 In the forward to uri case (t_relay()), if the original URI was
2071 rewritten (by UsrLoc, RR, strip/prefix, etc.) the new URI will be
2072 taken). The destination (including the protocol) is determined from the
2073 uri, using SIP specific DNS resolving if needed (NAPTR, SRV a.s.o
2074 depending also on the dns options).
2075
2076 Returns a negative value on failure -- you may still want to send a
2077 negative reply upstream statelessly not to leave upstream UAC in lurch.
2078
2079 Example 1.64. t_relay usage
2080 ...
2081 if (!t_relay())
2082 {
2083 send_reply_error();
2084 break;
2085 };
2086 ...
2087
2088 4.2. t_relay_to_udp([ip, port])
2089
2090 Relay a message statefully using a fixed protocol either to the
2091 specified fixed destination or to a destination derived from the
2092 message uri (if the host address and port are not specified). These
2093 along with t_relay are the functions most users want to use--all other
2094 are mostly for programming. Programmers interested in writing TM logic
2095 should review how t_relay is implemented in tm.c and how TM callbacks
2096 work.
2097
2098 Meaning of the parameters is as follows:
2099 * ip - IP address where the message should be sent.
2100 * port - Port number.
2101
2102 If no parameters are specified the message is sent to a destination
2103 derived from the message uri (using sip specific DNS lookups), but with
2104 the protocol corresponding to the function name.
2105
2106 Example 1.65. t_relay_to_udp usage
2107 ...
2108 if (src_ip==10.0.0.0/8)
2109 t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
2110 else
2111 t_relay_to_tcp(); # relay to msg. uri, but over tcp
2112 ...
2113
2114 4.3. t_relay_to_tcp([ip, port])
2115
2116 See function t_relay_to_udp([ip, port]).
2117
2118 4.4. t_relay_to_tls([ip, port])
2119
2120 See function t_relay_to_udp([ip, port]).
2121
2122 4.5. t_relay_to_sctp([ip, port])
2123
2124 See function t_relay_to_udp([ip, port]).
2125
2126 4.6. t_on_failure(failure_route)
2127
2128 Sets failure routing block, to which control is passed after a
2129 transaction completed with a negative result but before sending a final
2130 reply. In the referred block, you can either start a new branch (good
2131 for services such as forward_on_no_reply) or send a final reply on your
2132 own (good for example for message silo, which received a negative reply
2133 from upstream and wants to tell upstream "202 I will take care of it").
2134 Note that the set of commands which are usable within failure_routes is
2135 strictly limited to rewriting URI, initiating new branches, logging,
2136 and sending stateful replies (t_reply). Any other commands may result
2137 in unpredictable behavior and possible server failure. Note that
2138 whenever failure_route is entered, uri is reset to value which it had
2139 on relaying. If it temporarily changed during a reply_route processing,
2140 subsequent reply_route will ignore the changed value and use again the
2141 original one.
2142
2143 Meaning of the parameters is as follows:
2144 * failure_route - Failure route block to be called.
2145
2146 Example 1.66. t_on_failure usage
2147 ...
2148 route {
2149 t_on_failure("1");
2150 t_relay();
2151 }
2152
2153 failure_route[1] {
2154 revert_uri();
2155 setuser("voicemail");
2156 append_branch();
2157 }
2158 ...
2159
2160 See misc/examples/mixed/onr.cfg for a more complex example of
2161 combination of serial with parallel forking.
2162
2163 4.7. t_on_branch_failure(branch_failure_route)
2164
2165 Sets the branch_failure routing block, to which control is passed on
2166 each negative response to a transaction. This route is run before
2167 deciding if the transaction is complete. In the referred block, you can
2168 start a new branch which is required for failover of multiple outbound
2169 flows (RFC 5626). Note that the set of commands which are usable within
2170 a branch_failure route is limited to a subset of the failure_route
2171 commands including logging, rewriting URI and initiating new branches.
2172 Any other commands may generate errors or result in unpredictable
2173 behavior. Note that whenever failure_route is entered, uri is reset to
2174 value which it had on relaying. If it temporarily changed during a
2175 reply_route processing, subsequent reply_route will ignore the changed
2176 value and use again the original one.
2177
2178 Function Parameters:
2179 * branch_failure_route - Name of the branch_failure route block to be
2180 called (it is prefixed internally with 'tm:branch-failure:').
2181
2182 Example 1.67. t_on_branch_failure usage
2183 ...
2184 route {
2185 t_on_branch_failure("myroute");
2186 t_relay();
2187 }
2188
2189 event_route[tm:branch-failure:myroute] {
2190 if (t_check_status("430|403") {
2191 unregister("location", "$tu", "$T_reply_ruid");
2192 }
2193 }
2194 ...
2195
2196 4.8. t_on_reply(onreply_route)
2197
2198 Sets the reply routing block, to which control is passed when a reply
2199 for the current transaction is received. Note that the set of commands
2200 which are usable within onreply_routes is limited.
2201
2202 Meaning of the parameters is as follows:
2203 * onreply_route - Onreply route block to be called.
2204
2205 Example 1.68. t_on_reply usage
2206 ...
2207 loadmodule "/usr/local/lib/ser/modules/nathelper.so"
2208 ...
2209 route {
2210 /* if natted */
2211 t_on_reply("1");
2212 t_relay();
2213 }
2214
2215 onreply_route[1] {
2216 if (status=~ "(183)|2[0-9][0-9]"){
2217 force_rtp_proxy();
2218 search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=y
2219 es');
2220 }
2221 if (nat_uac_test("1")){
2222 fix_nated_contact();
2223 }
2224 }
2225
2226 4.9. t_on_branch(branch_route)
2227
2228 Sets the branch routing block, to which control is passed after forking
2229 (when a new branch is created). For now branch routes are intended only
2230 for last minute changes of the SIP messages (like adding new headers).
2231 Note that the set of commands which are usable within branch_routes is
2232 very limited. It is not possible to generate a reply.
2233
2234 Meaning of the parameters is as follows:
2235 * branch_route - branch route block to be called.
2236
2237 Example 1.69. t_on_branch usage
2238 ...
2239 route {
2240 t_on_branch("1");
2241 t_relay();
2242 }
2243
2244 branch_route[1] {
2245 if (uri=~"sip:[0-9]+"){
2246 append_hf("P-Warn: numeric uri\r\n");
2247 }
2248 }
2249
2250 4.10. t_newtran()
2251
2252 Creates a new transaction, returns a negative value on error.
2253 Typically, it is used to deploy a UAS.
2254
2255 Note: once the t_newtran() is executed, the new message flag operations
2256 (i.e., setflag() and resetflag()) are not synchronized to the
2257 transaction, being stored only in the private memory SIP message
2258 structure. Use the tmx module function t_flush_flags() to synchronize
2259 the modified message flags to the already created transaction.
2260
2261 Example 1.70. t_newtran usage
2262 ...
2263 if (t_newtran()) {
2264 xlog("the transaction has been created\n");
2265 t_reply("999","hello");
2266 } else {
2267 sl_reply_error();
2268 }
2269 ...
2270
2271 See misc/examples/mixed/uas.cfg for more examples.
2272
2273 4.11. t_reply(code, reason_phrase)
2274
2275 Sends a stateful reply after a transaction has been established. See
2276 t_newtran for usage.
2277
2278 If the code is in the range 300-399 (redirect reply), the current
2279 destination set is appended to the reply as Contact headers. The
2280 destination set contains the request URI (R-URI), if it is modified
2281 compared to the received one, plus the branches added to the request
2282 (e.g., after an append_branch() or lookup("location")). If the R-URI
2283 was changed but it is not desired to be part of the destination set, it
2284 can be reverted using the function revert_uri().
2285
2286 Custom headers to the reply can be added using append_to_reply()
2287 function from textops module.
2288
2289 Meaning of the parameters is as follows:
2290 * code - Reply code number.
2291 * reason_phrase - Reason string.
2292
2293 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
2294 ONREPLY_ROUTE.
2295
2296 Example 1.71. t_reply usage
2297 ...
2298 t_reply("404", "Not found");
2299 ...
2300
2301 4.12. t_reply_error()
2302
2303 Sends a stateful reply based in internal error code, similar to
2304 sl_send_error() from sl module.
2305
2306 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
2307 ONREPLY_ROUTE.
2308
2309 Example 1.72. t_reply_error usage
2310 ...
2311 t_reply_error();
2312 ...
2313
2314 4.13. t_send_reply(code, reason)
2315
2316 Creates the transaction if it does not exist (executing internally
2317 t_newtran()) and sends a stateful reply (executing internally
2318 t_reply()). If transaction exists, this function does not stop the
2319 execution of config, t_reply() being still executed.
2320
2321 For more, see the docs for t_newtran() and t_reply().
2322
2323 Meaning of the parameters is as follows:
2324 * code - Reply code number.
2325 * reason - Reason string.
2326
2327 Example 1.73. t_send_reply usage
2328 ...
2329 t_send_reply("404", "Not found");
2330 ...
2331
2332 4.14. t_lookup_request()
2333
2334 Checks if a transaction exists. Returns a positive value if so,
2335 negative otherwise. Most likely you will not want to use it, as a
2336 typical application of a look-up is to introduce a new transaction if
2337 none was found. However this is safely (atomically) done using
2338 t_newtran.
2339
2340 Example 1.74. t_lookup_request usage
2341 ...
2342 if (t_lookup_request()) {
2343 ...
2344 };
2345 ...
2346
2347 4.15. t_retransmit_reply()
2348
2349 Retransmits a reply sent previously by UAS transaction.
2350
2351 Example 1.75. t_retransmit_reply usage
2352 ...
2353 t_retransmit_reply();
2354 ...
2355
2356 4.16. t_release()
2357
2358 Remove transaction from memory (it will be first put on a wait timer to
2359 absorb delayed messages).
2360
2361 Example 1.76. t_release usage
2362 ...
2363 t_release();
2364 ...
2365
2366 4.17. t_forward_nonack([ip, port])
2367
2368 Mainly for internal usage -- forward a non-ACK request statefully.
2369 Variants of this functions can enforce a specific transport protocol.
2370
2371 Meaning of the parameters is as follows:
2372 * ip - IP address where the message should be sent.
2373 * port - Port number.
2374
2375 Example 1.77. t_forward_nonack usage
2376 ...
2377 t_forward_nonack("1.2.3.4", "5060");
2378 ...
2379
2380 4.18. t_forward_nonack_udp(ip, port)
2381
2382 See function t_forward_nonack([ip, port]).
2383
2384 4.19. t_forward_nonack_tcp(ip, port)
2385
2386 See function t_forward_nonack([ip, port]).
2387
2388 4.20. t_forward_nonack_tls(ip, port)
2389
2390 See function t_forward_nonack([ip, port]).
2391
2392 4.21. t_forward_nonack_sctp(ip, port)
2393
2394 See function t_forward_nonack([ip, port]).
2395
2396 4.22. t_set_fr(fr_inv_timeout [, fr_timeout])
2397
2398 Sets the fr_inv_timeout and optionally fr_timeout for the current
2399 transaction or for transactions created during the same script
2400 invocation, after calling this function. If the transaction is already
2401 created (e.g called after t_relay() or in an onreply_route) all the
2402 branches will have their final response timeout updated on-the-fly. If
2403 one of the parameters is 0, its value won't be changed.
2404
2405 Meaning of the parameters is as follows:
2406 * fr_inv_timeout - new final response timeout (in milliseconds) for
2407 INVITEs. See also fr_inv_timer.
2408 * fr_timeout - new final response timeout (in milliseconds) for
2409 non-INVITE transaction, or INVITEs which haven't received yet a
2410 provisional response. See also fr_timer.
2411
2412 See also: fr_timer, fr_inv_timer, t_reset_fr().
2413
2414 Example 1.78. t_set_fr usage
2415 ...
2416 route {
2417 t_set_fr(10000); # set only fr invite timeout to 10s
2418 t_on_branch("1");
2419 t_relay();
2420 }
2421
2422 branch_route[1] {
2423 # if we are calling the pstn, extend the invite timeout to 50s
2424 # for all the branches, and set the no-reply-received timeout to 2s
2425 if (uri=~"sip:[0-9]+"){
2426 t_set_fr(50000, 2000);
2427 }
2428 }
2429
2430 4.23. t_reset_fr()
2431
2432 Resets the fr_inv_timer and fr_timer for the current transaction to the
2433 default values (set using the tm module parameters fr_inv_timer and
2434 fr_timer).
2435
2436 It will effectively cancel any previous calls to t_set_fr for the same
2437 transaction.
2438
2439 See also: fr_timer, fr_inv_timer, t_set_fr.
2440
2441 Example 1.79. t_reset_fr usage
2442 ...
2443 route {
2444 ...
2445 t_reset_fr();
2446 ...
2447 }
2448
2449 4.24. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
2450
2451 Sets the maximum lifetime for the current INVITE or non-INVITE
2452 transaction, or for transactions created during the same script
2453 invocation, after calling this function (that's why it takes values for
2454 both INVITE and non-INVITE). If one of the parameters is 0, its value
2455 won't be changed.
2456
2457 It works as a per transaction max_inv_lifetime or max_noninv_lifetime.
2458
2459 Meaning of the parameters is as follows:
2460 * inv_lifetime - maximum INVITE transaction lifetime (in
2461 milliseconds). See also max_inv_lifetime.
2462 * noninv_lifetime - maximum non-INVITE transaction lifetime (in
2463 milliseconds). See also max_noninv_lifetime.
2464
2465 See also: max_inv_lifetime, max_noninv_lifetime, t_reset_max_lifetime.
2466
2467 Example 1.80. t_set_max_lifetime usage
2468 ...
2469 route {
2470 if (src_ip=1.2.3.4)
2471 t_set_max_lifetime(120000, 0); # set only max_inv_lifetime to 120s
2472 else
2473 t_set_max_lifetime(90000, 15000); # set the maximum lifetime to 90s if
2474 # the current transaction is an
2475 # INVITE and to 15s if not
2476 }
2477
2478 4.25. t_reset_max_lifetime()
2479
2480 Resets the maximum lifetime for the current INVITE or non-INVITE
2481 transaction to the default value (set using the tm module parameter
2482 max_inv_lifetime or max_noninv_lifetime).
2483
2484 It will effectively cancel any previous calls to t_set_max_lifetime for
2485 the same transaction.
2486
2487 See also: max_inv_lifetime, max_noninv_lifetime, t_set_max_lifetime.
2488
2489 Example 1.81. t_reset_max_lifetime usage
2490 ...
2491 route {
2492 ...
2493 t_reset_max_lifetime();
2494 ...
2495 }
2496
2497 4.26. t_set_retr(retr_t1_interval, retr_t2_interval)
2498
2499 Sets the retr_t1_interval and retr_t2_interval for the current
2500 transaction or for transactions created during the same script
2501 invocation, after calling this function. If one of the parameters is 0,
2502 its value won't be changed. If the transaction is already created (e.g
2503 called after t_relay() or in an onreply_route) all the existing
2504 branches will have their retransmissions intervals updated on-the-fly:
2505 if the retransmission interval for the branch has not yet reached T2
2506 the interval will be reset to retr_t1_interval, else to
2507 retr_t2_interval. Note that the change will happen after the current
2508 interval expires (after the next retransmission, the next-next
2509 retransmission will take place at retr_t1_interval or
2510 retr_t2_interval). All new branches of the same transaction will start
2511 with the new values. This function will work even if it's called in the
2512 script before a transaction creating function (e.g.: t_set_retr(500,
2513 4000); t_relay()). All new transaction created after this function
2514 call, during the same script invocation will use the new values.
2515
2516 Meaning of the parameters is as follows:
2517 * retr_t1_interval - new T1 retransmission interval (in
2518 milliseconds). See also retr_t1_timeout.
2519 * retr_t2_interval - new T2 (or maximum) retransmission interval (in
2520 milliseconds). See also retr_t2_timeout.
2521
2522 See also: retr_timer1, retr_timer2, t_reset_retr().
2523
2524 Example 1.82. t_set_retr usage
2525 ...
2526 route {
2527 t_set_retr(250, 0); # set only T1 to 250 ms
2528 t_on_branch("1");
2529 t_relay();
2530 }
2531
2532 branch_route[1] {
2533 # if we are calling the a remote pstn, extend T1 and decrease T2
2534 # for all the branches
2535 if (uri=~"sip:[0-9]+"){
2536 t_set_retr(500, 2000);
2537 }
2538 }
2539
2540 4.27. t_reset_retr()
2541
2542 Resets the retr_timer1 and retr_timer2 for the current transaction to
2543 the default values (set using the tm module parameters retr_timer1 and
2544 retr_timer2).
2545
2546 It will effectively cancel any previous calls to t_set_retr for the
2547 same transaction.
2548
2549 See also: retr_timer1, retr_timer2, t_set_retr.
2550
2551 Example 1.83. t_reset_retr usage
2552 ...
2553 route {
2554 ...
2555 t_reset_retr();
2556 ...
2557 }
2558
2559 4.28. t_set_auto_inv_100(0|1)
2560
2561 Switch automatically sending 100 replies to INVITEs on/off on a per
2562 transaction basis. It overrides the auto_inv_100 value for the current
2563 transaction.
2564
2565 See also: auto_inv_100.
2566
2567 Example 1.84. t_set_auto_inv_100 usage
2568 ...
2569 route {
2570 ...
2571 if (src_ip==1.2.3.0/24)
2572 t_set_auto_inv_100(0); # turn off automatic 100 replies
2573 ...
2574 }
2575
2576 4.29. t_branch_timeout()
2577
2578 Returns true if the failure route is executed for a branch that did
2579 timeout. It can be used from FAILURE_ROUTE and BRANCH_FAILURE_ROUTE
2580 event route.
2581
2582 Example 1.85. t_branch_timeout usage
2583 ...
2584 failure_route[0]{
2585 if (t_branch_timeout()){
2586 log("timeout\n");
2587 # ...
2588 }
2589 }
2590
2591 4.30. t_branch_replied()
2592
2593 Returns true if the failure route is executed for a branch that did
2594 receive at least one reply in the past (the "current" reply is not
2595 taken into account). It can be used from failure_route and
2596 branch-failure event route.
2597
2598 Example 1.86. t_branch_replied usage
2599 ...
2600 failure_route[0]{
2601 if (t_branch_timeout()){
2602 if (t_branch_replied())
2603 log("timeout after receiving a reply (no answer?)\n");
2604 else
2605 log("timeout, remote side seems to be down\n");
2606 # ...
2607 }
2608 }
2609
2610 4.31. t_any_timeout()
2611
2612 Returns true if at least one of the current transactions branches did
2613 timeout.
2614
2615 Example 1.87. t_any_timeout usage
2616 ...
2617 failure_route[0]{
2618 if (!t_branch_timeout()){
2619 if (t_any_timeout()){
2620 log("one branch did timeout\n");
2621 sl_send_reply("408", "Timeout");
2622 }
2623 }
2624 }
2625
2626 4.32. t_any_replied()
2627
2628 Returns true if at least one of the current transactions branches did
2629 receive some reply in the past. If called from a failure or onreply
2630 route, the "current" reply is not taken into account.
2631
2632 Example 1.88. t_any_replied usage
2633 ...
2634 onreply_route[0]{
2635 if (!t_any_replied()){
2636 log("first reply received\n");
2637 # ...
2638 }
2639 }
2640
2641 4.33. t_grep_status("code")
2642
2643 Returns true if "code" is the final reply received (or locally
2644 generated) in at least one of the current transactions branches.
2645
2646 Example 1.89. t_grep_status usage
2647 ...
2648 onreply_route[0]{
2649 if (t_grep_status("486")){
2650 /* force a 486 reply, even if this is not the winning branch */
2651 t_reply("486", "Busy");
2652 }
2653 }
2654
2655 4.34. t_is_canceled()
2656
2657 Returns true if the current transaction was canceled.
2658
2659 Example 1.90. t_is_canceled usage
2660 ...
2661 failure_route[0]{
2662 if (t_is_canceled()){
2663 log("transaction canceled\n");
2664 # ...
2665 }
2666 }
2667
2668 4.35. t_is_expired()
2669
2670 Returns true if the current transaction has already expired, i.e. the
2671 max_inv_lifetime/max_noninv_lifetime interval has already elapsed.
2672
2673 Example 1.91. t_is_expired usage
2674 ...
2675 failure_route[0]{
2676 if (t_is_expired()){
2677 log("transaction expired\n");
2678 # There is no point in adding a new branch.
2679 }
2680 }
2681
2682 4.36. t_relay_cancel()
2683
2684 Forwards the CANCEL if the corresponding INVITE transaction exists. The
2685 function is supposed to be used at the very beginning of the script,
2686 because the CANCELs can be caught and the rest of the script can be
2687 bypassed this way. Do not disable reparse_invite module parameter, and
2688 call t_relay_cancel() right after the sanity tests.
2689
2690 Return value is 0 (drop) if the corresponding INVITE was found and the
2691 CANCELs were successfully sent to the pending branches, true if the
2692 INVITE was not found, and false in case of any error.
2693
2694 Example 1.92. t_relay_cancel usage
2695 if (method == CANCEL) {
2696 if (!t_relay_cancel()) { # implicit drop if relaying was successful,
2697 # nothing to do
2698
2699 # corresponding INVITE transaction found but error occurred
2700 sl_reply("500", "Internal Server Error");
2701 drop;
2702 }
2703 # bad luck, corresponding INVITE transaction is missing,
2704 # do the same as for INVITEs
2705 }
2706
2707 4.37. t_lookup_cancel([1])
2708
2709 Returns true if the corresponding INVITE transaction exists for a
2710 CANCEL request. The function can be called at the beginning of the
2711 script to check whether or not the CANCEL can be immediately forwarded
2712 bypassing the rest of the script. Note however that t_relay_cancel
2713 includes t_lookup_cancel as well, therefore it is not needed to
2714 explicitly call this function unless something has to be logged for
2715 example.
2716
2717 If the function parameter (optional) is set to 1, the message flags are
2718 overwritten with the flags of the INVITE. isflagset() can be used to
2719 check the flags of the previously forwarded INVITE in this case.
2720
2721 Example 1.93. t_lookup_cancel usage
2722 if (method == CANCEL) {
2723 if (t_lookup_cancel()) {
2724 log("INVITE transaction exists");
2725 if (!t_relay_cancel()) { # implicit drop if
2726 # relaying was successful,
2727 # nothing to do
2728
2729 # corresponding INVITE transaction found
2730 # but error occurred
2731 sl_reply("500", "Internal Server Error");
2732 drop;
2733 }
2734 }
2735 # bad luck, corresponding INVITE transaction is missing,
2736 # do the same as for INVITEs
2737 }
2738
2739 4.38. t_drop_replies([mode])
2740
2741 Drops all the previously received replies in failure_route block to
2742 make sure that none of them is picked up again.
2743
2744 The parameter 'mode' controls which replies are dropped: 'a' or missing
2745 - all replies are dropped; 'l' - replies received for last set of
2746 branches are dropped; 'n' - no reply is dropped.
2747
2748 Dropping replies works only if a new branch is added to the
2749 transaction, or it is explicitly replied in the script!
2750
2751 Example 1.94. t_drop_replies() usage
2752 ...
2753 failure_route[0]{
2754 if (t_check_status("5[0-9][0-9]")){
2755 # I do not like the 5xx responses,
2756 # so I give another chance to "foobar.com",
2757 # and I drop all the replies to make sure that
2758 # they are not forwarded to the caller.
2759 t_drop_replies();
2760
2761 rewritehostport("foobar.com");
2762 append_branch();
2763 t_relay();
2764 }
2765 }
2766
2767 4.39. t_save_lumps()
2768
2769 Forces the modifications of the processed SIP message to be saved in
2770 shared memory before t_relay() is called. The new branches which are
2771 created in failure_route will contain the same modifications, and any
2772 other modification after t_save_lumps() will be lost.
2773
2774 Note that t_relay() automatically saves the modifications when it is
2775 called the first time, there is no need for t_save_lumps() unless
2776 message changes between t_save_lumps() and t_relay() must not be
2777 propagated to failure_route.
2778
2779 The transaction must be created by t_newtran() before calling
2780 t_save_lumps().
2781
2782 Example 1.95. t_save_lumps() usage
2783 route {
2784 ...
2785 t_newtran();
2786 append_hf("hf1: my first header\r\n");
2787 ...
2788 t_save_lumps();
2789 append_hf("hf2: my second header\r\n");
2790 ...
2791 t_on_failure("1");
2792 t_relay();
2793 }
2794
2795 failure_route[1] {
2796 append_branch();
2797 append_hf("hf3: my third header\r\n");
2798 #
2799 # This branch contains hf1 and hf3, but does
2800 # not contain hf2 header.
2801 # hf2 would be also present here without
2802 # t_save_lumps().
2803 ...
2804 t_relay();
2805 }
2806
2807 4.40. t_load_contacts([mode])
2808
2809 This is the first of the three functions that can be used to implement
2810 serial/parallel forking based on q and +sip.instance values of
2811 individual branches in the destination set.
2812
2813 Function t_load_contacts() removes all branches from the current
2814 destination set and stores them into the XAVP whose name is configured
2815 with the parameter contacts_avp. Note that you have to configure this
2816 parameter before you can use the function, the parameter is set to NULL
2817 by default, which disables the function.
2818
2819 If the destination set contains only one branch, the function does
2820 nothing.
2821
2822 If the current destination set contains more than one branch, the
2823 function sorts them according to the algorithm selected with the 'mode'
2824 parameter and then stores the branches in reverse order into the XAVP.
2825
2826 The q parameter of a branch contains a value from range 0-1.0 and it
2827 expresses relative preference of the branch among all branches in the
2828 destination set. The higher the q value the more preference the user
2829 agent gave to the branch. The parameter 'mode' controls which type of
2830 algorithm kamailio will apply to sort the branches based on the q
2831 values:
2832
2833 - '0' or missing: branches with higher q values will be tried before
2834 branches with lower ones when serial forking takes place Equals q
2835 values will result in a parallel forking.
2836
2837 - '1': branches are ordered using a proportional algorithm that uses to
2838 q value as the weight of the branch. Higher is the q value, higher is
2839 the probability to be tried as first. Equals q values means equals
2840 probability to be tried. Differently from the previous mode there is no
2841 possibility to have parallel forking. Branches with q values equals to
2842 0 or lower are not considered by the ordering algorithm, but just added
2843 at the end of the list as backup option if all other branches fail.
2844 This algorithm can be useful in case of endpoints in ACTIVE-ACTIVE
2845 configuration to load-balance the calls.
2846
2847 After calling t_load_contacts(), function t_next_contacts() and
2848 possibly also t_next_contact_flow() need to be called one or more times
2849 in order to retrieve the branches based on their order.
2850
2851 Function returns 1 if loading of contacts succeeded or there was
2852 nothing to do. In case of an error, function returns -1 (see syslog).
2853
2854 This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
2855
2856 Example 1.96. t_load_contacts usage
2857 ...
2858 if (!t_load_contacts()) {
2859 sl_send_reply("500", "Server Internal Error - Cannot load contacts");
2860 exit;
2861 };
2862 ...
2863
2864 4.41. t_next_contacts()
2865
2866 Function t_next_contacts() is the second of the three functions that
2867 can be used to implement serial/parallel forking based on the q value
2868 of the individual branches in a destination set.
2869
2870 The function adds to request a new destination set that includes the
2871 highest priority contacts in contacts_avp, but only one contact with
2872 the same +sip.instance value is included. Duplicate contacts are added
2873 to contact_flows_avp for later consumption by function
2874 next_contact_flow(). Upon each call, Request URI is rewritten with the
2875 first contact and the remaining contacts (if any) are added as
2876 branches. Then all highest priority contacts are removed from
2877 contacts_avp.
2878
2879 Function does nothing if contact_avp has no values.
2880
2881 Function returns 1 if contacts_avp was not empty and a destination set
2882 was successfully added, returns -2 if contacts_avp was empty and thus
2883 there was nothing to do, and returns -1 in case of an error (see
2884 syslog). Function can be called from REQUEST_ROUTE and FAILURE_ROUTE.
2885
2886 Note that if you use t_load_contacts and t_next_contacts functions then
2887 you should also set the value of restart_fr_on_each_reply parameter to
2888 0. If you do not do that, it can happen that a broken user agent that
2889 retransmits 180 periodically will keep resetting the fr_inv_timer value
2890 and serial forking never happens.
2891
2892 Before calling t_relay(), you can check if the previous call of
2893 next_contacts() consumed all branches by checking if contact_avp and
2894 contact_flows_avp are not anymore set. Based on that test, you can then
2895 use t_set_fr() function to set timers according to your needs.
2896
2897 Example 1.97. t_next_contacts usage
2898 ...
2899 # First call after t_load_contacts() when transaction does not exist yet
2900 # and contacts should be available
2901 if (!t_next_contacts()) {
2902 sl_send_reply("500", "Server Internal Error - Cannot get contacts");
2903 } else {
2904 t_relay();
2905 };
2906 ...
2907 # Following call, when transaction exists and there may or may not be
2908 # contacts left
2909 if (!t_next_contacts()) {
2910 t_reply("408", "Request Timeout");
2911 } else {
2912 t_relay();
2913 };
2914 ...
2915
2916 4.42. t_next_contact_flow()
2917
2918 Function t_next_contact_flow() is the last of the three functions that
2919 can be used to implement serial/parallel forking based on the q value
2920 and instance value of individual branches in a destination set.
2921
2922 Function adds a new branch to the request that includes the first
2923 contact from contact_flows_avp that matches the +sip.instance value of
2924 the flow that has failed. Upon each call, Request URI is rewritten with
2925 the contact. The used contact is removed from contact_flows_avp.
2926
2927 Function does nothing if there are no contact_flows_avp values.
2928
2929 Function returns 1 if contact_flows_avp was not empty and a destination
2930 set was successfully added, returns -2 if contacts_avp was empty and
2931 thus there was nothing to do, and returns -1 in case of an error (see
2932 syslog). This function can be used from a BRANCH_FAILURE_ROUTE event
2933 route.
2934
2935 Example 1.98. t_next_contact_flow usage
2936 ...
2937 event_route[tm:branch-failure:outbound]
2938 {
2939 if (t_next_contact_flow())
2940 {
2941 t_relay();
2942 } else {
2943 xlog("L_INFO", "No more flows\n");
2944 }
2945 ...
2946
2947 4.43. t_check_status(re)
2948
2949 Returns true if the regular expression “re” match the reply code of the
2950 response message as follows:
2951 * in routing block - the code of the last sent reply.
2952 * in on_reply block - the code of the current received reply.
2953 * in on_failure block - the code of the selected negative final
2954 reply.
2955
2956 This function can be used from ANY_ROUTE .
2957
2958 Example 1.99. t_check_status usage
2959 ...
2960 if (t_check_status("(487)|(408)")) {
2961 log("487 or 408 negative reply\n");
2962 }
2963 ...
2964
2965 4.44. t_check_trans()
2966
2967 t_check_trans() can be used to quickly check if a message belongs or is
2968 related to a transaction. It behaves differently for different types of
2969 messages:
2970 * For a SIP Reply it returns true if the reply belongs to an existing
2971 transaction and false otherwise.
2972 * For a CANCEL it behaves exactly as t_lookup_cancel(): returns true
2973 if a corresponding INVITE transaction exists for the CANCEL and
2974 false otherwise.
2975 * For ACKs to negative replies or for ACKs to local transactions it
2976 will terminate the script if the ACK belongs to a transaction (it
2977 would make very little sense to process an ACK to a negative reply
2978 for an existing transaction in some other way then to simply pass
2979 it to tm) or return false if not.
2980 * For end-to-end ACKs (ACKs to 2xx responses for forwarded INVITE
2981 transactions) it will return true if the corresponding INVITE
2982 transaction is found and still active and false if not.
2983
2984 Note
2985 Note that the e2e ACK matching is more of a hint then a certainty.
2986 A delayed e2e ACK might arrive after the transaction wait time
2987 elapses, when the INVITE transaction no longer exists and thus
2988 would not match anything. There are also cases when tm would not
2989 keep all the information needed for e2e ACK matching (since this is
2990 not needed for a stateful proxy and it requires additional memory,
2991 tm will not keep this information unless needed by some other
2992 module or callbacks).
2993 * For other requests (non ACKs and non CANCELs), in case of a
2994 retransmission matching a transaction, it resends the last reply
2995 for that transaction and terminates the config execution.
2996 Otherwise, it returns false (in case of new requests for which no
2997 transaction exists yet).
2998
2999 Note
3000
3001 An important difference from kamailio version is that for an ACK to
3002 negative reply or for a local transaction, the script execution will be
3003 immediately stopped and the message handled by tm, instead of returning
3004 true.
3005
3006 t_check_trans() functionality for requests, except for the e2e ACK
3007 matching, can be replicated in the script using t_lookup_cancel() and
3008 t_lookup_request().
3009
3010 See also: t_lookup_request(), t_lookup_cancel().
3011
3012 Example 1.100. t_check_trans usage
3013 if ( method == "CANCEL" && !t_check_trans())
3014 sl_reply("403", "cancel out of the blue forbidden");
3015 # note: in this example t_check_trans() can be replaced by t_lookup_cancel()
3016
3017 4.45. t_set_disable_6xx(0|1)
3018
3019 Turn off/on 6xx replies special rfc conforming handling on a per
3020 transaction basis. If turned off (t_set_disable_6xx("1")) 6XXs will be
3021 treated like normal replies.
3022
3023 It overrides the disable_6xx_block value for the current transaction.
3024
3025 See also: disable_6xx_block.
3026
3027 Example 1.101. t_set_disable_6xx usage
3028 ...
3029 route {
3030 ...
3031 if (src_ip==1.2.3.4) # bad user agent that sends 603
3032 t_set_disable_6xx(1); # turn off 6xx special handling
3033 ...
3034 }
3035
3036 4.46. t_set_disable_failover(0|1)
3037
3038 Turn off/on dns failover on a per transaction basis.
3039
3040 See also: use_dns_failover.
3041
3042 Example 1.102. t_set_disable_failover usage
3043 ...
3044 route {
3045 ...
3046 if (uri=~"@foo.bar$")
3047 t_set_disable_failover(1); # turn off dns failover
3048 ...
3049 }
3050
3051 4.47. t_set_disable_internal_reply(0|1)
3052
3053 Turn off/on sending internally a SIP reply in case of relay errors.
3054
3055 Example 1.103. t_set_disable_internal_reply usage
3056 ...
3057 t_set_disable_internal_reply(1); # turn off sending internal reply on error
3058 if(!t_relay()) {
3059 send_reply("500", "Server error");
3060 }
3061 ...
3062
3063 4.48. t_set_no_auto_ack(0|1)
3064
3065 Turn off/on generating e2e ACKs automatically for successfully answered
3066 local transactions (uac)
3067
3068 Example 1.104. t_set_no_auto_ack usage
3069 ...
3070 t_set_no_auto_ack(1); # when receiving a 200-299 fr for local transaction (uac),
3071 do not reply automatically
3072 if(!t_relay()) {
3073 send_reply("500", "Server error");
3074 }
3075 ...
3076
3077 4.49. t_replicate([params])
3078
3079 Replicate the SIP request to a specific address. Return values are the
3080 same as for t_relay(). Note that responses to the replicated request
3081 are suppressed and will not show up in any reply_route.
3082
3083 There are several function prototypes:
3084 * t_replicate([uri]),
3085 * t_replicate(host, port),
3086 * t_replicate_udp(host, port)
3087 * t_replicate_tcp(host, port)
3088 * t_replicate_tls(host, port)
3089 * t_replicate_sctp(host, port)
3090 * t_replicate_to(proto, hostport)
3091
3092 Meaning of the parameters is as follows:
3093 * uri - SIP URI where the message should be sent. It can be given via
3094 a script variable. It is optional - when missing, the dst-uri or
3095 r-uri are used as next hop address.
3096 * host - host address where the message should be sent.
3097 * port - port number.
3098 * proto - transport protocol to be used.
3099 * hostport - address in "host:port" format. It can be given via an
3100 AVP.
3101
3102 Example 1.105. t_replicate usage
3103 ...
3104 # sent to 1.2.3.4:5060 over tcp
3105 t_replicate("sip:1.2.3.4:5060;transport=tcp");
3106
3107 # sent to 1.2.3.4:5061 over tls
3108 $var(h) = "1.2.3.4:5061";
3109 t_replicate("sip:$var(h);transport=tls");
3110
3111 # sent to 1.2.3.4:5060 over udp
3112 t_replicate_to_udp("1.2.3.4", "5060");
3113 ...
3114
3115 4.50. t_relay_to(proxy, flags)
3116
3117 Forward the SIP request to a specific address, controlling internal
3118 behavior via flags.
3119
3120 There are several function prototypes:
3121 * t_relay_to(),
3122 * t_relay_to(proxy),
3123 * t_relay_to(flags)
3124 * t_relay_to(proxy, flags)
3125
3126 Meaning of the parameters is as follows:
3127 * proxy - address where the request should be sent. Format is:
3128 "proto:host:port" - any of proto or port can be omitted, along with
3129 the semicolon after or before.
3130 * flags - bitmask integer value to control the internal behavior.
3131 Bits can be:
3132 + 0x01 - do not generate 100 reply.
3133 + 0x02 - do not generate reply on internal error.
3134 + 0x04 - disable dns failover.
3135
3136 Example 1.106. t_relay_to usage
3137 ...
3138 # sent to 1.2.3.4:5060 over tcp
3139 t_relay_to("tcp:1.2.3.4:5060");
3140
3141 # sent to 1.2.3.4 over tls
3142 t_relay_to("tls:1.2.3.4");
3143
3144 # sent to dst URI or R-URI without a 100 reply
3145 t_relay_to("0x01");
3146 ...
3147
3148 4.51. t_relay_to_proxy(proxy [, flags])
3149
3150 Alternative function to relay the SIP request to a specific address,
3151 with the parameter supporting variables inside it.
3152
3153 The format of the proxy parameter is: "proto:host:port" - any of proto
3154 or port can be omitted, along with the semicolon after or before. The
3155 flags parameter is optional, with possible values like for
3156 t_relay_to().
3157
3158 The function can be used in REQUEST_ROUTE and FAILURE_ROUTE.
3159
3160 Example 1.107. t_relay_to_proxy usage
3161 ...
3162 t_relay_to_proxy("udp:$var(addr):5060");
3163 ...
3164
3165 4.52. t_set_no_e2e_cancel_reason(0|1)
3166
3167 Enables/disables reason header (RFC 3326) copying from the triggering
3168 received CANCEL to the generated hop-by-hop CANCEL. 0 enables and 1
3169 disables.
3170
3171 It overrides the e2e_cancel_reason setting (module parameter) for the
3172 current transaction.
3173
3174 Note: the function has to be used when processing the INVITE (not when
3175 processing the CANCEL).
3176
3177 See also: e2e_cancel_reason.
3178
3179 Example 1.108. t_set_no_e2e_cancel_reason usage
3180 ...
3181 route {
3182 ...
3183 if (src_ip!=10.0.0.0/8) # don't trust CANCELs from the outside
3184 t_set_no_e2e_cancel_reason(1); # turn off CANCEL reason header c
3185 opying
3186 ...
3187 }
3188
3189 4.53. t_is_set(target)
3190
3191 Return true if the attribute specified by 'target' is set for
3192 transaction.
3193
3194 The target parameter can be:
3195 * branch_route - the function returns true if a branch route is set
3196 to be executed.
3197 * failure_route - the function returns true if a failure route is set
3198 to be executed.
3199 * onreply_route - the function returns true if an onreply route is
3200 set to be executed.
3201
3202 Example 1.109. t_replicate usage
3203 ...
3204 if(!t_is_set("failure_route"))
3205 LM_DBG("no failure route will be executed for current transaction\n");
3206 ...
3207
3208 4.54. t_use_uac_headers()
3209
3210 Set internal flags to tell tm to use UAC side for building headers for
3211 local generated requests (ACK, CANCEL) - useful when changing From/To
3212 headers using other functions than uac_replace_[from|to]().
3213
3214 It returns true.
3215
3216 Example 1.110. t_use_uac_headers usage
3217 ...
3218 t_use_uac_headers();
3219 ...
3220
3221 4.55. t_is_retr_async_reply()
3222
3223 Check to see if the reply is a retransmitted reply on a transaction
3224 that is currently suspended asynchronously (suspended during reply
3225 processing). Right now the check is only on the transaction, we don't
3226 actually check to see if the reply message is an actual retransmission
3227 of the suspended reply. This is expected as you should not process
3228 another reply until the suspended reply processing has been completed.
3229 The trick here is to make sure you don't suspend for too long or even
3230 worse, indefinitely.
3231
3232 returns true if the transaction is currently reply suspended or false
3233 if not.
3234
3235 Example 1.111. t_is_retr_async_reply usage
3236 ...
3237 if (t_is_retr_async_reply()) {
3238 xlog("L_DBG", "Dropping retransmitted reply which is still currently sus
3239 pended\n");
3240 drop();
3241 }
3242 ...
3243
3244 4.56. t_uac_send(method, ruri, nexthop, socket, headers, body)
3245
3246 Send a UAC request.
3247
3248 It returns true (1) if successful, false (-1) on failure.
3249
3250 The parameters:
3251 * method - SIP method. Add a "." to the end of the method name to
3252 suppress automatic ACK generation (the dot is not transmitted, of
3253 course).
3254 * ruri - request URI.
3255 * nexthop - destination URI (can be empty).
3256 * socket - local send socket (can be empty).
3257 * headers - SIP headers. At least From and To have to be provided. It
3258 can include From/To tags, Call-ID, CSeq. If body is provided, then
3259 Content-Type header must exist.
3260 * body - SIP message body (can be empty).
3261
3262 Example 1.112. t_uac_send usage
3263 ...
3264 t_uac_send("OPTIONS", "sip:[email protected]", "", "",
3265 "From: [email protected];tag=2w3e\r\nTo: [email protected]", "");
3266 ...
3267
3268 4.57. t_get_status_code()
3269
3270 Return the status code for transaction - the most relevant SIP reply
3271 status code, or -1 in case of error or no status code was set.
3272
3273 Example 1.113. t_get_status_code usage
3274 ...
3275 $var(ts) = t_get_status_code();
3276 if($var(ts) == 500) { ... }
3277 ...
3278
3279 4.58. t_clean()
3280
3281 Cleans active but very old transactions. Returns true (1). Can be
3282 called from any route.
3283
3284 Example 1.114. t_clean usage
3285 ...
3286 t_clean();
3287 ...
3288
3289 4.59. t_exists()
3290
3291 Return true if a transaction for the current message exists, without
3292 setting the global references.
3293
3294 Example 1.115. t_exists usage
3295 ...
3296 reply_route {
3297 if (!t_exists()) {
3298 drop();
3299 }
3300 }
3301 ...
3302
3303 4.60. t_cell_append_branches(tindex, tlabel)
3304
3305 Append destination set branches to the transaction identified by
3306 (tindex, tlabel). The parameters can also be variables.
3307
3308 Example 1.116. t_cell_append_branches usage
3309 ...
3310 append_branch("sip:1.2.3.4:5060");
3311 t_cell_append_branches("1234", "$var(tlabel)");
3312 ...
3313
3314 4.61. t_msg_apply_changes()
3315
3316 Apply changes to the SIP request processed in a branch_route block. It
3317 changes the request only for that particular branch, not the
3318 transaction incoming request. It is similar to msg_apply_changes(), but
3319 designed to be used in the context of the branch route, after the
3320 transaction was created.
3321
3322 It is not needed to use this function explicitely, unless the changes
3323 to the SIP request are needed for the next functions in the same
3324 branch_route block, otherwise the operations for adding/removing
3325 headers or changing the body of the request are applied before writing
3326 to the outbound socket.
3327
3328 It requires to set core parameter msg_apply_changes_mode = 1.
3329
3330 Example 1.117. t_msg_apply_changes usage
3331 ...
3332 msg_apply_changes_mode = 1;
3333 ...
3334 branch_route[OUT] {
3335 append_hf("X-Hdr: abc\n");
3336 t_msg_apply_changes();
3337 }
3338 ...
3339
3340 5. RPC Commands
3341
3342 5.1. tm.list
3343 5.2. tm.t_uac_start
3344 5.3. tm.t_uac_start_hex
3345 5.4. tm.t_uac_wait
3346 5.5. tm.t_uac_wait_hex
3347 5.6. tm.t_uac_wait_block
3348 5.7. tm.t_uac_wait_block_hex
3349 5.8. tm.t_uac_start_noack
3350 5.9. tm.t_uac_start_noack_hex
3351 5.10. tm.t_uac_wait_noack
3352 5.11. tm.t_uac_wait_noack_hex
3353 5.12. tm.t_uac_wait_block_noack
3354 5.13. tm.t_uac_wait_block_noack_hex
3355 5.14. tm.t_uac_attrs
3356 5.15. tm.cancel
3357 5.16. tm.hash_stats
3358 5.17. tm.reply
3359 5.18. tm.reply_callid
3360 5.19. tm.retransmit_reply
3361 5.20. tm.retransmit_reply_callid
3362 5.21. tm.clean
3363 5.22. tm.stats
3364
3365 5.1. tm.list
3366
3367 List details of transactions.
3368
3369 Parameters:
3370 * none
3371
3372 5.2. tm.t_uac_start
3373
3374 Generates and sends a local SIP request.
3375
3376 Parameters:
3377 * method - request method
3378 * RURI - request SIP URI
3379 * NEXT HOP - next hop SIP URI (OBP); use “.” if no value.
3380 * socket - local socket to be used for sending the request; use “.”
3381 if no value.
3382 * headers - set of additional headers to be added to the request; at
3383 least “From” and “To” headers must be provided)
3384 * body - (optional, may not be present) request body (if present,
3385 requires the “Content-Type” and “Content-length” headers)
3386
3387 5.3. tm.t_uac_start_hex
3388
3389 Similar to tm.t_uac_start, but with hexa-encoded body. The whitespaces
3390 are ignored when decoding the body.
3391
3392 5.4. tm.t_uac_wait
3393
3394 Similar to tm.t_uac_start, but waits asynchronously for the SIP
3395 response and tries to provide its details via RPC response.
3396
3397 5.5. tm.t_uac_wait_hex
3398
3399 Similar to tm.t_uac_wait, but with hexa-encoded body. The whitespaces
3400 are ignored when decoding the body.
3401
3402 5.6. tm.t_uac_wait_block
3403
3404 Similar to tm.t_uac_start, but blocks waiting for the SIP response and
3405 returns the SIP reply code and reason text via RPC response. It waits
3406 up to 80 seconds, if no reply is received, it returns a RPC fault 500
3407 code. While waiting, the RPC process cannot handle other RPC commands.
3408
3409 5.7. tm.t_uac_wait_block_hex
3410
3411 Similar to tm.t_uac_wait_block, but with hexa-encoded body. The
3412 whitespaces are ignored when decoding the body.
3413
3414 5.8. tm.t_uac_start_noack
3415
3416 Similar to tm.t_uac_start, but do not automatically send ACK for local
3417 INVITE requests.
3418
3419 5.9. tm.t_uac_start_noack_hex
3420
3421 Similar to tm.t_uac_start_noack, but with hexa-encoded body. The
3422 whitespaces are ignored when decoding the body.
3423
3424 5.10. tm.t_uac_wait_noack
3425
3426 Similar to tm.t_uac_wait, but do not automatically send ACK for local
3427 INVITE requests.
3428
3429 5.11. tm.t_uac_wait_noack_hex
3430
3431 Similar to tm.t_uac_wait_noack, but with hexa-encoded body. The
3432 whitespaces are ignored when decoding the body.
3433
3434 5.12. tm.t_uac_wait_block_noack
3435
3436 Similar to tm.t_uac_wait_block, but do not automatically send ACK for
3437 local INVITE requests.
3438
3439 5.13. tm.t_uac_wait_block_noack_hex
3440
3441 Similar to tm.t_uac_wait_block_noack, but with hexa-encoded body. The
3442 whitespaces are ignored when decoding the body.
3443
3444 5.14. tm.t_uac_attrs
3445
3446 Combine the tm.t_uac_* variants, by providing the first parameter with
3447 attributes, then the other parameters are like for tm.t_uac_start.
3448
3449 The attributes are in the format "name1=value1;...;nameX=valueX". The
3450 name of the attribute can be:
3451 * mode - control how the command is done. If not provided or the
3452 value is "start", acts like tm.t_uac_start. The other values can
3453 be: "wait" - act like tm.t_uac_wait; "block" - act like
3454 tm.t_uac_wait_block.
3455 * cbflags - the transaction callback flags. The values can be:
3456 "noack" - to not automatically send ACK for local INVITE requests
3457 * rpflags - RPC parameters flags. The values can be: 1 - the body is
3458 hexa-encoded value.
3459 * fr_timeout - the fr_timeout value for the local transaction.
3460 * fr_inv_timeout - the fr_inv_timeout value for the local
3461 transaction.
3462
3463 Example 1.118. Using “tm.t_uac_attrs”
3464 ...
3465 kamcli rpc tm.t_uac_attrs 'reply=wait;cbflags=noack;rpflags=1' 'INVITE' ...
3466 ...
3467
3468 5.15. tm.cancel
3469
3470 Generates and sends a CANCEL for an existing local SIP request.
3471
3472 Parameters:
3473 * callid - callid of the INVITE request to be cancelled.
3474 * cseq - cseq of the INVITE request to be cancelled.
3475
3476 5.16. tm.hash_stats
3477
3478 Gets information about the load of TM internal hash table.
3479
3480 Parameters:
3481 * none
3482
3483 5.17. tm.reply
3484
3485 Generates and sends a reply for an existing inbound SIP transaction.
3486
3487 Parameters:
3488 * code - reply code
3489 * reason - reason phrase.
3490 * trans_id - transaction identifier (has the hash_entry:label format)
3491 * to_tag - To tag to be added to TO header
3492 * new_headers - extra headers to be appended to the reply; use a dot
3493 (“.”) char only if there are no headers;
3494 * body - (optional, may not be present) reply body (if present,
3495 requires the “Content-Type” and “Content-length” headers)
3496
3497 5.18. tm.reply_callid
3498
3499 Generates and sends a reply for an existing inbound SIP transaction.
3500
3501 Parameters:
3502 * code - reply code
3503 * reason - reason phrase.
3504 * callid - SIP Call-ID header
3505 * cseq - SIP CSeq header
3506 * to_tag - To tag to be added to TO header
3507 * new_headers - extra headers to be appended to the reply; use a dot
3508 (“.”) char only if there are no headers;
3509 * body - (optional, may not be present) reply body (if present,
3510 requires the “Content-Type” and “Content-length” headers)
3511
3512 5.19. tm.retransmit_reply
3513
3514 Retransmit the reply for an existing SIP transaction.
3515
3516 Parameters:
3517 * trans_id - transaction identifier (has the hash_entry:label format)
3518
3519 Example 1.119. Using “tm.retransmit_reply”
3520 ...
3521 kamcli rpc tm.retransmit_reply 1234:5678
3522 ...
3523
3524 5.20. tm.retransmit_reply_callid
3525
3526 Retransmit the reply for an existing SIP transaction.
3527
3528 Parameters:
3529 * callid - SIP Call-ID header
3530 * cseq - SIP CSeq header
3531
3532 Example 1.120. Using “tm.retransmit_reply_callid”
3533 ...
3534 kamcli rpc tm.retransmit_reply_callid "abc-xyz" "10 INVITE"
3535 ...
3536
3537 5.21. tm.clean
3538
3539 Trigger a hard clean of expired transactions.
3540
3541 Parameters:
3542 * none
3543
3544 5.22. tm.stats
3545
3546 Gets information about current and past TM transaction handling.
3547
3548 Parameters:
3549 * none
3550
3551 6. Event Routes
3552
3553 6.1. event_route[tm:branch-failure:id]
3554 6.2. event_route[tm:local-request]
3555 6.3. event_route[tm:local-response]
3556 6.4. event_route[tm:local-ack-sent]
3557
3558 6.1. event_route[tm:branch-failure:id]
3559
3560 Named branch failure routes can be defined to run when a failure
3561 response is received. This allows handling failures on individual
3562 branches, for example, retrying an alternative outbound flow.
3563
3564 The format of the event_route name is "tm:branch-failure:<id>" and is
3565 enabled with the t_on_branch_failure function. This event_route uses
3566 the BRANCH_FAILURE_ROUTE route type.
3567
3568 Example 1.121. event_route[tm:branch-failure:id] usage
3569 ...
3570 request_route {
3571 ...
3572 t_on_branch_failure("myroute");
3573 t_relay();
3574 }
3575
3576 event_route[tm:branch-failure:myroute] {
3577 xlog("L_INFO", "Received $T_reply_code to $rm message\n");
3578 }
3579 ...
3580
3581 6.2. event_route[tm:local-request]
3582
3583 Executed when the tm module generates a request, in other words, the
3584 request originates from Kamailio and a transaction is created for it.
3585 The source of the requests can be tm itself or other modules that use
3586 tm internally (e.g., msilo, uac). The event route is executed if it is
3587 defined in the native Kamailio config file. To execute the equivalent
3588 callback when using KEMI scripting, see the 'event_callback' module
3589 parameter.
3590
3591 The request can still be updated, i.e., changes are possible to R-URI
3592 ($ru), destination URI ($du) or the send socket ($fs).
3593
3594 Example 1.122. event_route[tm:local-request] usage
3595 ...
3596 event_route [tm:local-request] {
3597 xlog("L_INFO", "Routing locally generated $rm to $ru\n");
3598 t_set_fr(10000, 10000);
3599 }
3600 ...
3601
3602 6.3. event_route[tm:local-response]
3603
3604 Executed after the tm module sent a local generated, transaction
3605 stateful response.
3606
3607 Example 1.123. event_route[tm:local-response] usage
3608 ...
3609 event_route[tm:local-response] {
3610 xlog("tm:local-response replied locally\n");
3611 }
3612 ...
3613
3614 6.4. event_route[tm:local-ack-sent]
3615
3616 Executed after the tm module sent the ACK of the 200ok for a local
3617 generated INVITE. It is executed with the received 200ok response.
3618
3619 Example 1.124. event_route[tm:local-ack-sent] usage
3620 ...
3621 event_route[tm:local-ack-sent] {
3622 xlog("ACK for local INVITE was sent\n");
3623 }
3624 ...
3625
3626 7. TM Module API
3627
3628 7.1. Defines
3629 7.2. Functions
3630
3631 7.2.1. register_tmcb(cb_type, cb_func)
3632 7.2.2. load_tm(*import_structure)
3633 7.2.3. int t_suspend(struct sip_msg *msg, unsigned int
3634 *hash_index, unsigned int *label)
3635
3636 7.2.4. int t_continue(unsigned int hash_index, unsigned int label,
3637 struct action *route)
3638
3639 7.2.5. int t_cancel_suspend(unsigned int hash_index, unsigned int
3640 label)
3641
3642 There are applications which would like to generate SIP transactions
3643 without too big involvement in SIP stack, transaction management, etc.
3644 An example of such an application is sending instant messages from a
3645 website. To address needs of such apps, SIP-router accepts requests for
3646 new transactions via the management interface. If you want to enable
3647 this feature, start the management interface server by configuring the
3648 proper modules.
3649
3650 An application can easily launch a new transaction by writing a
3651 transaction request to this interface. The request must follow very
3652 simple format, which for the basic FIFO interface is
3653 :t_uac_from:[<file_name>]\n
3654 <method>\n
3655 <sender's uri>\n
3656 <dst uri>\n
3657 <CR_separated_headers>\n
3658 <body>\n
3659 .\n
3660 \n
3661
3662 (Filename is to where a report will be dumped. ser assumes /tmp as
3663 file's directory.)
3664
3665 Note the request write must be atomic, otherwise it might get
3666 intermixed with writes from other writers. You can easily use it via
3667 Unix command-line tools, see the following example:
3668 [jiri@bat jiri]$ cat > /tmp/ser_fifo
3669 :t_uac_from:xxx
3670 MESSAGE
3671 sip:[email protected]
3672 sip:[email protected]
3673 header:value
3674 foo:bar
3675 bznk:hjhjk
3676 p_header: p_value
3677
3678 body body body
3679 yet body
3680 end of body
3681 .
3682
3683 or cat test/transaction.fifo > /tmp/ser_fifo
3684
3685 7.1. Defines
3686
3687 * ACK_TAG enables stricter matching of acknowledgments including
3688 to-tags. Without it, to-tags are ignored. It is disabled by default
3689 for two reasons:
3690 + It eliminates an unlikely race condition in which
3691 transaction's to-tag is being rewritten by a 200 OK whereas an
3692 ACK is being looked up by to-tag.
3693 + It makes UACs happy who set wrong to-tags.
3694 It should not make a difference, as there may be only one negative
3695 reply sent upstream and 200/ACKs are not matched as they constitute
3696 another transaction. It will make no difference at all when the new
3697 magic cookie matching is enabled anyway.
3698 * CANCEL_TAG similarly enables strict matching of CANCELs including
3699 to-tags--act of mercy to UACs, who screw up the to-tags (however,
3700 it still depends on how forgiving the downstream UAS is). Like with
3701 ACK_TAG, all this complex transactions matching goes with RFC3261's
3702 magic cookie away anyway.
3703
3704 7.2. Functions
3705
3706 7.2.1. register_tmcb(cb_type, cb_func)
3707
3708 For programmatic use only--register a function to be called back on an
3709 event. See t_hooks.h for more details.
3710
3711 Meaning of the parameters is as follows:
3712 * cb_type - Callback type.
3713 * cb_func - Callback function.
3714
3715 7.2.2. load_tm(*import_structure)
3716
3717 For programmatic use only--import exported TM functions. See the acc
3718 module for an example of use.
3719
3720 Meaning of the parameters is as follows:
3721 * import_structure - Pointer to the import structure.
3722
3723 7.2.3. int t_suspend(struct sip_msg *msg, unsigned int *hash_index, unsigned
3724 int *label)
3725
3726 For programmatic use only. This function together with t_continue() can
3727 be used to implement asynchronous actions: t_suspend() saves the
3728 transaction, returns its identifiers, and t_continue() continues the
3729 SIP request/response processing. (The request/response processing does
3730 not continue from the same point in the script, a separate route block
3731 defined by the parameter of t_continue() is executed instead. The reply
3732 lock is held during the route block execution.) FR timer is ticking
3733 while the transaction is suspended, and the transaction's failure route
3734 is executed if t_continue() is not called in time.
3735
3736 Missing: message lumps are saved by t_suspend() and are not updated by
3737 the subsequent t_relay(). This means that the modifications made
3738 between them are lost.
3739
3740 Meaning of the parameters is as follows:
3741 * msg - SIP message pointer.
3742 * hash_index - transaction identifier.
3743 * label - transaction identifier.
3744
3745 Return value: 0 - success, <0 - error.
3746
3747 Usage: Allocate a memory block for storing the transaction identifiers
3748 (hash_index and label), and for storing also any variable related to
3749 the async query. Before calling t_suspend(), register for the following
3750 callbacks, and pass the pointer to the allocated shared memory as a
3751 parameter: TMCB_ON_FAILURE, TMCB_DESTROY, and TMCB_E2ECANCEL_IN (in
3752 case of INVITE transaction). The async operation can be cancelled, if
3753 it is still pending, when TMCB_ON_FAILURE or TMCB_E2ECANCEL_IN is
3754 called. TMCB_DESTROY is suitable to free the shared memory allocated
3755 for the async and SIP transaction identifiers. Once the async query
3756 result is available call t_continue(), see below. The SIP transaction
3757 must exist before calling t_suspend(), and the module function calling
3758 t_suspend() should return 0 to make sure that the script processing
3759 does not continue.
3760
3761 7.2.4. int t_continue(unsigned int hash_index, unsigned int label, struct
3762 action *route)
3763
3764 For programmatic use only. This function is the pair of t_suspend(),
3765 and is supposed to be called when the asynchronous query result is
3766 available. The function executes a route block with the saved SIP
3767 message. It is possible to add more branches to the transaction, or
3768 send a reply from the route block.
3769
3770 Meaning of the parameters is as follows:
3771 * hash_index - transaction identifier.
3772 * label - transaction identifier.
3773 * route - route block to execute.
3774
3775 Return value: 0 - success, <0 - error.
3776
3777 7.2.5. int t_cancel_suspend(unsigned int hash_index, unsigned int label)
3778
3779 For programmatic use only. This function is for revoking t_suspend()
3780 from the same process as it was executed before. t_cancel_suspend() can
3781 be used when something fails after t_suspend() has already been
3782 executed and it turns out that the transaction should not have been
3783 suspended. The function cancels the FR timer of the transaction.
3784
3785 The message lumps are saved by t_suspend() which cannot be restored.
3786
3787 Meaning of the parameters is as follows:
3788 * hash_index - transaction identifier.
3789 * label - transaction identifier.
3790
3791 Return value: 0 - success, <0 - error.
3792
3793 8. Known Issues
3794
3795 * Possibly, performance could be improved by not parsing non-INVITEs,
3796 as they are not replied with 100, and do not result in ACK/CANCELs,
3797 and other things which take parsing. However, we need to rethink
3798 whether we don't need parsed headers later for something else.
3799 Remember, when we now store a request in sh_mem, we can't apply any
3800 pkg_mem operations to it any more. (that might be redesigned too).
3801 * Another performance improvement may be achieved by not parsing CSeq
3802 in replies until reply branch matches branch of an INVITE/CANCEL in
3803 transaction table.
3804 * t_replicate should be done more cleanly--Vias, Routes, etc. should
3805 be removed from a message prior to replicating it (well, does not
3806 matter any longer so much as there is a new replication module).