Kamailio Dispatcher Module Load Balance between FreeSWITCH voicemail servers - Omid-Mohajerani/Learn-Kamailio GitHub Wiki

Kamailio Dispatcher Module:

The Dispatcher module in Kamailio offers SIP load balancer functionality and it can be used as a SIP traffic dispatcher. One of the most common use cases for dispatcher module is to load balance traffic between media servers such Asterisk or FreeSWITCH to implement High Available and Scalable Voice over IP solutions.

In order to understand this module I prepared a lab which Im using FreeSWITCH Servers as voice mail application servers.

Using Kamailio Dispatcher module we can load balance sip traffic to multiple FreeSWITCH servers. With this implementation even if 2 of FreeSWITCH servers goes down users still will be able to reach their voicemails. Also if we want to add more voicemail servers we can do it without any downtime.

---

Step 1 - Kamailio Installation on Debian 11

Add Kamailio repo to be able to install latest stable version

wget -O- https://deb.kamailio.org/kamailiodebkey.gpg | sudo apt-key add -
echo "deb http://deb.kamailio.org/kamailio56 bullseye main" >> /etc/apt/sources.list
echo "deb-src http://deb.kamailio.org/kamailio56 bullseye main" >> /etc/apt/sources.list
apt update

Install Kamailio

apt install kamailio

Verify the installed Kamailio version

dpkg --list | grep kamailio

Verify if Kamailio process is running

ps -aux | grep kamailio

---

Step2: VoiceMail configuration

This step is not needed in dispatcher configuration but I want you to know how voicemail to 1 FreeSWITCH works first and then we jump into Dispatcher configuration to load balance between Different voicemail Servers.

VoiceMail routing Configuration in Kamailio:

Default Kamailio configuration (/etc/kamailio/kamailio.cfg) also provides easy configuration of routing voicemail to voicemail servers.

You also need to enable password less authentication in FreeSWITCH. You can refer to this post on FreeSWITCH configuration : https://github.com/Omid-Mohajerani/Learn-Kamailio/wiki/Configuring-Kamailio-to-use-FreeSWITCH-as-Voicemail-Server

Test voicemail routing

In order to test if voicemail routing works you just need to register 2 SIP Soft phones in Kamailio, make one of them busy and make a call. In Zoiper you can choose "On the Phone" status to make the phone busy.

Default Kamailio configuration accept does not challenge sip authentication. You can register with any username and password. Just remember to open port 5060 to your source IP address in your firewall.

---

Step 3 - Dispatcher Module Configuration in Kamailio

Load dispatcher module

add loadmodule "dispatcher.so" after loadmodule "counters.so" in /etc/kamailio/kamailio.cfg

Set Dispatcher module parameters

add configurations after loadmodule "dispatcher.so"

# Dispatcher module parameters 
modparam("dispatcher", "list_file", "/etc/kamailio/dispatcher.list")
modparam("dispatcher", "force_dst", 1)
modparam("dispatcher", "flags", 2)

parameter	Values
list_file (string)	Path to the file with destination sets.
force_dst (int)	If set to 1, force overwriting of destination address (outbound proxy) when that is already set.
flags (int)	Various flags that affect dispatcher's behaviour. The flags are defined as a bit mask on an integer value. If flag 2 is set, then failover support is enabled. The functions exported by the module will store the rest of addresses from the destination set in the AVP, and use these AVPs to contact next address if the current-tried destination fails.

Set dispatcher list

#
# dispatcher destination sets (groups)
#

# line format
# setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attributes(str,opt)

# proxies
# 2 sip:127.0.0.1:5080;transport=tcp 0 10 class=4;prefix=448;strip=2
# 2 sip:127.0.0.1:5082;px=vx 0 5 duid=abc;socket=udp:192.168.0.125:5060;pipe=p10

1 sip:fs01.omid.blog:5060
1 sip:fs02.omid.blog:5060
1 sip:fs03.omid.blog:5060

---

Step 4 - Dispatch SIP traffic between FreeSWITCH Voicemail servers

Change TOVOICEMAIL route to send traffic to any of 3 FreeSWITCH Servers in group number 1 using ds_select_dst("1","4");

route[TOVOICEMAIL] {
#!ifdef WITH_VOICEMAIL
        if(!is_method("INVITE|SUBSCRIBE")) return;

        # check if VoiceMail server IP is defined
        if (strempty($sel(cfg_get.voicemail.srv_ip))) {
                xlog("SCRIPT: VoiceMail routing enabled but IP not defined\n");
                return;
        }
        if(is_method("INVITE")) {
                if($avp(oexten)==$null) return;

                $ru = "sip:" + $avp(oexten) + "@" + $sel(cfg_get.voicemail.srv_ip)
                                + ":" + $sel(cfg_get.voicemail.srv_port);
                ds_select_dst("1","4");
        } else {
                if($rU==$null) return;

                $ru = "sip:" + $rU + "@" + $sel(cfg_get.voicemail.srv_ip)
                                + ":" + $sel(cfg_get.voicemail.srv_port);
                ds_select_dst("1","4");
        }
        route(RELAY);
        exit;
#!endif

        return;
}

1 in ds_select_dst("1","4") mean choose from one of destination in group 1 ( in dispatcher.list) and 4 means use round robin algorithm. Here is the list of algorithms that can be used.

parameter	Values
0	hash over callid
1	hash over from URI.
2	hash over to URI.
3	hash over request-URI.
4	round-robin (next destination).
5	hash over authorization-username (Proxy-Authorization or "normal" authorization). If no username is found, round robin is used.
6	random destination (using rand()).
7	hash over the content of PVs string. Note: This works only when the parameter hash_pvar is set.
8	select destination sorted by priority attribute value (serial forking ordered by priority).
9	use weight based load distribution. You have to set the attribute 'weight' per each address in destination set.
10	use call load distribution. You have to set the attribute 'duid' (as an unique string id) per each address in destination set. Also, you must set parameters 'dstid_avp' and 'ds_hash_size'