-
Notifications
You must be signed in to change notification settings - Fork 564
/
README
1644 lines (1269 loc) · 55.2 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
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.1.1. Per-Branch flags
1.1.2. Timeout-Based Failover
1.1.3. DNS Failover
1.1.4. Anycast Scenario
1.1.5. Usage Scope
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. fr_timeout (integer)
1.3.2. fr_inv_timeout (integer)
1.3.3. wt_timer (integer)
1.3.4. delete_timer (integer)
1.3.5. T1_timer (integer)
1.3.6. T2_timer (integer)
1.3.7. ruri_matching (integer)
1.3.8. via1_matching (integer)
1.3.9. unix_tx_timeout (integer)
1.3.10. restart_fr_on_each_reply (integer)
1.3.11. tw_append (string)
1.3.12. pass_provisional_replies (integer)
1.3.13. syn_branch (integer)
1.3.14. onreply_avp_mode (integer)
1.3.15. disable_6xx_block (integer)
1.3.16. enable_stats (integer)
1.3.17. minor_branch_flag (string/integer)
1.3.18. timer_partitions (integer)
1.3.19. auto_100trying (integer)
1.3.20. tm_replication_cluster (integer)
1.3.21. cluster_param (string)
1.3.22. cluster_auto_cancel (boolean)
1.4. Exported Functions
1.4.1. t_relay([flags])
1.4.2. t_relay(proto:host:port,[flags])
1.4.3. t_reply(code, reason_phrase)
1.4.4. t_reply_with_body(code, reason_phrase, body)
1.4.5. t_newtran()
1.4.6. t_check_trans()
1.4.7. t_check_status(re)
1.4.8. t_local_replied(reply)
1.4.9. t_was_cancelled()
1.4.10. t_cancel_branch([flags])
1.4.11.
t_new_request(method,RURI,from,to[,body[,ctx]
])
1.4.12. t_on_failure(failure_route)
1.4.13. t_on_reply(reply_route)
1.4.14. t_on_branch(branch_route)
1.4.15. t_inject_branches(source[,flags])
1.4.16. t_wait_for_new_branches()
1.4.17. t_add_hdrs("sip_hdrs")
1.4.18. t_add_cancel_reason("Reason_hdr")
1.4.19. t_replicate(URI,[flags])
1.4.20. t_write_req(info,fifo)
t_write_unix(info,sock)
1.4.21. t_flush_flags()
1.4.22. t_anycast_replicate()
1.5. Exported Pseudo-Variables
1.5.1. $T_branch_idx
1.5.2. $T_reply_code
1.5.3. $T_fr_timeout
1.5.4. $T_fr_inv_timeout
1.5.5. $T_ruri
1.5.6. $bavp(name)
1.5.7. $T_id
1.6. Exported MI Functions
1.6.1. t_uac_dlg
1.6.2. t_uac_cancel
1.6.3. t_hash
1.6.4. t_reply
1.7. Exported Statistics
1.7.1. received_replies
1.7.2. relayed_replies
1.7.3. local_replies
1.7.4. UAS_transactions
1.7.5. UAC_transactions
1.7.6. 2xx_transactions
1.7.7. 3xx_transactions
1.7.8. 4xx_transactions
1.7.9. 5xx_transactions
1.7.10. 6xx_transactions
1.7.11. inuse_transactions
2. Developer Guide
2.1. Functions
2.1.1. load_tm(*import_structure)
3. Frequently Asked Questions
4. Contributors
4.1. By Commit Statistics
4.2. By Commit Activity
5. Documentation
5.1. Contributors
List of Tables
4.1. Top contributors by DevScore^(1), authored commits^(2) and
lines added/removed^(3)
4.2. Most recently active contributors^(1) to this module
List of Examples
1.1. Set fr_timeout parameter
1.2. Set fr_inv_timeout parameter
1.3. Set wt_timer parameter
1.4. Set delete_timer parameter
1.5. Set T1_timer parameter
1.6. Set T2_timer parameter
1.7. Set ruri_matching parameter
1.8. Set via1_matching parameter
1.9. Set unix_tx_timeout parameter
1.10. Set restart_fr_on_each_reply parameter
1.11. Set tw_append parameter
1.12. Set pass_provisional_replies parameter
1.13. Set syn_branch parameter
1.14. Set onreply_avp_mode parameter
1.15. Set disable_6xx_block parameter
1.16. Set enable_stats parameter
1.17. Set minor_branch_flag parameter
1.18. Set timer_partitions parameter
1.19. Set auto_100trying parameter
1.20. Set tm_replication_cluster parameter
1.21. Set the cluster_param parameter
1.22. Set the cluster_auto_cancel parameter
1.23. t_relay usage
1.24. t_relay usage
1.25. t_reply usage
1.26. t_reply_with_body usage
1.27. t_newtran usage
1.28. t_check_trans usage
1.29. t_check_status usage
1.30. t_local_replied usage
1.31. t_was_cancelled usage
1.32. t_cancel_branch usage
1.33. t_new_request usage
1.34. t_on_failure usage
1.35. t_on_reply usage
1.36. t_on_branch usage
1.37. t_inject_branches usage
1.38. t_wait_for_new_branches usage
1.39. t_add_hdrs usage
1.40. t_add_cancel_reason usage
1.41. t_replicate usage
1.42. t_write_req/unix usage
1.43. t_flush_flags usage
1.44. t_anycast_replicate usage
Chapter 1. Admin Guide
1.1. Overview
TM module enables stateful processing of SIP transactions. The
main use of stateful logic, which is costly in terms of memory
and CPU, is some services inherently need state. For example,
transaction-based accounting (module acc) needs to process
transaction state as opposed to individual messages, and any
kinds of forking must be implemented statefully. Other use of
stateful processing is it trading CPU caused by retransmission
processing for memory. That makes however only 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 user's perspective, the major function is t_relay(). It
setup transaction state, absorb retransmissions from upstream,
generate downstream retransmissions and correlate replies to
requests.
In general, if TM is used, it copies clones of received SIP
messages in shared memory. That costs the 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.
TM is quite big and uneasy to program--lot 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 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. Who wants to see the
transaction result may register for a callback.
1.1.1. Per-Branch flags
First what is the idea with the branch concept: branch route is
a route to be execute separately for each branch before being
sent out - changes in that route should reflect only on that
branch.
There are several types of flags in OpenSIPS :
* message/transaction flags - they are visible everywhere in
the transaction (in all routes and in all sequential
replies/request).
* branch flags - flags that are visible only from a specific
branch - in all replies and routes connected to this
branch.
* script flags - flags that exist only during script
execution. They are not store anywhere and are lost once
the top level route was left.
For example: I have a call parallel forking to GW and to a
user. And I would like to know from which branch I will get the
final negative reply (if so). I will set a branch route before
relaying the calls (with the 2 branches). The branch route will
be separately executed for each branch; in the branch going to
GW (I can identified it by looking to RURI), I will set a
branch flag. This flag will appear only in the onreply route
run for replied from GW. It will be also be visible in failure
route if the final elected reply belongs to the GW branch. This
flags will not be visible in the other branch (in routes
executing replies from the other branch).
For how to define branch flags and use via script, see
t_on_branch() and the setbflag(), resetbflag() and isbflagset()
script functions.
Also, modules may set branch flags before transaction creation
(for the moment this feature is not available in script). The
REGISTRAR module was the first to use this type of flags. The
NAT flag is pushed in branch flags instead in message flags
1.1.2. Timeout-Based Failover
Timeouts can be used to trigger failover behavior. E.g. if we
send a call to a gateway and the gateway does not send a
provisional response within 3 seconds, we want to cancel this
call and send the call to another gateway. Another example is
to ring a SIP client only for 30 seconds and then redirect the
call to the voicemail.
The transaction module exports two types of timeouts:
* fr_timeout - used when no response was received yet. If
there is no response after fr_timeout seconds, the timer
triggers (and failure route will be executed if
t_on_failure() was called). For INVITE transactions, if a
provisional response was received, the timeout is reset to
fr_inv_timeout seconds and RT_T2 for all other
transactions. Once a final response is received, the
transaction has finished.
* fr_inv_timeout - this timeout starts counting down once a
provisional response was received for an INVITE
transaction.
For example: You want to have failover if there is no
provisional response after 3 seconds, but you want to ring for
60 seconds. Thus, set the fr_timeout to 3 and fr_inv_timeout to
60.
1.1.3. DNS Failover
DNS based failover can be use when relaying stateful requests.
According to RFC 3263, DNS failover should be done on transport
level or transaction level. TM module supports them both.
Failover at transport level may be triggered by a failure of
sending out the request message. A failure occurs if the
corresponding interface was found for sending the request, if
the TCP connection was refused or if a generic internal error
happened during send. There is no ICMP error report support.
Failover at transaction level may be triggered when the
transaction completed either with a 503 reply, either with a
timeout without any received reply. In such a case,
automatically, a new branch will be forked if any other
destination IPs can be used to deliver the requests. The new
branch will be a clone of the winning branch.
The set of destinations IPs is step-by-step build (on demand)
based on the NAPTR, SRV and A records available for the
destination domain.
DNS-based failover is by default applied excepting when this
failover is globally disabled (see the core parameter
disable_dns_failover) or when the relay flag (per transaction)
is set (see the t_relay() function).
1.1.4. Anycast Scenario
Doing a load balancing scenario using Anycast IPs, one might
run into an issue where a transaction request comes on one
instance, and the reply (or replies) comes on different ones.
This would normaly break the transaction state, because the
local transaction will start re-transmissios and would
eventually timeout. Moreover, from UA's perspective, the reply
whould have been sent, but since it reaches a proxy that is not
aware of that transaction, it will not be forwarded (nor ACKed
in case of INVITES). And from this point things can escalade
quickly.
To sort out these problems, the module uses a distributed
mechanism to figure out where the transaction for a specific
reply was created. When an instance receives a reply that does
not have an associated transaction, it replicates it to be
handled by the instance that “owns” it. This is achieved using
the clusterer module support.
Setting up an anycast scenario is very simple: all the
instances that are part of an anycast secnario must be set up
in a cluster (more info at the tm_replication_cluster param).
When a transaction is created, a special identifier is appended
to the branch parameter, namely the instance that created the
transaction. When a reply comes in, the transaction module
checks who “owns” the transaction. If the identifier is the
instance's own id, then the reply is processed locally.
Otherwise it is replicated to the node indicated by the id.
Replication is done in a very efficient manner, using the
proto_bin transport.
Special handling is applied to CANCEL and ACK methods. Due to
the fact that these methods do not contain the special
identifier in the branch parameter (since they are generated by
the UAC and not by us), there is no way to determine who “owns”
the transaction. Therefore, if we do not find a local
transaction for these requests, we broadcast them to all the
other instances using the t_anycast_replicate() function.
Again, this is done in a very efficient manner using the
proto_bin transport.
1.1.5. Usage Scope
Transaction functions and variables are only designed to be
called on SIP request messages where a transaction can be
created, or in routes that are transaction aware, such as
branch_route[name], failure_route[name] or onreply_route[name].
Using TM functtions or variables in a route that is not
transaction aware, such as the generic onreply_route,
error_route or timer_route[name, timer] may lead to undefined
behavior, and most of the time in bogus or malformed
signalling. Therefore it is strongly recommended to avoid using
them in non-tm context aware routes.
1.2. Dependencies
1.2.1. OpenSIPS Modules
The following modules must be loaded before this module:
* clusterer module, if the anycast scenario is enabled (see
tm_replication_cluster param for more information).
1.2.2. External Libraries or Applications
The following libraries or applications must be installed
before running OpenSIPS with this module loaded:
* None.
1.3. Exported Parameters
1.3.1. fr_timeout (integer)
Timeout which is triggered if no final reply for a request or
ACK for a negative INVITE reply arrives (in seconds).
Default value is 30 seconds.
Example 1.1. Set fr_timeout parameter
...
modparam("tm", "fr_timeout", 10)
...
1.3.2. fr_inv_timeout (integer)
Timeout which is triggered if no final reply for an INVITE
arrives after a provisional message was received (in seconds).
This timeout starts counting down once the first provisional
response is received. Thus, fast failover (no 100 trying from
gateway) can be achieved by setting fr_timeout to low values.
See example below.
Default value is 120 seconds.
Example 1.2. Set fr_inv_timeout parameter
...
modparam("tm", "fr_inv_timeout", 200)
...
1.3.3. wt_timer (integer)
Time for which a transaction stays in memory to absorb delayed
messages after it completed; also, when this timer hits,
retransmission of local cancels 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).
For non-INVITE transaction this timer relates to timer J of RFC
3261 section 17.2.2. According to the RFC this timer should be
64*T1 (= 32 seconds). But this would increase memory usage as
the transactions are kept in memory very long.
Default value is 5 seconds.
Example 1.3. Set wt_timer parameter
...
modparam("tm", "wt_timer", 10)
...
1.3.4. delete_timer (integer)
Time after which a to-be-deleted transaction currently ref-ed
by a process will be tried to be deleted again.
Default value is 2 seconds.
Example 1.4. Set delete_timer parameter
...
modparam("tm", "delete_timer", 5)
...
1.3.5. T1_timer (integer)
Retransmission T1 period, in milliseconds.
Default value is 500 milliseconds.
Example 1.5. Set T1_timer parameter
...
modparam("tm", "T1_timer", 700)
...
1.3.6. T2_timer (integer)
Maximum retransmission period, in milliseconds.
Default value is 4000 milliseconds.
Example 1.6. Set T2_timer parameter
...
modparam("tm", "T2_timer", 8000)
...
1.3.7. ruri_matching (integer)
Should be request-uri matching used as a part of pre-3261
transaction matching as the standard wants us to do so? Turn
only off for better interaction with devices that are broken
and send different r-uri in CANCEL/ACK than in original INVITE.
Default value is 1 (true).
Example 1.7. Set ruri_matching parameter
...
modparam("tm", "ruri_matching", 0)
...
1.3.8. via1_matching (integer)
Should be top most VIA matching used as a part of pre-3261
transaction matching as the standard wants us to do so? Turn
only off for better interaction with devices that are broken
and send different top most VIA in CANCEL/ACK than in original
INVITE.
Default value is 1 (true).
Example 1.8. Set via1_matching parameter
...
modparam("tm", "via1_matching", 0)
...
1.3.9. unix_tx_timeout (integer)
Send timeout to be used by function which use UNIX sockets (as
t_write_unix).
Default value is 2 seconds.
Example 1.9. Set unix_tx_timeout parameter
...
modparam("tm", "unix_tx_timeout", 5)
...
1.3.10. restart_fr_on_each_reply (integer)
If true (non null value), the final response timer will be
re-triggered for each received provisional reply. In this case,
final response timeout may occur after a time longer than
fr_inv_timeout (if UAS keeps sending provisional replies)
Default value is 1 (true).
Example 1.10. Set restart_fr_on_each_reply parameter
...
modparam("tm", "restart_fr_on_each_reply", 0)
...
1.3.11. tw_append (string)
List of additional information to be appended by t_write_req
and t_write_unix functions.
Default value is null string.
Syntax of the parameter is:
* tw_append = append_name':' element (';'element)*
* element = ( [name '='] variable)
Each element will be appended per line in “name: value” format.
Element “$rb (message body)” is the only one which does not
accept name; the body it will be printed all the time at the
end, disregarding its position in the definition string.
Example 1.11. Set tw_append parameter
...
modparam("tm", "tw_append",
"test: ua=$hdr(User-Agent) ;avp=$avp(avp);$rb;time=$Ts")
...
1.3.12. pass_provisional_replies (integer)
Enable/disable passing of provisional replies to FIFO
applications.
Default value is 0.
Example 1.12. Set pass_provisional_replies parameter
...
modparam("tm", "pass_provisional_replies", 1)
...
1.3.13. syn_branch (integer)
Enable/disable the usage of stateful synonym branch IDs in the
generated Via headers. They are faster but not reboot-safe.
Default value is 1 (use synonym branches).
Example 1.13. Set syn_branch parameter
...
modparam("tm", "syn_branch", 0)
...
1.3.14. onreply_avp_mode (integer)
Describes how the AVPs should be handled in reply route:
* 0 - the AVPs will be per message only; they will not
interfere with the AVPS stored in transaction; initially
there will be an empty list and at the end of the route,
all AVPs that were created will be discarded.
* 1 - the AVPs will be the transaction AVPs; initially the
transaction AVPs will be visible; at the end of the route,
the list will attached back to transaction (with all the
changes)
In mode 1, you can see the AVPs you set in request route,
branch route or failure route. The side effect is performance
as more locking is required in order to keep the AVP's list
integrity.
Default value is 0.
Example 1.14. Set onreply_avp_mode parameter
...
modparam("tm", "onreply_avp_mode", 1)
...
1.3.15. disable_6xx_block (integer)
Tells how the 6xx replies should be internally handled:
* 0 - the 6xx replies will block any further serial forking
(adding new branches). This is the RFC3261 behaviour.
* 1 - the 6xx replies will be handled as any other negative
reply - serial forking will be allowed. Logically, you need
to break RFC3261 if you want to do redirects to
announcement and voicemail services.
Default value is 0.
Example 1.15. Set disable_6xx_block parameter
...
modparam("tm", "disable_6xx_block", 1)
...
1.3.16. enable_stats (integer)
Enables statistics support in TM module - If enabled, the TM
module will internally keep several statistics and export them
via the MI - Management Interface.
Default value is 1 (enabled).
Example 1.16. Set enable_stats parameter
...
modparam("tm", "enable_stats", 0)
...
1.3.17. minor_branch_flag (string/integer)
A branch flag index to be used in script to mark the minor
branches ( before t_relay() ).
A minor branch is a branch OpenSIPS will not wait to complete
during parallel forking. So, if the rest of the branches are
negativly replied OpenSIPS will not wait for a final answer
from the minor branch, but it will simply cancel it.
Main applicability of minor branch is to fork a branch to a
media server for injecting (via 183 Early Media) some pre-call
media - of course, this branch will be transparanent for the
rest of the call branches (from branch selection point of
view).
Default value is none (disabled).
Example 1.17. Set minor_branch_flag parameter
...
modparam("tm", "minor_branch_flag", "MINOR_BFLAG")
...
1.3.18. timer_partitions (integer)
The number of partitions for the internal TM timers
(retransmissions, delete, wait, etc). Partitioning the timers
increase the throughput under heavly load by handling timer
events in parallel, rather than all serial.
Recomanded range for timer partitions is max 16 (soft limit).
Default value is 1 (disabled).
Example 1.18. Set timer_partitions parameter
...
# Enable two timer partitions
modparam("tm", "timer_partitions", 2)
...
1.3.19. auto_100trying (integer)
This parameter controls if the TM module should automatically
generate an 100 Trying stateful reply when an INVITE
transaction is created.
You may want to disable this behavior if you want to control
from script level when the 100 Trying is to be sent out.
Default value is 1 (enabled).
Example 1.19. Set auto_100trying parameter
...
# Disable automatic 100 Trying
modparam("tm", "auto_100trying", 0)
...
1.3.20. tm_replication_cluster (integer)
This parameter should be used in an anycast setup, and
specifies the cluster id of all the nodes that use an anycast
IP.
Check out the tm_anycast section for more details.
Anycast replication is disabled by default.
Example 1.20. Set tm_replication_cluster parameter
...
# replicate anycast messages in cluster 1
modparam("tm", "tm_replication_cluster", 1)
...
1.3.21. cluster_param (string)
This parameter should be used in an anycast setup, and
specifies the name of the parameter used in the VIA branch
param to specifiy the instance id that created the transaction.
Check out the tm_anycast section for more details.
Default value is cid.
Example 1.21. Set the cluster_param parameter
...
modparam("tm", "cluster_param", "tid")
...
1.3.22. cluster_auto_cancel (boolean)
This parameter should be used in an anycast setup, and
specifies whether a CANCEL message received on a listener that
is marked as anycast should be automatically handled, or should
get in the OpenSIPS script. If this parameter is enabled
(default), CANCEL messages received on an anycast listener will
never enter the script, thus making the script cleaner.
Check out the tm_anycast section for more details.
Default value is yes (enabled).
Example 1.22. Set the cluster_auto_cancel parameter
...
# disable auto-cancel handling
modparam("tm", "cluster_auto_cancel", no)
...
1.4. Exported Functions
1.4.1. t_relay([flags])
Relay a message statefully to destination indicated in current
URI. (If the original URI was rewritten by UsrLoc, RR,
strip/prefix, etc., the new URI will be taken). Returns a
negative value on failure--you may still want to send a
negative reply upstream statelessly not to leave upstream UAC
in lurch.
The coresponding transaction may or may not be already created.
If not yet created, the function will automatically create it.
The function may take as parameter an optional set of flags for
controlling the internal behaviour. The flags may be given in
decimal or hexa format; supported flags are:
* 0x01 - deprecated, not used any more
* 0x02 - do not internally generate and send a "477 Send
failed (477/TM)" SIP reply in case of a global forwarding
failure (i.e. forwarding for each branch has failed due to
internal errors, bad R-URI, bad message, lack of network
reachability, etc.).
This flag only applies if the transaction was not
previously created by t_newtran(). When a global forwarding
failure occurs, no SIP request is relayed and therefore no
negative SIP reply or timeout will show up on the
failure_route, if one is set.
Useful if you want to implement a failover logic for when
none of the currently created branches can be forwarded to.
* 0x04 - disable the DNS failover for the transaction. Only
first IP will be used. It disables the failover both at
transport and transaction level.
* 0x08 - If the request is a CANCEL, trust and pass further
the Reason header from the received CANCEL - shortly, will
propagate the Reason header.
* 0x10 - Allows OpenSIPS to inspect and follow the
Content-Disposition "no-cancel" indication (if present). As
per RFC3841, section 9.1, the TM module may be instructed
not to cancel all ongoing branches when a 2xx reply is
received. It will keep the pending branches ongoing until
(1) all branches will receive a final reply or (2) the
transactionhits the timeout.
In case of error, the function returns the following codes:
* -1 - generic internal error
* -2 - bad message (parsing errors)
* -3 - no destination available (no branches were added or
request already cancelled)
* -4 - bad destination (unresolvable address)
* -5 - destination filtered (black listed)
* -6 - generic send failed
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
Example 1.23. t_relay usage
...
if (!t_relay()) {
sl_reply_error();
exit;
}
...
1.4.2. t_relay(proto:host:port,[flags])
Relay a message statefully to a fixed destination. The
destination is specified as “[proto:]host[:port]”. If a
destination URI “$du” for this message was set before the
function is called then this value will be used as the
destination instead of the function parameter.
The function may take as parameter an optional set of flags for
controlling the internal behaviour - for details see the above
“t_relay([flags])” function.
This functions can be used from REQUEST_ROUTE, FAILURE_ROUTE.
Example 1.24. t_relay usage
...
t_relay("tcp:192.168.1.10:5060");
t_relay("mydomain.com:5070","0x1");
t_relay("udp:mydomain.com");
...
1.4.3. t_reply(code, reason_phrase)
Sends a stateful SIP reply to the currently processed requests.
Note that if the transaction was not created yet, it will
automatically created by internally using the t_newtran
function.
Meaning of the parameters is as follows:
* code - Reply code number.
* reason_phrase - Reason string.
Both parameters accept any kind of variables.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
Example 1.25. t_reply usage
...
t_reply("404", "Use $rU not found");
...
1.4.4. t_reply_with_body(code, reason_phrase, body)
Sends a stateful SIP reply with a body to the currently
processed requests. Note that if the transaction was not
created yet, it will automatically created by internally using
the t_newtran function.
Meaning of the parameters is as follows:
* code - Reply code number.
* reason_phrase - Reason string.
* body - Reply body.
All parameters accept any kind of variables.
This function can be used from REQUEST_ROUTE.
Example 1.26. t_reply_with_body usage
...
if(is_method("INVITE"))
{
append_to_reply("Contact: $var(contact)\r\n"
"Content-Type: application/sdp\r\n");
t_reply_with_body("200", "Ok", "$var(body)");
exit;
}
...
1.4.5. t_newtran()
Creates the SIP transaction for the currently processed SIP
request, thus switching to stateful processing. For INVITE
requests, a 100 Trying reply will be immediately sent, unless
auto_100trying is disabled. Once a SIP transaction is created,
calling t_newtran() for retransmitted requests will end the
OpenSIPS script execution, with the lastly sent reply being
retransmitted upstream.
This function can be used from REQUEST_ROUTE.
Example 1.27. t_newtran usage
...
t_newtran(); # 100 Trying is fired here
xlog("doing my complicated routing logic\n");
....
t_relay(); # send the call further
...
1.4.6. t_check_trans()
Returns true if the current request is associated to a
transaction. The relationship between the request and
transaction is defined as follows:
* non-CANCEL/non-ACK requests - if the request belongs to a
transaction (it's a retransmision), the function will do a
standard processing of the retransmission and will
break/stop the script. The function returns false if the
request is not a retransmission.
* CANCEL request - true if the cancelled INVITE transaction
exists.
* ACK request - true if the ACK is a hop-by-hop ACK (to a
negative reply) corresponding to an previous INVITE
transaction. IMPORTANT: this function returns false (return
code -2) for end-to-end ACKs (to 2xx replies from a
different transaction).
Note: To detect retransmissions using this function you have to
make sure that the initial request has already created a
transaction, e.g. by using t_relay(). If the processing of
requests may take long time (e.g. DB lookups) and the
retransmission arrives before t_relay() is called, you can use
the t_newtran() function to manually create a transaction.
This function can be used from REQUEST_ROUTE and BRANCH_ROUTE.
Example 1.28. t_check_trans usage
...
if ( is_method("CANCEL") ) {
if ( t_check_trans() )
t_relay();
exit;
}
...
1.4.7. t_check_status(re)
Returns true if the regualr expression “re” match the reply
code of the response message as follows:
* in routing block - the code of the last sent reply.
* in on_reply block - the code of the current received reply.
* in on_failure block - the code of the selected negative
final reply.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
FAILURE_ROUTE and BRANCH_ROUTE .
Example 1.29. t_check_status usage
...
if (t_check_status("(487)|(408)")) {
log("487 or 408 negative reply\n");
}
...
1.4.8. t_local_replied(reply)
Returns true if all or last (depending of the parameter)
reply(es) were local generated (and not received).
Parameter may be “all” or “last”.
This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
FAILURE_ROUTE and ONREPLY_ROUTE.
Example 1.30. t_local_replied usage
...
if (t_local_replied("all")) {
log ("no reply received\n");
}
...
1.4.9. t_was_cancelled()
Retuns true if called for an INVITE transaction that was
explicitly cancelled by UAC side via a CANCEL request.
This function can be used from ONREPLY_ROUTE, FAILURE_ROUTE.
Example 1.31. t_was_cancelled usage
...
if (t_was_cancelled()) {
log("transaction was cancelled by UAC\n");
}
...
1.4.10. t_cancel_branch([flags])
This function is to be call when a reply is received for
cancelling a set of branches (see flags) of the current call.
Meaning of the parameters is as follows:
* flags - (optional) - set of flags (char based flags) to
control what branches to be cancelled:
+ a - all - cancel all pending branches
+ o - others - cancel all the other pending branches
except the current one
+ empty - current - cancel only the current branch
This function can be used from ONREPLY_ROUTE.
Example 1.32. t_cancel_branch usage
onreply_route[3] {
...
if (t_check_status("183")) {
# no support for early media
t_cancel_branch();
}
...
}
1.4.11. t_new_request(method,RURI,from,to[,body[,ctx]])