<?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"
	[ <!ENTITY % local.common.attrib
	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
	 <!-- Include general documentation entities -->
	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
	 %docentities;
	]
>

<section id="tm.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
    </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>,
				<varname>max_noninv_lifetime</varname>.
	</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>
	<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>
	<para>
	    Default value is 120000 ms (120 seconds).
	</para>
	<para>
		See also: <function>t_set_fr()</function>,
				<varname>max_inv_lifetime</varname>.
	</para>
	<example>
	    <title>Set <varname>fr_inv_timer</varname> parameter</title>
	    <programlisting>
...
modparam("tm", "fr_inv_timer", 180000)
...
	    </programlisting>
	</example>
    </section>

	<section id="max_inv_lifetime">
	<title><varname>max_inv_lifetime</varname> (integer)</title>
	<para>
		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  <varname>fr_inv_timer</varname> and
		<varname>fr_timer</varname> values.
	</para>
	<para>
		An INVITE transaction will be kept in memory for maximum:
		<varname>max_inv_lifetime</varname>+<varname>fr_timer</varname>(from 
		the ack to the final reply wait)+<varname>wt_timer</varname>.
	</para>
	<para>
		The main difference between this timer and 
		<varname>fr_inv_timer</varname> is that the 
		<varname>fr_inv_timer</varname> is per branch, while 
		<varname>max_inv_lifetime</varname> is per the whole transaction.
		Even on a per branch basis <varname>fr_inv_timer</varname> could be 
		restarted. For example, by default if 
		<varname>restart_fr_on_each_reply</varname> is not cleared, the 
		<varname>fr_inv_timer</varname> will be restarted for each received 
		provisional reply. Even if <varname>restart_fr_on_each_reply</varname>
		is not set the <varname>fr_inv_timer</varname> will still be restarted
		for each increasing reply (e.g. 180, 181, 182, ...). 
		Another example when a transaction can live substantially more then its
		<varname>fr_inv_timer</varname> and where
		<varname>max_inv_lifetime</varname> will help is when dns failover is 
		used (each failed dns destination can introduce a new branch).
	</para>
	<para>
		The default value is 180000 ms (180 seconds - the rfc3261 
		timer C value).
	</para>
	<para>
		See also: <varname>max_noninv_lifetime</varname>,
					<function>t_set_max_lifetime()</function> (allows changing
					<varname>max_inv_lifetime</varname> on a per transaction
					basis),
					<function>t_reset_max_lifetime</function>
					<varname>fr_timer</varname>,
					<varname>wt_timer</varname>,
					<varname>restart_fr_on_each_reply</varname>.
	</para>
	<example>
	    <title>Set <varname>max_inv_lifetime</varname> parameter</title>
	    <programlisting>
...
modparam("tm", "max_inv_lifetime", 150000)
...
	    </programlisting>
	</example>
    </section>

	<section id="max_noninv_lifetime">
	<title><varname>max_noninv_lifetime</varname> (integer)</title>
	<para>
		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 <varname>fr_timer</varname> value.
		It's the same as <varname>max_inv_lifetime</varname>, but for 
		non-INVITEs.
	</para>
	<para>
		A non-INVITE transaction will be kept in memory for maximum:
		<varname>max_noninv_lifetime</varname>+<varname>wt_timer</varname>.
	</para>
	<para>
		The main difference between this timer and 
		<varname>fr_timer</varname> is that the 
		<varname>fr_timer</varname> is per branch, while 
		<varname>max_noninv_lifetime</varname> is per the whole transaction.
		An example when a transaction can live substantially more then its
		<varname>fr_timer</varname> and where
		<varname>max_noninv_lifetime</varname> will help is when dns failover
		is used (each failed dns destination can introduce a new branch).
	</para>
	<para>
		The default value is 32000 ms (32 seconds - the rfc3261 timer F value).
	</para>
	<para>
		See also: <varname>max_inv_lifetime</varname>,
					<function>t_set_max_lifetime()</function> (allows changing
					<varname>max_noninv_lifetime</varname> on a per transaction
					basis),
					<function>t_reset_max_lifetime</function>
					<varname>fr_timer</varname>,
					<varname>wt_timer</varname>.
	</para>
	<example>
	    <title>Set <varname>max_noninv_lifetime</varname> parameter</title>
	    <programlisting>
...
modparam("tm", "max_noninv_lifetime", 30000)
...
	    </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>
	    Note: this parameter is obsolete for ser 2.1 (in 2.1 the transaction
		 is deleted the moment it's not referenced anymore).
	</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 1 (on).
	</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>,
				<varname>max_inv_lifetime</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="auto_inv_100">
	<title><varname>auto_inv_100</varname> (integer)</title>
	<para>
		If set (default) tm will automatically send and 100 reply to INVITEs.
	</para>
	<para>
		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 <function>t_reply()</function>). Note 
		however that in this case all the 100s have to be sent "by hand".
		<function>t_set_auto_inv_100()</function> might  help to selectively
		turn off this feature only for some specific transactions.
	</para>
	<para>
		Default value is 1 (on).
	</para>
	<para>
		See also: <function>t_set_auto_inv_100()</function>
				  <varname>auto_inv_100_reason</varname>. 
	</para>
	<example>
		<title>Set <varname>auto_inv_100</varname> parameter</title>
		<programlisting>
...
modparam("tm", "auto_inv_100", 0)
...
	    </programlisting>
	</example>
	</section>

	<section id="auto_inv_100_reason">
	<title><varname>auto_inv_100_reason</varname> (string)</title>
	<para>
		Set reason text of the automatically send 100 to an INVITE.
	</para>
	<para>
		Default value is "trying -- your call is important to us".
	</para>
	<para>
		See also: <varname>auto_inv_100</varname>.
	</para>
	<example>
		<title>Set <varname>auto_inv_100_reason</varname> parameter</title>
		<programlisting>
...
modparam("tm", "auto_inv_100_reason", "Trying")
...
	    </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) 
		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.
	</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 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 id="on_sl_reply">
	<title><varname>on_sl_reply</varname> (string)</title>
	<para>
		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.
	</para>
	<example>
	    <title>Set <varname>on_sl_reply</varname> parameter</title>
	    <programlisting>
...
modparam("tm", "on_sl_reply", "stateless_replies")
...

onreply_route["stateless_replies"] {
	# do not allow stateless replies to be forwarded
	return 0;
}
	    </programlisting>
	</example>
    </section>
	
	<section>
		<title><varname>contacts_avp</varname> (string)</title>
		<para>
		This is the name of an XAVP
                that <function>t_load_contacts()</function> function uses to
                store contacts of the destination set and that
                <function>t_next_contacts()</function> function uses to
                restore those contacts.
		</para>
		<para>
		<emphasis>
			Default value is "NULL"
			(t_load_contacts()/t_next_contacts() functions
			are disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>contacts_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "contacts_avp", "tm_contacts")
...
</programlisting>
		</example>
	</section>
	
	<section>
		<title><varname>contact_flows_avp</varname> (string)</title>
		<para>
		This is the name of an XAVP
                that <function>t_next_contacts()</function> function uses to
                store contacts (if any) that it skipped, because they
		contained same +sip.instance value than some other contact,
                and that <function>t_next_contact_flows()</function>
		function uses to restore those contacts.
		</para>
		<para>
		<emphasis>
			Default value is "NULL".  This parameter MUST be
			set if variable contacts_avp is set.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>contact_flows_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "contact_flows_avp", "tm_contact_flows")
...
</programlisting>
		</example>
	</section>

	<section id="fr_timer_avp">
		<title><varname>fr_timer_avp</varname> (string)</title>
		<para>
			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 <varname>fr_timer</varname> parameter for the
			current transaction.
		</para>
		<para>
			The value of this parameter is the the name of the AVP to be
			checked, without the $ character or "$avp" prefix.
		</para>
		<note><para>
			The value of the AVP is expected to be expressed in 
			<emphasis>seconds</emphasis> and not milliseconds (unlike the rest
			of the timers).
		</para></note>
		<para>
			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
			<function>t_set_fr()</function> on a per transaction basis.
		</para>
		<para>
			See also: <function>t_set_fr()</function>,
			<varname>fr_timer</varname>.
		</para>
		<para>
			In Kamailio compatibility mode (defined by #!KAMAILIO), the value
			of the parameter must be the name of an AVP in pseudo-variable
			format: $avp(name). In SER compatibility mode it must by just
			AVP name.
		</para>
		<example>
			<title>Set <varname>fr_timer_avp</varname> parameter</title>
			<programlisting>
...
modparam("tm", "fr_timer_avp", "i:708")
# K mode
modparam("tm", "fr_timer_avp", "$avp(i:708)")
...
			</programlisting>
		</example>
	</section>
	
	<section id="fr_inv_timer_avp">
		<title><varname>fr_inv_timer_avp</varname> (string)</title>
		<para>
			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 <varname>fr_inv_timer</varname> parameter for the
			current transaction.
		</para>
		<para>
			The value of this parameter is the the name of the AVP to be
			checked, without the $ character or "$avp" prefix.
		</para>
		<note><para>
			The value of the AVP is expected to be expressed in
			<emphasis>seconds</emphasis> and not milliseconds (unlike the rest
			of the timers).
		</para></note>
		<para>
			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
			<function>t_set_fr()</function> on a per transaction basis.
		</para>
		<para>
			See also: <function>t_set_fr()</function>,
			<varname>fr_inv_timer</varname>.
		</para>
		<para>
			In Kamailio compatibility mode (defined by #!KAMAILIO), the value
			of the parameter must be the name of an AVP in pseudo-variable
			format: $avp(name). In SER compatibility mode it must by just
			AVP name.
		</para>
		<example>
			<title>Set <varname>fr_inv_timer_avp</varname> parameter</title>
			<programlisting>
...
modparam("tm", "fr_inv_timer_avp", "my_fr_inv_timer")
# K mode
modparam("tm", "fr_inv_timer_avp", "$avp(my_fr_inv_timer)")
...
			</programlisting>
		</example>
	</section>

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

	<section id="ruri_matching">
	<title><varname>ruri_matching</varname> (integer)</title>
	<para>
		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).
	</para>
	<para>
		The only reason to have it not set is for interoperability with old,
		broken implementations.
	</para>
	<para>
		Default value is 1 (on).
	</para>
	<para>
		Can be set at runtime, e.g.:
		<programlisting>
	$ &sercmd; cfg.set_now_int tm ruri_matching 0
		</programlisting>
	</para>
	<example>
		<title>Set <varname>ruri_matching</varname> parameter</title>
		<programlisting>
...
modparam("tm", "ruri_matching", 1)
...
	    </programlisting>
	</example>
	</section>

	<section id="via1_matching">
	<title><varname>via1_matching</varname> (integer)</title>
	<para>
		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).
	</para>
	<para>
		The only reason to have it not set is for interoperability with old,
		broken implementations.
	</para>
	<para>
		Default value is 1 (on).
	</para>
	<para>
		Can be set at runtime, e.g.:
		<programlisting>
	$ &sercmd; cfg.set_now_int tm via1_matching 0
		</programlisting>
	</para>
	<example>
		<title>Set <varname>via1_matching</varname> parameter</title>
		<programlisting>
...
modparam("tm", "via1_matching", 1)
...
	    </programlisting>
	</example>
	</section>

	<section id="callid_matching">
	<title><varname>callid_matching</varname> (integer)</title>
	<para>
		If set it will also try to match the callid when doing
		transaction matching.
	</para>
	<para>
		Turn on if you don't want replies/requests from broken clients who
		send a mangled Call-ID to match the transaction. For example when
		the other side won't recognise the response anyway because of changed
		Call-ID, this setting will prevent accounting records to be created
		or failure_route to be skipped.
	</para>
	<para>
		Default value is 0 (off).
	</para>
	<para>
		Can be set at runtime, e.g.:
		<programlisting>
	$ sercmd cfg.set_now_int tm callid_matching 0
		</programlisting>
	</para>
	<example>
		<title>Set <varname>callid_matching</varname> parameter</title>
		<programlisting>
...
modparam("tm", "callid_matching", 1)
...
	    </programlisting>
	</example>
	</section>

	<section id="pass_provisional_replies">
	<title><varname>pass_provisional_replies</varname> (integer)</title>
	<para>
		If set, TMCB_LOCAL_REPONSE_OUT tm registered callbacks will be called
		also for provisional replies.
	</para>
	<para>
		Default value is 0 (off).
	</para>
	<para>
		Can be set at runtime, e.g.:
		<programlisting>
	$ &sercmd; cfg.set_now_int tm pass_provisional_replies 1
		</programlisting>
	</para>
	<example>
		<title>Set <varname>pass_provisional_replies</varname> parameter
		</title>
		<programlisting>
...
modparam("tm", "pass_provisional_replies", 1)
...
	    </programlisting>
	</example>
	</section>

	<section id="default_code">
	<title><varname>default_code</varname> (integer)</title>
	<para>
		Default response code sent by <function>t_reply()</function> if it
		cannot retrieve its parameters (e.g. inexistent avp).
		Valid values are between 400 and 699.
	</para>
	<para>
		Default value is 500.
	</para>
	<para>
		Can be set at runtime, e.g.:
		<programlisting>
	$ &sercmd; cfg.set_now_int tm default_code 505
		</programlisting>
	</para>
	<example>
		<title>Set <varname>default_code</varname> parameter </title>
		<programlisting>
...
modparam("tm", "default_code", 501)
...
	    </programlisting>
	</example>
	</section>

	<section id="default_reason">
	<title><varname>default_reason</varname> (string)</title>
	<para>
		Default SIP reason phrase sent by <function>t_reply()</function> if it
		cannot retrieve its parameters (e.g. inexistent avp).
	</para>
	<para>
		Default value is "Server Internal Error".
	</para>
	<para>
		Can be set at runtime, e.g.:
		<programlisting>
	$ &sercmd; cfg.set_now_string tm default_reason "Unknown error"
		</programlisting>
	</para>
	<example>
		<title>Set <varname>default_reason</varname> parameter </title>
		<programlisting>
...
modparam("tm", "default_reason", "Unknown reason")
...
	    </programlisting>
	</example>
	</section>

	<section id="disable_6xx_block">
	<title><varname>disable_6xx_block</varname> (integer)</title>
	<para>
		If set tm will treat all the 6xx replies like normal replies 
		(warning: this would be non-rfc conformant behaviour).
	</para>
	<para>
		If not set (default) receiving a 6xx will cancel all the running
		parallel branches, will stop dns failover and forking. However
		serial forking using <function>append_branch()</function> in the
		<function>failure_route</function> will still work.
	</para>
	<para>
		It can be overwritten on a per transaction basis using
		<function>t_set_disable_6xx()</function>.
	</para>
	<para>
		Default value is 0 (off, rfc conformant behaviour).
	</para>
	<para>
		Can be set at runtime, e.g.:
		<programlisting>
	$ &sercmd; cfg.set_now_int tm disable_6xx_block 0
		</programlisting>
	</para>
	<para>
		See also: <function>t_set_disable_6xx()</function>.
	</para>
	<example>
		<title>Set <varname>disable_6xx_block</varname> parameter</title>
		<programlisting>
...
modparam("tm", "disable_6xx_block", 1)
...
	    </programlisting>
	</example>
	</section>

<section id="local_ack_mode">
	<title><varname>local_ack_mode</varname> (integer)</title>
	<para>
		It controls where locally generated ACKs for 2xx replies to local
		transactions (transactions created via <function>t_uac*()</function>
		either thorugh the tm api or via RPC/mi/fifo) are sent.
	</para>
	<para> It has 3 possible values:</para>
	<itemizedlist>
		<listitem><para>
		<emphasis>0</emphasis> - the ACK destination is choosen according to
		the rfc: the next hop is found using the contact and the route set and
		then DNS resolution is used on it.
		</para></listitem>
		<listitem><para>
		<emphasis>1</emphasis> - the ACK is sent to the same address as the
		corresponding INVITE branch.
		</para></listitem>
		<listitem><para>
		<emphasis>2</emphasis> - the ACK is sent to the source of the 2xx
		reply.
		</para></listitem>
	</itemizedlist>
	<note><para>
	Mode 1 and 2 break the rfc, but are useful to deal with some simple UAs
	behind the NAT cases (no different routing for the ACK and the contact 
	contains an address behind the NAT).
	</para></note>
	<para>
		The default value is 0 (rfc conformant behaviour).
	</para>
	<para>
		Can be set at runtime, e.g.:
		<programlisting>
	$ &sercmd; cfg.set_now_int tm local_ack_mode 0
		</programlisting>
	</para>
	<example>
		<title>Set <varname>local_ack_mode</varname> parameter</title>
		<programlisting>
...
modparam("tm", "local_ack_mode", 1)
...
	    </programlisting>
	</example>
	</section>
	
	<section id="failure_reply_mode">
	<title><varname>failure_reply_mode</varname> (integer)</title>
	<para>
		It controls how branches are managed and replies are selected for
		failure_route handling: keep all, drop all, drop last branches in
		SIP serial forking handling.
	</para>
	<para>
		To control per transaction see <function>t_drop_replies()</function>.
	</para>
	<para> It has 4 possible values:</para>
	<itemizedlist>
		<listitem><para>
		<emphasis>0</emphasis> - all branches are kept, no matter a new leg of
		serial forking has been started. Beware that if the new leg fails, you
		may get in failure_route a reply code from a branch of previous serial
		forking legs (e.g., if in first leg you got a 3xx, then you handled
		the redirection in failure route, sent to a new destination and this
		one timeout, you will get again the 3xx). Use t_drop_replies() on per
		transaction fashion to control the behavior you want. It is the
		default behaviour comming from SER 2.1.x.
		</para></listitem>
		<listitem><para>
		<emphasis>1</emphasis> - all branches are discarded by default. You
		can still overwrite the behaviour via t_drop_replies()
		</para></listitem>
		<listitem><para>
		<emphasis>2</emphasis> - by default only the branches of previous leg
		of serial forking are discarded
		</para></listitem>
		<listitem><para>
		<emphasis>3</emphasis> - all previous branches are discarded if there
		is a new serial forking leg. This is the default behaviour coming from
		Kamailio 1.5.x. Use this mode if you don't want to handle in a per
		transaction fashion with t_drop_replies(). It ensures that you will
		get the winning reply from the branches of last serial forking step
		(e.g., if in first step you get 3xx, then you forward to a new
		destination, you will get in failure_route the reply coming from that
		destination or a local timeout).
		</para></listitem>
	</itemizedlist>
	<para>
		The default value is 3.
	</para>
	<example>
		<title>Set <varname>failure_reply_mode</varname> parameter</title>
		<programlisting>
...
modparam("tm", "failure_reply_mode", 0)
...
	    </programlisting>
	</example>
	</section>

	<section id="faked_reply_prio">
	<title><varname>faked_reply_prio</varname> (integer)</title>
	<para>
		It controls how branch selection is done. It allows to give a penalty
		to faked replies such as the infamous 408 on branch timeout.
	</para>
	<para>
		Internally, every reply is assigned a priority between 0 (high prio) 
		and 32000 (low prio). With this parameter the priority of fake replies
		can be adjusted.
	</para>
	<itemizedlist>
		<listitem><para>
		<emphasis>0</emphasis> - disabled (default)
		</para></listitem>
		<listitem><para>
		<emphasis>&lt; 0</emphasis> - priority is increased by given amount.
		</para></listitem>
		<listitem><para>
		<emphasis>&gt; 0</emphasis> - priority is decreased by given amount.
		Do not make it higer than 10000 or faked replies will even loose
		from 1xx clsss replies.
		</para></listitem>
	</itemizedlist>
	<para>
		The default value is 0.
	</para>
	<para>
		To let received replies win from a locally generated 408, set this
		value to 2000.
	</para>
	<example>
		<title>Set <varname>faked_reply_prio</varname> parameter</title>
		<programlisting>
...
modparam("tm", "faked_reply_prio", 2000)
...
	    </programlisting>
	</example>
	</section>

	<section id="local_cancel_reason">
		<title><varname>local_cancel_reason</varname> (boolean)</title>
		<para>
			Enables/disables adding reason headers (RFC 3326) for CANCELs
			generated due to receiving a final reply. The reason header added
			will look like: "Reason: SIP;cause=&lt;final_reply_code&gt;".
		</para>
		<para>
			Default value is 1 (enabled).
		</para>
		<para>
			Can be set at runtime, e.g.:
			<programlisting>
	$ &sercmd; cfg.set_now_int tm local_cancel_reason 0
			</programlisting>
		</para>
		<para>
			See also: <varname>e2e_cancel_reason</varname>.
		</para>
		<example>
			<title>Set <varname>local_cancel_reason</varname> parameter</title>
			<programlisting>
...
modparam("tm", "local_cancel_reason", 0)
...
			</programlisting>
		</example>
	</section>


	<section id="e2e_cancel_reason">
		<title><varname>e2e_cancel_reason</varname> (boolean)</title>
		<para>
			Enables/disables adding reason headers (RFC 3326) for CANCELs
			generated due to a received CANCEL.  If enabled the reason headers
			from received CANCELs will be copied into the generated hop-by-hop
			CANCELs.
		</para>
		<para>
			Default value is 1 (enabled).
		</para>
		<para>
			Can be changed at runtime, e.g.:
			<programlisting>
	$ &sercmd; cfg.set_now_int tm e2e_cancel_reason 0
			</programlisting>
		</para>
		<para>
			See also: <function>t_set_no_e2e_cancel_reason()</function> and
						<varname>local_cancel_reason</varname>.
		</para>
		<example>
			<title>Set <varname>e2e_cancel_reason</varname> parameter</title>
			<programlisting>
...
modparam("tm", "e2e_cancel_reason", 0)
...
			</programlisting>
		</example>
	</section>

	<section id="remap_503_500">
		<title><varname>remap_503_500</varname> (boolean)</title>
		<para>
			Enables/disables conversion of 503 response code to 500. By default
			it is enabled, based on the SIP RFC requirement. This is global
			setting for all received replies handled by TM. To do it per
			transaction basis, let this option disabled, set a failure route
			and then do t_reply("500", "...") inside it.
		</para>
		<para>
			Default value is 1 (enabled).
		</para>
		<example>
			<title>Set <varname>remap_503_500</varname> parameter</title>
			<programlisting>
...
modparam("tm", "remap_503_500", 0)
...
			</programlisting>
		</example>
	</section>

	<section id="tm.p.failure_exec_mode">
		<title><varname>failure_exec_mode</varname> (boolean)</title>
		<para>
			Add local failed branches in timer to be cosidered for failure
			routing blocks. If disabled, relay functions will return false
			in case the branch could not be forwarded (default behaviour
			before v4.1.0).
		</para>
		<para>
			Default value is 0 (disabled).
		</para>
		<example>
			<title>Set <varname>failure_exec_mode</varname> parameter</title>
			<programlisting>
...
modparam("tm", "failure_exec_mode", 1)
...
			</programlisting>
		</example>
	</section>


	<section id="tm.p.dns_reuse_rcv_socket">
		<title><varname>dns_reuse_rcv_socket</varname> (boolean)</title>
		<para>
			Control reuse of the receive socket for additional branches added
			by dns failover. If set to 1, the receive socket is used for
			sending out the new branches, unless the socket is forced
			explicitely in configuration file. If set to 0, selected socket
			is done depending on value of global parameter mhomed (if mhomed=0,
			then the first listen socket is used, otherwise the socket is
			selected based on routing rules).
		</para>
		<para>
			Do enable it with caution, it might create troubles on dns results
			with different transport layer. Better let it disabled and enable
			mhomed.
		</para>
		<para>
			Default value is 0 (disabled).
		</para>
		<example>
			<title>Set <varname>dns_reuse_rcv_socket</varname> parameter</title>
			<programlisting>
...
modparam("tm", "dns_reuse_rcv_socket", 1)
...
			</programlisting>
		</example>
	</section>

</section>