Load-Balancer Module

Bogdan-Andrei Iancu

   Voice Sistem SRL

Edited by

Bogdan-Andrei Iancu

   Copyright © 2009 voice-system.ro
   Revision History
   Revision $Revision: 5913 $ $Date: 2009-07-21 10:45:05 +0300
                              (Tue, 21 Jul 2009) $
     __________________________________________________________

   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.6. Exported Functions

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

        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_dlg_profile usage
   1.8. lb_disable() usage
   1.9. lb_list usage
   1.10. 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.DocsTutLoadbalanc
   ing.

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@192.168.2.10")
...

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.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.7. set_dlg_profile usage
...
if (load_balance("1","trascoding;conference")) {
        # dst URI points to the new destination
        xlog("sending call to $du\n");
        t_relay();
        exit;
}
...

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.8. lb_disable() usage
...
if (t_check_status("(408)|(5[0-9][0-9])")) {
        lb_disable();
        if ( load_balance("1","pstn") ) {
                t_on_failure("1");
                xlog("-----------new dst is $du\n");
                t_relay();
        } else {
                t_reply("500","Error");
        }
}

...

1.7. Exported statistics

   NONE

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:
                :lb_reload:_reply_fifo_file_
                _empty_line_

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:
                :lb_resize:_reply_fifo_file_
                11   /*dstination id*/
                voicemail  /*resource name*/
                56   /* new resource capacity*/
                _empty_line_

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:
                :lb_list:_reply_fifo_file_
                _empty_line_

   Example 1.9. lb_list usage
$ ./opensipsctl fifo lb_list
Destination:: sip:127.0.0.1:5100 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:127.0.0.1:5200 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:
                :lb_status:_reply_fifo_file_
                id
                status (optional)
                _empty_line_

   Example 1.10. 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

   NONE

Chapter 2. Developer Guide

2.1. Available Functions

   NONE

Chapter 3. Frequently Asked Questions

   3.1.

       Where can I find more about OpenSIPS?

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

   3.2.

       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:
         * User Mailing List -
           http://lists.opensips.org/cgi-bin/mailman/listinfo/users
         * Developer Mailing List -
           http://lists.opensips.org/cgi-bin/mailman/listinfo/devel

       E-mails regarding any stable OpenSIPS release should be sent to
       <users@lists.opensips.org> and e-mails regarding development
       versions should be sent to <devel@lists.opensips.org>.

       If you want to keep the mail private, send it to
       <users@lists.opensips.org>.

   3.3.

       How can I report a bug?

       Please follow the guidelines provided at:
       http://sourceforge.net/tracker/?group_id=232389.
