|
|
@@ -1,2 +1,1822 @@
|
|
|
+1. TM Module
|
|
|
|
|
|
+Jiri Kuthan
|
|
|
|
|
|
+ FhG FOKUS
|
|
|
+
|
|
|
+Juha Heinanen
|
|
|
+
|
|
|
+ <[email protected]>
|
|
|
+
|
|
|
+ Copyright © 2003 FhG FOKUS
|
|
|
+
|
|
|
+ Copyright © 2008 Juha Heinanen
|
|
|
+ Revision History
|
|
|
+ Revision $Revision$ $Date$
|
|
|
+ __________________________________________________________________
|
|
|
+
|
|
|
+ 1.1. Overview
|
|
|
+ 1.2. Known Issues
|
|
|
+ 1.3. Parameters
|
|
|
+
|
|
|
+ 1.3.1. fr_timer (integer)
|
|
|
+ 1.3.2. fr_inv_timer (integer)
|
|
|
+ 1.3.3. max_inv_lifetime (integer)
|
|
|
+ 1.3.4. max_noninv_lifetime (integer)
|
|
|
+ 1.3.5. wt_timer (integer)
|
|
|
+ 1.3.6. delete_timer (integer)
|
|
|
+ 1.3.7. retr_timer1 (integer)
|
|
|
+ 1.3.8. retr_timer2 (integer)
|
|
|
+ 1.3.9. noisy_ctimer (integer)
|
|
|
+ 1.3.10. restart_fr_on_each_reply (integer)
|
|
|
+ 1.3.11. auto_inv_100 (integer)
|
|
|
+ 1.3.12. auto_inv_100_reason (string)
|
|
|
+ 1.3.13. unix_tx_timeout (integer)
|
|
|
+ 1.3.14. aggregate_challenges (integer)
|
|
|
+ 1.3.15. reparse_invite (integer)
|
|
|
+ 1.3.16. ac_extra_hdrs (string)
|
|
|
+ 1.3.17. blst_503 (integer)
|
|
|
+ 1.3.18. blst_503_def_timeout (integer)
|
|
|
+ 1.3.19. blst_503_min_timeout (integer)
|
|
|
+ 1.3.20. blst_503_max_timeout (integer)
|
|
|
+ 1.3.21. blst_methods_add (unsigned integer)
|
|
|
+ 1.3.22. blst_methods_lookup (unsigned integer)
|
|
|
+ 1.3.23. cancel_b_method (integer)
|
|
|
+ 1.3.24. reparse_on_dns_failover (integer)
|
|
|
+ 1.3.25. on_sl_reply (string)
|
|
|
+ 1.3.26. fr_inv_timer_next (integer)
|
|
|
+ 1.3.27. contacts_avp (string)
|
|
|
+ 1.3.28. fr_timer_avp (string)
|
|
|
+ 1.3.29. fr_inv_timer_avp (string)
|
|
|
+ 1.3.30. unmatched_cancel (string)
|
|
|
+ 1.3.31. ruri_matching (integer)
|
|
|
+ 1.3.32. via1_matching (integer)
|
|
|
+ 1.3.33. pass_provisional_replies (integer)
|
|
|
+ 1.3.34. default_code (integer)
|
|
|
+ 1.3.35. default_reason (string)
|
|
|
+ 1.3.36. disable_6xx_block (integer)
|
|
|
+
|
|
|
+ 1.4. Functions
|
|
|
+
|
|
|
+ 1.4.1. t_relay_to_udp(ip, port), t_relay_to_udp(),
|
|
|
+ t_relay_to_tcp(ip, port) t_relay_to_tcp()
|
|
|
+ t_relay_to_tls(ip, port) t_relay_to_tls()
|
|
|
+ t_relay_to_sctp(ip, port) t_relay_to_sctp()
|
|
|
+
|
|
|
+ 1.4.2. t_relay() t_relay(host, port)
|
|
|
+ 1.4.3. t_on_failure(failure_route)
|
|
|
+ 1.4.4. t_on_reply(onreply_route)
|
|
|
+ 1.4.5. t_on_branch(branch_route)
|
|
|
+ 1.4.6. append_branch()
|
|
|
+ 1.4.7. t_newtran()
|
|
|
+ 1.4.8. t_reply(code, reason_phrase)
|
|
|
+ 1.4.9. t_lookup_request()
|
|
|
+ 1.4.10. t_retransmit_reply()
|
|
|
+ 1.4.11. t_release()
|
|
|
+ 1.4.12. t_forward_nonack() t_forward_nonack(ip, port)
|
|
|
+ t_forward_nonack_udp(ip, port) t_forward_nonack_tcp(ip,
|
|
|
+ port) t_forward_nonack_tls(ip, port)
|
|
|
+ t_forward_nonack_sctp(ip, port)
|
|
|
+
|
|
|
+ 1.4.13. t_set_fr(fr_inv_timeout [, fr_timeout])
|
|
|
+ 1.4.14. t_reset_fr()
|
|
|
+ 1.4.15. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
|
|
|
+ 1.4.16. t_reset_max_lifetime()
|
|
|
+ 1.4.17. t_set_retr(retr_t1_interval, retr_t2_interval)
|
|
|
+ 1.4.18. t_reset_retr()
|
|
|
+ 1.4.19. t_set_auto_inv_100(0|1)
|
|
|
+ 1.4.20. t_branch_timeout()
|
|
|
+ 1.4.21. t_branch_replied()
|
|
|
+ 1.4.22. t_any_timeout()
|
|
|
+ 1.4.23. t_any_replied()
|
|
|
+ 1.4.24. t_grep_status("code")
|
|
|
+ 1.4.25. t_is_canceled()
|
|
|
+ 1.4.26. t_is_expired()
|
|
|
+ 1.4.27. t_relay_cancel()
|
|
|
+ 1.4.28. t_lookup_cancel(), t_lookup_cancel(1)
|
|
|
+ 1.4.29. t_drop_replies()
|
|
|
+ 1.4.30. t_save_lumps()
|
|
|
+ 1.4.31. t_load_contacts()
|
|
|
+ 1.4.32. t_next_contacts()
|
|
|
+ 1.4.33. t_check_trans()
|
|
|
+ 1.4.34. t_set_disable_6xx(0|1)
|
|
|
+ 1.4.35. t_set_disable_failover(0|1)
|
|
|
+
|
|
|
+ 1.5. TM Module API
|
|
|
+
|
|
|
+ 1.5.1. Defines
|
|
|
+ 1.5.2. Functions
|
|
|
+
|
|
|
+ 1.5.2.1. register_tmcb(cb_type, cb_func)
|
|
|
+ 1.5.2.2. load_tm(*import_structure)
|
|
|
+ 1.5.2.3. int t_suspend(struct sip_msg *msg, unsigned int
|
|
|
+ *hash_index, unsigned int *label)
|
|
|
+
|
|
|
+ 1.5.2.4. int t_continue(unsigned int hash_index, unsigned
|
|
|
+ int label, struct action *route)
|
|
|
+
|
|
|
+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, there are these 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 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.
|
|
|
+
|
|
|
+Note
|
|
|
+
|
|
|
+ Several Kamailio (OpenSER) TM module functionalities are now
|
|
|
+ implemented in the TMX module: "modules_k/tmx". Check it to see if what
|
|
|
+ you are looking for is there.
|
|
|
+
|
|
|
+1.2. Known Issues
|
|
|
+
|
|
|
+ * Possibly, performance could be improved by not parsing non-INVITEs,
|
|
|
+ as they do not be replied with 100, and do not result in
|
|
|
+ ACK/CANCELs, and other things which take parsing. However, we need
|
|
|
+ to rethink whether we don't need parsed headers later for something
|
|
|
+ else. Remember, when we now conserver a request in sh_mem, we can't
|
|
|
+ apply any pkg_mem operations to it any more. (that might be
|
|
|
+ redesigned too).
|
|
|
+ * Another performance improvement may be achieved by not parsing CSeq
|
|
|
+ in replies until reply branch matches branch of an INVITE/CANCEL in
|
|
|
+ transaction table.
|
|
|
+ * t_replicate should be done more cleanly--Vias, Routes, etc. should
|
|
|
+ be removed from a message prior to replicating it (well, does not
|
|
|
+ matter any longer so much as there is a new replication module).
|
|
|
+
|
|
|
+1.3. Parameters
|
|
|
+
|
|
|
+ Revision History
|
|
|
+ Revision $Revision$ $Date$
|
|
|
+
|
|
|
+1.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. Set fr_timer parameter
|
|
|
+...
|
|
|
+modparam("tm", "fr_timer", 10000)
|
|
|
+...
|
|
|
+
|
|
|
+1.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 2. Set fr_inv_timer parameter
|
|
|
+...
|
|
|
+modparam("tm", "fr_inv_timer", 180000)
|
|
|
+...
|
|
|
+
|
|
|
+1.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 then 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 3. Set max_inv_lifetime parameter
|
|
|
+...
|
|
|
+modparam("tm", "max_inv_lifetime", 150000)
|
|
|
+...
|
|
|
+
|
|
|
+1.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 maximum:
|
|
|
+ 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 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 4. Set max_noninv_lifetime parameter
|
|
|
+...
|
|
|
+modparam("tm", "max_inv_lifetime", 30000)
|
|
|
+...
|
|
|
+
|
|
|
+1.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 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).
|
|
|
+
|
|
|
+ Default value is 5000 ms (5 seconds).
|
|
|
+
|
|
|
+ Example 5. Set wt_timer parameter
|
|
|
+...
|
|
|
+modparam("tm", "wt_timer", 1000)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.6. delete_timer (integer)
|
|
|
+
|
|
|
+ Time after which a to-be-deleted transaction currently ref-ed by a
|
|
|
+ process will be tried to be deleted again (in milliseconds).
|
|
|
+
|
|
|
+ Note: this parameter is obsolete for ser 2.1 (in 2.1 the transaction is
|
|
|
+ deleted the moment it's not referenced anymore).
|
|
|
+
|
|
|
+ Default value is 200 milliseconds.
|
|
|
+
|
|
|
+ Example 6. Set delete_timer parameter
|
|
|
+...
|
|
|
+modparam("tm", "delete_timer", 100)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.7. retr_timer1 (integer)
|
|
|
+
|
|
|
+ Initial retransmission period (in milliseconds).
|
|
|
+
|
|
|
+ Default value is 500 milliseconds.
|
|
|
+
|
|
|
+ Example 7. Set retr_timer1 parameter
|
|
|
+...
|
|
|
+modparam("tm", "retr_timer1", 1000)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.8. 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 8. Set retr_timer2 parameter
|
|
|
+...
|
|
|
+modparam("tm", "retr_timer2", 2000)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.9. 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 acc
|
|
|
+ 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 9. Set noisy_ctimer parameter
|
|
|
+...
|
|
|
+modparam("tm", "noisy_ctimer", 1)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.10. 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 10. Set restart_fr_on_each_reply parameter
|
|
|
+...
|
|
|
+modparam("tm", "restart_fr_on_each_reply", 0)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.11. auto_inv_100 (integer)
|
|
|
+
|
|
|
+ If set (default) tm will automatically send and 100 reply to INVITEs.
|
|
|
+
|
|
|
+ Setting it to 0 one can be used to enable doing first 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 11. Set auto_inv_100 parameter
|
|
|
+...
|
|
|
+modparam("tm", "auto_inv_100", 0)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.12. auto_inv_100_reason (string)
|
|
|
+
|
|
|
+ Set reason text of the automatically send 100 to an INVITE.
|
|
|
+
|
|
|
+ Default value is "trying -- your call is important to us".
|
|
|
+
|
|
|
+ See also: auto_inv_100.
|
|
|
+
|
|
|
+ Example 12. Set auto_inv_100_reason parameter
|
|
|
+...
|
|
|
+modparam("tm", "auto_inv_100_reason", "Trying")
|
|
|
+...
|
|
|
+
|
|
|
+1.3.13. 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 then unix_tx_timeout, the send
|
|
|
+ will fail.
|
|
|
+
|
|
|
+ The default value is 500 milliseconds.
|
|
|
+
|
|
|
+ Example 13. Set unix_tx_timeout parameter
|
|
|
+...
|
|
|
+modparam("tm", "unix_tx_timeout", 250)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.14. aggregate_challenges (integer)
|
|
|
+
|
|
|
+ If set (default), the final reply is a 401 or a 407 and more then 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 reply. If only one branch received the
|
|
|
+ winning 401 or 407 then this reply will be forwarded (no new one will
|
|
|
+ be built). If 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 rfc3261).
|
|
|
+
|
|
|
+ Example 14. Set aggregate_challenges parameter
|
|
|
+...
|
|
|
+modparam("tm", "aggregate_challenges", 0)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.15. 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 SER 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.
|
|
|
+
|
|
|
+ - SER 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 15. Set reparse_invite parameter
|
|
|
+...
|
|
|
+modparam("tm", "reparse_invite", 0)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.16. 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 16. Set ac_extra_hdrs parameter
|
|
|
+...
|
|
|
+modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
|
|
|
+...
|
|
|
+
|
|
|
+1.3.17. blst_503 (integer)
|
|
|
+
|
|
|
+ If set and the blacklist support is enabled, every 503 reply source is
|
|
|
+ added to the blacklist. The initial blacklist timeout (or ttl) depends
|
|
|
+ on the presence of a Retry-After header in the reply and the values of
|
|
|
+ the following tm parameters: blst_503_def_timeout, blst_503_min_timeout
|
|
|
+ and blst_503_max_timeout.
|
|
|
+
|
|
|
+ WARNING:blindly allowing 503 blacklisting could be very easily
|
|
|
+ exploited for DOS attacks in most network setups.
|
|
|
+
|
|
|
+ The default value is 0 (disabled due to the reasons above).
|
|
|
+
|
|
|
+ Example 17. Set blst_503 parameter
|
|
|
+...
|
|
|
+modparam("tm", "blst_503", 1)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.18. blst_503_def_timeout (integer)
|
|
|
+
|
|
|
+ Blacklist interval in seconds for a 503 reply with no Retry-After
|
|
|
+ header. See also blst_503, blst_503_min_timeout and
|
|
|
+ blst_503_max_timeout.
|
|
|
+
|
|
|
+ The default value is 0, which means that if no Retry-After header is
|
|
|
+ present, the 503 reply source will not be blacklisted (rfc conformant
|
|
|
+ behaviour).
|
|
|
+
|
|
|
+ Example 18. Set blst_503_def_timeout parameter
|
|
|
+...
|
|
|
+modparam("tm", "blst_503_def_timeout", 120)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.19. blst_503_min_timeout (integer)
|
|
|
+
|
|
|
+ Minimum blacklist interval in seconds for a 503 reply with a
|
|
|
+ Retry-After header. It will be used if the Retry-After value is
|
|
|
+ smaller. See also blst_503, blst_503_def_timeout and
|
|
|
+ blst_503_max_timeout.
|
|
|
+
|
|
|
+ The default value is 0
|
|
|
+
|
|
|
+ Example 19. Set blst_503_min_timeout parameter
|
|
|
+...
|
|
|
+modparam("tm", "blst_503_min_timeout", 30)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.20. blst_503_max_timeout (integer)
|
|
|
+
|
|
|
+ Maximum blacklist interval in seconds for a 503 reply with a
|
|
|
+ Retry-After header. It will be used if the Retry-After value is
|
|
|
+ greater. See also blst_503, blst_503_def_timeout and
|
|
|
+ blst_503_min_timeout.
|
|
|
+
|
|
|
+ The default value is 3600
|
|
|
+
|
|
|
+ Example 20. Set blst_503_max_timeout parameter
|
|
|
+...
|
|
|
+modparam("tm", "blst_503_max_timeout", 604800)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.21. blst_methods_add (unsigned integer)
|
|
|
+
|
|
|
+ Bitmap of method types that trigger blacklisting on transaction
|
|
|
+ timeouts. (This setting has no effect on blacklisting because of send
|
|
|
+ failures.)
|
|
|
+
|
|
|
+ The following values are associated to the request methods: INVITE=1,
|
|
|
+ CANCEL=2, ACK=4 (not retransmitted, thus, never times-out), BYE=8,
|
|
|
+ INFO=16, REGISTER=32, SUBSCRIBE=64, NOTIFY=126, OTHER=256 (all the
|
|
|
+ unknown types). Check parser/msg_parser.h for farther details.
|
|
|
+
|
|
|
+ Change the value carefully, because requests not having provisional
|
|
|
+ response (everything but INVITE) can easily cause the next hop to be
|
|
|
+ inserted into the blacklist by mistake. For exmaple the next hop is a
|
|
|
+ proxy, it is alive, but waiting for the response of the UAS, and has
|
|
|
+ higher fr_timer value.
|
|
|
+
|
|
|
+ The default value is 1, only INVITEs trigger blacklisting
|
|
|
+
|
|
|
+ Example 21. Set blst_methods_add parameter
|
|
|
+...
|
|
|
+# INVITEs and REGISTERs trigger blacklisting
|
|
|
+modparam("tm", "blst_methods_add", 33)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.22. blst_methods_lookup (unsigned integer)
|
|
|
+
|
|
|
+ Bitmap of method types that are looked-up in the blacklist before
|
|
|
+ statefull forwarding. See also blst_methods_add
|
|
|
+
|
|
|
+ The default value is 4294967287, every method type except BYE. (We try
|
|
|
+ to deliver BYEs no matter what)
|
|
|
+
|
|
|
+ Example 22. Set blst_methods_lookup parameter
|
|
|
+...
|
|
|
+# lookup only INVITEs
|
|
|
+modparam("tm", "blst_methods_lookup", 1)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.23. cancel_b_method (integer)
|
|
|
+
|
|
|
+ Method used when attempting to CANCEL an unreplied transaction branch
|
|
|
+ (a branch where no reply greater the 99 was received). The possible
|
|
|
+ values are 0, 1, and 2.
|
|
|
+
|
|
|
+ 0 will immediately stop the request (INVITE) retransmission on the
|
|
|
+ branch and it will behave as if the branch was immediately replied with
|
|
|
+ a 487 (a fake internal 487 reply). The advantage is the unreplied
|
|
|
+ branches will be terminated immediately. However it introduces a race
|
|
|
+ risk with a possible slightly delayed 2xx reply. In this case we could
|
|
|
+ have an UA receiving a 2xx after a 487. Moreover this risk is greatly
|
|
|
+ amplified by packet loss (e.g. if an 180 is lost the branch will look
|
|
|
+ as unreplied and a CANCEL will silently drop the branch, but a 2xx can
|
|
|
+ still come at a later time). This is the behaviour for ser versions
|
|
|
+ older then 2.1.
|
|
|
+
|
|
|
+ 1 will keep retransmitting the request on unreplied branches. If a
|
|
|
+ provisional answer is later received a CANCEL will be immediately sent
|
|
|
+ back (attempting to quickly trigger a 487). This approach is race free
|
|
|
+ and avoids the 2xx after 487 problem, but it's more resource intensive:
|
|
|
+ faced with a branch towards and UA that doesn't answer, a CANCEL
|
|
|
+ attempt will keep the transaction alive for the whole timeout interval
|
|
|
+ (fr_timer).
|
|
|
+
|
|
|
+ 2 will send and retransmit CANCEL even on unreplied branches, stopping
|
|
|
+ the request retransmissions. This has the same advantages as 1 and also
|
|
|
+ avoids the extra roundtrip in the case of the provisional reply, but
|
|
|
+ it's not RFC 3261 conforming (the RFC allows sending CANCELs only on
|
|
|
+ pending branches).
|
|
|
+
|
|
|
+ The default value is 1.
|
|
|
+
|
|
|
+ Example 23. Set cancel_b_method parameter
|
|
|
+...
|
|
|
+modparam("tm", "cancel_b_method", 1)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.24. reparse_on_dns_failover (integer)
|
|
|
+
|
|
|
+ If set to 1, the SIP message after a DNS failover is constructed from
|
|
|
+ the outgoing message buffer of the failed branch instead of from the
|
|
|
+ received request.
|
|
|
+
|
|
|
+ It must be set if multiple branches are installed, the SIP message is
|
|
|
+ modified differently in them, and at least one of them can result in
|
|
|
+ DNS failover. If the parameter is not set the per-branch modifications
|
|
|
+ are lost after the failover.
|
|
|
+
|
|
|
+ Note: If the parameter is set, branch route block and
|
|
|
+ TMCB_REQUEST_FWDED callback are not called in case of the failover.
|
|
|
+
|
|
|
+ Disadvantage: only the via header is replaced in the message buffer, so
|
|
|
+ the outgoing socket address is not corrected in any other part of the
|
|
|
+ message. It is dangerous on multihomed hosts: when the new SIP request
|
|
|
+ after the DNS failover is sent via different interface than the first
|
|
|
+ request, the message can contain incorrect ip address in the
|
|
|
+ Record-Route header for instance.
|
|
|
+
|
|
|
+ Default value is 1.
|
|
|
+
|
|
|
+ Example 24. Set reparse_on_dns_failover parameter
|
|
|
+...
|
|
|
+modparam("tm", "reparse_on_dns_failover", 0)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.25. on_sl_reply (string)
|
|
|
+
|
|
|
+ Sets reply route block, to which control is passed when a reply is
|
|
|
+ received that has no associated transaction. The reply is passed to the
|
|
|
+ core for stateless forwarding after the route block execution unless it
|
|
|
+ returns 0.
|
|
|
+
|
|
|
+ Example 25. Set on_sl_reply parameter
|
|
|
+...
|
|
|
+modparam("tm", "on_sl_reply", "stateless_replies")
|
|
|
+...
|
|
|
+
|
|
|
+onreply_route["stateless_replies"] {
|
|
|
+ # do not allow stateless replies to be forwarded
|
|
|
+ return 0;
|
|
|
+}
|
|
|
+
|
|
|
+1.3.26. fr_inv_timer_next (integer)
|
|
|
+
|
|
|
+ Value of the Final Response timeout for INVITE transactions to be used
|
|
|
+ during serial forwarding:
|
|
|
+
|
|
|
+ Function t_next_contacts() sets fr_inv_timer to fr_inv_timer_next value
|
|
|
+ if, after t_next_contacts() is called, there are still lower qvalue
|
|
|
+ contacts available, and to fr_inv_timer value if there are not.
|
|
|
+
|
|
|
+ Default value is 30.
|
|
|
+
|
|
|
+ Example 26. Set fr_inv_timer_next parameter
|
|
|
+...
|
|
|
+modparam("tm", "fr_inv_timer_next", 10)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.27. contacts_avp (string)
|
|
|
+
|
|
|
+ Internal AVP that t_load_contacts() function uses to store contacts of
|
|
|
+ the destination set and that t_next_contacts() function uses to restore
|
|
|
+ those contacts.
|
|
|
+
|
|
|
+ Default value is "NULL" (t_load_contacts()/t_next_contacts() functions
|
|
|
+ are disabled).
|
|
|
+
|
|
|
+ Example 27. Set contacts_avp parameter
|
|
|
+...
|
|
|
+modparam("tm", "contacts_avp", "$avp(i:25)")
|
|
|
+...
|
|
|
+
|
|
|
+1.3.28. fr_timer_avp (string)
|
|
|
+
|
|
|
+ The value of fr_timer timer can be overriden on per-transaction basis.
|
|
|
+ The administrator can provide a value to be used for a particular
|
|
|
+ transaction in an AVP. This parameter contains the name of the AVP that
|
|
|
+ will be checked. If the AVP exists then its value will be used for the
|
|
|
+ fr_timer timer, effectively overriding the value configured in fr_timer
|
|
|
+ parameter for the current transaction.
|
|
|
+
|
|
|
+ The value of this parameter is the the name of the AVP to be checked,
|
|
|
+ without the $ character or "$avp" prefix.
|
|
|
+
|
|
|
+Note
|
|
|
+
|
|
|
+ The value of the AVP is expected to be expressed in seconds and not
|
|
|
+ milliseconds (unlike the rest of the timers).
|
|
|
+
|
|
|
+ This parameter is kept for backwards compatibility (hence its value
|
|
|
+ expressed in seconds instead of milliseconds and its arcane way of
|
|
|
+ specifying the avps). The recommended replacement is using t_set_fr()
|
|
|
+ on a per transaction basis.
|
|
|
+
|
|
|
+ See also: t_set_fr(), fr_timer.
|
|
|
+
|
|
|
+ Example 28. Set fr_timer_avp parameter
|
|
|
+...
|
|
|
+modparam("tm", "fr_timer_avp", "i:708")
|
|
|
+...
|
|
|
+
|
|
|
+1.3.29. fr_inv_timer_avp (string)
|
|
|
+
|
|
|
+ The value of fr_inv_timer timer can be overriden on per-transaction
|
|
|
+ basis. The administrator can provide a value to be used for a
|
|
|
+ particular transaction in an AVP. This parameter contains the name of
|
|
|
+ the AVP that will be checked. If the AVP exists, is non-empty and
|
|
|
+ non-zero then its value will be used for the fr_inv_timer timer,
|
|
|
+ effectively overriding the value configured in fr_inv_timer parameter
|
|
|
+ for the current transaction.
|
|
|
+
|
|
|
+ The value of this parameter is the the name of the AVP to be checked,
|
|
|
+ without the $ character or "$avp" prefix.
|
|
|
+
|
|
|
+Note
|
|
|
+
|
|
|
+ The value of the AVP is expected to be expressed in seconds and not
|
|
|
+ milliseconds (unlike the rest of the timers).
|
|
|
+
|
|
|
+ This parameter is kept for backwards compatibility (hence its value
|
|
|
+ expressed in seconds instead of milliseconds and its arcane way of
|
|
|
+ specifying the avps). The recommended replacement is using t_set_fr()
|
|
|
+ on a per transaction basis.
|
|
|
+
|
|
|
+ See also: t_set_fr(), fr_inv_timer.
|
|
|
+
|
|
|
+ Example 29. Set fr_inv_timer_avp parameter
|
|
|
+...
|
|
|
+modparam("tm", "fr_inv_timer_avp", "my_fr_inv_timer")
|
|
|
+...
|
|
|
+
|
|
|
+1.3.30. unmatched_cancel (string)
|
|
|
+
|
|
|
+ This parameter selects between forwarding CANCELs that do not match any
|
|
|
+ transaction statefully (0, default value), statelessly (1) or dropping
|
|
|
+ them (2). Note that the statefull forwarding has an additional hidden
|
|
|
+ advantage: tm will be able to recognize INVITEs that arrive after their
|
|
|
+ CANCEL. Note also that this feature could be used to try a memory
|
|
|
+ exhaustion DOS attack against a proxy that authenticates all requests,
|
|
|
+ by continuously flooding the victim with CANCELs to random destinations
|
|
|
+ (since the CANCEL cannot be authenticated, each received bogus CANCEL
|
|
|
+ will create a new transaction that will live by default 30s).
|
|
|
+
|
|
|
+ Default value is 0.
|
|
|
+
|
|
|
+ Example 30. Set unmatched_cancel parameter
|
|
|
+...
|
|
|
+modparam("tm", "unmatched_cancel", "2")
|
|
|
+...
|
|
|
+
|
|
|
+1.3.31. ruri_matching (integer)
|
|
|
+
|
|
|
+ If set it will also try to match the request uri when doing pre-3261
|
|
|
+ transaction matching (the via branch parameter does not contain the
|
|
|
+ 3261 cookie).
|
|
|
+
|
|
|
+ The only reason to have it not set is for interoperability with old,
|
|
|
+ broken implementations.
|
|
|
+
|
|
|
+ Default value is 1 (on).
|
|
|
+
|
|
|
+ Can be set at runtime, e.g.:
|
|
|
+ $ sercmd cfg.set_now_int tm ruri_matching 0
|
|
|
+
|
|
|
+ Example 31. Set ruri_matching parameter
|
|
|
+...
|
|
|
+modparam("tm", "ruri_matching", 1)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.32. via1_matching (integer)
|
|
|
+
|
|
|
+ If set it will also try to match the topmost via when doing pre-3261
|
|
|
+ transaction matching (the via branch parameter does not contain the
|
|
|
+ 3261 cookie).
|
|
|
+
|
|
|
+ The only reason to have it not set is for interoperability with old,
|
|
|
+ broken implementations.
|
|
|
+
|
|
|
+ Default value is 1 (on).
|
|
|
+
|
|
|
+ Can be set at runtime, e.g.:
|
|
|
+ $ sercmd cfg.set_now_int tm via1_matching 0
|
|
|
+
|
|
|
+ Example 32. Set via1_matching parameter
|
|
|
+...
|
|
|
+modparam("tm", "via1_matching", 1)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.33. pass_provisional_replies (integer)
|
|
|
+
|
|
|
+ If set, TMCB_LOCAL_REPONSE_OUT tm registered callbacks will be called
|
|
|
+ also for provisional replies.
|
|
|
+
|
|
|
+ Default value is 0 (off).
|
|
|
+
|
|
|
+ Can be set at runtime, e.g.:
|
|
|
+ $ sercmd cfg.set_now_int tm pass_provisional_replies 1
|
|
|
+
|
|
|
+ Example 33. Set pass_provisional_replies parameter
|
|
|
+...
|
|
|
+modparam("tm", "pass_provisional_replies", 1)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.34. default_code (integer)
|
|
|
+
|
|
|
+ Default response code sent by t_reply() if it cannot retrieve its
|
|
|
+ parameters (e.g. inexistent avp). Valid values are between 400 and 699.
|
|
|
+
|
|
|
+ Default value is 500.
|
|
|
+
|
|
|
+ Can be set at runtime, e.g.:
|
|
|
+ $ sercmd cfg.set_now_int tm default_code 505
|
|
|
+
|
|
|
+ Example 34. Set default_code parameter
|
|
|
+...
|
|
|
+modparam("tm", "default_code", 501)
|
|
|
+...
|
|
|
+
|
|
|
+1.3.35. default_reason (string)
|
|
|
+
|
|
|
+ Default SIP reason phrase sent by t_reply() if it cannot retrieve its
|
|
|
+ parameters (e.g. inexistent avp).
|
|
|
+
|
|
|
+ Default value is "Server Internal Error".
|
|
|
+
|
|
|
+ Can be set at runtime, e.g.:
|
|
|
+ $ sercmd cfg.set_now_string tm default_reason "Unknown error"
|
|
|
+
|
|
|
+ Example 35. Set default_reason parameter
|
|
|
+...
|
|
|
+modparam("tm", "default_reason", "Unknown reason")
|
|
|
+...
|
|
|
+
|
|
|
+1.3.36. disable_6xx_block (integer)
|
|
|
+
|
|
|
+ If set tm will treat all the 6xx replies like normal replies (warning:
|
|
|
+ this would be non-rfc conformant behaviour).
|
|
|
+
|
|
|
+ If not set (default) receiving a 6xx will cancel all the running
|
|
|
+ parallel branches, will stop dns failover and forking. However serial
|
|
|
+ forking using append_branch() in the failure_route will still work.
|
|
|
+
|
|
|
+ It can be overwritten on a per transaction basis using
|
|
|
+ t_set_disable_6xx().
|
|
|
+
|
|
|
+ Default value is 0 (off, rfc conformant behaviour).
|
|
|
+
|
|
|
+ Can be set at runtime, e.g.:
|
|
|
+ $ sercmd cfg.set_now_int tm disable_6xx_block 0
|
|
|
+
|
|
|
+ See also: t_set_disable_6xx().
|
|
|
+
|
|
|
+ Example 36. Set disable_6xx_block parameter
|
|
|
+...
|
|
|
+modparam("tm", "disable_6xx_block", 1)
|
|
|
+...
|
|
|
+
|
|
|
+1.4. Functions
|
|
|
+
|
|
|
+ Revision History
|
|
|
+ Revision $Revision$ $Date$
|
|
|
+
|
|
|
+1.4.1. t_relay_to_udp(ip, port), t_relay_to_udp(), t_relay_to_tcp(ip, port)
|
|
|
+t_relay_to_tcp() t_relay_to_tls(ip, port) t_relay_to_tls()
|
|
|
+t_relay_to_sctp(ip, port) t_relay_to_sctp()
|
|
|
+
|
|
|
+ Relay a message statefully using a fixed protocol either to the
|
|
|
+ specified fixed destination or to a destination derived from the
|
|
|
+ message uri (if the host address and port are not specified). These
|
|
|
+ along with t_relay are the functions most users want to use--all other
|
|
|
+ are mostly for programming. Programmers interested in writing TM logic
|
|
|
+ should review how t_relay is implemented in tm.c and how TM callbacks
|
|
|
+ work.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * ip - IP address where the message should be sent.
|
|
|
+ * port - Port number.
|
|
|
+
|
|
|
+ If no parameters are specified the message is sent to a destination
|
|
|
+ derived from the message uri (using sip sepcific DNS lookups), but with
|
|
|
+ the protocol corresponding to the function name.
|
|
|
+
|
|
|
+ Example 37. t_relay_to_udp usage
|
|
|
+...
|
|
|
+if (src_ip==10.0.0.0/8)
|
|
|
+ t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
|
|
|
+else
|
|
|
+ t_relay_to_tcp(); # relay to msg. uri, but over tcp
|
|
|
+...
|
|
|
+
|
|
|
+1.4.2. t_relay() t_relay(host, port)
|
|
|
+
|
|
|
+ Relay a message statefully either to the destination indicated in the
|
|
|
+ current URI (if called without any parameters) or to the specified host
|
|
|
+ and port. In the later case (host and port specified) the protocol used
|
|
|
+ is the same protocol on which the message was received.
|
|
|
+
|
|
|
+ t_relay() is the statefull version for forward(uri:host, uri:port)
|
|
|
+ while t_relay(host, port) is similar to forward(host, port).
|
|
|
+
|
|
|
+ In the forward to uri case (t_relay()), if the original URI was
|
|
|
+ rewritten (by UsrLoc, RR, strip/prefix, etc.) the new URI will be
|
|
|
+ taken). The destination (including the protocol) is determined from the
|
|
|
+ uri, using SIP specific DNS resolving if needed (NAPTR, SRV a.s.o
|
|
|
+ depending also on the dns options).
|
|
|
+
|
|
|
+ Returns a negative value on failure--you may still want to send a
|
|
|
+ negative reply upstream statelessly not to leave upstream UAC in lurch.
|
|
|
+
|
|
|
+ Example 38. t_relay usage
|
|
|
+...
|
|
|
+if (!t_relay())
|
|
|
+{
|
|
|
+ sl_reply_error();
|
|
|
+ break;
|
|
|
+};
|
|
|
+...
|
|
|
+
|
|
|
+1.4.3. t_on_failure(failure_route)
|
|
|
+
|
|
|
+ Sets failure routing block, to which control is passed after a
|
|
|
+ transaction completed with a negative result but before sending a final
|
|
|
+ reply. In the referred block, you can either start a new branch (good
|
|
|
+ for services such as forward_on_no_reply) or send a final reply on your
|
|
|
+ own (good for example for message silo, which received a negative reply
|
|
|
+ from upstream and wants to tell upstream "202 I will take care of it").
|
|
|
+ Note that the set of commands which are usable within failure_routes is
|
|
|
+ strictly limited to rewriting URI, initiating new branches, logging,
|
|
|
+ and sending stateful replies (t_reply). Any other commands may result
|
|
|
+ in unpredictable behavior and possible server failure. Note that
|
|
|
+ whenever failure_route is entered, uri is reset to value which it had
|
|
|
+ on relaying. If it temporarily changed during a reply_route processing,
|
|
|
+ subsequent reply_route will ignore the changed value and use again the
|
|
|
+ original one.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * failure_route - Failure route block to be called.
|
|
|
+
|
|
|
+ Example 39. t_on_failure usage
|
|
|
+...
|
|
|
+route {
|
|
|
+ t_on_failure("1");
|
|
|
+ t_relay();
|
|
|
+}
|
|
|
+
|
|
|
+failure_route[1] {
|
|
|
+ revert_uri();
|
|
|
+ setuser("voicemail");
|
|
|
+ append_branch();
|
|
|
+}
|
|
|
+...
|
|
|
+
|
|
|
+ See test/onr.cfg for a more complex example of combination of serial
|
|
|
+ with parallel forking.
|
|
|
+
|
|
|
+1.4.4. t_on_reply(onreply_route)
|
|
|
+
|
|
|
+ Sets the reply routing block, to which control is passed when a reply
|
|
|
+ for the current transaction is received. Note that the set of commands
|
|
|
+ which are usable within onreply_routes is limited.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * onreply_route - Onreply route block to be called.
|
|
|
+
|
|
|
+ Example 40. t_on_reply usage
|
|
|
+...
|
|
|
+loadmodule "/usr/local/lib/ser/modules/nathelper.so"
|
|
|
+...
|
|
|
+route {
|
|
|
+ /* if natted */
|
|
|
+ t_on_reply("1");
|
|
|
+ t_relay();
|
|
|
+}
|
|
|
+
|
|
|
+onreply_route[1] {
|
|
|
+ if (status=~ "(183)|2[0-9][0-9]"){
|
|
|
+ force_rtp_proxy();
|
|
|
+ search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=y
|
|
|
+es');
|
|
|
+ }
|
|
|
+ if (nat_uac_test("1")){
|
|
|
+ fix_nated_contact();
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.5. t_on_branch(branch_route)
|
|
|
+
|
|
|
+ Sets the branch routing block, to which control is passed after forking
|
|
|
+ (when a new branch is created). For now branch routes are intended only
|
|
|
+ for last minute changes of the SIP messages (like adding new headers).
|
|
|
+ Note that the set of commands which are usable within branch_routes is
|
|
|
+ very limited. It is not possible to drop a message or generate a reply.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * branch_route - branch route block to be called.
|
|
|
+
|
|
|
+ Example 41. t_on_branch usage
|
|
|
+...
|
|
|
+route {
|
|
|
+ t_on_branch("1");
|
|
|
+ t_relay();
|
|
|
+}
|
|
|
+
|
|
|
+branch_route[1] {
|
|
|
+ if (uri=~"sip:[0-9]+"){
|
|
|
+ append_hf("P-Warn: numeric uri\r\n");
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.6. append_branch()
|
|
|
+
|
|
|
+ Similarly to t_fork_to, it extends destination set by a new entry. The
|
|
|
+ difference is that current URI is taken as new entry.
|
|
|
+
|
|
|
+ Example 42. append_branch usage
|
|
|
+...
|
|
|
+set_user("john");
|
|
|
+t_fork();
|
|
|
+set_user("alice");
|
|
|
+t_fork();
|
|
|
+t_relay();
|
|
|
+...
|
|
|
+
|
|
|
+1.4.7. t_newtran()
|
|
|
+
|
|
|
+ Creates a new transaction, returns a negative value on error. This is
|
|
|
+ the only way a script can add a new transaction in an atomic way.
|
|
|
+ Typically, it is used to deploy a UAS.
|
|
|
+
|
|
|
+ Example 43. t_newtran usage
|
|
|
+...
|
|
|
+if (t_newtran()) {
|
|
|
+ log("UAS logic");
|
|
|
+ t_reply("999","hello");
|
|
|
+} else sl_reply_error();
|
|
|
+...
|
|
|
+
|
|
|
+ See test/uas.cfg for more examples.
|
|
|
+
|
|
|
+1.4.8. t_reply(code, reason_phrase)
|
|
|
+
|
|
|
+ Sends a stateful reply after a transaction has been established. See
|
|
|
+ t_newtran for usage.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * code - Reply code number.
|
|
|
+ * reason_phrase - Reason string.
|
|
|
+
|
|
|
+ Example 44. t_reply usage
|
|
|
+...
|
|
|
+t_reply("404", "Not found");
|
|
|
+...
|
|
|
+
|
|
|
+1.4.9. t_lookup_request()
|
|
|
+
|
|
|
+ Checks if a transaction exists. Returns a positive value if so,
|
|
|
+ negative otherwise. Most likely you will not want to use it, as a
|
|
|
+ typical application of a look-up is to introduce a new transaction if
|
|
|
+ none was found. However this is safely (atomically) done using
|
|
|
+ t_newtran.
|
|
|
+
|
|
|
+ Example 45. t_lookup_request usage
|
|
|
+...
|
|
|
+if (t_lookup_request()) {
|
|
|
+ ...
|
|
|
+};
|
|
|
+...
|
|
|
+
|
|
|
+1.4.10. t_retransmit_reply()
|
|
|
+
|
|
|
+ Retransmits a reply sent previously by UAS transaction.
|
|
|
+
|
|
|
+ Example 46. t_retransmit_reply usage
|
|
|
+...
|
|
|
+t_retransmit_reply();
|
|
|
+...
|
|
|
+
|
|
|
+1.4.11. t_release()
|
|
|
+
|
|
|
+ Remove transaction from memory (it will be first put on a wait timer to
|
|
|
+ absorb delayed messages).
|
|
|
+
|
|
|
+ Example 47. t_release usage
|
|
|
+...
|
|
|
+t_release();
|
|
|
+...
|
|
|
+
|
|
|
+1.4.12. t_forward_nonack() t_forward_nonack(ip, port)
|
|
|
+t_forward_nonack_udp(ip, port) t_forward_nonack_tcp(ip, port)
|
|
|
+t_forward_nonack_tls(ip, port) t_forward_nonack_sctp(ip, port)
|
|
|
+
|
|
|
+ mainly for internal usage--forward a non-ACK request statefully.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * ip - IP address where the message should be sent.
|
|
|
+ * port - Port number.
|
|
|
+
|
|
|
+ Example 48. t_forward_nonack usage
|
|
|
+...
|
|
|
+t_forward_nonack("1.2.3.4", "5060");
|
|
|
+...
|
|
|
+
|
|
|
+1.4.13. t_set_fr(fr_inv_timeout [, fr_timeout])
|
|
|
+
|
|
|
+ Sets the fr_inv_timeout and optionally fr_timeout for the current
|
|
|
+ transaction or for transactions created during the same script
|
|
|
+ invocation, after calling this function. If the transaction is already
|
|
|
+ created (e.g called after t_relay() or in an onreply_route) all the
|
|
|
+ branches will have their final response timeout updated on-the-fly. If
|
|
|
+ one of the parameters is 0, its value won't be changed.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * fr_inv_timeout - new final response timeout (in milliseconds) for
|
|
|
+ INVITEs. See also fr_inv_timer.
|
|
|
+ fr_timeout - new final response timeout (in milliseconds) for
|
|
|
+ non-INVITE transaction, or INVITEs which haven't received yet a
|
|
|
+ provisional response. See also fr_timer.
|
|
|
+
|
|
|
+ See also: fr_timer, fr_inv_timer, t_reset_fr().
|
|
|
+
|
|
|
+ Example 49. t_set_fr usage
|
|
|
+...
|
|
|
+route {
|
|
|
+ t_set_fr(10000); # set only fr invite timeout to 10s
|
|
|
+ t_on_branch("1");
|
|
|
+ t_relay();
|
|
|
+}
|
|
|
+
|
|
|
+branch_route[1] {
|
|
|
+ # if we are calling the pstn, extend the invite timeout to 50s
|
|
|
+ # for all the branches, and set the no-reply-received timeout to 2s
|
|
|
+ if (uri=~"sip:[0-9]+"){
|
|
|
+ t_set_fr(50000, 2000);
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.14. t_reset_fr()
|
|
|
+
|
|
|
+ Resets the fr_inv_timer and fr_timer for the current transaction to the
|
|
|
+ default values (set using the tm module parameters fr_inv_timer and
|
|
|
+ fr_timer).
|
|
|
+
|
|
|
+ It will effectively cancel any previous calls to t_set_fr for the same
|
|
|
+ transaction.
|
|
|
+
|
|
|
+ See also: fr_timer, fr_inv_timer, t_set_fr.
|
|
|
+
|
|
|
+ Example 50. t_reset_fr usage
|
|
|
+...
|
|
|
+route {
|
|
|
+...
|
|
|
+ t_reset_fr();
|
|
|
+...
|
|
|
+}
|
|
|
+
|
|
|
+1.4.15. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
|
|
|
+
|
|
|
+ Sets the maximum lifetime for the current INVITE or non-INVITE
|
|
|
+ transaction, or for transactions created during the same script
|
|
|
+ invocation, after calling this function (that's why it takes values for
|
|
|
+ both INVITE and non-INVITE). If one of the parameters is 0, its value
|
|
|
+ won't be changed.
|
|
|
+
|
|
|
+ It works as a per transaction max_inv_lifetime or max_noninv_lifetime.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * inv_lifetime - maximum INVITE transaction lifetime (in
|
|
|
+ milliseconds). See also max_inv_lifetime.
|
|
|
+ noninv_lifetime - maximum non-INVITE transaction lifetime (in
|
|
|
+ milliseconds). See also max_noninv_lifetime.
|
|
|
+
|
|
|
+ See also: max_inv_lifetime, max_noninv_lifetime, t_reset_max_lifetime.
|
|
|
+
|
|
|
+ Example 51. t_set_max_lifetime usage
|
|
|
+...
|
|
|
+route {
|
|
|
+ if (src_ip=1.2.3.4)
|
|
|
+ t_set_max_lifetime(120000, 0); # set only max_inv_lifetime to 120s
|
|
|
+ else
|
|
|
+ t_set_max_lifetime(90000, 15000); # set the maximum lifetime to 90s if
|
|
|
+ # the current transaction is an
|
|
|
+ # INVITE and to 15s if not
|
|
|
+}
|
|
|
+
|
|
|
+1.4.16. t_reset_max_lifetime()
|
|
|
+
|
|
|
+ Resets the the maximum lifetime for the current INVITE or non-INVITE
|
|
|
+ transaction to the default value (set using the tm module parameter
|
|
|
+ max_inv_lifetime or max_noninv_lifetime).
|
|
|
+
|
|
|
+ It will effectively cancel any previous calls to t_set_max_lifetime for
|
|
|
+ the same transaction.
|
|
|
+
|
|
|
+ See also: max_inv_lifetime, max_noninv_lifetime, t_set_max_lifetime.
|
|
|
+
|
|
|
+ Example 52. t_reset_max_lifetime usage
|
|
|
+...
|
|
|
+route {
|
|
|
+...
|
|
|
+ t_reset_max_lifetime();
|
|
|
+...
|
|
|
+}
|
|
|
+
|
|
|
+1.4.17. t_set_retr(retr_t1_interval, retr_t2_interval)
|
|
|
+
|
|
|
+ Sets the retr_t1_interval and retr_t2_interval for the current
|
|
|
+ transaction or for transactions created during the same script
|
|
|
+ invocation, after calling this function. If one of the parameters is 0,
|
|
|
+ it's value won't be changed. If the transaction is already created (e.g
|
|
|
+ called after t_relay() or in an onreply_route) all the existing
|
|
|
+ branches will have their retransmissions intervals updated on-the-fly:
|
|
|
+ if the retransmission interval for the branch has not yet reached T2
|
|
|
+ the interval will be reset to retr_t1_interval, else to
|
|
|
+ retr_t2_interval. Note that the change will happen after the current
|
|
|
+ interval expires (after the next retransmission, the next-next
|
|
|
+ retransmission will take place at retr_t1_interval or
|
|
|
+ retr_t2_interval). All new branches of the same transaction will start
|
|
|
+ with the new values. This function will work even if it's called in the
|
|
|
+ script before a transaction creating function (e.g.: t_set_retr(500,
|
|
|
+ 4000); t_relay()). All new transaction created after this function
|
|
|
+ call, during the same script invocation will use the new values. Note
|
|
|
+ that this function will work only if tm is compile with
|
|
|
+ -DTM_DIFF_RT_TIMEOUT (which increases every transaction size with 4
|
|
|
+ bytes).
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * retr_t1_interval - new T1 retransmission interval (in
|
|
|
+ milliseconds). See also retr_t1_timeout.
|
|
|
+ retr_t2_interval - new T2 (or maximum) retransmission interval (in
|
|
|
+ milliseconds). See also retr_t2_timeout.
|
|
|
+
|
|
|
+ See also: retr_timer1, retr_timer2, t_reset_retr().
|
|
|
+
|
|
|
+ Example 53. t_set_retr usage
|
|
|
+...
|
|
|
+route {
|
|
|
+ t_set_retr(250, 0); # set only T1 to 250 ms
|
|
|
+ t_on_branch("1");
|
|
|
+ t_relay();
|
|
|
+}
|
|
|
+
|
|
|
+branch_route[1] {
|
|
|
+ # if we are calling the a remote pstn, extend T1 and decrease T2
|
|
|
+ # for all the branches
|
|
|
+ if (uri=~"sip:[0-9]+"){
|
|
|
+ t_set_retr(500, 2000);
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.18. t_reset_retr()
|
|
|
+
|
|
|
+ Resets the retr_timer1 and retr_timer2 for the current transaction to
|
|
|
+ the default values (set using the tm module parameters retr_timer1 and
|
|
|
+ retr_timer2).
|
|
|
+
|
|
|
+ It will effectively cancel any previous calls to t_set_retr for the
|
|
|
+ same transaction.
|
|
|
+
|
|
|
+ See also: retr_timer1, retr_timer2, t_set_retr.
|
|
|
+
|
|
|
+ Example 54. t_reset_retr usage
|
|
|
+...
|
|
|
+route {
|
|
|
+...
|
|
|
+ t_reset_retr();
|
|
|
+...
|
|
|
+}
|
|
|
+
|
|
|
+1.4.19. t_set_auto_inv_100(0|1)
|
|
|
+
|
|
|
+ Switch automatically sending 100 replies to INVITEs on/off on a per
|
|
|
+ transaction basis. It overrides the auto_inv_100 value for the current
|
|
|
+ transaction.
|
|
|
+
|
|
|
+ See also: auto_inv_100.
|
|
|
+
|
|
|
+ Example 55. t_set_auto_inv_100 usage
|
|
|
+...
|
|
|
+route {
|
|
|
+...
|
|
|
+ if (src_ip==1.2.3.0/24)
|
|
|
+ t_set_auto_inv_100(0); # turn off automatic 100 replies
|
|
|
+...
|
|
|
+}
|
|
|
+
|
|
|
+1.4.20. t_branch_timeout()
|
|
|
+
|
|
|
+ Returns true if the failure route is executed for a branch that did
|
|
|
+ timeout. It can be used only from the failure_route.
|
|
|
+
|
|
|
+ Example 56. t_branch_timeout usage
|
|
|
+...
|
|
|
+failure_route[0]{
|
|
|
+ if (t_branch_timeout()){
|
|
|
+ log("timeout\n");
|
|
|
+ # ...
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.21. t_branch_replied()
|
|
|
+
|
|
|
+ Returns true if the failure route is executed for a branch that did
|
|
|
+ receive at least one reply in the past (the "current" reply is not
|
|
|
+ taken into account). It can be used only from the failure_route.
|
|
|
+
|
|
|
+ Example 57. t_branch_replied usage
|
|
|
+...
|
|
|
+failure_route[0]{
|
|
|
+ if (t_branch_timeout()){
|
|
|
+ if (t_branch_replied())
|
|
|
+ log("timeout after receiving a reply (no answer?)\n");
|
|
|
+ else
|
|
|
+ log("timeout, remote side seems to be down\n");
|
|
|
+ # ...
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.22. t_any_timeout()
|
|
|
+
|
|
|
+ Returns true if at least one of the current transactions branches did
|
|
|
+ timeout.
|
|
|
+
|
|
|
+ Example 58. t_any_timeout usage
|
|
|
+...
|
|
|
+failure_route[0]{
|
|
|
+ if (!t_branch_timeout()){
|
|
|
+ if (t_any_timeout()){
|
|
|
+ log("one branch did timeout\n");
|
|
|
+ sl_send_reply("408", "Timeout");
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.23. t_any_replied()
|
|
|
+
|
|
|
+ Returns true if at least one of the current transactions branches did
|
|
|
+ receive some reply in the past. If called from a failure or onreply
|
|
|
+ route, the "current" reply is not taken into account.
|
|
|
+
|
|
|
+ Example 59. t_any_replied usage
|
|
|
+...
|
|
|
+onreply_route[0]{
|
|
|
+ if (!t_any_replied()){
|
|
|
+ log("first reply received\n");
|
|
|
+ # ...
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.24. t_grep_status("code")
|
|
|
+
|
|
|
+ Returns true if "code" is the final reply received (or locally
|
|
|
+ generated) in at least one of the current transactions branches.
|
|
|
+
|
|
|
+ Example 60. t_grep_status usage
|
|
|
+...
|
|
|
+onreply_route[0]{
|
|
|
+ if (t_grep_status("486")){
|
|
|
+ /* force a 486 reply, even if this is not the winning branch */
|
|
|
+ t_reply("486", "Busy");
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.25. t_is_canceled()
|
|
|
+
|
|
|
+ Returns true if the current transaction was canceled.
|
|
|
+
|
|
|
+ Example 61. t_is_canceled usage
|
|
|
+...
|
|
|
+failure_route[0]{
|
|
|
+ if (t_is_canceled()){
|
|
|
+ log("transaction canceled\n");
|
|
|
+ # ...
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.26. t_is_expired()
|
|
|
+
|
|
|
+ Returns true if the current transaction has already been expired, i.e.
|
|
|
+ the max_inv_lifetime/max_noninv_lifetime interval has already elapsed.
|
|
|
+
|
|
|
+ Example 62. t_is_expired usage
|
|
|
+...
|
|
|
+failure_route[0]{
|
|
|
+ if (t_is_expired()){
|
|
|
+ log("transaction expired\n");
|
|
|
+ # There is no point in adding a new branch.
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.27. t_relay_cancel()
|
|
|
+
|
|
|
+ Forwards the CANCEL if the corresponding INVITE transaction exists. The
|
|
|
+ function is supposed to be used at the very beginning of the script,
|
|
|
+ because the CANCELs can be caught and the rest of the script can be
|
|
|
+ bypassed this way. Do not disable reparse_invite module parameter, and
|
|
|
+ call t_relay_cancel() right after the sanity tests.
|
|
|
+
|
|
|
+ Return value is 0 (drop) if the corresponding INVITE was found and the
|
|
|
+ CANCELs were successfully sent to the pending branches, true if the
|
|
|
+ INVITE was not found, and false in case of any error.
|
|
|
+
|
|
|
+ Example 63. t_relay_cancel usage
|
|
|
+if (method == CANCEL) {
|
|
|
+ if (!t_relay_cancel()) { # implicit drop if relaying was successful,
|
|
|
+ # nothing to do
|
|
|
+
|
|
|
+ # corresponding INVITE transaction found but error occurred
|
|
|
+ sl_reply("500", "Internal Server Error");
|
|
|
+ drop;
|
|
|
+ }
|
|
|
+ # bad luck, corresponding INVITE transaction is missing,
|
|
|
+ # do the same as for INVITEs
|
|
|
+}
|
|
|
+
|
|
|
+1.4.28. t_lookup_cancel(), t_lookup_cancel(1)
|
|
|
+
|
|
|
+ Returns true if the corresponding INVITE transaction exists for a
|
|
|
+ CANCEL request. The function can be called at the beginning of the
|
|
|
+ script to check whether or not the CANCEL can be immediately forwarded
|
|
|
+ bypassing the rest of the script. Note however that t_relay_cancel
|
|
|
+ includes t_lookup_cancel as well, therefore it is not needed to
|
|
|
+ explicitly call this function unless something has to be logged for
|
|
|
+ example.
|
|
|
+
|
|
|
+ If the function parameter (optional) is set to 1, the message flags are
|
|
|
+ overwritten with the flags of the INVITE. isflagset() can be used to
|
|
|
+ check the flags of the previously forwarded INVITE in this case.
|
|
|
+
|
|
|
+ Example 64. t_lookup_cancel usage
|
|
|
+if (method == CANCEL) {
|
|
|
+ if (t_lookup_cancel()) {
|
|
|
+ log("INVITE transaction exists");
|
|
|
+ if (!t_relay_cancel()) { # implicit drop if
|
|
|
+ # relaying was successful,
|
|
|
+ # nothing to do
|
|
|
+
|
|
|
+ # corresponding INVITE transaction found
|
|
|
+ # but error occurred
|
|
|
+ sl_reply("500", "Internal Server Error");
|
|
|
+ drop;
|
|
|
+ }
|
|
|
+ }
|
|
|
+ # bad luck, corresponding INVITE transaction is missing,
|
|
|
+ # do the same as for INVITEs
|
|
|
+}
|
|
|
+
|
|
|
+1.4.29. t_drop_replies()
|
|
|
+
|
|
|
+ Drops all the previously received replies in failure_route block to
|
|
|
+ make sure that none of them is picked up again. Works only if a new
|
|
|
+ branch is added to the transaction, or it is explicitly replied in the
|
|
|
+ script!
|
|
|
+
|
|
|
+ Example 65. t_drop_replies() usage
|
|
|
+...
|
|
|
+failure_route[0]{
|
|
|
+ if (t_check_status("5[0-9][0-9]")){
|
|
|
+ # I do not like the 5xx responses,
|
|
|
+ # so I give another chance to "foobar.com",
|
|
|
+ # and I drop all the replies to make sure that
|
|
|
+ # they are not forwarded to the caller.
|
|
|
+ t_drop_replies();
|
|
|
+
|
|
|
+ rewritehostport("foobar.com");
|
|
|
+ append_branch();
|
|
|
+ t_relay();
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+1.4.30. t_save_lumps()
|
|
|
+
|
|
|
+ Forces the modifications of the processed SIP message to be saved in
|
|
|
+ shared memory before t_relay() is called. The new branches which are
|
|
|
+ created in failure_route will contain the same modifications, and any
|
|
|
+ other modification after t_save_lumps() will be lost.
|
|
|
+
|
|
|
+ Note that t_relay() automatically saves the modifications when it is
|
|
|
+ called the first time, there is no need for t_save_lumps() unless
|
|
|
+ message changes between t_save_lumps() and t_relay() must not be
|
|
|
+ propagated to failure_route.
|
|
|
+
|
|
|
+ The transaction must be created by t_newtran() before calling
|
|
|
+ t_save_lumps().
|
|
|
+
|
|
|
+ Example 66. t_save_lumps() usage
|
|
|
+route {
|
|
|
+ ...
|
|
|
+ t_newtran();
|
|
|
+ append_hf("hf1: my first header\r\n");
|
|
|
+ ...
|
|
|
+ t_save_lumps();
|
|
|
+ append_hf("hf2: my second header\r\n");
|
|
|
+ ...
|
|
|
+ t_on_failure("1");
|
|
|
+ t_relay();
|
|
|
+}
|
|
|
+
|
|
|
+failure_route[1] {
|
|
|
+ append_branch();
|
|
|
+ append_hf("hf3: my third header\r\n");
|
|
|
+ #
|
|
|
+ # This branch contains hf1 and hf3, but does
|
|
|
+ # not contain hf2 header.
|
|
|
+ # hf2 would be also present here without
|
|
|
+ # t_save_lumps().
|
|
|
+ ...
|
|
|
+ t_relay();
|
|
|
+}
|
|
|
+
|
|
|
+1.4.31. t_load_contacts()
|
|
|
+
|
|
|
+ Loads contacts in destination set in increasing qvalue order as values
|
|
|
+ of contacts_avp. If all contacts in the destination set have the same
|
|
|
+ qvalue, t_load_contacts() does not do anything thus minimizing
|
|
|
+ performance impact of serial forking capability when it is not needed.
|
|
|
+ Returns 1 if loading of contacts succeeded or there was nothing to do.
|
|
|
+ Returns -1 on error (see syslog).
|
|
|
+
|
|
|
+ This function can be used from REQUEST_ROUTE.
|
|
|
+
|
|
|
+ Example 67. t_load_contacts usage
|
|
|
+...
|
|
|
+if (!t_load_contacts()) {
|
|
|
+ sl_send_reply("500", "Server Internal Error - Cannot load contacts");
|
|
|
+ exit;
|
|
|
+};
|
|
|
+...
|
|
|
+
|
|
|
+1.4.32. t_next_contacts()
|
|
|
+
|
|
|
+ If transaction does not exist when t_next_contacts() is called,
|
|
|
+ replaces Request-URI with the first contacts_avp value, adds the
|
|
|
+ remaining contacts_avp values with the same qvalue as branches, and
|
|
|
+ destroys those AVPs. It does nothing if there are no contacts_avp
|
|
|
+ values. Returns 1 if there were no errors and -1 if an error occurred
|
|
|
+ (see syslog).
|
|
|
+
|
|
|
+ If transaction does exist when t_next_contacts() is called, adds the
|
|
|
+ first contacts_avp value and all following contacts_avp values with the
|
|
|
+ same qvalue as new branches to request and destroys those AVPs. Returns
|
|
|
+ 1 if new branches were successfully added and -1 on error (see syslog)
|
|
|
+ or if there were no more contacts_avp values.
|
|
|
+
|
|
|
+ This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
|
|
|
+
|
|
|
+ Example 68. t_next_contacts usage
|
|
|
+...
|
|
|
+# First call after t_load_contacts() when transaction does not exist yet
|
|
|
+# and contacts should be available
|
|
|
+if (!t_next_contacts()) {
|
|
|
+ sl_send_reply("500", "Server Internal Error - Cannot get contacts");
|
|
|
+} else {
|
|
|
+ t_relay();
|
|
|
+};
|
|
|
+...
|
|
|
+# Following call, when transaction exists and there may or may not be
|
|
|
+# contacts left
|
|
|
+if (!t_next_contacts()) {
|
|
|
+ t_reply("408", "Request Timeout");
|
|
|
+} else {
|
|
|
+ t_relay();
|
|
|
+};
|
|
|
+...
|
|
|
+
|
|
|
+1.4.33. t_check_trans()
|
|
|
+
|
|
|
+ t_check_trans() can be used to quickly check if a message belongs or is
|
|
|
+ related to a transaction. It behaves differently for different types of
|
|
|
+ messages:
|
|
|
+ * For a SIP Reply it returns true if the reply belongs to an existing
|
|
|
+ transaction and false otherwise.
|
|
|
+ * For a CANCEL it behaves exactly as t_lookup_cancel(): returns true
|
|
|
+ if a corresponding INVITE transaction exists for the CANCEL and
|
|
|
+ false otherwise.
|
|
|
+ * For ACKs to negative replies or for ACKs to local transactions it
|
|
|
+ will terminate the script if the ACK belongs to a transaction (it
|
|
|
+ would make very little sense to process an ACK to a negative reply
|
|
|
+ for an existing transaction in some other way then to simply pass
|
|
|
+ it to tm) or return false if not.
|
|
|
+ * For end-to-end ACKs (ACKs to 2xx responses for forwarded INVITE
|
|
|
+ transactions) it will return true if the corresponding INVITE
|
|
|
+ transaction is found and still active and false if not.
|
|
|
+
|
|
|
+Note
|
|
|
+ Note that the e2e ACK matching is more of a hint then a certainty.
|
|
|
+ A delayed e2e ACK might arrive after the transaction wait time
|
|
|
+ elapses, when the INVITE transaction no longer exists and thus
|
|
|
+ would not match anything. There are also cases when tm would not
|
|
|
+ keep all the information needed for e2e ACK matching (since this is
|
|
|
+ not needed for a statefull proxy and it requires additional memory,
|
|
|
+ tm will not keep this information unless needed by some other
|
|
|
+ module or callbacks).
|
|
|
+ * For other requests (non ACKs and non CANCELs), it will terminate
|
|
|
+ the script for retransmissions and return false for new requests
|
|
|
+ (for which no transaction exists yet).
|
|
|
+
|
|
|
+Note
|
|
|
+
|
|
|
+ An important difference from kamailio version is that for an ACK to
|
|
|
+ negative reply or for a local transaction, the script execution will be
|
|
|
+ immediately stopped and the message handled by tm, instead of returning
|
|
|
+ true.
|
|
|
+
|
|
|
+ t_check_trans() functionality for requests, except for the e2e ACK
|
|
|
+ matching, can be replicated in the script using t_lookup_cancel() and
|
|
|
+ t_lookup_request().
|
|
|
+
|
|
|
+ See also: t_lookup_request(), t_lookup_cancel().
|
|
|
+
|
|
|
+ Example 69. t_check_trans usage
|
|
|
+if ( method == "CANCEL" && !t_check_trans())
|
|
|
+ sl_reply("403", "cancel out of the blue forbidden");
|
|
|
+# note: in this example t_check_trans() can be replaced by t_lookup_cancel()
|
|
|
+
|
|
|
+1.4.34. t_set_disable_6xx(0|1)
|
|
|
+
|
|
|
+ Turn off/on 6xx replies special rfc conformant handling on a per
|
|
|
+ transaction basis. If turned off (t_set_disable_6xx("1")) 6XXs will be
|
|
|
+ treated like normal replies.
|
|
|
+
|
|
|
+ It overrides the disable_6xx_block value for the current transaction.
|
|
|
+
|
|
|
+ See also: disable_6xx_block.
|
|
|
+
|
|
|
+ Example 70. t_set_disable_6xx usage
|
|
|
+...
|
|
|
+route {
|
|
|
+...
|
|
|
+ if (src_ip==1.2.3.4) # bad user agent that sends 603
|
|
|
+ t_set_disable_6xx(1); # turn off 6xx special handling
|
|
|
+...
|
|
|
+}
|
|
|
+
|
|
|
+1.4.35. t_set_disable_failover(0|1)
|
|
|
+
|
|
|
+ Turn off/on dns failover on a per transaction basis.
|
|
|
+
|
|
|
+ See also: use_dns_failover.
|
|
|
+
|
|
|
+ Example 71. t_set_disable_failover usage
|
|
|
+...
|
|
|
+route {
|
|
|
+...
|
|
|
+ if (uri=~"@foo.bar$")
|
|
|
+ t_set_disable_failover(1); # turn off dns failover
|
|
|
+...
|
|
|
+}
|
|
|
+
|
|
|
+1.5. TM Module API
|
|
|
+
|
|
|
+ Revision History
|
|
|
+ Revision $Revision$ $Date$
|
|
|
+
|
|
|
+ There are applications which would like to generate SIP transactions
|
|
|
+ without too big involvement in SIP stack, transaction management, etc.
|
|
|
+ An example of such an application is sending instant messages from a
|
|
|
+ website. To address needs of such apps, SIP-router accepts requests for
|
|
|
+ new transactions via the management interface. If you want to enable
|
|
|
+ this feature, start the management interface server by configuring the
|
|
|
+ proper modules.
|
|
|
+
|
|
|
+ An application can easily launch a new transaction by writing a
|
|
|
+ transaction request to this interface. The request must follow very
|
|
|
+ simple format, which for the basic FIFO interface is
|
|
|
+ :t_uac_from:[<file_name>]\n
|
|
|
+ <method>\n
|
|
|
+ <sender's uri>\n
|
|
|
+ <dst uri>\n
|
|
|
+ <CR_separated_headers>\n
|
|
|
+ <body>\n
|
|
|
+ .\n
|
|
|
+ \n
|
|
|
+
|
|
|
+ (Filename is to where a report will be dumped. ser assumes /tmp as
|
|
|
+ file's directory.)
|
|
|
+
|
|
|
+ Note the request write must be atomic, otherwise it might get
|
|
|
+ intermixed with writes from other writers. You can easily use it via
|
|
|
+ Unix command-line tools, see the following example:
|
|
|
+[jiri@bat jiri]$ cat > /tmp/ser_fifo
|
|
|
+:t_uac_from:xxx
|
|
|
+MESSAGE
|
|
|
+sip:[email protected]
|
|
|
+sip:[email protected]
|
|
|
+header:value
|
|
|
+foo:bar
|
|
|
+bznk:hjhjk
|
|
|
+p_header: p_value
|
|
|
+
|
|
|
+body body body
|
|
|
+yet body
|
|
|
+end of body
|
|
|
+.
|
|
|
+
|
|
|
+ or cat test/transaction.fifo > /tmp/ser_fifo
|
|
|
+
|
|
|
+1.5.1. Defines
|
|
|
+
|
|
|
+ * ACK_TAG enables stricter matching of acknowledgments including
|
|
|
+ to-tags. Without it, to-tags are ignored. It is disabled by default
|
|
|
+ for two reasons:
|
|
|
+ + It eliminates an unlikely race condition in which
|
|
|
+ transaction's to-tag is being rewritten by a 200 OK whereas an
|
|
|
+ ACK is being looked up by to-tag.
|
|
|
+ + It makes UACs happy who set wrong to-tags.
|
|
|
+ It should not make a difference, as there may be only one negative
|
|
|
+ reply sent upstream and 200/ACKs are not matched as they constitute
|
|
|
+ another transaction. It will make no difference at all when the new
|
|
|
+ magic cookie matching is enabled anyway.
|
|
|
+ * CANCEL_TAG similarly enables strict matching of CANCELs including
|
|
|
+ to-tags--act of mercy to UACs, who screw up the to-tags (however,
|
|
|
+ it still depends on how forgiving the downstream UAS is). Like with
|
|
|
+ ACK_TAG, all this complex transactions matching goes with RFC3261's
|
|
|
+ magic cookie away anyway.
|
|
|
+
|
|
|
+1.5.2. Functions
|
|
|
+
|
|
|
+1.5.2.1. register_tmcb(cb_type, cb_func)
|
|
|
+
|
|
|
+ For programmatic use only--register a function to be called back on an
|
|
|
+ event. See t_hooks.h for more details.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * cb_type - Callback type.
|
|
|
+ * cb_func - Callback function.
|
|
|
+
|
|
|
+1.5.2.2. load_tm(*import_structure)
|
|
|
+
|
|
|
+ For programmatic use only--import exported TM functions. See the acc
|
|
|
+ module for an example of use.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * import_structure - Pointer to the import structure.
|
|
|
+
|
|
|
+1.5.2.3. int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
|
|
|
+unsigned int *label)
|
|
|
+
|
|
|
+ For programmatic use only. This function together with t_continue() can
|
|
|
+ be used to implement asynchronous actions: t_suspend() saves the
|
|
|
+ transaction, returns its identifiers, and t_continue() continues the
|
|
|
+ SIP request processing. (The request processing does not continue from
|
|
|
+ the same point in the script, a separate route block defined by the
|
|
|
+ parameter of t_continue() is executed instead. The reply lock is held
|
|
|
+ during the route block execution.) FR timer is ticking while the
|
|
|
+ transaction is suspended, and the transaction's failure route is
|
|
|
+ executed if t_continue() is not called in time.
|
|
|
+
|
|
|
+ Missing: message lumps are saved by t_suspend() and are not updated by
|
|
|
+ the subsequent t_relay(). This means that the modifications made
|
|
|
+ between them are lost.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * msg - SIP message pointer.
|
|
|
+ * hash_index - transaction identifier.
|
|
|
+ * label - transaction identifier.
|
|
|
+
|
|
|
+ Return value: 0 - success, <0 - error.
|
|
|
+
|
|
|
+ Usage: Allocate a memory block for storing the transaction identifiers
|
|
|
+ (hash_index and label), and for storing also any variable related to
|
|
|
+ the async query. Before calling t_suspend(), register for the following
|
|
|
+ callbacks, and pass the pointer to the allocated shared memory as a
|
|
|
+ parameter: TMCB_ON_FAILURE, TMCB_DESTROY, and TMCB_E2ECANCEL_IN (in
|
|
|
+ case of INVITE transaction). The async operation can be cancelled, if
|
|
|
+ it is still pending, when TMCB_ON_FAILURE or TMCB_E2ECANCEL_IN is
|
|
|
+ called. TMCB_DESTROY is suitable to free the shared memory allocated
|
|
|
+ for the async and SIP transaction identifiers. Once the async query
|
|
|
+ result is available call t_continue(), see below. The SIP transaction
|
|
|
+ must exist before calling t_suspend(), and the module function calling
|
|
|
+ t_suspend() should return 0 to make sure that the script processing
|
|
|
+ does not continue.
|
|
|
+
|
|
|
+1.5.2.4. int t_continue(unsigned int hash_index, unsigned int label, struct
|
|
|
+action *route)
|
|
|
+
|
|
|
+ For programmatic use only. This function is the pair of t_suspend(),
|
|
|
+ and is supposed to be called when the asynchronous query result is
|
|
|
+ available. The function executes a route block with the saved SIP
|
|
|
+ message. It is possible to add more branches to the transaction, or
|
|
|
+ send a reply from the route block.
|
|
|
+
|
|
|
+ Meaning of the parameters is as follows:
|
|
|
+ * hash_index - transaction identifier.
|
|
|
+ * label - transaction identifier.
|
|
|
+ * route - route block to execute.
|
|
|
+
|
|
|
+ Return value: 0 - success, <0 - error.
|
oej