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 are 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>

	<section id="iptrtpproxy.parameters">

		<title>Parameters</title>

		<section id="config">
		<title><varname>config</varname> (string)</title>
		<para>
  References <emphasis>iptrtpproxy.cfg</emphasis>, see <emphasis>iptrtpproxy_helper</emphasis>. Default value
		is <emphasis>/etc/iptrtpproxy.cfg</emphasis>. If only codec authorization is to be used then 
		<emphasis>/dev/null</emphasis> may be used.
		</para>
		</section>

		<section id="switchboard">
		<title><varname>switchboard</varname> (string)</title>
		<para>
  References <emphasis>xt_RTPPROXY</emphasis> switchboard for usage by ser module. 
		</para>
		<para>
		The format is:
		</para>
			<programlisting>
  "name=" value * ( ";" name "=" value )

  name =  "aggregation" | "sip-addr-" 
			</programlisting>

		<para>
  The <emphasis>name</emphasis> is the switchboard name as declared in config and will be used by script functions and references switchboard. 
  It's mandatory parameter. The special name <emphasis>*</emphasis> set values for all switchboards. 
		</para>
		<para>
  The <emphasis>sip-addr</emphasis> is address used by <function>iptrtpproxy_ser_param(by_sip_ip)</function> to find a switchboard for particular
  connection. If not explicitly configured then RTP switchboard gate address are used for this feature. 
		</para>
		<para>
The <emphasis>aggregation</emphasis> enables to aggregate more switchboards in cluster and to widden bandwidth.
Aggregation will take <emphasis>sip-addr</emphasis> from the first switchboard of its. 
		</para>
		<example>
			<title>Declare <varname>switchboard</varname></title>
			<programlisting>
	...
	modparam("iptrtpproxy", "config", "/etc/iptrtpproxy.cfg");
	modparam("iptrtpproxy", "switchboard", "name=my1;sip-addr-a=1.2.3.4;sip-addr-b=5.6.7.8");
	modparam("iptrtpproxy", "switchboard", "name=my2;sip-addr-a=2.3.4.5;sip-addr-b=3.4.5.6;aggregation=my23");
	modparam("iptrtpproxy", "switchboard", "name=my3;aggregation=my23");
	modparam("iptrtpproxy", "switchboard", "name=*;aggregation=my123");
	...
			</programlisting>
		</example>
		</section>

		<section id="rpc_heartbeat_timeout">
		<title><varname>rpc_heartbeat_timeout</varname> (int)</title>
		<para>
		Timeout in seconds used for rerequest remote RTP proxy via RPC command after preceeding error.
		In other words if a RPC server is unresponsive at the moment then next attempt will be forced
		after this timeout. Default value is <emphasis>30</emphasis>.
		</para>
		</section>

		<section id="hostname">
		<title><varname>hostname</varname> (string)</title>
		<para>
		The hostname used by RPC to identify machine where Ser is running to communicate which RTP proxy
		via local interface. Default value is taken from system hostname.
		</para>
		</section>

		<section id="declare_codec">
		<title><varname>declare_codec</varname> (string)</title>
		<para>
		There are basic implicit codecs compiled in module, more codecs may be added by this parameter (one codec per modparam).
		</para>
		</section>

		<section id="codec_set">
		<title><varname>codec_set</varname> (string)</title>
		<para>
		Declares new codec set. Codecs are declared for each media type independently. 
		</para>
		<para>
		The format is:
		</para>
			<programlisting>
  "name=" value * ( ";" name "=" value )

  name =  "media_type" | "rights" | "codecs" | "max_streams" | ( "rtp" | "rtcp" ) "_" ( "bytes" | "packets" )

  media_types = "audio" | "video" | "application" | "text" | "message" | "data" | "control" | "?" | "*"
			</programlisting>		

		<para>
  The <emphasis>name</emphasis> is the codec set name to be defined.
		</para>
		<para>
  The <emphasis>media_type</emphasis> belongs to type at <emphasis>m=</emphasis> SDP line. Question mark means
  "unknown media" type and asterisk "all media types".
		</para>
		<para>
  The <emphasis>max_streams</emphasis> defines how many streams (m= lines) is allowed per media type.
		</para>
		<para>
  The <emphasis>rights</emphasis> defines if particular codec is allowed <emphasis>0</emphasis>, disallowed, i.e. will be removed
  if bit AND operation with <function>remove_codec_mask</function> is non-zero or its presence will be signallized by <function>@iptrtpproxy.auth_rights</function> (any other value).
		</para>
		<para>
  The <emphasis>codecs</emphasis> comma separated list of codecs. Previous <emphasis>media_type&amp;rights</emphasis> will be applied.
		</para>
		<para>
  The <emphasis>rtp/rtcp_bytes/packets</emphasis> limits bandwidth per <emphasis>media_type</emphasis> (0 is unlimited). It will override
  bandwidth limited by <function>iptrtpproxy_set_param("throttle_*")</function>.
		</para>
		<example>
			<title>Declare <varname>codec_set</varname></title>
			<programlisting>
	...
	# enable all codecs, default state when codec is declared
	modparam("iptrtpproxy", "codec_set", "name=cs1;media_type=*;max_streams=9999;rights=0;codecs=*");
	# allow only 2 audio and 1 video stream
	modparam("iptrtpproxy", "codec_set", "name=cs2;media_type=*;max_streams=0;media_type=audio;max_streams=2;media_type=video;max_streams=1");
	# dtto, allow only a few audio and video codecs, GSM codec is allowed but signallized
	modparam("iptrtpproxy", "codec_set", "name=cs3;media_type=*;max_streams=0;rights=1;codecs=*;media_type=audio;max_streams=2;rights=0;codecs=PCMU,G729,G728,parityfec,telephone-events;rights=2;codecs=GSM;media_type=video;max_streams=1;rights=0;codecs=jpeg,parityfec");
	# limit max. bandwidth for video¨	
	modparam("iptrtpproxy", "codec_set", "name=cs4;media_type=video;rtp_bytes=10000;rtcp_bytes=1000");
	...
			</programlisting>
		</example>
		</section>

	</section>

	<section id="iptrtpproxy.functions">
		<title>Functions</title>

		<section id="iptrtpproxy_alloc">
		<title>
			<function>iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])</function>
		</title>
		<para>
			Parses SDP content and allocates for each RTP media stream one RTP proxy session.
			SDP is updates to reflect allocated sessions. Switchboard/aggregation is set using
			<function>iptrtpproxy_set_param(by_sip_ip)</function> or <function>iptrtpproxy_set_param("switchboard/aggregation")</function>.
		</para>
		<para>
			Aggregation supports load balancing among more RTP proxies controlled by RPC.
			The module try to allocate at machines/switchboards in following order (priorities)
			not yet asked (or being heartbeated) machines, responsive machines, switchboards
			having percentualy more free slots, non responsive machines.
		</para>
		<para>
			Proxy may hide caller identity provided at <emphasis>o=</emphasis> line using
			<function>@iptrtpproxy.o_name/addr</function> and <function>iptrtpproxy_set_param(o_name/addr)</function>
			functions. But the script is responsible for rewritting to original values in
			a response or a callee initiated re-INVITE. Therefore original value need to be stored
			in-dialog.
		</para>
		<itemizedlist>
			<listitem>
			<para>
				if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
				then SDP regards to gate-a to gate-b direction.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>protected_session_ids</emphasis> list of existing sessions
				enables reusing already allocated sessions in re-INVITE without 
				allocating new sessions for each stream in SDP regardless a IP/port
				is required. It's mostly undesirable, typically "hold-on" is
				done via re-INVITE without any change. There is drawback because
				callee cannot change IP:port in 200OK which is legal case in RFC3264. 
				But because some non-RFC3264 compliant phones dislike proactively 
				changed IP:port at RTP proxy it seems it's less evil.
			</para>
			</listitem>
			<listitem>
			<para>
				function returns true is a session was created, identifier is available
				via select <function>@iptrtpproxy.session_ids</function>.
			</para>
			</listitem>
		</itemizedlist>
		<example>
			<title><function>iptrtpproxy_alloc</function> usage</title>
			<programlisting>
	...
	if (!iptrtpproxy_set_param("aggregation_by_sip_ip_a", "@received.ip")) {
		if (!iptrtpproxy_set_param("switchboard_by_sip_ip_a", "@received.ip")) {
			t_reply("500", "RTP proxy error");
			drop;
		}
	}
	eval_push("x:%@next_hop.src_ip");
	if (@eval.get[-1] == @received.ip) {
		if (@iptrtpproxy.aggregation_a) {
			iptrtpproxy_set_param("aggregation_b", "@iptrtpproxy.aggregation_a");
		}
		else {
			iptrtpproxy_set_param("switchboard_b", "@iptrtpproxy.switchboard_a");
		}
	}
	else {
		if (!iptrtpproxy_set_param("aggregation_by_sip_ip_b", "@eval.get[-1]")) {
			if (!iptrtpproxy_set_param("switchboard_by_sip_ip_b", "@eval.get[-1]")) {
				t_reply("500", "RTP proxy error");
				drop;
			}
		}
	}
	eval_remove(-1, 1);
	
	if (!iptrtpproxy_alloc("1")) {
		t_reply("500", "RTP proxy error");
		drop;
	}
	$sess_ids = @iptrtpproxy.session_ids;
	...
			</programlisting>
		</example>
		</section>

		<section id="iptrtpproxy_update">
		<title>
			<function>iptrtpproxy_update(gate_a_to_b, session_ids)</function>
		</title>
		<para>
		Parses SDP content and updates sessions provided by <emphasis>session_ids</emphasis> and
		updates SDP. If succesfull then session_ids may be changed (in case e.g. media 
		stream has port zero particular session is released), the
		result of <function>@iptrtpproxy.session_ids</function> should be stored for future in-dialog usage.
		</para>
		<para>
			The SDP contect is also affected by <function>iptrtpproxy_set_param(o_name/addr)</function>
			functions. If a stream is deactivated in SDP then Sessions may be deleted unless 
			mentioned in <emphasis>protected_session_ids</emphasis>.
		</para>
		<itemizedlist>
			<listitem>
			<para>
				if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
				then SDP regards to gate-a to gate-b direction.
			</para>
			<para>
				if <emphasis>gate_a_to_b</emphasis> bit 1 is set 
				then SDP is updated only, no RTP session are affected.
				Should be used when handling retransmission in onreply route,
				retransmission replies are not eaten be tm module!
			</para>
			</listitem>
		</itemizedlist>
		<example>
			<title><function>iptrtpproxy_update</function> usage</title>
			<programlisting>
	...
	# load $sess_ids from dialog
	if (iptrtpproxy_update("0", $sess_ids)) {
	  $sess_ids = @iptrtpproxy.session_ids;
	  # save sess_ids in dialog
	}
	...
			</programlisting>
		</example>
		</section>

		<section id="iptrtpproxy_adjust_timeout">
		<title>
			<function>iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)</function>
		</title>
		<para>
		Adjust timeout for particular gate. It's useful in "200 OK"
		decrease timeout to learning timeout if INVITE has set (long) <emphasis>ringing timeout</emphasis>.
		</para>
		<itemizedlist>
			<listitem>
			<para>
				if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
				then it regards to gate-a to gate-b direction.
			</para>
			</listitem>
		</itemizedlist>
		<example>
			<title><function>iptrtpproxy_adjust_timeout</function> usage</title>
			<programlisting>
	...
	# load $sess_ids from dialog
	if (status=~"18[0-9]") {
		iptrtpproxy_set_param("learning_timeout", "60");
	}
	else {
		iptrtpproxy_set_param("learning_timeout", "5");
	}
	if (iptrtpproxy_adjust_timeout("0", $sess_ids)) {
	}
	...
			</programlisting>
		</example>
		</section>
		<section id="iptrtpproxy_delete">
		<title>
			<function>iptrtpproxy_delete(session_ids)</function>
		</title>
		<para>
		Delete sessions identified by <emphasis>session_ids</emphasis>. May be used when dialog is being
		destroyed (BYE) or when INVITE failed in failure route. If <emphasis>protected_session_ids</emphasis>
		list is provided then this set is excluded from sessions to be deleted.
		</para>
		<example>
			<title><function>iptrtpproxy_delete</function> usage</title>
			<programlisting>
	...
	# load $sess_ids from dialog
	iptrtpproxy_delete($sess_ids);
	...
			</programlisting>
		</example>
		</section>

		<section id="iptrtpproxy_authorize_media">
		<title>
			<function>iptrtpproxy_authorize_media()</function>
		</title>
		<para>
		Authorizes SDP media according currect <emphasis>codec_set</emphasis>. If bit AND operation 
		between rights in codec set and <function>remove_codec_mask</function> is non zero then
		such a codec are to be removed. The result may be obtained from
		<function>@iptrtpproxy.auth_rights</function> which returns max. right which has been applied when
		processing all codecs of enabled streams. <function>@iptrtpproxy.active_media_num</function> may
		be used to get info if some media stream is to be throttled.
		</para>
		<para>
		The function MUST NOT be called after <function>iptrtpproxy_alloc/update</function>! 
		But the function may be called several times to authorize using more codec sets.
		</para>
		<example>
			<title><function>iptrtpproxy_authorize_media</function> usage</title>
			<programlisting>
	...
	if (@iptrtpproxy.active_media_num == "0") break;
	iptrtpproxy_set_param("codec_set", "cs2");
	iptrtpproxy_set_param("remove_codec_mask", "1");
	if (!iptrtpproxy_authorize_media()) {
		t_reply("415", "Cannot authorize media");
		drop;
	}
	iptrtpproxy_set_param("codec_set", "cs3");
	if (!iptrtpproxy_authorize_media()) {
		t_reply("415", "Cannot authorize media");
		drop;
	}
	if (@iptrtpproxy.active_media_num == "0") {
		t_reply("488", "Not acceptable here");
		drop;
	}
	if (@iptrtpproxy.auth_rights == "2") {
		append_hf_value("Contact: &lt;sip:1.2.3.4&gt;");
		t_reply("301", "Redirect to transcoder");
		drop;

	}
	...
			</programlisting>
		</example>
		</section>

		<section id="iptrtpproxy_set_param">
		<title>
			<function>iptrtpproxy_set_param(param, value)</function>
		</title>
		<para>
			Set particular parameter needed mainly by <function>iptrtpproxy_alloc/update/adjust_timeout</function>.
			The paramter value is availble via <function>@iptrtpproxy.&lt;param&gt;</function>.
		</para>
		<itemizedlist>
			<listitem>
			<para>
				Supported parameters: <emphasis>expiration_timeout</emphasis>, <emphasis>ttl</emphasis>, <emphasis>learning_timeout</emphasis>, 
				<emphasis>always_flags</emphasis>,
				<emphasis>aggregation_a</emphasis>, <emphasis>aggregation_b</emphasis>, 
				<emphasis>switchboard_a</emphasis>, <emphasis>switchboard_b</emphasis>,
				<emphasis>throttle_mark</emphasis>,
				<emphasis>throttle_rtp_max_bytes</emphasis>, <emphasis>throttle_rtp_max_packets</emphasis>, 
				<emphasis>throttle_rtcp_max_bytes</emphasis>, <emphasis>throttle_rtcp_max_packets</emphasis>.
			</para>
			</listitem>
		</itemizedlist>
		</section>

		<section id="iptrtpproxy_set_param(by_sip_ip)">
		<title>
			<function>iptrtpproxy_set_param("(aggregation/switchboard)_by_sip_ip_(a/b)", sip_ip)</function>
		</title>
		<para>
			Find corresponding aggregation or switchboard and set 
			<function>@iptrtpproxy.aggregation_a/b</function> or <function>@iptrtpproxy.switchboard_a/b</function>.
			Switchboards/aggregations are compared against <emphasis>sip-addr</emphasis>, 
			it allow separate SIP and RTP traffic and RTP aggregation.
		</para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>sip_ip</emphasis> IP to be compared, typically <function>@received.ip</function>
				or <function>@next_hop.src_ip</function>.
			</para>
			</listitem>
			<listitem>
			<para>
				function returns true if switchboard/aggregation was found
			</para>
			</listitem>
		</itemizedlist>
		</section>

		<section id="iptrtpproxy_set_param(protected_session_ids)">
		<title>
			<function>iptrtpproxy_set_param("protected_session_ids", sess_ids)</function>
		</title>
		<para>
			Used for reusing sessions in <function>iptrtpproxy_alloc</function>,  <function>iptrtpproxy_update</function>
			and <function>iptrtpproxy_delete</function>.
		</para>
		</section>

		<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_set_param(o_name)">
		<title>
			<function>iptrtpproxy_set_param("o_name", value)</function>
		</title>
		<para>
		Username to be rewritten at <emphasis>o=</emphasis> line by <function>iptrtpproxy_alloc/update</function> 
		to hide caller identity. If value is blank then username is left unchanged.
		</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_set_param(o_addr)">
		<title>
			<function>iptrtpproxy_set_param("o_addr", value)</function>
		</title>
		<para>
		Address to be rewritten at <emphasis>o=</emphasis> line by <function>iptrtpproxy_alloc/update</function> 
		to hide caller identity. If value is blank then address is left unchanged.
		</para>
		</section>

		<section id="iptrtpproxy_set_param(codec_set)">
		<title>
			<function>iptrtpproxy_set_param("codec_set", value)</function>
		</title>
		<para>
		Codec set for <function>iptrtpproxy_authorize_media</function>. Current codec set
		may be obtained by <function>@iptrtpproxy.codec_set</function>.
		</para>
		</section>

		<section id="iptrtpproxy_set_param(remove_codec_mask)">
		<title>
			<function>iptrtpproxy_set_param("remove_codec_mask", value)</function>
		</title>
		<para>
		Mask used in <function>iptrtpproxy_authorize_media</function>. Current mask 
		may be obtained by <function>@iptrtpproxy.remove_codec_mask</function>.
		</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 id="iptrtpproxy.auth_throttling">
		<title>
			<function>@iptrtpproxy.auth_throttling</function>
		</title>
		<para>
		Returns 1 if <function>iptrtpproxy_authorize_media</function> detected that some media stream is to be throttled.
		In this case RTP proxy should be applied.
		</para>
		</section>
	</section>

</section>