<?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: 1.5.2.2 $</revnumber>
		<date>$Date: 2008/06/20 17:37:22 $</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 30000 ms (30 seconds).
	</para>
	<para>
		See also: <function>t_set_fr()</function>.
	</para>
	<example>
	    <title>Set <varname>fr_timer</varname> parameter</title>
	    <programlisting>
...
modparam("tm", "fr_timer", 10000)
...
	    </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>
	</para>
		Note: this timer can be restarted when a provisional response is
		received. For more details see
		<varname>restart_fr_on_each_reply</varname>.
	<para>
	    Default value is 120000 ms (120 seconds).
	</para>
	<para>
		See also: <function>t_set_fr()</function>.
	</para>
	<example>
	    <title>Set <varname>fr_inv_timer</varname> parameter</title>
	    <programlisting>
...
modparam("tm", "fr_inv_timer", 180000)
...
	    </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 (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).
	</para>
	<para>
	    Default value is 5000 ms (5 seconds).
	</para>
	<example>
	    <title>Set <varname>wt_timer</varname> parameter</title>
	    <programlisting>
...
modparam("tm", "wt_timer", 1000)
...
	    </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 (in milliseconds).
	</para>
	<para>
	    Default value is 200 milliseconds.
	</para>
	<example>
	    <title>Set <varname>delete_timer</varname> parameter</title>
	    <programlisting>
...
modparam("tm", "delete_timer", 100)
...
	    </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 for INVITEs is lower or equal than tm's
		<varname>fr_inv_timer</varname>.
	</para>
	<para>
	    Default value is 0 (false).
	</para>
	<example>
	    <title>Set <varname>noisy_ctimer</varname> parameter</title>
	    <programlisting>
...
modparam("tm", "noisy_ctimer", 1)
...
	    </programlisting>
	</example>
    </section>

	<section id="restart_fr_on_each_reply">
	<title><varname>restart_fr_on_each_reply</varname> (integer)</title>
	<para>
		If set (default), the <varname>fr_inv_timer</varname> for an INVITE
		transaction will be restarted for each provisional reply received
		(rfc3261 mandated behaviour). If not set, the 
		<varname>fr_inv_timer</varname> will be restarted only for the first
		provisional replies and for increasing replies greater or equal 180
		(e.g. 180, 181, 182, 185, ...).
	</para>
	<para>
		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).
	</para>
	<para>
		Default value is 1 (on).
	</para>
	<para>
		See also: <varname>fr_inv_timer</varname>.
	</para>
	<example>
		<title>Set <varname>restart_fr_on_each_reply</varname>
				parameter</title>
		<programlisting>
...
modparam("tm", "restart_fr_on_each_reply", 0)
...
	    </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="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>
