kamailio/modules/iptrtpproxy/doc/iptrtpproxy.xml

<?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="iptrtpproxy" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
	<authorgroup>
	    <author>
		<firstname>Tomas</firstname>
		<surname>Mandys</surname>
		<affiliation><orgname>Iptel.org</orgname></affiliation>
		<address>
		    <email>tomas dot mandys at iptel dot org</email>
		</address>
	    </author>
	</authorgroup>
	<copyright>
	    <year>2007</year>
	    <holder>Tomas Mandys</holder>
	</copyright>

    </sectioninfo>

    <title>Iptrtpproxy module</title>

    <section id="iptrtpproxy.overview">
	<title>Overview</title>
	<para>
	It provides similar functionality as <emphasis>nathelper</emphasis> but
	communicates with <emphasis>netfilter</emphasis> kernel <emphasis>xt_RTPPROXY</emphasis> module using
	<emphasis>libipt_RTPPROXY</emphasis> userspace library. 
	See <ulink url="http://www.2p.cz/en/netfilter_rtp_proxy">http://www.2p.cz/en/netfilter_rtp_proxy</ulink>
	All RTP streams are 
	manipulated directly in kernel space, no data is copied from 
	kernel to userspace and back, it reduces load and delay. 
	See <ulink url="http://www.2p.cz/en/netfilter_rtp_proxy">
	http://www.2p.cz/en/netfilter_rtp_proxy</ulink> for more details.
	</para>

	<para>
	The ser module is written as light-weighted, there is not implemented
	any dialog managment as in <emphasis>nathelper</emphasis>, the reason is that such an API
	should be provided by core or specialized dialog manager module.
	Because such module is not in CVS, session information may be stored 
	in extra attributes of <emphasis>avp_db</emphasis> module and
	session id itself in record route as cookie, see <emphasis>rr</emphasis> module.
	</para>

	<para>
	It should be able to support all cases as re-invites when SIP client offers media change in SDP and
	when number of medias in offer/answer are different. 
	</para>

	<para>
	<emphasis>Nathelper</emphasis> may be still used for testing if client is behind the NAT.
	</para>

	<para>
	There is also support for media authorization. Number of codec sets may be defined. When a message containing 
	SDP offer/answer is being processed then current codecs and streams may be inspected, removed or signallized
	according a codec set.
	</para>


	<para>
	Limitations:
	<itemizedlist>
		<listitem>
			<para>
		 only IPv4 addresses are supported.
			</para>
		</listitem>
		<listitem>
			<para>
		 more media streams per session supported
			</para>
		</listitem>
	</itemizedlist>
	</para>
    </section>

	<section id="iptrtpproxy.dep">
	<title>Dependencies</title>
				   
	<para>
	The following libraries or applications must be installed before
	running SER with this module loaded:
	<itemizedlist>
		<listitem>
		<para>
		netfilter xt_RTPPROXY &amp; libipt_RTPPROXY,
	    see <ulink url="http://www.2p.cz/en/netfilter_rtp_proxy">http://www.2p.cz/en/netfilter_rtp_proxy</ulink>
		</para>
		</listitem>
	</itemizedlist>
	</para>
	<note><para>
	The module Makefile must be edited and iptdir setup to the directory with
	the iptable sources (if different from ~/iptables). Alternatively
	compile the module using: 
	<programlisting>
		make -C modules/iptrtpproxy iptdir=path_to_iptables_src
	</programlisting>
	</para></note>
	</section>


	<xi:include href="params.xml"/>
    <xi:include href="functions.xml"/>


	<section>
		<title>Selects</title>

		<section id="iptrtpproxy.session_ids">
		<title>
			<function>@iptrtpproxy.session_ids</function>
		</title>
		<para>
		Returns sessions allocated/updated in <function>iptrtpproxy_alloc/update</function>.
		</para>

		<para>
		The format is:
		</para>

		<programlisting>

	switchboard_name [ ":" [ session_id "/" created ] * ( "," session_id "/" created ) ] ]
	session_id = * ( [0-9] )   ; empty when no session allocated
	created = timestamp
		</programlisting>

		</section>

		<section id="iptrtpproxy.sdp_ip">
		<title>
			<function>@iptrtpproxy.sdp_ip</function>
		</title>
		<para>
		Return first rewritten IP provided at SDP <emphasis>c=</emphasis> line.
		</para>
		</section>

		<section id="iptrtpproxy.o_name">
		<title>
			<function>@iptrtpproxy.o_name</function>
		</title>
		<para>
		Return username from original <emphasis>o=</emphasis> line.
		</para>
		</section>

		<section id="iptrtpproxy.o_addr">
		<title>
			<function>@iptrtpproxy.o_addr</function>
		</title>
		<para>
		Return address from original <emphasis>o=</emphasis> line.
		</para>
		</section>

		<section id="iptrtpproxy.auth_rights">
		<title>
			<function>@iptrtpproxy.auth_rights</function>
		</title>
		<para>
		Result of <function>iptrtpproxy_authorize_media</function>.
		</para>
		</section>

		<section id="iptrtpproxy.active_media_num">
		<title>
			<function>@iptrtpproxy.active_media_num</function>
		</title>
		<para>
		Returns number of active media streams in SDP. <function>iptrtpproxy_authorize_media</function>
		may disable some streams, i.e. returned value may change after authorization.
		</para>
		</section>

	</section>

</section>