tm_user.sgml

来自「性能优秀的SIP Proxy」· SGML 代码 · 共 1,224 行 · 第 1/3 页

<!-- Module User's Guide -->

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1.17 $</revnumber>
		<date>$Date: 2006/06/09 16:16:07 $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<para>
		<acronym>TM</acronym> module enables stateful processing of SIP 
		transactions. The main use of stateful logic, which is costly in 
		terms of memory and <acronym>CPU</acronym>, is some services 
		inherently need state. For example, transaction-based accounting 
		(module acc) needs to process transaction state as opposed to 
		individual messages, and any kinds of forking must be implemented 
		statefully. Other use of stateful processing is it trading
		<acronym>CPU</acronym> caused by retransmission processing for memory.
		That makes however only sense if <acronym>CPU</acronym> consumption 
		per request is huge. For example, if you want to avoid costly 
		<acronym>DNS</acronym> resolution for every retransmission of a 
		request to an unresolvable destination, use stateful mode. Then,
		only the initial message burdens server by <acronym>DNS</acronym> 
		queries, subsequent retransmissions will be dropped and will not 
		result in more processes blocked by <acronym>DNS</acronym> resolution.
		The price is more memory consumption and higher processing latency.
	</para>
	<para>
		From user's perspective, there are these major functions : t_relay, 
		t_relay_to_udp and t_relay_to_tcp. All of them setup transaction state,
		absorb retransmissions from upstream, generate downstream 
		retransmissions and correlate replies to requests. t_relay forwards 
		to current URI; (be it original request's URI or a URI changed by 
		some of URI-modifying functions, such as sethost). t_relay_to_udp and 
		t_relay_to_tcp forward to a specific address over UDP or TCP 
		respectively.
	</para>
	<para>
		In general, if <acronym>TM</acronym> is used, it copies clones of 
		received SIP messages in shared memory. That costs the memory and 
		also <acronym>CPU</acronym> time (memcpys, lookups, shmem locks, etc.)
		Note that non-<acronym>TM</acronym> functions operate over the 
		received message in private memory, that means that any core 
		operations will have no effect on statefully processed messages after 
		creating the transactional state. For example, calling record_route 
		<emphasis>after</emphasis> t_relay is pretty useless, as the 
		<acronym>RR</acronym> is added to privately held message whereas its
		<acronym>TM</acronym> clone is being forwarded.
	</para>
	<para>
		<acronym>TM</acronym> is quite big and uneasy to program--lot of 
		mutexes, shared memory access, malloc & free, timers--you really 
		need to be careful when you do anything. To simplify 
		<acronym>TM</acronym> programming, there is the instrument of 
		callbacks. The callback mechanisms allow programmers to register 
		their functions to specific event. See t_hooks.h for a list of 
		possible events.
	</para>
	<para>
		Other things programmers may want to know is UAC--it is a very 
		simplistic code which allows you to generate your own transactions. 
		Particularly useful for things like NOTIFYs or <acronym>IM</acronym> 
		gateways. The UAC takes care of all the transaction machinery: 
		retransmissions , FR timeouts, forking, etc.  See t_uac prototype 
		in uac.h for more details. Who wants to see the transaction result 
		may register for a callback.
	</para>
	<section id="branch-flags">
		<title>Per-Branch flags</title>
		<para>
		First what is the idea with the branch concept: branch route is a 
		route to be execute separately for each branch before being sent 
		out - changes in that route should reflect only on that branch.
		</para>
		<para>
		There are two types of flags in &ser; :
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>global</emphasis> flags - global because they are 
				visible everywhere in the transaction (in all routes and in 
				all sequential replies/request).
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>branch</emphasis> flags - flags that are visible only
				from a specific branch - in all replies and routes connected 
				to this branch.
			</para>
			</listitem>
			</itemizedlist>
		<para>
		For example: I have a call parallel forking to GW and to a user. And I 
		would like to know from which branch I will get the final negative 
		reply (if so). I will set a branch route before relaying the calls 
		(with the 2 branches). The branch route will be separately executed for 
		each branch; in the branch going to GW (I can identified it by looking 
		to RURI), I will set a branch flag. This flag will appear only in the 
		onreply route run for replied from GW. It will be also be visible in 
		failure route if the final elected reply belongs to the GW branch. 
		This flags will not be visible in the other branch (in routes executing 
		replies from the other branch).
		</para>
		<para>
		For how to define branch flags and use via script, see 
		<xref linkend="branch-flag-mask"> and <xref linkend="branch-route">.
		</para>
		<para>
		Also, modules may set branch flags before transaction creation 
		(for the moment this feature is not available in script). The REGISTRAR 
		module is the first to use this feature. If the 
		<quote>use_branch_flags</quote> param is enabled, the NAT flag will be 
		push in branch flags instead in message flags - IMPORTANT: be sure that 
		NAT flag is in the range of the branch flags ad defined in TM. Using 
		this, NAT traversal per branch may be implemented.
		</para>
	</section>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&ser; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &ser; modules</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before 
		running &ser; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Exported Parameters</title>
	<section>
		<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 seconds).
		</para>
		<para>
		<emphasis>
			Default value is 30 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fr_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "fr_timer", 10)
...
</programlisting>
		</example>
	</section>

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

	<section>
		<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>
		<emphasis>
			Default value is 5 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>wt_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "wt_timer", 10)
...
</programlisting>
		</example>
	</section>

	<section>
		<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>
		<emphasis>
			Default value is 2 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>delete_timer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "delete_timer", 5)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>retr_timer1p1</varname> (integer)</title>
		<para>
		Retransmission period.
		</para>
		<para>
		<emphasis>
			Default value is 1 second.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>retr_timer1p1</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer1p1", 2)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>retr_timer1p2</varname> (integer)</title>
		<para>
		Retransmission period.
		</para>
		<para>
		<emphasis>
			Default value is 2 * <varname>retr_timer1p1</varname> second.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>retr_timer1p2</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer1p2", 4)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>retr_timer1p3</varname> (integer)</title>
		<para>
		Retransmission period.
		</para>
		<para>
		<emphasis>
			Default value is 4 * <varname>retr_timer1p1</varname> second.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>retr_timer1p4</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer1p3", 8)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>retr_timer2</varname> (integer)</title>
		<para>
		Maximum retransmission period.
		</para>
		<para>
		<emphasis>
			Default value is 4 seconds.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>retr_timer2</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "retr_timer2", 8)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>noisy_ctimer</varname> (integer)</title>
		<para>
		If set, on FR timer INVITE transactions will be explicitly canceled 
		if possible, silently dropped otherwise. Preferably, it is turned off 
		to allow very long ringing. This behavior is overridden if a request 
		is forked, or some functionality explicitly turned it off for a 
		transaction (like acc does to avoid unaccounted transactions due to 
		expired timer).
		</para>
		<para>
		<emphasis>
			Default value is 0 (false).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>noisy_ctimer</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "noisy_ctimer", 1)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>ruri_matching</varname> (integer)</title>
		<para>
		Should be request-uri matching used as a part of pre-3261 transaction
		matching as the standard wants us to do so? Turn only off for better 
		interaction with devices that are broken and send different r-uri in
		CANCEL/ACK than in original INVITE.
		</para>
		<para>
		<emphasis>
			Default value is 1 (true).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>ruri_matching</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "ruri_matching", 0)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>via1_matching</varname> (integer)</title>
		<para>
		Should be top most VIA matching used as a part of pre-3261 transaction
		matching as the standard wants us to do so? Turn only off for better 
		interaction with devices that are broken and send different top most
		VIA in CANCEL/ACK than in original INVITE.
		</para>
		<para>
		<emphasis>
			Default value is 1 (true).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>via1_matching</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tm", "via1_matching", 0)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>unix_tx_timeout</varname> (integer)</title>
		<para>
		Send timeout to be used by function which use UNIX sockets 
		(as t_write_unix).
		</para>
		<para>
		<emphasis>
			Default value is 2 seconds.
		</emphasis>