Browse code

lrkproxy: initial version of README

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