nathelper_user.sgml

sip server服务器

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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.6 $</revnumber>
		<date>$Date: 2004/09/05 15:39:02 $</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>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>
    <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>
    <section>
	<title>Exported Functions</title>
	<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).
		    </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(ip_address)</function>
	    </title>
	    <para>
		Rewrites &sdp; body with given IP address to ensure that media is passed through an
		&rtp; proxy.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para>
			<emphasis>ip_address</emphasis> - new SDP IP address.
		    </para>
		</listitem>
	    </itemizedlist>

	    <example>
		<title><function>force_rtp_proxy</function> usage</title>
		<programlisting format="linespecific">
...
if (search("User-Agent: Cisco ATA.*") {force_rtp_proxy("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. Both flags can be bitwise combined,
			the test returns true if any of the tests identified a NAT.
		</para>
    </section>
</chapter>

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