Skip to content

Commit

Permalink
tm: update documentation with latest changes
Browse files Browse the repository at this point in the history
  • Loading branch information
@liviuchircu
liviuchircu committed Mar 18, 2014
1 parent 4b5e4f8 commit 26af2e8
Show file tree
Hide file tree
Showing 2 changed files with 87 additions and 83 deletions.
90 changes: 47 additions & 43 deletions modules/tm/README
View file
Expand Up @@ -28,7 +28,7 @@ Bogdan-Andrei Iancu
1.1. Overview

1.1.1. Per-Branch flags
1.1.2. Timer-Based Failover
1.1.2. Timeout-Based Failover
1.1.3. DNS Failover

1.2. Dependencies
Expand All @@ -38,8 +38,8 @@ Bogdan-Andrei Iancu

1.3. Exported Parameters

1.3.1. fr_timer (integer)
1.3.2. fr_inv_timer (integer)
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)
Expand Down Expand Up @@ -82,8 +82,8 @@ Bogdan-Andrei Iancu

1.5.1. $T_branch_idx
1.5.2. $T_reply_code
1.5.3. $T_fr_timer
1.5.4. $T_fr_inv_timer
1.5.3. $T_fr_timeout
1.5.4. $T_fr_inv_timeout
1.5.5. $T_ruri
1.5.6. $bavp(name)

Expand Down Expand Up @@ -118,8 +118,8 @@ Bogdan-Andrei Iancu

List of Examples

1.1. Set fr_timer parameter
1.2. Set fr_inv_timer parameter
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
Expand Down Expand Up @@ -242,29 +242,31 @@ Chapter 1. Admin Guide
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. Timer-Based Failover
1.1.2. Timeout-Based Failover

Timers can be used to trigger failover behavior. E.g. if we
send a call a gateway and the gateway does not send a
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.

There are two timers in OpenSIPS :
* fr_timer - this timer is used when no response was received
yet. If there is no response after fr_timer seconds the
timer triggers (and failure route will be executed if
t_on_failure() was called). If a provisional response was
received, the timer is set to fr_inv_timer for INVITE
transactions, and RT_T2 for all other transactions. If a
final reponse is received, the transaction has finished.
* fr_inv_timer - this timer is used when a provisional
reponse was received for an INVITE transaction.
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. Thuse, set the fr_timer to 3 and fr_inv_timer to
60 seconds. Thus, set the fr_timeout to 3 and fr_inv_timeout to
60.

1.1.3. DNS Failover
Expand Down Expand Up @@ -310,31 +312,32 @@ Chapter 1. Admin Guide

1.3. Exported Parameters

1.3.1. fr_timer (integer)
1.3.1. fr_timeout (integer)

Timer which hits if no final reply for a request or ACK for a
negative INVITE reply arrives (in seconds).
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_timer parameter
Example 1.1. Set fr_timeout parameter
...
modparam("tm", "fr_timer", 10)
modparam("tm", "fr_timeout", 10)
...

1.3.2. fr_inv_timer (integer)
1.3.2. fr_inv_timeout (integer)

Timer which hits if no final reply for an INVITE arrives after
a provisional message was received (in seconds). This timer is
started after the first provisional response. Thus, fast
failover (no 100 trying from gateway) can be achieved by
setting fr_timer to low values. See example below
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_timer parameter
Example 1.2. Set fr_inv_timeout parameter
...
modparam("tm", "fr_inv_timer", 200)
modparam("tm", "fr_inv_timeout", 200)
...

1.3.3. wt_timer (integer)
Expand Down Expand Up @@ -437,8 +440,8 @@ modparam("tm", "unix_tx_timeout", 5)

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 occure after a time longe than
fr_inv_timer (if UAS keeps sending provisional replies)
final response timeout may occure after a time longer than
fr_inv_timeout (if UAS keeps sending provisional replies)

Default value is 1 (true).

Expand Down Expand Up @@ -1073,18 +1076,19 @@ branch_route[1] {
failure_route will be the negative winning reply. In case of
no-reply or error, '0' value is returned.

1.5.3. $T_fr_timer
1.5.3. $T_fr_timeout

$T_fr_timer (R/W) - the timeout for the final reply to the
$T_fr_timeout (R/W) - the timeout for the final reply to the
current transaction; with each different request received,
$T_fr_timer will initially be equal to the fr_timer parameter.
$T_fr_timeout will initially be equal to the fr_timeout
parameter.

1.5.4. $T_fr_inv_timer
1.5.4. $T_fr_inv_timeout

$T_fr_inv_timer (R/W) - the timeout for the final reply to an
$T_fr_inv_timeout (R/W) - the timeout for the final reply to an
INVITE request, after a 1XX reply was received; with each
different request received, $T_fr_inv_timer will initially be
equal to the fr_inv_timer parameter.
different request received, $T_fr_inv_timeout will initially be
equal to the fr_inv_timeout parameter.

1.5.5. $T_ruri

Expand Down
80 changes: 40 additions & 40 deletions modules/tm/doc/tm_admin.xml
View file
Expand Up @@ -115,41 +115,42 @@
</para>
</section>
<section id="timer-based-failover">
<title>Timer-Based Failover</title>
<title>Timeout-Based Failover</title>
<para>
Timers can be used to trigger failover behavior. E.g. if we send a call
a gateway and the gateway does not send a provisional response within 3
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.
</para>
<para>
There are two timers in &osips; :
The transaction module exports two types of timeouts:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis>fr_timer</emphasis> - this timer is used when
no response was received yet. If there is no response after
<emphasis>fr_timer</emphasis> seconds the timer triggers
<emphasis role='bold'>fr_timeout</emphasis> - used when no response was
received yet. If there is no response after
<emphasis>fr_timeout</emphasis> seconds, the timer triggers
(and failure route will be executed if t_on_failure() was
called). If a provisional response was received, the timer
is set to fr_inv_timer for INVITE transactions, and RT_T2
for all other transactions. If a final reponse is received,
the transaction has finished.
called). For INVITE transactions, if a provisional response was
received, the timeout is reset to <emphasis>fr_inv_timeout</emphasis>
seconds and RT_T2 for all other transactions. Once a final response
is received, the transaction has finished.
</para>
</listitem>
<listitem>
<para>
<emphasis>fr_inv_timer</emphasis> - this timer is used when
a provisional reponse was received for an INVITE transaction.
<emphasis role='bold'>fr_inv_timeout</emphasis> - this timeout
starts counting down once a provisional response was received
for an INVITE transaction.
</para>
</listitem>
</itemizedlist>
<para>
For example: You want to have failover if there is no provisional
response after 3 seconds, but you want to ring for 60 seconds.
Thuse, set the fr_timer to 3 and fr_inv_timer to 60.
Thus, set the <emphasis>fr_timeout</emphasis> to 3 and <emphasis>fr_inv_timeout</emphasis> to 60.
</para>
</section>
<section>
Expand Down Expand Up @@ -219,10 +220,10 @@

<section>
<title>Exported Parameters</title>
<section id='fr_timer' xreflabel='fr_timer'>
<title><varname>fr_timer</varname> (integer)</title>
<section id='fr_timeout' xreflabel='fr_timeout'>
<title><varname>fr_timeout</varname> (integer)</title>
<para>
Timer which hits if no final reply for a request or ACK for a
Timeout which is triggered if no final reply for a request or ACK for a
negative INVITE reply arrives (in seconds).
</para>
<para>
Expand All @@ -231,35 +232,34 @@
</emphasis>
</para>
<example>
<title>Set <varname>fr_timer</varname> parameter</title>
<title>Set <varname>fr_timeout</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("tm", "fr_timer", 10)
modparam("tm", "fr_timeout", 10)
...
</programlisting>
</example>
</section>

<section id='fr_inv_timer' xreflabel='fr_inv_timer'>
<title><varname>fr_inv_timer</varname> (integer)</title>
<para>
Timer which hits if no final reply for an INVITE arrives after a
provisional message was received (in seconds). This timer is started
after the first provisional response. Thus, fast failover (no 100
trying from gateway) can be achieved by setting fr_timer to low
values. See example below

<section id='fr_inv_timeout' xreflabel='fr_inv_timeout'>
<title><varname>fr_inv_timeout</varname> (integer)</title>
<para>
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
<emphasis> fr_timeout</emphasis> to low values. See example below.
</para>
<para>
<emphasis>
Default value is 120 seconds.
</emphasis>
</para>
<example>
<title>Set <varname>fr_inv_timer</varname> parameter</title>
<title>Set <varname>fr_inv_timeout</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("tm", "fr_inv_timer", 200)
modparam("tm", "fr_inv_timeout", 200)
...
</programlisting>
</example>
Expand Down Expand Up @@ -428,8 +428,8 @@ modparam("tm", "unix_tx_timeout", 5)
<para>
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 occure after a time longe than fr_inv_timer (if UAS keeps
sending provisional replies)
timeout may occure after a time longer than <emphasis>fr_inv_timeout</emphasis>
(if UAS keeps sending provisional replies)
</para>
<para>
<emphasis>
Expand Down Expand Up @@ -1449,24 +1449,24 @@ branch_route[1] {
</para>
</section>
<section>
<title>$T_fr_timer</title>
<title>$T_fr_timeout</title>
<para>
<emphasis>$T_fr_timer (R/W)</emphasis> - the timeout
<emphasis>$T_fr_timeout (R/W)</emphasis> - the timeout
for the final reply to the current transaction; with each different
request received, <emphasis>$T_fr_timer</emphasis> will initially
request received, <emphasis>$T_fr_timeout</emphasis> will initially
be equal to the
<emphasis role='bold'><xref linkend="fr_timer"/></emphasis> parameter.
<emphasis role='bold'><xref linkend="fr_timeout"/></emphasis> parameter.
</para>
</section>
<section>
<title>$T_fr_inv_timer</title>
<title>$T_fr_inv_timeout</title>
<para>
<emphasis>$T_fr_inv_timer (R/W)</emphasis> - the timeout
<emphasis>$T_fr_inv_timeout (R/W)</emphasis> - the timeout
for the final reply to an INVITE request, after a 1XX reply
was received; with each different request received,
<emphasis>$T_fr_inv_timer</emphasis> will initially be equal to the
<emphasis>$T_fr_inv_timeout</emphasis> will initially be equal to the
<emphasis role='bold'>
<xref linkend="fr_inv_timer"/></emphasis> parameter.
<xref linkend="fr_inv_timeout"/></emphasis> parameter.
</para>
</section>
<section>
Expand Down

0 comments on commit 26af2e8

Please sign in to comment.