iptrtpproxy: moved from modules_s/ to modules/
[sip-router] / modules / iptrtpproxy / README
1 1. Iptrtpproxy module
2
3 Tomas Mandys
4
5    Iptel.org
6
7    Copyright © 2007 Tomas Mandys
8    Revision History
9    Revision $Revision$ $Date$
10      __________________________________________________________________
11
12    1.1. Overview
13    1.2. Dependencies
14    1.3. Parameters
15
16         1.3.1. config (string)
17         1.3.2. switchboard (string)
18
19    1.4. Functions
20
21         1.4.1. iptrtpproxy_alloc(gate_a_to_b, switchboard_id)
22         1.4.2. iptrtpproxy_update(gate_a_to_b, session_ids)
23         1.4.3. iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)
24         1.4.4. iptrtpproxy_delete(session_ids)
25         1.4.5. iptrtpproxy_find(gate_a, gate_b)
26         1.4.6. @iptrtpproxy.session_ids
27         1.4.7. @iptrtpproxy.sdp_ip
28         1.4.8. @iptrtpproxy.switchboard
29         1.4.9. @iptrtpproxy.direction
30
31 1.1. Overview
32
33    It provides similar functionality as nathelper but communicates with
34    netfilter kernel xt_RTPPROXY module using libipt_RTPPROXY userspace
35    library. See http://www.2p.cz/en/netfilter_rtp_proxy All RTP streams
36    are manipulated directly in kernel space, no data are copied from
37    kernel to userspace and back, it reduces load and delay.
38
39    The ser module is written as light-weighted, there is not implemented
40    any dialog managment as in nathelper, the reason is that such API
41    should be provided by core or specialized dialog manager module.
42    Because such module is not in CVS, session information may be stored in
43    extra attributes of avp_db module and session id itself in record route
44    as cookie, see rr module.
45
46    It should be able to support all cases as re-invites when SIP client
47    offers media change in SDP and when number of medias in offer/answer
48    are different.
49
50    Nathelper may be still used for testing if client is behind the NAT.
51
52    Limitations:
53      * only IPv4 addresses are supported.
54      * more media streams per session supported
55
56 1.2. Dependencies
57
58    The following libraries or applications must be installed before
59    running SER with this module loaded:
60      * netfilter xt_RTPROXY & libipt_RTPPROXY, see
61        http://www.2p.cz/en/netfilter_rtp_proxy
62
63 1.3. Parameters
64
65 1.3.1. config (string)
66
67    References iptrtpproxy.cfg, see iptrtpproxy_helper. Default value is
68    /etc/iptrtpproxy.cfg.
69
70 1.3.2. switchboard (string)
71
72    References xt_RTPPROXY switchboard for usage by ser module.
73
74    The format is:
75   name "=" value * ( ";" name "=" value )
76
77   name =  "name" | "*" | ( "ringing-timeout " ) | ( ( "learning-timeout-" | "alw
78 ays-learn-") ("a" | "b") )
79
80    The meaning of parameters is described in libipt_RTPROXY and
81    iptrtpproxy documentation. ringing timeout is explicit timeout in sec
82    regarding ringing. Ringing requires manual callee action, i.e. it may
83    takes long time. Default value is 60 sec.
84
85    The name" is identifier that will be used by script functions and
86    references switchboard. It's mandatory parameter. More switchboards may
87    be declared. The special name * set values for all switchboards.
88
89    Example 1. Declare switchboard
90         ...
91         modparam("iptrtpproxy", "config", "/etc/iptrtpproxy.cfg");
92         modparam("iptrtpproxy", "switchboard", "name=*;learning-timeout-a=10;lea
93 rning-timeout-b=10;ringing-timeout=90");
94         modparam("iptrtpproxy", "switchboard", "name=my;ringing-timeout=60");
95         ...
96
97 1.4. Functions
98
99 1.4.1.  iptrtpproxy_alloc(gate_a_to_b, switchboard_id)
100
101    Parses SDP content and allocates for each RTP media stream one RTP
102    proxy session. SDP is updates to reflect allocated sessions.
103      * if gate_a_to_b bit 0 is set then SDP regards to gate-a to gate-b
104        direction. If bit 1 is set then ringing timeout is used instead of
105        learning timeout for particular gate timeout.
106      * switchboard_id is reference to a switchboard with name declared as
107        switchboard modparam. If empty then use switchboard found by
108        iptrtpproxy_find (equal using @iptrtpproxy.switchboard).
109      * function returns true is a session was created, identifier is
110        available via select @iptrtpproxy.session_ids.
111
112    Example 2. iptrtpproxy_alloc usage
113         ...
114         if (iptrtpproxy_alloc("1", "my")) {
115           $sess_ids = @iptrtpproxy.session_ids;
116           # save sess_ids in dialog
117         }
118         ...
119
120 1.4.2.  iptrtpproxy_update(gate_a_to_b, session_ids)
121
122    Parses SDP content and updates sessions provided by session_ids and
123    updates SDP. If succesfull then session_ids may be changed (in case
124    e.g. media stream has port zero particular session is released), the
125    result of @iptrtpproxy.session_ids should be stored for future
126    in-dialog usage.
127      * if gate_a_to_b bit 0 is set then SDP regards to gate-a to gate-b
128        direction. If bit 1 is set then ringing timeout is used instead of
129        learning timeout for particular gate timeout.
130
131    Example 3. iptrtpproxy_update usage
132         ...
133         # load $sess_ids from dialog
134         if (iptrtpproxy_update("0", $sess_ids)) {
135           $sess_ids = @iptrtpproxy.session_ids;
136           # save sess_ids in dialog
137         }
138         ...
139
140 1.4.3.  iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)
141
142    Adjust timeout for particular gate. It's useful in "200 OK" decrease
143    timeout to learning timeout if INVITE has set (long) ringing timeout.
144      * if gate_a_to_b bit 0 is set then it regards to gate-a to gate-b
145        direction. If bit 1 is set then ringing timeout is used instead of
146        learning timeout for particular gate timeout.
147
148    Example 4. iptrtpproxy_adjust_timeout usage
149         ...
150         # load $sess_ids from dialog
151         if (iptrtpproxy_adjust_timeout("0", $sess_ids)) {
152         }
153         ...
154
155 1.4.4.  iptrtpproxy_delete(session_ids)
156
157    Delete sessions identified by session_ids. May be used when dialog is
158    being destroyed (BYE) or when INVITE failed in failure route.
159
160    Example 5. iptrtpproxy_delete usage
161         ...
162         # load $sess_ids from dialog
163         iptrtpproxy_delete($sess_ids);
164         ...
165
166 1.4.5.  iptrtpproxy_find(gate_a, gate_b)
167
168    Find corresponding switchboard and set @iptrtpproxy.switchboard and
169    @iptrtpproxy.direction.
170      * if gate_a/b switchboard identification
171      * function returns true if switch was found
172
173    Example 6. iptrtpproxy_find usage
174         ...
175         if (iptrtpproxy_find("@received.ip", "@next_hop.src_ip")) {
176                 if (iptrtpproxy_alloc("1", "")) {
177                           $sess_ids = @iptrtpproxy.session_ids;
178
179                 }
180         }
181         ...
182
183 1.4.6.  @iptrtpproxy.session_ids
184
185    Returns sessions allocated/updated in iptrtpproxy_alloc/update.
186
187    The format is:
188         switchboard_name [ ":" [ session_id *( "," session_id) ] ]
189         session_id = *( [0-9] )   ; empty when no session allocated
190
191 1.4.7.  @iptrtpproxy.sdp_ip
192
193    Return first rewritten IP provided in SDP c= line.
194
195 1.4.8.  @iptrtpproxy.switchboard
196
197    Switchboard found by iptrtpproxy_find.
198
199 1.4.9.  @iptrtpproxy.direction
200
201    Direction determined by iptrtpproxy_find. 1..gate A->B, 0..gate B->A