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