nathelper_user.sgml

用来作为linux中SIP SERVER,完成VOIP网络电话中服务器的功能

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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.6.2.2 $</revnumber>
		<date>$Date: 2005/06/22 23:12:07 $</date>
	    </revision>
	</revhistory>
    </chapterinfo>
    <title>User's Guide</title>
    
    <section>
	<title>Overview</title>
	<para>
	    This is a module to help with &nat; traversal. In particular, it helps symmetric &ua;s
	    that don't advertise they are symmetric and are not able to determine their public
	    address. fix_nated_contact rewrites Contact header field with request's source
	    address:port pair. fix_nated_sdp adds the active direction indication to &sdp; (flag
	    0x01) and updates source &ip; address too (flag 0x02).
	</para>
	<para>
	    Known devices that get along over &nat;s with nathelper are ATAs (as clients) and Cisco
	    Gateways (since 12.2(T)) as servers.  See <ulink
	    url="http://www.cisco.com/en/US/products/sw/iosswrel/ps1839/products_feature_guide09186a0080110bf9.html">
		http://www.cisco.com/en/US/products/sw/iosswrel/ps1839/products_feature_guide09186a0080110bf9.html"></ulink>
	</para>
	
    </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>natping_interval</varname> (integer)</title>
	    <para>
		Period of time in seconds between sending short &udp; packets to all currently
		registered &ua;s to keep their &nat; bindings alive. Value of 0 disables this
		functionality.
	    </para>
	    <para>
		<emphasis>
		    Default value is 0.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>natping_interval</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("nathelper", "natping_interval", 10)
...
</programlisting>
	    </example>
	</section>
	<section>
	    <title><varname>ping_nated_only</varname> (integer)</title>
	    <para>
		If this variable is set then only contacts that have <quote>behind_NAT</quote> flag
		in user location database set set will get ping.
	    </para>
	    <para>
		<emphasis>
		    Default value is 0.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>ping_nated_only</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("nathelper", "ping_nated_only", 1)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>rtpproxy_sock</varname> (string)</title>
	    <para>
		The name of the socket for the communication between SER and RTPProxy.
	    </para>
	    <para>
		<emphasis>
		    Default value is "unix:/var/run/rtpproxy.sock".
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>rtpproxy_disable</varname> (integer)</title>
	    <para>
		This parameter can be used to disable communication with
		RTPproxy completely.
	    </para>
	    <para>
		<emphasis>
		    Default value is 0 (communication with RTPproxy enabled).
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>rtpproxy_disable_tout</varname> (integer)</title>
	    <para>
		This parameter controls the minimum interval between periodic
		attempts to establish communication with RTPProxy. SER
		periodically tries to establish communication with RTPProxy if
		it failed previously, for example due to wrong protocol version
		or RTPProxy not running. The value of -1 will disable peridic
		attempts to reach RTPproxy.
	    </para>
	    <para>
		<emphasis>
		    Default value is 60 s.
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>rtpproxy_retr</varname> (integer)</title>
	    <para>
		This parameter controls the number of attempts of SER to
		establish communication with RTPProxy.
	    </para>
	    <para>
		<emphasis>
		    Default value is 5 attempts.
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>rtpproxy_tout</varname> (integer)</title>
	    <para>
		The value of this parameter controls how long SER waits for a
		reply from RTPProxy.
	    </para>
	    <para>
		<emphasis>
		    Default value is 1 s.
		</emphasis>
	    </para>
	</section>

	<section>
	    <title><varname>received_avp</varname> (integer)</title>
	    <para>
		The number of the Attribute-Value-Pair (AVP) used to store the URI containing the
		received IP, port, and protocol. The URI is created by fix_nated_register function
		of nathelper module and the attribute is then used by the registrar to store the
		received parameters. Do not forget to change the value of corresponding parameter in
		registrar module if you change the value of this parameter.
	    </para>
	    <para>
		<emphasis>
		    Default value is 42.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>received_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("nathelper", "received_avp", 43)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>force_socket</varname> (string)</title>
	    <para>
		This parameter controls the socket that will be used to send
		NAT pings. This can be something like "udp:10.0.0.1:5060".
	    </para>
	    <para>
		<emphasis>
		    Default value is disabled.
		</emphasis>
	    </para>
	</section>
    </section>

    <section>
	<title>Exported Functions</title>
	<section>
	    <title>
		<function moreinfo="none">fix_nated_contact()</function>
	    </title>
	    <para>
		Rewrites Contact <acronym>HF</acronym> to contain request's source address:port.
	    </para>
	    <example>
		<title><function>fix_nated_contact</function> usage</title>
		<programlisting format="linespecific">
...
if (search("User-Agent: Cisco ATA.*") {fix_nated_contact();};
...
</programlisting>
	    </example>
	</section>
	<section>
	    <title>
		<function moreinfo="none">fix_nated_sdp(mode)</function>
	    </title>
	    <para>
		Rewrites Contact <acronym>HF</acronym> to contain request's source address:port.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para>
			<emphasis>mode</emphasis> - 0x01 (add direction=active), 0x02 (rewrite media
			&ip; address with source address of the message). The
			value of mode parameter is bitwise OR of the numbers
			(0x03 for both tests).
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>fix_nated_sdp</function> usage</title>
		<programlisting format="linespecific">
...
if (search("User-Agent: Cisco ATA.*") {fix_nated_sdp("3");};
...
</programlisting>
	    </example>
	</section>
	<section>
	    <title>
		<function moreinfo="none">force_rtp_proxy()</function>
	    </title>
	    <para>
		Rewrites &sdp; body to ensure that media is passed through an &rtp; proxy.
	    </para>
	    <example>
		<title><function>force_rtp_proxy</function> usage</title>
		<programlisting format="linespecific">
...
if (search("User-Agent: Cisco ATA.*") {force_rtp_proxy();};
...
</programlisting>
	    </example>
	</section>
	<section>
	    <title>
		<function moreinfo="none">add_rcv_param()</function>
	    </title>
	    <para>
		Add received parameter to Contact header fields. The parameter will contain URI
		created from the source IP, port, and protocol of the packet containing the SIP
		message. The parameter can be then processed by another registrar, this is useful,
		for example, when replicating register messages using t_replicate function to
		another registrar.
	    </para>
	    <example>
		<title><function>add_rcv_paramer</function> usage</title>
		<programlisting format="linespecific">
...
add_rcv_param();
...
</programlisting>
	    </example>
	</section>
	<section>
	    <title>
		<function moreinfo="none">fix_nated_register()</function>
	    </title>
	    <para>
		The function creates a URI consisting of the source IP, port, and protocol and
		stores the URI in an Attribute-Value-Pair. The URI will be appended as "received"
		parameter to Contact in 200 OK and registrar will store it in the user location database.
	    </para>
	    <example>
		<title><function>fix_nated_register</function> usage</title>
		<programlisting format="linespecific">
...
fix_nated_register();
...
</programlisting>
	    </example>
	</section>
	<section>
	    <title>
		<function
		moreinfo="none">force_rtp_proxy([options [, new_ip]])</function>
	    </title>
	    <para>
		Rewrites &sdp; body with given IP address to ensure that media is passed through an
		&rtp; proxy. The function accepts 0, 1, or 2
		parameters. Default value of options parameter is an empty
		string and default value of new_ip parameter is the destination
		IP of the SIP request.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para>
			<emphasis>options</emphasis> - String containing
			various options to control behavior of force_rtp_proxy
			function. Each option is represented by one character
			in the string. The function supports the following options:
		    </para>
		    <itemizedlist>
			<listitem>
			    <para> 
				<emphasis>A</emphasis> - The originator of the
				SIP message does not support symmetric RTP.
			    </para>
			</listitem>
			<listitem>
			    <para> 
				<emphasis>I</emphasis> - The originator of the
				SIP message is in the same LAN as
				RTPProxy. Useful when RTPProxy is running in
				bridging mode.
			    </para>
			</listitem>
			<listitem>
			    <para> 
				<emphasis>E</emphasis> - The originator of the
				SIP message is reachable through external
				interface, not LAN. Useful when RTPProxy is
				running in bridging mode.
			    </para>
			</listitem>
			<listitem>
			    <para> 
				<emphasis>L</emphasis> - Do not create a new
				session in RTPProxy, instead lookup existing
				sessions and rewrite SDP only if it
				exists. This is only useful for SIP requests,
				this flag is automatically enabled when the
				function is executed during reply processing
				(from onreply_route blocks).
			    </para>
			</listitem>
			<listitem>
			    <para> 
				<emphasis>F</emphasis> - This flag instructs
				nathelper to ignore marks inserted by another
				nathelper instance along the path of the
				message to indicate that the session is already
				passing through another RTPProxy. This allows
				chains of RTP proxies.
			    </para>
			</listitem>
			<listitem>
			    <para> 
				<emphasis>R</emphasis> - The IP in SDP should
				be trusted. Without this flag, nathelper would
				ignore address in SDP and use source address of
				the SIP message as media address which is
				passed to the RTPProxy.
			    </para>
			</listitem>
		    </itemizedlist>

		</listitem>
		<listitem>
		    <para>
			<emphasis>new_ip</emphasis> - Replace the IP address in
			SDP with the value of this parameter if present.
		    </para>
		</listitem>
	    </itemizedlist>

	    <example>
		<title><function>force_rtp_proxy</function> usage</title>
		<programlisting format="linespecific">
...
if (search("User-Agent: Cisco ATA.*") {
    force_rtp_proxy("IF", 1.2.3.4");
};
...
</programlisting>
	    </example>
	</section>
	<section>
		<title>
			<function>nat_uac_test(mode)</function>
		</title>
		<para>
			Tries to guess if client's request originated behind a nat.
			The parameter determines what heuristics is used. If flag 
			1 is set, the "received" test is used -- address in Via is 
			compared against source IP address of signaling. If flag
			2 is set, Contact header field is searched for occurrence
			of RFC1918 addresses. If flag 4 is set the address in Via is
			compared with "private" RFC1918 addresses. If flag 8 is set
			the ip in the SDP message body is compared with RFC1918 
			addresses. If flag 16 is set the rport test is used: the source 
			port of the message is compared with the source port advertised in
			Via (good to catch broken STUN implementations, but might cause
			problems for UAs with asymmetric signaling).
			All the  flags can be bitwise combined, the test returns true if
			any of the tests identified a NAT (e.g. nat_uac_test(19) will
			 return true if any of the received test, contact RFC1918 test or.
			 rport test are true).
		</para>
    </section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("nathelper.sgml" "Book" "chapter")
End:
-->