7c9e039e00646b78d597c46d8894c0efbf4cdad4
[sip-router] / modules_s / iptrtpproxy / doc / iptrtpproxy.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
3    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <section id="iptrtpproxy" xmlns:xi="http://www.w3.org/2001/XInclude">
6     <sectioninfo>
7         <authorgroup>
8             <author>
9                 <firstname>Tomas</firstname>
10                 <surname>Mandys</surname>
11                 <affiliation><orgname>Iptel.org</orgname></affiliation>
12                 <address>
13                     <email>tomas dot mandys at iptel dot org</email>
14                 </address>
15             </author>
16         </authorgroup>
17         <copyright>
18             <year>2007</year>
19             <holder>Tomas Mandys</holder>
20         </copyright>
21         <revhistory>
22             <revision>
23                 <revnumber>$Revision$</revnumber>
24                 <date>$Date$</date>
25             </revision>
26         </revhistory>
27
28     </sectioninfo>
29
30     <title>Iptrtpproxy module</title>
31
32     <section id="iptrtpproxy.overview">
33         <title>Overview</title>
34         <para>
35         It provides similar functionality as <emphasis>nathelper</emphasis> but
36         communicates with <emphasis>netfilter</emphasis> kernel <emphasis>xt_RTPPROXY</emphasis> module using
37         <emphasis>libipt_RTPPROXY</emphasis> userspace library. 
38         See <ulink url="http://www.2p.cz/en/netfilter_rtp_proxy">http://www.2p.cz/en/netfilter_rtp_proxy</ulink>
39         All RTP streams are 
40         manipulated directly in kernel space, no data are copied from 
41         kernel to userspace and back, it reduces load and delay. 
42         </para>
43
44         <para>
45         The ser module is written as light-weighted, there is not implemented
46         any dialog managment as in <emphasis>nathelper</emphasis>, the reason is that such API
47         should be provided by core or specialized dialog manager module.
48         Because such module is not in CVS, session information may be stored 
49         in extra attributes of <emphasis>avp_db</emphasis> module and
50         session id itself in record route as cookie, see <emphasis>rr</emphasis> module.
51         </para>
52
53         <para>
54         It should be able to support all cases as re-invites when SIP client offers media change in SDP and
55         when number of medias in offer/answer are different. 
56         </para>
57
58         <para>
59         <emphasis>Nathelper</emphasis> may be still used for testing if client is behind the NAT.
60         </para>
61
62
63         <para>
64         Limitations:
65         <itemizedlist>
66                 <listitem>
67                         <para>
68                  only IPv4 addresses are supported.
69                         </para>
70                 </listitem>
71                 <listitem>
72                         <para>
73                  more media streams per session supported
74                         </para>
75                 </listitem>
76         </itemizedlist>
77         </para>
78     </section>
79
80         <section id="iptrtpproxy.dep">
81         <title>Dependencies</title>
82                                    
83         <para>
84         The following libraries or applications must be installed before
85         running SER with this module loaded:
86         <itemizedlist>
87                 <listitem>
88                 <para>
89                 netfilter xt_RTPROXY &amp; libipt_RTPPROXY,
90             see <ulink url="http://www.2p.cz/en/netfilter_rtp_proxy">http://www.2p.cz/en/netfilter_rtp_proxy</ulink>
91                 </para>
92                 </listitem>
93         </itemizedlist>
94         </para>
95         </section>
96
97         <section id="iptrtpproxy.parameters">
98
99                 <title>Parameters</title>
100
101                 <section id="config">
102                 <title><varname>config</varname> (string)</title>
103                 <para>
104   References <emphasis>iptrtpproxy.cfg</emphasis>, see <emphasis>iptrtpproxy_helper</emphasis>. Default value
105                 is <emphasis>/etc/iptrtpproxy.cfg</emphasis>.
106                 </para>
107                 </section>
108
109                 <section id="switchboard">
110                 <title><varname>switchboard</varname> (string)</title>
111                 <para>
112   References <emphasis>xt_RTPPROXY</emphasis> switchboard for usage by ser module. 
113                 </para>
114                 <para>
115                 The format is:
116                 </para>
117                         <programlisting>
118   name "=" value * ( ";" name "=" value )
119
120   name =  "name" | "*" | ( "ringing-timeout " ) | ( ( "learning-timeout-" | "always-learn-") ("a" | "b") )
121                         </programlisting>
122
123                 <para>
124   The meaning of parameters is described in <emphasis>libipt_RTPROXY</emphasis> and <emphasis>iptrtpproxy</emphasis> documentation.
125   <emphasis>ringing timeout</emphasis> is explicit timeout in sec regarding ringing. Ringing requires manual callee action, i.e.
126   it may takes long time. Default value is 60 sec.
127                 </para>
128                 <para>
129   The <emphasis>name</emphasis>" is identifier that will be used by script functions and references switchboard. 
130   It's mandatory parameter. More switchboards may be declared. The special name <emphasis>*</emphasis> set values
131   for all switchboards.
132                 </para>
133                 <example>
134                         <title>Declare <varname>switchboard</varname></title>
135                         <programlisting>
136         ...
137         modparam("iptrtpproxy", "config", "/etc/iptrtpproxy.cfg");
138         modparam("iptrtpproxy", "switchboard", "name=*;learning-timeout-a=10;learning-timeout-b=10;ringing-timeout=90");
139         modparam("iptrtpproxy", "switchboard", "name=my;ringing-timeout=60");
140         ...
141                         </programlisting>
142                 </example>
143                 </section>
144
145         </section>
146
147         <section id="iptrtpproxy.functions">
148                 <title>Functions</title>
149
150                 <section id="iptrtpproxy_alloc">
151                 <title>
152                         <function>iptrtpproxy_alloc(gate_a_to_b, switchboard_id)</function>
153                 </title>
154                 <para>
155                         Parses SDP content and allocates for each RTP media stream one RTP proxy session.
156                         SDP is updates to reflect allocated sessions.
157                 </para>
158                 <itemizedlist>
159                         <listitem>
160                         <para>
161                                 if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
162                                 then SDP regards to gate-a to gate-b direction.
163                                 If bit 1 is set then <emphasis>ringing timeout</emphasis>
164                                 is used instead of <emphasis>learning timeout</emphasis> for
165                                 particular gate timeout.
166                         </para>
167                         </listitem>
168                         <listitem>
169                         <para>
170                                 <emphasis>switchboard_id</emphasis> is reference to a switchboard with name declared as
171                                 <varname>switchboard</varname> modparam. If empty then use switchboard found by
172                                 <function>iptrtpproxy_find</function> (equal using <function>@iptrtpproxy.switchboard</function>).
173                         </para>
174                         </listitem>
175                         <listitem>
176                         <para>
177                                 function returns true is a session was created, identifier is available
178                                 via select <function>@iptrtpproxy.session_ids</function>.
179                         </para>
180                         </listitem>
181                 </itemizedlist>
182                 <example>
183                         <title><function>iptrtpproxy_alloc</function> usage</title>
184                         <programlisting>
185         ...
186         if (iptrtpproxy_alloc("1", "my")) {
187           $sess_ids = @iptrtpproxy.session_ids;
188           # save sess_ids in dialog
189         }
190         ...
191                         </programlisting>
192                 </example>
193                 </section>
194
195                 <section id="iptrtpproxy_update">
196                 <title>
197                         <function>iptrtpproxy_update(gate_a_to_b, session_ids)</function>
198                 </title>
199                 <para>
200                 Parses SDP content and updates sessions provided by <emphasis>session_ids</emphasis> and
201                 updates SDP. If succesfull then session_ids may be changed (in case e.g. media 
202                 stream has port zero particular session is released), the
203                 result of <function>@iptrtpproxy.session_ids</function> should be stored for future in-dialog usage.
204                 </para>
205                 <itemizedlist>
206                         <listitem>
207                         <para>
208                                 if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
209                                 then SDP regards to gate-a to gate-b direction.
210                                 If bit 1 is set then <emphasis>ringing timeout</emphasis>
211                                 is used instead of <emphasis>learning timeout</emphasis> for
212                                 particular gate timeout.
213                         </para>
214                         </listitem>
215                 </itemizedlist>
216                 <example>
217                         <title><function>iptrtpproxy_update</function> usage</title>
218                         <programlisting>
219         ...
220         # load $sess_ids from dialog
221         if (iptrtpproxy_update("0", $sess_ids)) {
222           $sess_ids = @iptrtpproxy.session_ids;
223           # save sess_ids in dialog
224         }
225         ...
226                         </programlisting>
227                 </example>
228                 </section>
229
230                 <section id="iptrtpproxy_adjust_timeout">
231                 <title>
232                         <function>iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)</function>
233                 </title>
234                 <para>
235                 Adjust timeout for particular gate. It's useful in "200 OK"
236                 decrease timeout to learning timeout if INVITE has set (long) <emphasis>ringing timeout</emphasis>.
237                 </para>
238                 <itemizedlist>
239                         <listitem>
240                         <para>
241                                 if <emphasis>gate_a_to_b</emphasis> bit 0 is set 
242                                 then it regards to gate-a to gate-b direction.
243                                 If bit 1 is set then <emphasis>ringing timeout</emphasis>
244                                 is used instead of <emphasis>learning timeout</emphasis> for
245                                 particular gate timeout.
246                         </para>
247                         </listitem>
248                 </itemizedlist>
249                 <example>
250                         <title><function>iptrtpproxy_adjust_timeout</function> usage</title>
251                         <programlisting>
252         ...
253         # load $sess_ids from dialog
254         if (iptrtpproxy_adjust_timeout("0", $sess_ids)) {
255         }
256         ...
257                         </programlisting>
258                 </example>
259                 </section>
260                 <section id="iptrtpproxy_delete">
261                 <title>
262                         <function>iptrtpproxy_delete(session_ids)</function>
263                 </title>
264                 <para>
265                 Delete sessions identified by <emphasis>session_ids</emphasis>. May be used when dialog is being
266                 destroyed (BYE) or when INVITE failed in failure route.
267                 </para>
268                 <example>
269                         <title><function>iptrtpproxy_delete</function> usage</title>
270                         <programlisting>
271         ...
272         # load $sess_ids from dialog
273         iptrtpproxy_delete($sess_ids);
274         ...
275                         </programlisting>
276                 </example>
277                 </section>
278
279                 <section id="iptrtpproxy_find">
280                 <title>
281                         <function>iptrtpproxy_find(gate_a, gate_b)</function>
282                 </title>
283                 <para>
284                         Find corresponding switchboard and set <function>@iptrtpproxy.switchboard</function> 
285                         and <function>@iptrtpproxy.direction</function>.
286                 </para>
287                 <itemizedlist>
288                         <listitem>
289                         <para>
290                                 if <emphasis>gate_a/b</emphasis> switchboard identification
291                         </para>
292                         </listitem>
293                         <listitem>
294                         <para>
295                                 function returns true if switch was found
296                         </para>
297                         </listitem>
298                 </itemizedlist>
299                 <example>
300                         <title><function>iptrtpproxy_find</function> usage</title>
301                         <programlisting>
302         ...
303         if (iptrtpproxy_find("@received.ip", "@next_hop.src_ip")) {
304                 if (iptrtpproxy_alloc("1", "")) {
305                           $sess_ids = @iptrtpproxy.session_ids;
306
307                 }
308         }
309         ...
310                         </programlisting>
311                 </example>
312                 </section>
313
314                 <section id="iptrtpproxy.session_ids">
315                 <title>
316                         <function>@iptrtpproxy.session_ids</function>
317                 </title>
318                 <para>
319                 Returns sessions allocated/updated in <function>iptrtpproxy_alloc/update</function>.
320                 </para>
321
322                 <para>
323                 The format is:
324                 </para>
325
326                 <programlisting>
327
328         switchboard_name [ ":" [ session_id *( "," session_id) ] ]
329         session_id = *( [0-9] )   ; empty when no session allocated
330                 </programlisting>
331
332                 </section>
333
334                 <section id="iptrtpproxy.sdp_ip">
335                 <title>
336                         <function>@iptrtpproxy.sdp_ip</function>
337                 </title>
338                 <para>
339                 Return first rewritten IP provided in SDP <emphasis>c=</emphasis> line.
340                 </para>
341                 </section>
342
343                 <section id="iptrtpproxy.switchboard">
344                 <title>
345                         <function>@iptrtpproxy.switchboard</function>
346                 </title>
347                 <para>
348                 Switchboard found by <function>iptrtpproxy_find</function>.
349                 </para>
350                 </section>
351
352                 <section id="iptrtpproxy.direction">
353                 <title>
354                         <function>@iptrtpproxy.direction</function>
355                 </title>
356                 <para>
357                 Direction determined by <function>iptrtpproxy_find</function>. 1..gate A->B, 0..gate B->A
358                 </para>
359                 </section>
360         </section>
361
362 </section>
363