From 6c0d06eb0068d554bfebc87c57430aa3507f7302 Mon Sep 17 00:00:00 2001 From: Daniel-Constantin Mierla Date: Tue, 9 Mar 2021 12:38:28 +0100 Subject: [PATCH] lrkproxy: initial version of README --- src/modules/lrkproxy/README | 316 ++++++++++++++++++++++++++++++++++++ 1 file changed, 316 insertions(+) create mode 100644 src/modules/lrkproxy/README diff --git a/src/modules/lrkproxy/README b/src/modules/lrkproxy/README new file mode 100644 index 00000000000..d95b5442f74 --- /dev/null +++ b/src/modules/lrkproxy/README @@ -0,0 +1,316 @@ +lrkproxy Module + +Mojtaba Esfandiari.S + + Nasim Telecom + + Copyright © 2020 Nasim Telecom Inc. + __________________________________________________________________ + + Table of Contents + + 1. Admin Guide + + 1. Overview + 2. LRKProxy Architecture + + 2.1. LRKP_Controlling Layer (LRKP_CL) + 2.2. LRKP_Transport Stateful Layer (LRKP_TSL) + + 3. Multiple LRKProxy usage + 4. Dependencies + + 4.1. Kamailio Modules + 4.2. External Libraries or Applications + 4.3. Parameters + + 4.3.1. lrkproxy_sock (string) + 4.3.2. lrkproxy_disable_tout (integer) + 4.3.3. lrkproxy_tout (integer) + 4.3.4. lrkproxy_retr (integer) + 4.3.5. lrkp_alg (integer) + 4.3.6. hash_table_tout (integer) + 4.3.7. hash_table_size (integer) + + 4.4. Functions + + 4.4.1. set_lrkproxy_set(setid) + 4.4.2. lrkproxy_manage([flags [, ip_address]]) + + List of Examples + + 1.1. Set lrkproxy_sock parameter + 1.2. Set lrkproxy_disable_tout parameter + 1.3. Set lrkproxy_tout parameter + 1.4. Set lrkproxy_retr parameter + 1.5. Set lrkp_alg parameter + 1.6. Set hash_table_tout parameter + 1.7. Set hash_table_size parameter + 1.8. set_lrkproxy_set usage + 1.9. lrkproxy_manage usage + +Chapter 1. Admin Guide + + Table of Contents + + 1. Overview + 2. LRKProxy Architecture + + 2.1. LRKP_Controlling Layer (LRKP_CL) + 2.2. LRKP_Transport Stateful Layer (LRKP_TSL) + + 3. Multiple LRKProxy usage + 4. Dependencies + + 4.1. Kamailio Modules + 4.2. External Libraries or Applications + 4.3. Parameters + + 4.3.1. lrkproxy_sock (string) + 4.3.2. lrkproxy_disable_tout (integer) + 4.3.3. lrkproxy_tout (integer) + 4.3.4. lrkproxy_retr (integer) + 4.3.5. lrkp_alg (integer) + 4.3.6. hash_table_tout (integer) + 4.3.7. hash_table_size (integer) + + 4.4. Functions + + 4.4.1. set_lrkproxy_set(setid) + 4.4.2. lrkproxy_manage([flags [, ip_address]]) + +1. Overview + + This is a module that enables media streams to be relayed via an + lrkproxy. This module works with py_lrkproxy engine in: + https://github.com/mojtabaesfandiari/pylrkproxy This module does + relaying audio streams between peers in PREROUTING netfilter-hooking + section in kernel-space linux. The LRKProxy architecture is composed of + two different layers. These layers are independent of each other. + +2. LRKProxy Architecture + + 2.1. LRKP_Controlling Layer (LRKP_CL) + 2.2. LRKP_Transport Stateful Layer (LRKP_TSL) + +2.1. LRKP_Controlling Layer (LRKP_CL) + + The first layer is developed as User-Space application that allows + User-Space to directly access and manipulate cache data buffer and + packet buffer in Kernel-Space. This layer gets all information about + creating new sessions, active sessions and tear-down sessions which is + gotten from SDP body during signaling plan and relay them to the + LRKP-Transport Stateful Layer (LRKP- TSL). + +2.2. LRKP_Transport Stateful Layer (LRKP_TSL) + + The second layer is developed in Kernel-Space as a main decision point + for RTP admission controller and Quickpath selector to where a received + packet should be forwarded with power of packet mangling framework in + the network stack. + + The LRKP_CL and LRKP-TSL could be run as independence functions on + different machines. We could have one LRKP_CL with multiple LRKP-TSL on + different machines. The LRKP_CL could works with all LRKP-TSL with + different strategies(lrkp_alg parameter). + +3. Multiple LRKProxy usage + + The LRKP_CL Layer can support multiple LRKP_TSL Layer for + balancing/distribution and control/selection purposes. + + The module allows definition of several sets of LRKP_TSL. + Load-balancing will be performed over predefine algorithm by setting + lrkp_alg parameter. + + IMPORTANT: This module does not support balancing inside a set like as + is done RTPProxy module based on the weight of each rtpproxy from the + set. The balancing would be run on different machine + +4. Dependencies + + 4.1. Kamailio Modules + 4.2. External Libraries or Applications + 4.3. Parameters + + 4.3.1. lrkproxy_sock (string) + 4.3.2. lrkproxy_disable_tout (integer) + 4.3.3. lrkproxy_tout (integer) + 4.3.4. lrkproxy_retr (integer) + 4.3.5. lrkp_alg (integer) + 4.3.6. hash_table_tout (integer) + 4.3.7. hash_table_size (integer) + + 4.4. Functions + + 4.4.1. set_lrkproxy_set(setid) + 4.4.2. lrkproxy_manage([flags [, ip_address]]) + +4.1. Kamailio Modules + + The following modules must be loaded before this module: + * tm module - (optional) if you want to have lrkproxy_manage() fully + functional + +4.2. External Libraries or Applications + + The following libraries or applications must be installed before + running Kamailio with this module loaded: + * None. + +4.3. Parameters + +4.3.1. lrkproxy_sock (string) + + Used to define the list of LRKP_TSL instances to connect to. These can + be UNIX sockets or IPv4/IPv6 UDP sockets. Each modparam entry will + insert sockets into a single set with default value set ID '0'. To + define multiple LRKP_TSL, just add the instances in each modparam. + + Default value is "NONE" (disabled). + + Example 1.1. Set lrkproxy_sock parameter +... +# single lrkproxy +modparam("lrkproxy", "lrkproxy_sock", "udp:192.168.122.108:8080") + +# multiple lrkproxies for LB in diffenrent machine +modparam("lrkproxy", "lrkproxy_sock", "udp:192.168.122.108:8080") +modparam("lrkproxy", "lrkproxy_sock", "udp:192.168.122.109:8080") + +... + +4.3.2. lrkproxy_disable_tout (integer) + + Once LRKP_TSL was found unreachable and marked as disabled, the LRKP_CL + module will not attempt to establish communication to LRKP_TSL for + lrkproxy_disable_tout seconds. + + Default value is "60". + + Example 1.2. Set lrkproxy_disable_tout parameter +... +modparam("lrkproxy", "lrkproxy_disable_tout", 20) +... + +4.3.3. lrkproxy_tout (integer) + + Timeout value in waiting for reply from LRKP_TSL. + + Default value is "1". + + Example 1.3. Set lrkproxy_tout parameter +... +modparam("lrkproxy", "lrkproxy_tout", 2) +... + +4.3.4. lrkproxy_retr (integer) + + How many times the LRKP_CL should retry to send and receive after + timeout was generated. + + Default value is "5". + + Example 1.4. Set lrkproxy_retr parameter +... +modparam("lrkproxy", "lrkproxy_retr", 2) +... + +4.3.5. lrkp_alg (integer) + + This parameter set the algorithm of LRKP_TSL selection. lrk_LINER=0, + lrk_RR=1 + + Default value is "0". + + Example 1.5. Set lrkp_alg parameter +... +modparam("lrkproxy", "lrkp_alg", 1) +... + +4.3.6. hash_table_tout (integer) + + Number of seconds after an lrkproxy hash table entry is marked for + deletion. By default, this parameter is set to 3600 (seconds). + + To maintain information about a selected rtp machine node, for a given + call, entries are added in a hashtable of (callid, viabranch) pairs. + When command comes, lookup callid, viabranch pairs. If found, return + chosen node. If not found, choose a new node, insert it in the hastable + and return the chosen node. + + NOTE: In the current implementation, the actual deletion happens on the + fly, while insert/remove/lookup the hastable, only for the entries in + the insert/remove/lookup path. + + NOTE: When configuring this parameter, one should consider maximum call + time VS share memory for unfinished calls. + + Default value is "3600". + + Example 1.6. Set hash_table_tout parameter +... +modparam("lrkproxy", "hash_table_tout", "3600") +... + +4.3.7. hash_table_size (integer) + + Size of the hash table. Default value is 128. + + Default value is "128". + + Example 1.7. Set hash_table_size parameter +... +modparam("lrkproxy", "hash_table_size", 256) +... + +4.4. Functions + +4.4.1. set_lrkproxy_set(setid) + + Sets the Id of the lrkproxy set to be used for the next + lrkproxy_manage() command. The parameter can be an integer or a config + variable holding an integer. + + This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, + BRANCH_ROUTE. + + Example 1.8. set_lrkproxy_set usage +... +set_lrkproxy_set("0"); +lrkproxy_manage(); +... + +4.4.2. lrkproxy_manage([flags [, ip_address]]) + + Manage the LRKProxy session - it combines the functionality of + lrkproxy_offer(), lrkproxy_answer() and unforce_lrkproxy(), detecting + internally based on message type and method which one to execute. + + IMPORTANT:The LRKProxy just has one function relating rtp packets. It + does not support combination of functionality of lrkproxy_offer(), + lrkproxy_answer() and unforce_lrkproxy() and other etc. So you have to + just use lrkproxy_manage. + + Meaning of the parameters is as follows: + * flags - flags to turn on some features. + + internal,external - The shorthand of this flag is "ie". This + can be used to relay media sessions between two different NIC + from internal to external path. + + external,internal - The shorthand of this flag is "ei". This + can be used to relay media sessions between two different NIC + from external to internal path. + * ip_address - new SDP IP address.This optional parameter is under + development. + + This function can be used from ANY_ROUTE. + + Example 1.9. lrkproxy_manage usage +... +lrkproxy_manage(); +//or +lrkproxy_manage("ie"); +//or +lrkproxy_manage("ei"); + +...