Load-Balancer Module

Bogdan-Andrei Iancu

Edited by

Bogdan-Andrei Iancu

Revision History
Revision $Revision: 8740 $$Date$

Table of Contents

1. Admin Guide
1.1. Overview
1.2. How it works
1.3. Probing and Disabling destinations
1.4. Dependencies
1.4.1. OpenSIPS Modules
1.4.2. External Libraries or Applications
1.5. Exported Parameters
1.5.1. db_url (string)
1.5.2. db_table (string)
1.5.3. probing_interval (integer)
1.5.4. probing_method (string)
1.5.5. probing_from (string)
1.5.6. probing_reply_codes (string)
1.5.7. lb_define_blacklist (string)
1.6. Exported Functions
1.6.1. load_balance(grp,resources[,alg])
1.6.2. lb_disable()
1.6.3. lb_is_destination(ip,port[,group[,active]])
1.6.4. lb_count_call(ip,port,grp,resources)
1.7. Exported statistics
1.8. Exported MI Functions
1.8.1. lb_reload
1.8.2. lb_resize
1.8.3. lb_list
1.8.4. lb_status
1.9. Exported pseudo-variables
2. Developer Guide
2.1. Available Functions
3. Frequently Asked Questions

List of Examples

1.1. Set db_url parameter
1.2. Set db_table parameter
1.3. Set probing_interval parameter
1.4. Set probing_method parameter
1.5. Set probing_from parameter
1.6. Set probing_reply_codes parameter
1.7. Set the lb_define_blacklist parameter
1.8. load_balance usage
1.9. lb_disable() usage
1.10. lb_is_destination usage
1.11. lb_count_call usage
1.12. lb_list usage
1.13. lb_status usage

Chapter 1. Admin Guide

1.1. Overview

The Load-Balancer module comes to provide traffic routing based on load. Shortly, when OpenSIPS routes calls to a set of destinations, it is able to keep the load status (as number of ongoing calls) of each destination and to choose to route to the less loaded destination (at that moment). OpenSIPS is aware of the capacity of each destination - it is preconfigured with the maximum load accepted by the destinations. To be more precise, when routing, OpenSIPS will consider the less loaded destination not the destination with the smallest number of ongoing calls, but the destination with the largest available slot.

Also the module has the capability to do failover (to try a new destination if the selected one done not responde), to keep state of the destinations (to remember the failed destination and avoid using them agai) and to check the health of the destination (by doing probing of the destination and auto re-enabling).

1.2. How it works

Please refer to the Load-Balancer tutorial from the OpenSIPS website: http://www.opensips.org/index.php?n=Resources.DocsTutLoadbalancing.

1.3. Probing and Disabling destinations

The module has the capability to monitor the status of the destinations by doing SIP probing (sending SIP requests like OPTIONS).

For each destination, you can configure what kind of probing should be done (probe_mode column):

  • (0) - no probing at all;

  • (1) - probing only when the destination is in disabled mode (disabling via MI command will competely stop the probing also). The destination will be automatically re-enabled when the probing will succeed next time;

  • (2) - probing all the time. If disabled, the destination will be automatically re-enabled when the probing will succeed next time;

A destination can become disabled in two ways:

  • script detection - by calling from script the lb_disabled() function after try the destination. In this case, if probing mode for the destination is (1) or (2), the destination will be automatically re-enabled when the probing will succeed.
  • MI command - by calling the lb_status MI command for disabling (on demand) the destination. If so, the probing and re-enabling of this destination will be completly disabled until you re-enable it again via MI command - this is designed to allow controlled and complete disabling of some destination during maintenance.

1.4. Dependencies

1.4.1. OpenSIPS Modules

The following modules must be loaded before this module:

  • Dialog - Dialog module

  • Dialog - TM module (only if probing enabled)

  • database - one of the DB modules

1.4.2. External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

  • None.

1.5. Exported Parameters

1.5.1. db_url (string)

The URL pointing to the database where the load-balancing rules are stored.

Default value is “mysql://opensips:opensipsrw@localhost/opensips”.

Example 1.1. Set db_url parameter

modparam("load_balancer", "db_url", "dbdriver://username:password@dbhost/dbname")

1.5.2. db_table (string)

The name of the DB table containing the load-balancing rules.

Default value is “load_balancer”.

Example 1.2. Set db_table parameter

modparam("load_balancer", "db_table", "lb")

1.5.3. probing_interval (integer)

How often (in seconds) the probing of a destination should be done. If set to 0, the probing will be disabled as functionality (for all destinations)

Default value is “30”.

Example 1.3. Set probing_interval parameter

modparam("load_balancer", "probing_interval", 60)

1.5.4. probing_method (string)

The SIP method to be used for the probing requests.

Default value is “"OPTIONS"”.

Example 1.4. Set probing_method parameter

modparam("load_balancer", "probing_method", "INFO")

1.5.5. probing_from (string)

The FROM SIP URI to be advertised in the SIP probing requests.

Default value is “"sip:prober@localhost"”.

Example 1.5. Set probing_from parameter

modparam("load_balancer", "probing_from", "sip:pinger@")

1.5.6. probing_reply_codes (string)

A comma separted list of SIP reply codes. The codes defined here will be considered as valid reply codes for probing messages, apart for 200.

Default value is “NULL”.

Example 1.6. Set probing_reply_codes parameter

modparam("load_balancer", "probing_reply_codes", "501, 403")

1.5.7. lb_define_blacklist (string)

Defines a blacklist based on a lb group. This list will contain the IPs (no port, all protocols) of the destinations matching the given group.

Multiple instances of this param are allowed.

Default value is “NULL”.

Example 1.7. Set the lb_define_blacklist parameter

modparam("load_balancer", "lb_define_blacklist", "list= 1,4,3")
modparam("load_balancer", "lb_define_blacklist", "blist2= 2,10,6")

1.6. Exported Functions

1.6.1.  load_balance(grp,resources[,alg])

The function performs load-balancing over the available destinations in order to find the less loaded destination that can provide the requested resources and belong to a requested group.

Meaning of the parameters is as follows:

  • grp - group id for the destinations; the destination may be grouped in several groups you can you for differnet scenarios; this can be a number or a variable containing a numerical value.

  • resources - string containing a semi-colon list of resources required by the current call.

  • algorithm - algorithm used for computing the available load on the system:

    • 0 - Absolute value - the effective available load ( maximum_load - current_load) is used in computing the load of each pear/resource.

    • 1 - Relative value - the relative available load (how many percentages are free) is used in computing the load of each pear/resource.

    If missing, the default algorithm in 0.

Function returns true is a new destination URI is set pointing to the selected destiantion. NOTE that the RURI will not be changed by this function.

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and FAILURE_ROUTE.

Example 1.8. load_balance usage

if (load_balance("1","trascoding;conference")) {
	# dst URI points to the new destination
	xlog("sending call to $du\n");

1.6.2.  lb_disable()

Marks as disabled the last destination that was used for the current call. The disabling done via this function will prevent the destination to be used for usage from now on. The probing mechanism can re-enable this peer (see the probing section in the begining)

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

Example 1.9. lb_disable() usage

if (t_check_status("(408)|(5[0-9][0-9])")) {
	if ( load_balance("1","pstn") ) {
		xlog("-----------new dst is $du\n");
	} else {


1.6.3.  lb_is_destination(ip,port[,group[,active]])

Checks if the given IP and PORT belongs to a destination configured in the load-balancer's list. Returns true if found and active (see the "active" parameter).


Meaning of the parameters is as follows:

  • ip and port - IP and PORT to be checked (any kind of variables are allowed, but take care as the PORT variables should have an interger value); A value 0 for the port means "any" - will match any port.

  • group - in what LB group the destination should be looked for; If not specified, the search will be in all groups.

  • active - if "1", the search will be performed only over "active" (not disabled) destinations. If missing, the search will consider any kind of destinations.

Example 1.10. lb_is_destination usage

if (lb_is_destination("$si","$sp") ) {
	# request from a LB destination

1.6.4.  lb_count_call(ip,port,grp,resources)

The function counts the current call as load for a given destination with some given resources. Note that this call is not going through the load-balancing logic (there are not routing decision taken for the call); it is simply counted by LB as ongoing call for a destination;

Meaning of the parameters is as follows:

  • ip and port - IP and PORT to identify the destination the call has to be counted for.

  • grp - group id for the destinations; if no knows, "-1" will mean all groups.

  • resources - string containing a semi-colon list of resources required by the current call.

Function returns true if the call was properly taken into consideration for estimating the load on the destination.

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and FAILURE_ROUTE.

Example 1.11. lb_count_call usage

# count as load also the calls orgininated by lb destinations
if (lb_is_destination("$si","$sp") ) {
	# inbound call from destination
} else {
	# outbound call to destinations
	if ( !load_balance("1","conference") ) {
	# dst URI points to the new destination
	xlog("sending call to $du\n");

1.7. Exported statistics


1.8. Exported MI Functions

1.8.1. lb_reload

Trigers the reload of the load balancing data from the DB.

MI FIFO Command Format:


1.8.2. lb_resize

Changes the capacity for a resource of a destination. The function receives as parameters the ID (as per DB) of the destination along with the name of the resource you want to resize.

MI FIFO Command Format:

		11   /*dstination id*/
		voicemail  /*resource name*/
		56   /* new resource capacity*/

1.8.3. lb_list

Lists all the destinations and the maximum and current load for each resource of the destination.

MI FIFO Command Format:


Example 1.12. lb_list usage

$ ./opensipsctl fifo lb_list
Destination:: sip: id=1 enabled=yes auto-re=on
        Resource:: pstn max=3 load=0
        Resource:: transc max=5 load=1
        Resource:: vm max=5 load=2
Destination:: sip: id=2 enabled=no auto-re=on
        Resource:: pstn max=6 load=0
        Resource:: trans max=57 load=0
        Resource:: vm max=5 load=0

1.8.4. lb_status

Gets or sets the status (enabled or disabled) of a destination. The function takes 2 parameters, first mandatory, the id of the destiantion and second, optional, the new status. If no new status is given, the function will return the current status. If a new status is given (0 - disable, 1 - enable), this status will be forced for the destination.

MI FIFO Command Format:

		status (optional)

Example 1.13. lb_status usage

$ ./opensipsctl fifo lb_status 2
enable:: no
$ ./opensipsctl fifo lb_status 2 1
$ ./opensipsctl fifo lb_status 2
enable:: yes

1.9. Exported pseudo-variables


Chapter 2. Developer Guide

2.1. Available Functions


Chapter 3. Frequently Asked Questions


Where can I find more about OpenSIPS?

Take a look at http://www.opensips.org/.


Where can I post a question about this module?

First at all check if your question was already answered on one of our mailing lists:

E-mails regarding any stable OpenSIPS release should be sent to and e-mails regarding development versions should be sent to .

If you want to keep the mail private, send it to .


How can I report a bug?

Please follow the guidelines provided at: https://github.com/OpenSIPS/opensips/issues.