Kamailio Balancing capability

  • 12/3/2023
  • 4-minute read

The “dispatcher” module provides support for several traffic balancing and dispatching algorithms.
In this tutorial we will see how to configure Kamailio to balance traffic to different destinations based on their availability, illustrating round-robin modes and priorities. Kamailio is able to monitor the status of the target endpoints through the use of SIP OPTIONS or other messages like INFO.

Create a list of target servers

To activate the balancing support it is necessary to enable the “dispatcher” module and configure it appropriately, in addition to defining the list of destination endpoints to be monitored and to which to send the traffic.

As a first step, create the “dispatcher.list” file (usually placed in the same path as the configuration file, eg /etc/kamailio/) and add the destination targets.

	# setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
	 1 sip:192.168.0.24 1 5
	 1 sip:192.168.0.25 1 0
  • setid(int): is the id of the target group
  • destination(sip uri): is the target server sip:ip:port
  • flags(int): optional parameter is the status of the target; 0=inactive destination, 1=temporary trying (status depends on probe response)
  • priority(int): optional parameter indicates the priority for the specific target

In the example above the two targets will both be active or inactive based on their responses to the probe, but the first has a higher priority than the second.

Activate the dispatcher module

Enable the dispatcher module by adding the “#!define WITH_DISPATCHER” directive at the beginning of the configuration file and then loading the “dispatcher.so” module in the “Modules” section of the configuration file.

	#!KAMAILIO
	#
	#!define WITH_DEBUG
	#!define WITH_TLS
	#!define WITH_NAT
	#!define WITH_DISPATCHER
	#

	...

	####### Modules Section ########

	...

	#!ifdef WITH_DISPATCHER
	loadmodule "dispatcher.so"
	#!endif

Configure the module within the “setting module-specific parameters” section of the kamailio configuration file.

	#!ifdef WITH_DISPATCHER
	modparam("dispatcher", "list_file", "/etc/kamailio/dispatcher.list")
	modparam("dispatcher", "ds_ping_method", "OPTIONS")
	modparam("dispatcher", "ds_ping_interval", 30)
	modparam("dispatcher", "ds_ping_from", "sip:192.168.0.20")
	modparam("dispatcher", "ds_ping_reply_codes", "code=200;code=484")
	modparam("dispatcher", "ds_probing_mode", 1)
	modparam("dispatcher", "ds_probing_threshold", 1)
	#!endif
  • list_file: full path of dispatcher.list with destination sets
  • ds_ping_mehod: SIP method used for probing the targets
  • ds_ping_interval: the interval (in seconds) for sending a probe
  • ds_ping_from: the “From:"-Line for the probe
  • ds_ping_reply_codes: the valid response codes, which are accepted as a valid reply to the probe
  • ds_probing_mode: 1 to probe all the configured targets
  • ds_probing_threshold: specific number of failed probes until a target will change from “active” to “inactive”

With the configuration listed above, the system will send probe SIP OPTIONS every 30 seconds to all the targets configured in the list, accepting the codes 200 OK and 484 Address Incomplete as OK response, and considering the destination offline as soon as there is no response to the probe.

Configure distributed routing to destination servers

Routing to destinations is controlled by the “ds_select_dst()” (or “ds_select_domain()”) method added in the appropriate routing rule configured on Kamailio. In this example we use the routing rule applied by default to forward traffic to destinations outside the system domain, identified by the “SIPOUT” label.

	route[SIPOUT] {
		#if (uri==myself) return;

		append_hf("P-hint: outbound\r\n");

		xlog("Request URI: $ru, user[$rU]");
		if ($rd == "external.domain1.local")
			route(RELAY);
		else if ($rd == "external.domain2.local") {
			if(!ds_select_dst("1", "8")) {
				send_reply("404", "No destination");
				exit;
			}
			route(RELAY);
		}
		exit;
	}

In the example, the system will forward calls received on the “external.domain2.local” domain to one of the targets available on the list. In particular using the method “ds_select_dst()” you can decide the routing algorithm to use:

  • ds_select_dst(“1”, “8”): select destination sorted by priority attribute value for target group “setid 1”
  • ds_select_dst(“1”, “4”): select destination in round-robin for target group “setid 1”

In addition to “ds_select_dst()” method it is possible to use the “ds_select_domain()” method, which unlike the first one replaces the “domain” part of the original request URI with the IP address of the destination selected in the availability list (the “to” header field remains unchanged). Both methods have the same input parameters.

All the details are available on the official Kamailio documentation for the specific module dispatcher.

sipkamailio