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" [
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
11 <!-- Module User's Guide -->
15 <title>&adminguide;</title>
18 <title>Overview</title>
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
28 For more information about LRKProxy architecture, please visit our paper in ieeexplore:
29 https://ieeexplore.ieee.org/document/9303608
34 <title>LRKProxy Architecture</title>
36 <title>LRKP_Controlling Layer (LRKP_CL)</title>
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-
50 <title>LRKP_Transport Stateful Layer (LRKP_TSL)</title>
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.
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).
68 <title>Multiple LRKProxy usage</title>
70 The LRKP_CL Layer can support multiple LRKP_TSL Layer
71 for balancing/distribution and control/selection purposes.
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.
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
85 <title>Dependencies</title>
87 <title>&kamailio; Modules</title>
89 The following modules must be loaded before this module:
93 <emphasis>tm module</emphasis> - (optional) if you want to
94 have lrkproxy_manage() fully functional
101 <title>External Libraries or Applications</title>
103 The following libraries or applications must be installed before
104 running &kamailio; with this module loaded:
108 <emphasis>None</emphasis>.
115 <title>Parameters</title>
116 <section id="lrkproxy.p.lrkproxy_sock">
117 <title><varname>lrkproxy_sock</varname> (string)</title>
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.
126 Default value is <quote>NONE</quote> (disabled).
130 <title>Set <varname>lrkproxy_sock</varname> parameter</title>
131 <programlisting format="linespecific">
134 modparam("lrkproxy", "lrkproxy_sock", "udp:192.168.122.108:8080")
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")
144 <section id="lrkproxy.p.lrkproxy_disable_tout">
145 <title><varname>lrkproxy_disable_tout</varname> (integer)</title>
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.
153 Default value is <quote>60</quote>.
157 <title>Set <varname>lrkproxy_disable_tout</varname> parameter</title>
158 <programlisting format="linespecific">
160 modparam("lrkproxy", "lrkproxy_disable_tout", 20)
165 <section id="lrkproxy.p.lrkproxy_tout">
166 <title><varname>lrkproxy_tout</varname> (integer)</title>
168 Timeout value in waiting for reply from LRKP_TSL.
172 Default value is <quote>1</quote>.
176 <title>Set <varname>lrkproxy_tout</varname> parameter</title>
177 <programlisting format="linespecific">
179 modparam("lrkproxy", "lrkproxy_tout", 2)
184 <section id="lrkproxy.p.lrkproxy_retr">
185 <title><varname>lrkproxy_retr</varname> (integer)</title>
187 How many times the LRKP_CL should retry to send and receive after
188 timeout was generated.
192 Default value is <quote>5</quote>.
196 <title>Set <varname>lrkproxy_retr</varname> parameter</title>
197 <programlisting format="linespecific">
199 modparam("lrkproxy", "lrkproxy_retr", 2)
204 <section id="lrkproxy.p.lrkp_alg">
205 <title><varname>lrkp_alg</varname> (integer)</title>
207 This parameter set the algorithm of LRKP_TSL selection.
213 Default value is <quote>0</quote>.
217 <title>Set <varname>lrkp_alg</varname> parameter</title>
218 <programlisting format="linespecific">
220 modparam("lrkproxy", "lrkp_alg", 1)
226 <section id="lrkproxy.p.hash_table_tout">
227 <title><varname>hash_table_tout</varname> (integer)</title>
229 Number of seconds after an lrkproxy hash table entry is marked for
230 deletion. By default, this parameter is set to 3600 (seconds).
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
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.
245 NOTE: When configuring this parameter, one should consider maximum call
246 time VS share memory for unfinished calls.
250 Default value is <quote>3600</quote>.
254 <title>Set <varname>hash_table_tout</varname> parameter</title>
255 <programlisting format="linespecific">
257 modparam("lrkproxy", "hash_table_tout", "3600")
262 <section id="lrkproxy.p.hash_table_size">
263 <title><varname>hash_table_size</varname> (integer)</title>
265 Size of the hash table. Default value is 128.
269 Default value is <quote>128</quote>.
273 <title>Set <varname>hash_table_size</varname> parameter</title>
274 <programlisting format="linespecific">
276 modparam("lrkproxy", "hash_table_size", 256)
283 <title>Functions</title>
284 <section id="lrkproxy.f.set_lrkproxy_set">
286 <function moreinfo="none">set_lrkproxy_set(setid)</function>
289 Sets the Id of the lrkproxy set to be used for the next
290 lrkproxy_manage() command. The parameter can be an integer or a config
291 variable holding an integer.
294 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
298 <title><function>set_lrkproxy_set</function> usage</title>
299 <programlisting format="linespecific">
301 set_lrkproxy_set("0");
307 <section id="lrkproxy.f.lrkproxy_manage">
309 <function moreinfo="none">lrkproxy_manage([flags [, ip_address]])</function>
312 Manage the LRKProxy session - it combines the functionality of
313 lrkproxy_offer(), lrkproxy_answer() and unforce_lrkproxy(), detecting
314 internally based on message type and method which one to execute.
317 IMPORTANT:The LRKProxy just has one function relating rtp packets.
318 It does not support combination of functionality of lrkproxy_offer(),
319 lrkproxy_answer() and unforce_lrkproxy() and other etc.
320 So you have to just use lrkproxy_manage.
322 <para>Meaning of the parameters is as follows:</para>
326 <emphasis>flags</emphasis> - flags to turn on some features.
330 <emphasis>internal,external</emphasis> - The shorthand of this flag is "ie".
331 This can be used to relay media sessions between two different NIC from internal to external path.
336 <emphasis>external,internal</emphasis> - The shorthand of this flag is "ei".
337 This can be used to relay media sessions between two different NIC from external to internal path.
342 <emphasis>ip_address</emphasis> - new SDP IP address.This optional parameter is under development.
346 This function can be used from ANY_ROUTE.
349 <title><function>lrkproxy_manage</function> usage</title>
350 <programlisting format="linespecific">
354 lrkproxy_manage("ie");
356 lrkproxy_manage("ei");