-
Notifications
You must be signed in to change notification settings - Fork 910
/
README
3288 lines (2612 loc) · 112 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
TM Module
Jiri Kuthan
FhG FOKUS
Juha Heinanen
<jh@tutpro.com>
Daniel-Constantin Mierla
<miconda@gmail.com>
Copyright © 2003 FhG FOKUS
Copyright © 2008 Juha Heinanen
Copyright © 2016 Daniel-Constantin Mierla
__________________________________________________________________
Table of Contents
1. Admin Guide
1. Overview
2. Serial Forking Based on Q Value
3. Parameters
3.1. fr_timer (integer)
3.2. fr_inv_timer (integer)
3.3. max_inv_lifetime (integer)
3.4. max_noninv_lifetime (integer)
3.5. wt_timer (integer)
3.6. retr_timer1 (integer)
3.7. retr_timer2 (integer)
3.8. noisy_ctimer (integer)
3.9. restart_fr_on_each_reply (integer)
3.10. auto_inv_100 (integer)
3.11. auto_inv_100_reason (string)
3.12. unix_tx_timeout (integer)
3.13. aggregate_challenges (integer)
3.14. reparse_invite (integer)
3.15. ac_extra_hdrs (string)
3.16. blst_503 (integer)
3.17. blst_503_def_timeout (integer)
3.18. blst_503_min_timeout (integer)
3.19. blst_503_max_timeout (integer)
3.20. blst_methods_add (unsigned integer)
3.21. blst_methods_lookup (unsigned integer)
3.22. cancel_b_method (integer)
3.23. reparse_on_dns_failover (integer)
3.24. on_sl_reply (string)
3.25. contacts_avp (string)
3.26. contact_flows_avp (string)
3.27. fr_timer_avp (string)
3.28. fr_inv_timer_avp (string)
3.29. unmatched_cancel (string)
3.30. ruri_matching (integer)
3.31. via1_matching (integer)
3.32. callid_matching (integer)
3.33. pass_provisional_replies (integer)
3.34. default_code (integer)
3.35. default_reason (string)
3.36. disable_6xx_block (integer)
3.37. local_ack_mode (integer)
3.38. failure_reply_mode (integer)
3.39. faked_reply_prio (integer)
3.40. local_cancel_reason (boolean)
3.41. e2e_cancel_reason (boolean)
3.42. remap_503_500 (boolean)
3.43. failure_exec_mode (boolean)
3.44. dns_reuse_rcv_socket (boolean)
3.45. xavp_contact (string)
3.46. event_callback (str)
3.47. event_callback_lres_sent (str)
3.48. relay_100 (str)
3.49. rich_redirect (int)
3.50. exec_time_check (int)
4. Functions
4.1. t_relay([host, port])
4.2. t_relay_to_udp([ip, port])
4.3. t_relay_to_tcp([ip, port])
4.4. t_relay_to_tls([ip, port])
4.5. t_relay_to_sctp([ip, port])
4.6. t_on_failure(failure_route)
4.7. t_on_branch_failure(branch_failure_route)
4.8. t_on_reply(onreply_route)
4.9. t_on_branch(branch_route)
4.10. t_newtran()
4.11. t_reply(code, reason_phrase)
4.12. t_send_reply(code, reason)
4.13. t_lookup_request()
4.14. t_retransmit_reply()
4.15. t_release()
4.16. t_forward_nonack([ip, port])
4.17. t_forward_nonack_udp(ip, port)
4.18. t_forward_nonack_tcp(ip, port)
4.19. t_forward_nonack_tls(ip, port)
4.20. t_forward_nonack_sctp(ip, port)
4.21. t_set_fr(fr_inv_timeout [, fr_timeout])
4.22. t_reset_fr()
4.23. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
4.24. t_reset_max_lifetime()
4.25. t_set_retr(retr_t1_interval, retr_t2_interval)
4.26. t_reset_retr()
4.27. t_set_auto_inv_100(0|1)
4.28. t_branch_timeout()
4.29. t_branch_replied()
4.30. t_any_timeout()
4.31. t_any_replied()
4.32. t_grep_status("code")
4.33. t_is_canceled()
4.34. t_is_expired()
4.35. t_relay_cancel()
4.36. t_lookup_cancel([1])
4.37. t_drop_replies([mode])
4.38. t_save_lumps()
4.39. t_load_contacts([mode])
4.40. t_next_contacts()
4.41. t_next_contact_flow()
4.42. t_check_status(re)
4.43. t_check_trans()
4.44. t_set_disable_6xx(0|1)
4.45. t_set_disable_failover(0|1)
4.46. t_set_disable_internal_reply(0|1)
4.47. t_replicate([params])
4.48. t_relay_to(proxy, flags)
4.49. t_set_no_e2e_cancel_reason(0|1)
4.50. t_is_set(target)
4.51. t_use_uac_headers()
4.52. t_is_retr_async_reply()
4.53. t_uac_send(method, ruri, nexthop, socket, headers,
body)
4.54. t_get_status_code()
4.55. t_clean()
5. RPC Commands
5.1. tm.list
5.2. tm.t_uac_start
5.3. tm.t_uac_wait
5.4. tm.cancel
5.5. tm.hash_stats
5.6. tm.reply
5.7. tm.reply_callid
5.8. tm.clean
5.9. tm.stats
6. Event Routes
6.1. event_route[tm:branch-failure:id]
6.2. event_route[tm:local-request]
6.3. event_route[tm:local-response]
7. TM Module API
7.1. Defines
7.2. Functions
7.2.1. register_tmcb(cb_type, cb_func)
7.2.2. load_tm(*import_structure)
7.2.3. int t_suspend(struct sip_msg *msg, unsigned int
*hash_index, unsigned int *label)
7.2.4. int t_continue(unsigned int hash_index,
unsigned int label, struct action *route)
7.2.5. int t_cancel_suspend(unsigned int hash_index,
unsigned int label)
8. Known Issues
List of Examples
1.1. Set fr_timer parameter
1.2. Set fr_inv_timer parameter
1.3. Set max_inv_lifetime parameter
1.4. Set max_noninv_lifetime parameter
1.5. Set wt_timer parameter
1.6. Set retr_timer1 parameter
1.7. Set retr_timer2 parameter
1.8. Set noisy_ctimer parameter
1.9. Set restart_fr_on_each_reply parameter
1.10. Set auto_inv_100 parameter
1.11. Set auto_inv_100_reason parameter
1.12. Set unix_tx_timeout parameter
1.13. Set aggregate_challenges parameter
1.14. Set reparse_invite parameter
1.15. Set ac_extra_hdrs parameter
1.16. Set blst_503 parameter
1.17. Set blst_503_def_timeout parameter
1.18. Set blst_503_min_timeout parameter
1.19. Set blst_503_max_timeout parameter
1.20. Set blst_methods_add parameter
1.21. Set blst_methods_lookup parameter
1.22. Set cancel_b_method parameter
1.23. Set reparse_on_dns_failover parameter
1.24. Set on_sl_reply parameter
1.25. Set contacts_avp parameter
1.26. Set contact_flows_avp parameter
1.27. Set fr_timer_avp parameter
1.28. Set fr_inv_timer_avp parameter
1.29. Set unmatched_cancel parameter
1.30. Set ruri_matching parameter
1.31. Set via1_matching parameter
1.32. Set callid_matching parameter
1.33. Set pass_provisional_replies parameter
1.34. Set default_code parameter
1.35. Set default_reason parameter
1.36. Set disable_6xx_block parameter
1.37. Set local_ack_mode parameter
1.38. Set failure_reply_mode parameter
1.39. Set faked_reply_prio parameter
1.40. Set local_cancel_reason parameter
1.41. Set e2e_cancel_reason parameter
1.42. Set remap_503_500 parameter
1.43. Set failure_exec_mode parameter
1.44. Set dns_reuse_rcv_socket parameter
1.45. Set xavp_contact parameter
1.46. Set event_callback parameter
1.47. Set event_callback_lres_sent parameter
1.48. Set relay_100 parameter
1.49. rich_redirect example
1.50. Set exec_time_check parameter
1.51. t_relay usage
1.52. t_relay_to_udp usage
1.53. t_on_failure usage
1.54. t_on_branch_failure usage
1.55. t_on_reply usage
1.56. t_on_branch usage
1.57. t_newtran usage
1.58. t_reply usage
1.59. t_send_reply usage
1.60. t_lookup_request usage
1.61. t_retransmit_reply usage
1.62. t_release usage
1.63. t_forward_nonack usage
1.64. t_set_fr usage
1.65. t_reset_fr usage
1.66. t_set_max_lifetime usage
1.67. t_reset_max_lifetime usage
1.68. t_set_retr usage
1.69. t_reset_retr usage
1.70. t_set_auto_inv_100 usage
1.71. t_branch_timeout usage
1.72. t_branch_replied usage
1.73. t_any_timeout usage
1.74. t_any_replied usage
1.75. t_grep_status usage
1.76. t_is_canceled usage
1.77. t_is_expired usage
1.78. t_relay_cancel usage
1.79. t_lookup_cancel usage
1.80. t_drop_replies() usage
1.81. t_save_lumps() usage
1.82. t_load_contacts usage
1.83. t_next_contacts usage
1.84. t_next_contact_flow usage
1.85. t_check_status usage
1.86. t_check_trans usage
1.87. t_set_disable_6xx usage
1.88. t_set_disable_failover usage
1.89. t_set_disable_internal_reply usage
1.90. t_replicate usage
1.91. t_relay_to usage
1.92. t_set_no_e2e_cancel_reason usage
1.93. t_replicate usage
1.94. t_use_uac_headers usage
1.95. t_is_retr_async_reply usage
1.96. t_uac_send usage
1.97. t_get_status_code usage
1.98. t_clean usage
1.99. event_route[tm:branch-failure:id] usage
1.100. event_route[tm:local-request] usage
1.101. event_route[tm:local-response] usage
Chapter 1. Admin Guide
Table of Contents
1. Overview
2. Serial Forking Based on Q Value
3. Parameters
3.1. fr_timer (integer)
3.2. fr_inv_timer (integer)
3.3. max_inv_lifetime (integer)
3.4. max_noninv_lifetime (integer)
3.5. wt_timer (integer)
3.6. retr_timer1 (integer)
3.7. retr_timer2 (integer)
3.8. noisy_ctimer (integer)
3.9. restart_fr_on_each_reply (integer)
3.10. auto_inv_100 (integer)
3.11. auto_inv_100_reason (string)
3.12. unix_tx_timeout (integer)
3.13. aggregate_challenges (integer)
3.14. reparse_invite (integer)
3.15. ac_extra_hdrs (string)
3.16. blst_503 (integer)
3.17. blst_503_def_timeout (integer)
3.18. blst_503_min_timeout (integer)
3.19. blst_503_max_timeout (integer)
3.20. blst_methods_add (unsigned integer)
3.21. blst_methods_lookup (unsigned integer)
3.22. cancel_b_method (integer)
3.23. reparse_on_dns_failover (integer)
3.24. on_sl_reply (string)
3.25. contacts_avp (string)
3.26. contact_flows_avp (string)
3.27. fr_timer_avp (string)
3.28. fr_inv_timer_avp (string)
3.29. unmatched_cancel (string)
3.30. ruri_matching (integer)
3.31. via1_matching (integer)
3.32. callid_matching (integer)
3.33. pass_provisional_replies (integer)
3.34. default_code (integer)
3.35. default_reason (string)
3.36. disable_6xx_block (integer)
3.37. local_ack_mode (integer)
3.38. failure_reply_mode (integer)
3.39. faked_reply_prio (integer)
3.40. local_cancel_reason (boolean)
3.41. e2e_cancel_reason (boolean)
3.42. remap_503_500 (boolean)
3.43. failure_exec_mode (boolean)
3.44. dns_reuse_rcv_socket (boolean)
3.45. xavp_contact (string)
3.46. event_callback (str)
3.47. event_callback_lres_sent (str)
3.48. relay_100 (str)
3.49. rich_redirect (int)
3.50. exec_time_check (int)
4. Functions
4.1. t_relay([host, port])
4.2. t_relay_to_udp([ip, port])
4.3. t_relay_to_tcp([ip, port])
4.4. t_relay_to_tls([ip, port])
4.5. t_relay_to_sctp([ip, port])
4.6. t_on_failure(failure_route)
4.7. t_on_branch_failure(branch_failure_route)
4.8. t_on_reply(onreply_route)
4.9. t_on_branch(branch_route)
4.10. t_newtran()
4.11. t_reply(code, reason_phrase)
4.12. t_send_reply(code, reason)
4.13. t_lookup_request()
4.14. t_retransmit_reply()
4.15. t_release()
4.16. t_forward_nonack([ip, port])
4.17. t_forward_nonack_udp(ip, port)
4.18. t_forward_nonack_tcp(ip, port)
4.19. t_forward_nonack_tls(ip, port)
4.20. t_forward_nonack_sctp(ip, port)
4.21. t_set_fr(fr_inv_timeout [, fr_timeout])
4.22. t_reset_fr()
4.23. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
4.24. t_reset_max_lifetime()
4.25. t_set_retr(retr_t1_interval, retr_t2_interval)
4.26. t_reset_retr()
4.27. t_set_auto_inv_100(0|1)
4.28. t_branch_timeout()
4.29. t_branch_replied()
4.30. t_any_timeout()
4.31. t_any_replied()
4.32. t_grep_status("code")
4.33. t_is_canceled()
4.34. t_is_expired()
4.35. t_relay_cancel()
4.36. t_lookup_cancel([1])
4.37. t_drop_replies([mode])
4.38. t_save_lumps()
4.39. t_load_contacts([mode])
4.40. t_next_contacts()
4.41. t_next_contact_flow()
4.42. t_check_status(re)
4.43. t_check_trans()
4.44. t_set_disable_6xx(0|1)
4.45. t_set_disable_failover(0|1)
4.46. t_set_disable_internal_reply(0|1)
4.47. t_replicate([params])
4.48. t_relay_to(proxy, flags)
4.49. t_set_no_e2e_cancel_reason(0|1)
4.50. t_is_set(target)
4.51. t_use_uac_headers()
4.52. t_is_retr_async_reply()
4.53. t_uac_send(method, ruri, nexthop, socket, headers, body)
4.54. t_get_status_code()
4.55. t_clean()
5. RPC Commands
5.1. tm.list
5.2. tm.t_uac_start
5.3. tm.t_uac_wait
5.4. tm.cancel
5.5. tm.hash_stats
5.6. tm.reply
5.7. tm.reply_callid
5.8. tm.clean
5.9. tm.stats
6. Event Routes
6.1. event_route[tm:branch-failure:id]
6.2. event_route[tm:local-request]
6.3. event_route[tm:local-response]
7. TM Module API
7.1. Defines
7.2. Functions
7.2.1. register_tmcb(cb_type, cb_func)
7.2.2. load_tm(*import_structure)
7.2.3. int t_suspend(struct sip_msg *msg, unsigned int
*hash_index, unsigned int *label)
7.2.4. int t_continue(unsigned int hash_index, unsigned int
label, struct action *route)
7.2.5. int t_cancel_suspend(unsigned int hash_index,
unsigned int label)
8. Known Issues
1. Overview
The TM module enables stateful processing of SIP transactions. Stateful
logic is costly in terms of memory and CPU. The main use is services
that inherently need state. For example, transaction-based accounting
(module acc) needs to process transaction state as opposed to
individual messages. Any kind of forking must be implemented
transaction statefully. By using transaction states you trade CPU
caused by retransmission processing for memory. That only makes sense
if CPU consumption per request is huge. For example, if you want to
avoid costly DNS resolution for every retransmission of a request to an
unresolvable destination, use stateful mode. Then, only the initial
message burdens server by DNS queries, subsequent retransmissions will
be dropped and will not result in more processes blocked by DNS
resolution. The price is more memory consumption and higher processing
latency.
From the admin's perspective, these are the major functions : t_relay,
t_relay_to_udp and t_relay_to_tcp. All of them setup transaction state,
absorb retransmissions from upstream, generate downstream
retransmissions and correlate replies to requests. t_relay forwards to
current URI (be it original request's URI or a URI changed by some of
URI-modifying functions, such as sethost). t_relay_to_udp and
t_relay_to_tcp forward to a specific address over UDP or TCP
respectively.
In general, if TM is used, it copies clones of received SIP messages in
shared memory. That costs memory and also CPU time (memcpys, lookups,
shmem locks, etc.) Note that non-TM functions operate over the received
message in private memory, that means that any core operations will
have no effect on statefully processed messages after creating the
transactional state. For example, calling record_route after t_relay is
pretty useless, as the RR is added to privately held message whereas
its TM clone is being forwarded.
The TM module is quite big and uneasy to program --lots of mutexes,
shared memory access, malloc and free, timers--you really need to be
careful when you do anything. To simplify TM programming, there is the
instrument of callbacks. The callback mechanisms allow programmers to
register their functions to a specific event. See t_hooks.h for a list
of possible events.
Other things programmers may want to know is UAC--it is a very
simplistic code which allows you to generate your own transactions.
Particularly useful for things like NOTIFYs or IM gateways. The UAC
takes care of all the transaction machinery: retransmissions, FR
timeouts, forking, etc. See t_uac prototype in uac.h for more details.
If you want to see the transaction result the code can register for a
callback.
Note
Several Kamailio TM module functions are now implemented in the TMX
module. Check it to see if what you are looking for is there.
2. Serial Forking Based on Q Value
A single SIP INVITE request may be forked to multiple destinations. We
call the set of all such destinations a “destination set”. Individual
elements within the destination sets are called branches. The script
writer can add URIs to the destination set from the configuration file,
or they can be loaded from the user location database. Each registered
contact then becomes one branch in the destination set.
The default behavior of the TM module, if it encounters a SIP message
with multiple branches in the destination set, is to forward the SIP
message to all the branches in parallel. That means it sends the
message to all the branch destinations before it waits for replies from
any of them. This is the default behavior if you call t_relay() and
similar functions without any other arguments.
Another approach of handling multiple branches in a destination set is
serial forking. When configured to do serial forking, the server takes
the first branch out of the destination set, forwards the message to
its destination and waits for a reply or timeout. Only after a reply
has been received or a timeout occurred, the server takes another
destination from the destination set and tries again, until it receives
a positive final reply or until all branches from the destination set
have been tried.
Yet another, more sophisticated, way of handling multiple branches is
combined serial/parallel forking, where individual branches within the
destination set are assigned priorities. The order in which individual
branches are tried is then determined by their relative priority within
the destination set. Branches can be tried sequentially in the
descending priority order and all branches that have the same priority
can be tried in parallel. Such combined serial/parallel forking can be
achieved in the TM module with the help of functions t_load_contacts()
and t_next_contacts().
Every branch in the destination set is assigned a priority number, also
known as the “q value”. The q value is a floating point number in a
range 0 to 1.0. The higher the q value number, the more priority is
given to the particular branch in the destination set. Branches with q
value 1.0 have maximum priority, such branches should be always be
tried first in serial forking. Branches with q value 0 have the lowest
priority and they should by tried after all other branches with higher
priority in the destination set.
As an example, consider the following simple configuration file. When
the server receives an INVITE, it creates four branches with usernames
A through D and then forwards the request using t_relay():
request_route {
seturi("sip:a@example.com");
append_branch("sip:b@example.com");
append_branch("sip:c@example.com");
append_branch("sip:d@example.com");
t_relay();
break;
}
With this configuration the server forwards the request to all four
branches at once, performing parallel forking as described above. We
did not set the q value for individual branches in this example but we
can do that by slightly modifying the arguments given to
append_branch():
request_route {
seturi("sip:a@example.com");
append_branch("sip:b@example.com", "0.5");
append_branch("sip:c@example.com", "0.5");
append_branch("sip:d@example.com", "1.0");
t_relay();
break;
}
Here we assigned q value 0.5 to branches B and C and q value 1.0 to
branch D. We did not specify any q value for branch A and in that case
it is assumed that its q value is the lowest from all branches within
the destination set. If you try to run this example again, you will
figure out that nothing changed, t_relay() still forward the message to
all branches in parallel.
We now want to implement the combined serial/parallel forking. Branch D
should be tried first, because its q value is 1.0. Branches B and C
should be tried in parallel, but only after D finishes. Branch A should
be tried after B and C finished, because its q value (the default) is
the lowest of all. To do that, we need to introduce two new functions
into our example and two tm module parameters:
modparam("tm", "contacts_avp", "tm_contacts");
modparam("tm", "contact_flows_avp", "tm_contact_flows");
request_route {
seturi("sip:a@example.com");
append_branch("sip:b@example.com", "0.5");
append_branch("sip:c@example.com", "0.5");
append_branch("sip:d@example.com", "1.0");
t_load_contacts();
t_next_contacts();
t_relay();
break;
}
First of all, the tm module parameters are mandatory if the two new
functions are used. Function t_load_contacts() takes all branches from
the destination set, sorts them according to their q values and stores
them in the AVP configured in the modparam. The function also clears
the destination set, which means that it removes all branches
configured before with seturi() and append_branch().
Function t_next_contacts() takes the AVP created by the previous
function and extract the branches with highest q values from it. In our
example it is branch D. That branch is then put back into the
destination set and when the script finally reaches t_relay(), the
destination set only contains branch D and the request will be
forwarded there.
We achieved the first step of serial forking, but this is not
sufficient. Now we also need to forward to other branches with lower
priority values when branch D finishes. To do that, we need to extend
the configuration file again and introduce a failure_route section:
modparam("tm", "contacts_avp", "tm_contacts");
request_route {
seturi("sip:a@example.com");
append_branch("sip:b@example.com", "0.5");
append_branch("sip:c@example.com", "0.5");
append_branch("sip:d@example.com", "1.0");
t_load_contacts();
t_next_contacts();
t_on_failure("serial");
t_relay();
break;
}
failure_route["serial"]
{
if (!t_next_contacts()) {
exit;
}
t_on_failure("serial");
t_relay();
}
The failure_route section will be executed when branch D finishes. It
executes t_next_contacts() again and this time the function retrieves
branches B and C from the AVP and adds them to the destination set.
Here we need to check the return value of the function, because a
negative value indicates that there were no more branches, in that case
the failure_route should just terminate and forward the response from
branch D upstream.
If t_next_contact() returns a positive value then we have more new
branches to try and we need to setup the failure_route again and call
t_relay(). In our example the request will now be forwarded to branches
B and C in paralell, because they were both added to the destination
set by t_next_contacts() at the same time.
When branches B and C finish, the failure_route block is executed
again, this time t_next_contacts() puts the final branch A into the
destination set and t_relay() forwards the request there.
And that's the whole example, we achieved combined serial/parallel
forking based on the q value of individual branches. In real-world
configuration files the script writer would need to check the return
value of all functions and restart_fr_on_each_reply. The destination
set would not be configured directly in the configuration file, but can
be retrieved from the user location database. In that case registered
contacts will be stored in the destination set as branches and their q
values (provided by UAs) will be used.
3. Parameters
3.1. fr_timer (integer)
3.2. fr_inv_timer (integer)
3.3. max_inv_lifetime (integer)
3.4. max_noninv_lifetime (integer)
3.5. wt_timer (integer)
3.6. retr_timer1 (integer)
3.7. retr_timer2 (integer)
3.8. noisy_ctimer (integer)
3.9. restart_fr_on_each_reply (integer)
3.10. auto_inv_100 (integer)
3.11. auto_inv_100_reason (string)
3.12. unix_tx_timeout (integer)
3.13. aggregate_challenges (integer)
3.14. reparse_invite (integer)
3.15. ac_extra_hdrs (string)
3.16. blst_503 (integer)
3.17. blst_503_def_timeout (integer)
3.18. blst_503_min_timeout (integer)
3.19. blst_503_max_timeout (integer)
3.20. blst_methods_add (unsigned integer)
3.21. blst_methods_lookup (unsigned integer)
3.22. cancel_b_method (integer)
3.23. reparse_on_dns_failover (integer)
3.24. on_sl_reply (string)
3.25. contacts_avp (string)
3.26. contact_flows_avp (string)
3.27. fr_timer_avp (string)
3.28. fr_inv_timer_avp (string)
3.29. unmatched_cancel (string)
3.30. ruri_matching (integer)
3.31. via1_matching (integer)
3.32. callid_matching (integer)
3.33. pass_provisional_replies (integer)
3.34. default_code (integer)
3.35. default_reason (string)
3.36. disable_6xx_block (integer)
3.37. local_ack_mode (integer)
3.38. failure_reply_mode (integer)
3.39. faked_reply_prio (integer)
3.40. local_cancel_reason (boolean)
3.41. e2e_cancel_reason (boolean)
3.42. remap_503_500 (boolean)
3.43. failure_exec_mode (boolean)
3.44. dns_reuse_rcv_socket (boolean)
3.45. xavp_contact (string)
3.46. event_callback (str)
3.47. event_callback_lres_sent (str)
3.48. relay_100 (str)
3.49. rich_redirect (int)
3.50. exec_time_check (int)
3.1. fr_timer (integer)
Timer which hits if no final reply for a request or ACK for a negative
INVITE reply arrives (in milliseconds).
Default value is 30000 ms (30 seconds).
See also: t_set_fr(), max_noninv_lifetime.
Example 1.1. Set fr_timer parameter
...
modparam("tm", "fr_timer", 10000)
...
3.2. fr_inv_timer (integer)
Timer which hits if no final reply for an INVITE arrives after a
provisional message was received (in milliseconds).
Note: This timer can be restarted when a provisional response is
received. For more details see restart_fr_on_each_reply.
Default value is 120000 ms (120 seconds).
See also: t_set_fr(), max_inv_lifetime.
Example 1.2. Set fr_inv_timer parameter
...
modparam("tm", "fr_inv_timer", 180000)
...
3.3. max_inv_lifetime (integer)
Maximum time an INVITE transaction is allowed to be active (in
milliseconds). After this interval has passed from the transaction
creation, the transaction will be either moved into the wait state or
in the final response retransmission state, irrespective of the
transaction fr_inv_timer and fr_timer values.
An INVITE transaction will be kept in memory for maximum:
max_inv_lifetime+fr_timer(from the ACK to the final reply
wait)+wt_timer.
The main difference between this timer and fr_inv_timer is that the
fr_inv_timer is per branch, while max_inv_lifetime is per the whole
transaction. Even on a per branch basis fr_inv_timer could be
restarted. For example, by default if restart_fr_on_each_reply is not
cleared, the fr_inv_timer will be restarted for each received
provisional reply. Even if restart_fr_on_each_reply is not set the
fr_inv_timer will still be restarted for each increasing reply (e.g.
180, 181, 182, ...). Another example when a transaction can live
substantially more than its fr_inv_timer and where max_inv_lifetime
will help is when DNS failover is used (each failed DNS destination can
introduce a new branch).
The default value is 180000 ms (180 seconds - the rfc3261 timer C
value).
See also: max_noninv_lifetime, t_set_max_lifetime() (allows changing
max_inv_lifetime on a per transaction basis), t_reset_max_lifetime
fr_timer, wt_timer, restart_fr_on_each_reply.
Example 1.3. Set max_inv_lifetime parameter
...
modparam("tm", "max_inv_lifetime", 150000)
...
3.4. max_noninv_lifetime (integer)
Maximum time a non-INVITE transaction is allowed to be active (in
milliseconds). After this interval has passed from the transaction
creation, the transaction will be either moved into the wait state or
in the final response retransmission state, irrespective of the
transaction fr_timer value. It's the same as max_inv_lifetime, but for
non-INVITEs.
A non-INVITE transaction will be kept in memory for a maximum of:
max_noninv_lifetime+wt_timer.
The main difference between this timer and fr_timer is that the
fr_timer is per branch, while max_noninv_lifetime is per the whole
transaction. An example when a transaction can live substantially more
then its fr_timer and where max_noninv_lifetime will help is when DNS
failover is used (each failed DNS SRV destination can introduce a new
branch).
The default value is 32000 ms (32 seconds - the RFC3261 timer F value).
See also: max_inv_lifetime, t_set_max_lifetime() (allows changing
max_noninv_lifetime on a per transaction basis), t_reset_max_lifetime
fr_timer, wt_timer.
Example 1.4. Set max_noninv_lifetime parameter
...
modparam("tm", "max_noninv_lifetime", 30000)
...
3.5. wt_timer (integer)
Time for which a transaction stays in memory to absorb delayed messages
after it completed (in milliseconds); also, when this timer hits,
retransmission of local CANCEL requests is stopped (a puristic but
complex behavior would be not to enter wait state until local branches
are finished by a final reply or FR timer--we simplified).
Default value is 5000 ms (5 seconds).
Example 1.5. Set wt_timer parameter
...
modparam("tm", "wt_timer", 1000)
...
3.6. retr_timer1 (integer)
Initial retransmission period (in milliseconds).
Default value is 500 milliseconds.
Example 1.6. Set retr_timer1 parameter
...
modparam("tm", "retr_timer1", 1000)
...
3.7. retr_timer2 (integer)
Maximum retransmission period (in milliseconds). The retransmission
interval starts with retr_timer1 and increases until it reaches this
value. After this it stays constant at retr_timer2.
Default value is 4000 milliseconds.
Example 1.7. Set retr_timer2 parameter
...
modparam("tm", "retr_timer2", 2000)
...
3.8. noisy_ctimer (integer)
If set, INVITE transactions that time-out (FR INV timer) will be always
replied. If it's not set, the transaction has only one branch and no
response was ever received on this branch, it will be silently dropped
(no 408 reply will be generated) This behavior is overridden if a
request is forked, the transaction has a failure route or callback, or
some functionality explicitly turned it on for a transaction (like the
ACC module does to avoid unaccounted transactions due to expired
timer). Turn this off only if you know the client UACs will timeout and
their timeout interval for INVITEs is lower or equal than tm's
fr_inv_timer.
Default value is 1 (on).
Example 1.8. Set noisy_ctimer parameter
...
modparam("tm", "noisy_ctimer", 1)
...
3.9. restart_fr_on_each_reply (integer)
If set (default), the fr_inv_timer for an INVITE transaction will be
restarted for each provisional reply received (rfc3261 mandated
behaviour). If not set, the fr_inv_timer will be restarted only for the
first provisional replies and for increasing replies greater or equal
180 (e.g. 180, 181, 182, 185, ...).
Setting it to 0 is especially useful when dealing with bad UAs that
continuously retransmit 180s, not allowing the transaction to timeout
(and thus making impossible the implementation of certain services,
like automatic voicemail after x seconds).
Default value is 1 (on).
See also: fr_inv_timer, max_inv_lifetime.
Example 1.9. Set restart_fr_on_each_reply parameter
...
modparam("tm", "restart_fr_on_each_reply", 0)
...
3.10. auto_inv_100 (integer)
If set (default) tm will automatically send and 100 reply to INVITEs.
Setting it to 0 can be used to enable first running some tests or
pre-processing on the INVITE and only if some conditions are met
manually send a 100 (using t_reply()). Note however that in this case
all the 100s have to be sent "by hand". t_set_auto_inv_100() might help
to selectively turn off this feature only for some specific
transactions.
Default value is 1 (on).
See also: t_set_auto_inv_100() auto_inv_100_reason.
Example 1.10. Set auto_inv_100 parameter
...
modparam("tm", "auto_inv_100", 0)
...
3.11. auto_inv_100_reason (string)
Set reason text of the automatically sent 100 to an INVITE.
Default value is "trying -- your call is important to us".
See also: auto_inv_100.
Example 1.11. Set auto_inv_100_reason parameter
...
modparam("tm", "auto_inv_100_reason", "Trying")
...
3.12. unix_tx_timeout (integer)
Unix socket transmission timeout, in milliseconds.
If UNIX sockets are used (e.g.: to communicate with sems) and sending a
message on a UNIX socket takes longer than unix_tx_timeout, the send
will fail.
The default value is 500 milliseconds.
Example 1.12. Set unix_tx_timeout parameter
...
modparam("tm", "unix_tx_timeout", 250)
...
3.13. aggregate_challenges (integer)
If set (default) and the final response is a 401 or a 407 and more than
one branch received a 401 or 407, then all the WWW-Authenticate and
Proxy-Authenticate headers from all the 401 and 407 replies will be
aggregated in a new final response. If only one branch received the
winning 401 or 407 then this reply will be forwarded (no new one will
be built).
If disabled (set to 0) only the first 401, or if no 401 was received
the first 407, will be forwarded (no header aggregation).
Default value is 1 (required by RFC 3261).
Example 1.13. Set aggregate_challenges parameter
...
modparam("tm", "aggregate_challenges", 0)
...
3.14. reparse_invite (integer)
If set (default), the CANCEL and negative ACK requests are constructed
from the INVITE message which was sent out instead of building them
from the received request. The disadvantage is that the outgoing INVITE
has to be partially re-parsed, the advantage is that the CANCEL/ACK is
always RFC 3261-compliant, it always contains the same route-set as the
INVITE message. Do not disable the INVITE re-parsing for example in the
following cases:
- The INVITE contains a preloaded route-set, and Kamailio forwards the
message to the next hop according to the "Route" header. The "Route"
header is not removed in the CANCEL without reparse_invite=1.
- Kamailio record-routes, thus an in-dialog INVITE contains a "Route"
header which is removed during loose routing. If the in-dialog INVITE
is rejected, the negative ACK still contains the "Route" header without
reparse_invite=1.
Default value is 1.
Example 1.14. Set reparse_invite parameter
...
modparam("tm", "reparse_invite", 0)
...
3.15. ac_extra_hdrs (string)
Header fields prefixed by this parameter value are included in the
CANCEL and negative ACK messages if they were present in the outgoing
INVITE.
Note, that the parameter value effects only those headers which are not
covered by RFC 3261 (which are neither mandatory nor prohibited in
CANCEL and ACK), and the parameter can be used only together with
reparse_invite=1.
Default value is "".
Example 1.15. Set ac_extra_hdrs parameter
...
modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")