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