mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
380 lines
11 KiB
380 lines
11 KiB
<?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>
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>$Revision$</revnumber>
|
|
<date>$Date$</date>
|
|
</revision>
|
|
</revhistory>
|
|
|
|
</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.
|
|
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 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>
|
|
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_RTPROXY & 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>.
|
|
</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 = "name" | "*" | ( "ringing-timeout " ) | ( ( "learning-timeout-" | "always-learn-") ("a" | "b") )
|
|
</programlisting>
|
|
|
|
<para>
|
|
The meaning of parameters is described in <emphasis>libipt_RTPROXY</emphasis> and <emphasis>iptrtpproxy</emphasis> documentation.
|
|
<emphasis>ringing timeout</emphasis> is explicit timeout in sec regarding ringing. Ringing requires manual callee action, i.e.
|
|
it may takes long time. Default value is 60 sec.
|
|
</para>
|
|
<para>
|
|
The <emphasis>name</emphasis>" is identifier that will be used by script functions and references switchboard.
|
|
It's mandatory parameter. More switchboards may be declared. The special name <emphasis>*</emphasis> set values
|
|
for all switchboards.
|
|
</para>
|
|
<example>
|
|
<title>Declare <varname>switchboard</varname></title>
|
|
<programlisting>
|
|
...
|
|
modparam("iptrtpproxy", "config", "/etc/iptrtpproxy.cfg");
|
|
modparam("iptrtpproxy", "switchboard", "name=*;learning-timeout-a=10;learning-timeout-b=10;ringing-timeout=90");
|
|
modparam("iptrtpproxy", "switchboard", "name=my;ringing-timeout=60");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="iptrtpproxy.functions">
|
|
<title>Functions</title>
|
|
|
|
<section id="iptrtpproxy_alloc">
|
|
<title>
|
|
<function>iptrtpproxy_alloc(gate_a_to_b, switchboard_id)</function>
|
|
</title>
|
|
<para>
|
|
Parses SDP content and allocates for each RTP media stream one RTP proxy session.
|
|
SDP is updates to reflect allocated sessions.
|
|
</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.
|
|
If bit 1 is set then <emphasis>ringing timeout</emphasis>
|
|
is used instead of <emphasis>learning timeout</emphasis> for
|
|
particular gate timeout.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>switchboard_id</emphasis> is reference to a switchboard with name declared as
|
|
<varname>switchboard</varname> modparam. If empty then use switchboard found by
|
|
<function>iptrtpproxy_find</function> (equal using <function>@iptrtpproxy.switchboard</function>).
|
|
</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_alloc("1", "my")) {
|
|
$sess_ids = @iptrtpproxy.session_ids;
|
|
# save sess_ids in dialog
|
|
}
|
|
...
|
|
</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>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
if <emphasis>gate_a_to_b</emphasis> bit 0 is set
|
|
then SDP regards to gate-a to gate-b direction.
|
|
If bit 1 is set then <emphasis>ringing timeout</emphasis>
|
|
is used instead of <emphasis>learning timeout</emphasis> for
|
|
particular gate timeout.
|
|
</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.
|
|
If bit 1 is set then <emphasis>ringing timeout</emphasis>
|
|
is used instead of <emphasis>learning timeout</emphasis> for
|
|
particular gate timeout.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>iptrtpproxy_adjust_timeout</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
# load $sess_ids from dialog
|
|
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.
|
|
</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_find">
|
|
<title>
|
|
<function>iptrtpproxy_find(gate_a, gate_b)</function>
|
|
</title>
|
|
<para>
|
|
Find corresponding switchboard and set <function>@iptrtpproxy.switchboard</function>
|
|
and <function>@iptrtpproxy.direction</function>.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
if <emphasis>gate_a/b</emphasis> switchboard identification
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
function returns true if switch was found
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>iptrtpproxy_find</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
if (iptrtpproxy_find("@received.ip", "@next_hop.src_ip")) {
|
|
if (iptrtpproxy_alloc("1", "")) {
|
|
$sess_ids = @iptrtpproxy.session_ids;
|
|
|
|
}
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</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 *( "," session_id) ] ]
|
|
session_id = *( [0-9] ) ; empty when no session allocated
|
|
</programlisting>
|
|
|
|
</section>
|
|
|
|
<section id="iptrtpproxy.sdp_ip">
|
|
<title>
|
|
<function>@iptrtpproxy.sdp_ip</function>
|
|
</title>
|
|
<para>
|
|
Return first rewritten IP provided in SDP <emphasis>c=</emphasis> line.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy.switchboard">
|
|
<title>
|
|
<function>@iptrtpproxy.switchboard</function>
|
|
</title>
|
|
<para>
|
|
Switchboard found by <function>iptrtpproxy_find</function>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy.direction">
|
|
<title>
|
|
<function>@iptrtpproxy.direction</function>
|
|
</title>
|
|
<para>
|
|
Direction determined by <function>iptrtpproxy_find</function>. 1..gate A->B, 0..gate B->A
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
</section>
|
|
|