====== SIP Transaction Timers ======
The timers of the tm module can be confusing and normally you do not have to
(or should) tweak timers except the `fr_inv_timer` (controlling "how long to
ring"). The table below gives an overview of the timers that can be changed
from SER configuration file and their relationship to the timer names in
RFC3261 and how/why you would want to change it.

<note>
Starting in SER 2.0 the timer implementation has been completely
rewritten. The timers are now controlled in milliseconds and (not in seconds
as in SER 0.9), for example

  modparam("tm", "fr_timer", 30000) # default value of 30s.

Timers have a resolution of 1/TIMER_TICKS_HZ. This is by default 62.5
ms. Thus, the timer can fire every 62.5 ms.  Note that this also is the error
interval (they can fire anywhere in a 62.5 ms interval from their
"theoretical" expire point).
</note>

===== fr_timer =====
This timer is used for all SIP requests. It hits if no reply
for an INVITE request or other request has been received (F in milliseconds).
If a provisional reply is received for an INVITE (any 1xx), then the
''fr_inv_timer'' will be used instead. And if no replies (at all) for an INVITE
are received before `fr_timer` hits, the transaction is terminated with a 408
in failure route.

See ''fr_inv_timer'' for description of handling of multiple branches and local
generation of 408 vs. 408s received from the network etc.

Intention of the RFC is having this value equal to the time required to send
seven requests.

  * **Corresponding RFC 3261 timers**: Timer F and Timer B
  * **Default value**: 30000 ms
  * **Example**: modparam("tm", "fr_timer", 20000)

This timer can also be changed per transaction (INVITE) by calling

  t_set_fr(timeout_fr_inv, timeout_fr);

in a route section of the configuration file. If one of the vaules is 0, the
corresponding timer won't be changed (e.g ''t_set_fr(0, 15000)'' changes only the
''fr_timer'').
If it was changed using t_set_fr() for a transaction, it can be reset to the default value
using t_reset_fr().

===== fr_inv_timer =====
This is the timer which hits if no final reply for an INVITE arrives after a
provisional message was received (in milliseconds). This means that this timer
controls how long time a phone will ring before a 408 timeout is generated in
failure_route. Note that it will not always be the 108 reply that will be seen
in the failure_route as SER will choose a reply from all the replies received
on all the branches and the "winner" will get to the failure route.

  * **Corresponding RFC 3261 timers**: Timer C
  * **Default value**: 120000 ms
  * **Example**: modparam("tm", "fr_inv_timer", 100000)

This timer can also be changed per transaction (INVITE) by calling
''t_set_fr(timer_fr_inv, timeout_fr)'' in a route section of the configuration
file. If one of the vaules is 0, the corresponding timer won't be changed (e.g
''t_set_fr(0, 15000)'' changes only the ''fr_timer'').

The tm module parameter ''restart_fr_on_each_reply'' controls whether the
''fr_inv_timer'' is restarted every time a provisonal reply is received, default
is 1 (yes).

Setting the parameter to 0 is not RFC conformant but is very usefull for
dealing with phones that will periodically retransmit the 18x Ringing, which
otherwise could make the transaction live forever or mess up your voicemail
activation.

In the failure route, the new tm module functions:
  - ''t_branch_timeout''
  - ''t_branch_replied''
  - ''t_any_timeout''
  - ''t_any_replied''

can be used to find out if the failure route is executed as a result of a
timeout (even if the selected reply is a 408, it could be something forwarded
from downstream and not a local timeout), and if it is a timeout, to find out
which kind (no reply or "ringing").

  if (!t_branch_timeout() && t_check_status("408")) ...  # a 408 received from the network.
  if (t_branch_timeout() && ! t_branch_replied()) ... # a local transaction timed out w/o any reply received.
  if (t_branch_timeout() && t_branch_replied()) ... # a local timeout after some provsional reply.

Even more script functions:
  - ''t_any_timeout'': true if any of the transaction branches did timeout
  - ''t_any_replied'': true if at least one branch received a reply (when used from an on_reply route it will ignore the "current" reply)
  - ''t_is_canceled'': true if the current transaction has been canceled

For more information see the documentation of tm module (especially t_set_fr() and t_reset_fr()).

===== wt_timer =====
Time for which a transaction stays in memory to absorb delayed messages after
it is completed. Also, when this timer hits, retransmissions of local CANCELs
are stopped.

  * **Corresponding RFC 3261 timers**: Timer I and Timer K
  * **Default value**: 5000 ms
  * **Example**: modparam("tm", "wt_timer", 10000)

Within this time, retransmissions will be absorbed by the server. After this
time, the transaction is cleared and late retransmissions not
recognized. Increase if there is an extreme problem with late retransmissions.

<note>
The longer this timer is, the longer the transaction will be kept
in memory and memory consumtion increases (Try to set it to a lower value if
you want to minimize memory consumption).
</note>

===== retr_timer1 =====
Initial retransmission timer (for everything). On the first retransmit of
INVITEs, **timer A** is set to this value. For each subsequent retransmit, the
timer value is doubled until ''fr_timer'' hits (RFC 3261: Timer B).

For non-INVITE transactions, the timer is set to
MIN(4 * retr_timer1, retr_timer2) until ''fr_timer'' hits (RFC 3261: Timer F).

  * **Corresponding RFC 3261 timers**: Timer T1, initial value for A, E, and G.
  * **Default value**: 500 ms
  * **Example**: modparam("tm", "retr_timer1", 1000)

If you have a network with very long roundtrip time (above 1 sec), you may
increase this value (but change ''fr_timer'' as well).

===== retr_timer2 =====
The maximum length between two retransmits (for everything).

  * **Corresponding RFC 3261 timers**: Timer T2, maximum value for A, E, and G.
  * **Default value**: 4000 ms
  * **Example**: modparam("tm", "retr_timer2", 8000)

===== max_inv_lifetime =====

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:
<code>
modparam("tm", "max_inv_lifetime", 150000)
</code>

===== max_noninv_lifetime =====
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.

===== delete_timer =====
<note>
This timer is obsolete for ser 2.1 and sip-router (in 2.1 the transaction is deleted the moment it's not referenced anymore).
</note>
This is the amount of time for which the deletion of a transaction will be
delayed if the transaction is still use.

  * **Corresponding RFC 3261 timers**: No corresponding timer, SER specific
  * **Default value**: 200 ms
  * **Example**: modparam("tm", "retr_timer1", 1000)

In general there's no need to change it except for testing ways to minimize
the memory consumption (setting it to 100ms might help).