app_lua: added internal alternative to luaL_openlib()
[sip-router] / src / modules / lrkproxy / README
1 lrkproxy Module
2
3 Mojtaba Esfandiari.S
4
5    Nasim Telecom
6
7    Copyright © 2020 Nasim Telecom Inc.
8      __________________________________________________________________
9
10    Table of Contents
11
12    1. Admin Guide
13
14         1. Overview
15         2. LRKProxy Architecture
16
17               2.1. LRKP_Controlling Layer (LRKP_CL)
18               2.2. LRKP_Transport Stateful Layer (LRKP_TSL)
19
20         3. Multiple LRKProxy usage
21         4. Dependencies
22
23               4.1. Kamailio Modules
24               4.2. External Libraries or Applications
25               4.3. Parameters
26
27                     4.3.1. lrkproxy_sock (string)
28                     4.3.2. lrkproxy_disable_tout (integer)
29                     4.3.3. lrkproxy_tout (integer)
30                     4.3.4. lrkproxy_retr (integer)
31                     4.3.5. lrkp_alg (integer)
32                     4.3.6. hash_table_tout (integer)
33                     4.3.7. hash_table_size (integer)
34                     4.3.8. custom_sdp_ip_avp (string)
35                     4.3.9. gt (integer)
36
37               4.4. Functions
38
39                     4.4.1. set_lrkproxy_set(setid)
40                     4.4.2. lrkproxy_manage([flags [, ip_address]])
41
42    List of Examples
43
44    1.1. Set lrkproxy_sock parameter
45    1.2. Set lrkproxy_disable_tout parameter
46    1.3. Set lrkproxy_tout parameter
47    1.4. Set lrkproxy_retr parameter
48    1.5. Set lrkp_alg parameter
49    1.6. Set hash_table_tout parameter
50    1.7. Set hash_table_size parameter
51    1.8. Set custom_sdp_ip_avp parameter
52    1.9. Set gt parameter
53    1.10. set_lrkproxy_set usage
54    1.11. lrkproxy_manage usage
55
56 Chapter 1. Admin Guide
57
58    Table of Contents
59
60    1. Overview
61    2. LRKProxy Architecture
62
63         2.1. LRKP_Controlling Layer (LRKP_CL)
64         2.2. LRKP_Transport Stateful Layer (LRKP_TSL)
65
66    3. Multiple LRKProxy usage
67    4. Dependencies
68
69         4.1. Kamailio Modules
70         4.2. External Libraries or Applications
71         4.3. Parameters
72
73               4.3.1. lrkproxy_sock (string)
74               4.3.2. lrkproxy_disable_tout (integer)
75               4.3.3. lrkproxy_tout (integer)
76               4.3.4. lrkproxy_retr (integer)
77               4.3.5. lrkp_alg (integer)
78               4.3.6. hash_table_tout (integer)
79               4.3.7. hash_table_size (integer)
80               4.3.8. custom_sdp_ip_avp (string)
81               4.3.9. gt (integer)
82
83         4.4. Functions
84
85               4.4.1. set_lrkproxy_set(setid)
86               4.4.2. lrkproxy_manage([flags [, ip_address]])
87
88 1. Overview
89
90    This is a module that enables media streams to be relayed via
91    pylrkproxy engine that exist in:
92    https://github.com/mojtabaesfandiari/pylrkproxy It does relaying audio
93    streams between peers in PREROUTING netfilter-hooking section in
94    kernel-space linux. The LRKProxy architecture is composed of two
95    different layers. These layers are independent of each other. For more
96    information about LRKProxy architecture, please visit our paper in
97    ieeexplore: https://ieeexplore.ieee.org/document/9303608
98
99 2. LRKProxy Architecture
100
101    2.1. LRKP_Controlling Layer (LRKP_CL)
102    2.2. LRKP_Transport Stateful Layer (LRKP_TSL)
103
104 2.1. LRKP_Controlling Layer (LRKP_CL)
105
106    The first layer is developed as User-Space application that allows
107    User-Space to directly access and manipulate cache data buffer and
108    packet buffer in Kernel-Space. This layer gets all information about
109    creating new sessions, active sessions and teardown sessions which is
110    gotten from SDP body during signaling plan and relay them to the
111    LRKP-Transport Stateful Layer (LRKP- TSL).
112
113 2.2. LRKP_Transport Stateful Layer (LRKP_TSL)
114
115    The second layer is developed in Kernel-Space as a main decision point
116    for RTP admission controller and Quickpath selector to where a received
117    packet should be forwarded with power of packet mangling framework in
118    the network stack.
119
120    The LRKP_CL and LRKP-TSL could be run as independence functions on
121    different machines. We could have one LRKP_CL with multiple LRKP-TSL on
122    different machines. The LRKP_CL could works with all LRKP-TSL with
123    different strategies(lrkp_alg parameter).
124
125 3. Multiple LRKProxy usage
126
127    The LRKP_CL Layer can support multiple LRKP_TSL Layer for
128    balancing/distribution and control/selection purposes.
129
130    The module allows definition of several sets of LRKP_TSL.
131    Load-balancing will be performed over predefine algorithm by setting
132    lrkp_alg parameter.
133
134    IMPORTANT: This module does not support balancing inside a set like as
135    is done RTPProxy module based on the weight of each rtpproxy from the
136    set. The balancing would be run on different machine
137
138 4. Dependencies
139
140    4.1. Kamailio Modules
141    4.2. External Libraries or Applications
142    4.3. Parameters
143
144         4.3.1. lrkproxy_sock (string)
145         4.3.2. lrkproxy_disable_tout (integer)
146         4.3.3. lrkproxy_tout (integer)
147         4.3.4. lrkproxy_retr (integer)
148         4.3.5. lrkp_alg (integer)
149         4.3.6. hash_table_tout (integer)
150         4.3.7. hash_table_size (integer)
151         4.3.8. custom_sdp_ip_avp (string)
152         4.3.9. gt (integer)
153
154    4.4. Functions
155
156         4.4.1. set_lrkproxy_set(setid)
157         4.4.2. lrkproxy_manage([flags [, ip_address]])
158
159 4.1. Kamailio Modules
160
161    The following modules must be loaded before this module:
162      * tm module - (optional) if you want to have lrkproxy_manage() fully
163        functional
164
165 4.2. External Libraries or Applications
166
167    The following libraries or applications must be installed before
168    running Kamailio with this module loaded:
169      * None.
170
171 4.3. Parameters
172
173 4.3.1. lrkproxy_sock (string)
174
175    Used to define the list of LRKP_TSL instances to connect to. These can
176    be UNIX sockets or IPv4/IPv6 UDP sockets. Each modparam entry will
177    insert sockets into a single set with default value set ID '0'. To
178    define multiple LRKP_TSL, just add the instances in each modparam.
179
180    Default value is “NONE” (disabled).
181
182    Example 1.1. Set lrkproxy_sock parameter
183                                                 ...
184                                                 # single lrkproxy
185                                                 modparam("lrkproxy", "lrkproxy_s
186 ock", "udp:192.168.122.108:8080")
187
188                                                 # multiple lrkproxies for LB in
189 diffenrent machine
190                                                 modparam("lrkproxy", "lrkproxy_s
191 ock", "udp:192.168.122.108:8080")
192                                                 modparam("lrkproxy", "lrkproxy_s
193 ock", "udp:192.168.122.109:8080")
194
195                                                 ...
196
197 4.3.2. lrkproxy_disable_tout (integer)
198
199    Once LRKP_TSL was found unreachable and marked as disabled, the LRKP_CL
200    module will not attempt to establish communication to LRKP_TSL for
201    lrkproxy_disable_tout seconds.
202
203    Default value is “60”.
204
205    Example 1.2. Set lrkproxy_disable_tout parameter
206                                                 ...
207                                                 modparam("lrkproxy", "lrkproxy_d
208 isable_tout", 20)
209                                                 ...
210
211 4.3.3. lrkproxy_tout (integer)
212
213    Timeout value in waiting for reply from LRKP_TSL.
214
215    Default value is “1”.
216
217    Example 1.3. Set lrkproxy_tout parameter
218                                                 ...
219                                                 modparam("lrkproxy", "lrkproxy_t
220 out", 2)
221                                                 ...
222
223 4.3.4. lrkproxy_retr (integer)
224
225    How many times the LRKP_CL should retry to send and receive after
226    timeout was generated.
227
228    Default value is “5”.
229
230    Example 1.4. Set lrkproxy_retr parameter
231                                                 ...
232                                                 modparam("lrkproxy", "lrkproxy_r
233 etr", 2)
234                                                 ...
235
236 4.3.5. lrkp_alg (integer)
237
238    This parameter set the algorithm of LRKP_TSL selection. lrk_LINER=0,
239    lrk_RR=1
240
241    Default value is “0”.
242
243    Example 1.5. Set lrkp_alg parameter
244                                                 ...
245                                                 modparam("lrkproxy", "lrkp_alg",
246  1)
247                                                 ...
248
249 4.3.6. hash_table_tout (integer)
250
251    Number of seconds after an lrkproxy hash table entry is marked for
252    deletion. By default, this parameter is set to 3600 (seconds).
253
254    To maintain information about a selected rtp machine node, for a given
255    call, entries are added in a hashtable of (callid, viabranch) pairs.
256    When command comes, lookup callid, viabranch pairs. If found, return
257    chosen node. If not found, choose a new node, insert it in the hastable
258    and return the chosen node.
259
260    NOTE: In the current implementation, the actual deletion happens on the
261    fly, while insert/remove/lookup the hastable, only for the entries in
262    the insert/remove/lookup path.
263
264    NOTE: When configuring this parameter, one should consider maximum call
265    time VS share memory for unfinished calls.
266
267    Default value is “3600”.
268
269    Example 1.6. Set hash_table_tout parameter
270                                                 ...
271                                                 modparam("lrkproxy", "hash_table
272 _tout", "3600")
273                                                 ...
274
275 4.3.7. hash_table_size (integer)
276
277    Size of the hash table. Default value is 128.
278
279    Default value is “128”.
280
281    Example 1.7. Set hash_table_size parameter
282                                                 ...
283                                                 modparam("lrkproxy", "hash_table
284 _size", 256)
285                                                 ...
286
287 4.3.8. custom_sdp_ip_avp (string)
288
289    This option useful for solving STUN and help UDP packets make it across
290    NAT devices safe and sound. In this way, it should be set by clients's
291    ip public manually.
292
293    Default value is “NULL”.
294
295    Example 1.8. Set custom_sdp_ip_avp parameter
296                                                 ...
297                                                 modparam("lrkproxy", "custom_sdp
298 _ip_avp", "$avp(RR_CUSTOM_SDP_IP_AVP)")
299                                                 ...
300
301 4.3.9. gt (integer)
302
303    This option useful for optimization in allocation port resource in
304    lrkproxy service.
305
306    Default value is “0”.
307
308    Example 1.9. Set gt parameter
309                                                 ...
310                                                 modparam("lrkproxy", "gt", "1")
311                                                 ...
312
313 4.4. Functions
314
315 4.4.1.  set_lrkproxy_set(setid)
316
317    Sets the Id of the lrkproxy set to be used for the next
318    lrkproxy_manage() command. The parameter can be an integer or a config
319    variable holding an integer.
320
321    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
322    BRANCH_ROUTE.
323
324    Example 1.10. set_lrkproxy_set usage
325                                                 ...
326                                                 set_lrkproxy_set("0");
327                                                 lrkproxy_manage();
328                                                 ...
329
330 4.4.2.  lrkproxy_manage([flags [, ip_address]])
331
332    Manage the LRKProxy session - it combines the functionality of
333    lrkproxy_offer(), lrkproxy_answer() and unforce_lrkproxy(), detecting
334    internally based on message type and method which one to execute.
335
336    IMPORTANT:The LRKProxy just has one function relating rtp packets. It
337    does not support combination of functionality of lrkproxy_offer(),
338    lrkproxy_answer() and unforce_lrkproxy() and other etc. So you have to
339    just use lrkproxy_manage.
340
341    Meaning of the parameters is as follows:
342      * flags - flags to turn on some features.
343           + internal,external - The shorthand of this flag is "ie". This
344             can be used to relay media sessions between two different NIC
345             from internal to external path.
346           + external,internal - The shorthand of this flag is "ei". This
347             can be used to relay media sessions between two different NIC
348             from external to internal path.
349      * ip_address - new SDP IP address.This optional parameter is under
350        development.
351
352    This function can be used from ANY_ROUTE.
353
354    Example 1.11. lrkproxy_manage usage
355                                                 ...
356                                                 lrkproxy_manage();
357                                                 //or
358                                                 lrkproxy_manage("ie");
359                                                 //or
360                                                 lrkproxy_manage("ei");
361
362                                                 ...