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.3.8. custom_sdp_ip_avp (string)
                    4.3.9. gt (integer)
                    4.3.10. behind_nat (integer)
                    4.3.11. start_port (integer)
                    4.3.12. end_port (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 custom_sdp_ip_avp parameter
   1.9. Set gt parameter
   1.10. Set behind_nat parameter
   1.11. Set start_port parameter
   1.12. Set start_port parameter
   1.13. set_lrkproxy_set usage
   1.14. 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.3.8. custom_sdp_ip_avp (string)
              4.3.9. gt (integer)
              4.3.10. behind_nat (integer)
              4.3.11. start_port (integer)
              4.3.12. end_port (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
   pylrkproxy engine that exist in:
   https://github.com/mojtabaesfandiari/pylrkproxy It 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. For more
   information about LRKProxy architecture, please visit our paper in
   ieeexplore: https://ieeexplore.ieee.org/document/9303608

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 teardown 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.3.8. custom_sdp_ip_avp (string)
        4.3.9. gt (integer)
        4.3.10. behind_nat (integer)
        4.3.11. start_port (integer)
        4.3.12. end_port (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_s
ock", "udp:192.168.122.108:8080")

                                                # multiple lrkproxies for LB in
different machine
                                                modparam("lrkproxy", "lrkproxy_s
ock", "udp:192.168.122.108:8080")
                                                modparam("lrkproxy", "lrkproxy_s
ock", "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_d
isable_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_t
out", 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_r
etr", 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 shared 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.3.8. custom_sdp_ip_avp (string)

   This option useful for solving STUN and help UDP packets make it across
   NAT devices safe and sound. In this way, it should be set by clients'
   IP public manually.

   Default value is “NULL”.

   Example 1.8. Set custom_sdp_ip_avp parameter
                                                ...
                                                modparam("lrkproxy", "custom_sdp
_ip_avp", "$avp(RR_CUSTOM_SDP_IP_AVP)")
                                                ...

4.3.9. gt (integer)

   This option useful for optimization in allocation port resource in
   lrkproxy service.

   Default value is “0”.

   Example 1.9. Set gt parameter
                                                ...
                                                modparam("lrkproxy", "gt", "1")
                                                ...

4.3.10. behind_nat (integer)

   The behind_nat is used when the LRKProxy is behind NAT firewall and the
   external IP should be as Advertised IP. It could be set 0:disable or
   1:enable. If you use AWS for LRKProxy, you might should set behind_nat
   option.

   Default value is “0”.

   Example 1.10. Set behind_nat parameter
                                                ...
                                                modparam("lrkproxy", "behind_nat
", "1")
                                                ...

4.3.11. start_port (integer)

   This option use for local rang port for working with LRKProxy engine.
   Default value is based on LRKProxy engine option. For example if the
   range of ports in LRKProxy is set from 20000 to 30000, You could use
   this option to set a subset of the LRKProxy range.

   Example 1.11. Set start_port parameter
                                                ...
                                                modparam("lrkproxy", "start_port
", "25000")
                                                ...

4.3.12. end_port (integer)

   This option use for local rang port for working with LRKProxy engine.
   Default value is based on LRKProxy engine option. For example if the
   range of ports in LRKProxy is set from 20000 to 30000, You could use
   this option to set a subset of the LRKProxy range.

   Example 1.12. Set start_port parameter
                                                ...
                                                modparam("lrkproxy", "end_port",
 "28000")
                                                ...

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.13. 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.14. lrkproxy_manage usage
                                                ...
                                                lrkproxy_manage();
                                                //or
                                                lrkproxy_manage("ie");
                                                //or
                                                lrkproxy_manage("ei");

                                                ...
