- Requests after a DNS failover are constructed from the outgoing

[sip-router] / modules / tm / doc / params.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<section id="tm.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
        <revhistory>
            <revision>
                <revnumber>$Revision$</revnumber>
                <date>$Date$</date>
            </revision>
        </revhistory>
    </sectioninfo>

    <title>Parameters</title>

    <section id="fr_timer">
        <title><varname>fr_timer</varname> (integer)</title>
        <para>
            Timer which hits if no final reply for a request or ACK for a
            negative INVITE reply arrives (in milliseconds).
        </para>
        <para>
            Default value is 30 seconds.
        </para>
        <example>
            <title>Set <varname>fr_timer</varname> parameter</title>
            <programlisting>
...
modparam("tm", "fr_timer", 10)
...
            </programlisting>
        </example>
    </section>

    <section id="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 milliseconds).
        </para>
        <para>
            Default value is 120 seconds.
        </para>
        <example>
            <title>Set <varname>fr_inv_timer</varname> parameter</title>
            <programlisting>
...
modparam("tm", "fr_inv_timer", 200)
...
            </programlisting>
        </example>
    </section>

    <section id="wt_timer">
        <title><varname>wt_timer</varname> (integer)</title>
        <para>
            Time for which a transaction stays in memory to absorb delayed
            messages after it completed; also, when this timer hits,
            retransmission of local cancels is stopped (a puristic but complex
            behavior would be not to enter wait state until local branches are
            finished by a final reply or FR timer--we simplified).
        </para>
        <para>
            Default value is 5 seconds.
        </para>
        <example>
            <title>Set <varname>wt_timer</varname> parameter</title>
            <programlisting>
...
modparam("tm", "wt_timer", 10)
...
            </programlisting>
        </example>
    </section>

    <section id="delete_timer">
        <title><varname>delete_timer</varname> (integer)</title>
        <para>
            Time after which a to-be-deleted transaction currently ref-ed by a
            process will be tried to be deleted again.
        </para>
        <para>
            Default value is 200 milliseconds.
        </para>
        <example>
            <title>Set <varname>delete_timer</varname> parameter</title>
            <programlisting>
...
modparam("tm", "delete_timer", 5)
...
            </programlisting>
        </example>
    </section>
    
    <section id="retr_timer1">
        <title><varname>retr_timer1</varname> (integer)</title>
        <para>
            Initial retransmission period (in milliseconds).
        </para>
        <para>
            Default value is 500 milliseconds.
        </para>
        <example>
            <title>Set <varname>retr_timer1</varname> parameter</title>
            <programlisting>
...
modparam("tm", "retr_timer1", 1000)
...
            </programlisting>
        </example>
    </section>

    <section id="retr_timer2">
        <title><varname>retr_timer2</varname> (integer)</title>
        <para>
            Maximum retransmission period (in milliseconds). The retransmission
                interval starts with <varname>retr_timer1</varname> and increases until
                it reaches this value. After this it stays constant at 
                <varname>retr_timer2</varname>.
        </para>
        <para>
            Default value is 4000 milliseconds.
        </para>
        <example>
            <title>Set <varname>retr_timer2</varname> parameter</title>
            <programlisting>
...
modparam("tm", "retr_timer2", 2000)
...
            </programlisting>
        </example>
    </section>

    <section id="noisy_ctimer">
        <title><varname>noisy_ctimer</varname> (integer)</title>
        <para>
            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 fro INVITEs is lower or equal than tm's
                <varname>fr_inv_timer</varname>.
        </para>
        <para>
            Default value is 1 (on).
        </para>
        <example>
            <title>Set <varname>noisy_ctimer</varname> parameter</title>
            <programlisting>
...
modparam("tm", "noisy_ctimer", 1)
...
            </programlisting>
        </example>
    </section>

        <section id="unix_tx_timeout">
        <title><varname>unix_tx_timeout</varname> (integer)</title>
        <para>
                Unix socket transmission timeout, in milliseconds.
        </para>
        <para>
                If unix sockets are used (e.g.: to communicate with sems) and sending
                a message on a unix socket takes longer then 
                <varname>unix_tx_timeout</varname>, the send will fail.
        </para>
        <para>
            The default value is 500 milliseconds.
        </para>
        <example>
            <title>Set <varname>unix_tx_timeout</varname> parameter</title>
            <programlisting>
...
modparam("tm", "unix_tx_timeout", 250)
...
            </programlisting>
        </example>
        </section>

    <section id="aggregate_challenges">
        <title><varname>aggregate_challenges</varname> (integer)</title>
        <para>
                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).
        </para>
        <para>
            Default value is 1 (required by rfc3261).
        </para>
        <example>
            <title>Set <varname>aggregate_challenges</varname> parameter</title>
            <programlisting>
...
modparam("tm", "aggregate_challenges", 0)
...
            </programlisting>
        </example>
    </section>

    <section id="reparse_invite">
        <title><varname>reparse_invite</varname> (integer)</title>
        <para>
                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:
        </para>
        <para>
                - 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
                <varname>reparse_invite</varname>=1.
        </para>
        <para>
                - 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 <varname>reparse_invite</varname>=1.
        </para>
        <para>
            Default value is 1.
        </para>
        <example>
            <title>Set <varname>reparse_invite</varname> parameter</title>
            <programlisting>
...
modparam("tm", "reparse_invite", 0)
...
            </programlisting>
        </example>
    </section>

    <section id="ac_extra_hdrs">
        <title><varname>ac_extra_hdrs</varname> (string)</title>
        <para>
                Header fields prefixed by this parameter value are included
                in the CANCEL and negative ACK messages if they were present
                in the outgoing INVITE.
        </para>
        <para>
                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 <varname>reparse_invite</varname>=1.
        </para>
        <para>
            Default value is "".
        </para>
        <example>
            <title>Set <varname>ac_extra_hdrs</varname> parameter</title>
            <programlisting>
...
modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
...
            </programlisting>
        </example>
    </section>

    <section id="blst_503">
        <title><varname>blst_503</varname> (integer)</title>
        <para>
                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: <varname>blst_503_def_timeout</varname>, 
                <varname>blst_503_min_timeout</varname> and 
                <varname>blst_503_max_timeout</varname>.
        </para>
        <para>
                <emphasis>WARNING:</emphasis>blindly allowing 503 blacklisting could 
                be very easily exploited for DOS attacks in most network setups.
        </para>
        <para>
                The default value is 0 (disabled due to the reasons above).
        </para>
        <example>
            <title>Set <varname>blst_503</varname> parameter</title>
            <programlisting>
...
modparam("tm", "blst_503", 1)
...
            </programlisting>
        </example>
    </section>

    <section id="blst_503_def_timeout">
        <title><varname>blst_503_def_timeout</varname> (integer)</title>
        <para>
                
                Blacklist interval in seconds for a 503 reply with no Retry-After 
                header.
                See also <varname>blst_503</varname>, 
                <varname>blst_503_min_timeout</varname> and 
                <varname>blst_503_max_timeout</varname>.
        </para>
        <para>
                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).
        </para>
        <example>
            <title>Set <varname>blst_503_def_timeout</varname> parameter</title>
            <programlisting>
...
modparam("tm", "blst_503_def_timeout", 120)
...
            </programlisting>
        </example>
    </section>

    <section id="blst_503_min_timeout">
        <title><varname>blst_503_min_timeout</varname> (integer)</title>
        <para>
                
                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 <varname>blst_503</varname>, 
                <varname>blst_503_def_timeout</varname> and 
                <varname>blst_503_max_timeout</varname>.
        </para>
        <para>
                The default value is 0 
        </para>
        <example>
            <title>Set <varname>blst_503_min_timeout</varname> parameter</title>
            <programlisting>
...
modparam("tm", "blst_503_min_timeout", 30)
...
            </programlisting>
        </example>
    </section>

    <section id="blst_503_max_timeout">
        <title><varname>blst_503_max_timeout</varname> (integer)</title>
        <para>
                
                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 <varname>blst_503</varname>, 
                <varname>blst_503_def_timeout</varname> and 
                <varname>blst_503_min_timeout</varname>.
        </para>
        <para>
                The default value is 3600 
        </para>
        <example>
            <title>Set <varname>blst_503_max_timeout</varname> parameter</title>
            <programlisting>
...
modparam("tm", "blst_503_max_timeout", 604800)
...
            </programlisting>
        </example>
    </section>

    <section id="blst_methods_add">
        <title><varname>blst_methods_add</varname> (unsigned integer)</title>
        <para>
                Bitmap of method types that trigger blacklisting on
                transaction timeouts. (This setting has no
                effect on blacklisting because of send failures.)
        </para>
        <para>
                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.
        </para>
        <para>
                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.
        </para>
        <para>
                The default value is 1, only INVITEs trigger blacklisting
        </para>
        <example>
            <title>Set <varname>blst_methods_add</varname> parameter</title>
            <programlisting>
...
# INVITEs and REGISTERs trigger blacklisting
modparam("tm", "blst_methods_add", 33)
...
            </programlisting>
        </example>
    </section>

    <section id="blst_methods_lookup">
        <title><varname>blst_methods_lookup</varname> (unsigned integer)</title>
        <para>
                Bitmap of method types that are looked-up in the blacklist
                before statefull forwarding.
                See also <varname>blst_methods_add</varname>
        </para>
        <para>
                The default value is 4294967287, every method type except BYE.
                (We try to deliver BYEs no matter what)
        </para>
        <example>
            <title>Set <varname>blst_methods_lookup</varname> parameter</title>
            <programlisting>
...
# lookup only INVITEs
modparam("tm", "blst_methods_lookup", 1)
...
            </programlisting>
        </example>
    </section>

    <section id="cancel_b_method">
        <title><varname>cancel_b_method</varname> (integer)</title>
        <para>
                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.
        </para>
        <para>
                <emphasis>0</emphasis> will immediately stop the request (INVITE) 
                retrasmission 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).
        </para>
        <para>
                <emphasis>1</emphasis> 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 (<varname>fr_timer</varname>).
        </para>
        <para>
                <emphasis>2</emphasis> will send and retransmit CANCEL even on 
                unreplied branches, stopping the request retransmissions. This has the
                same advantages as <emphasis>1</emphasis> 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).
        </para>
        <para>
                The default value is 0 (the same behaviour as ser versions
                less then 2.1).
        </para>
        <example>
            <title>Set <varname>cancel_b_method</varname> parameter</title>
            <programlisting>
...
modparam("tm", "cancel_b_method", 1)
...
            </programlisting>
        </example>
    </section>

    <section id="reparse_on_dns_failover">
        <title><varname>reparse_on_dns_failover</varname> (integer)</title>
        <para>
                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.
        </para>
        <para>
                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.
        </para>
        <para>
                Note: If the parameter is set, branch route block and TMCB_REQUEST_FWDED
                callback are not called in case of the failover.
        </para>
        <para>
                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.
        </para>
        <para>
                Default value is 1.
        </para>
        <example>
            <title>Set <varname>reparse_on_dns_failover</varname> parameter</title>
            <programlisting>
...
modparam("tm", "reparse_on_dns_failover", 0)
...
            </programlisting>
       </example>
    </section>

</section>