DISPATCHER Module

Daniel-Constantin Mierla

   voice-system.ro

Edited by

Daniel-Constantin Mierla

Carsten Bock

   Copyright  2004 FhG FOKUS

   Copyright  2005 Voice-System.RO
     __________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSER modules
              1.2.2. External libraries or applications

        1.3. Exported Parameters

              1.3.1. list_file (string)
              1.3.2. db_url (string)
              1.3.3. table_name (string)
              1.3.4. setid_col (string)
              1.3.5. destination_col (string)
              1.3.6. force_dst (int)
              1.3.7. flags (int)
              1.3.8. use_default (int)
              1.3.9. dst_avp (str)
              1.3.10. grp_avp (str)
              1.3.11. cnt_avp (str)
              1.3.12. ds_ping_method (string)
              1.3.13. ds_ping_from (string)
              1.3.14. ds_ping_interval (int)
              1.3.15. ds_probing_threshhold (int)

        1.4. Exported Functions

              1.4.1. ds_select_dst(set, alg)
              1.4.2. ds_select_domain(set, alg)
              1.4.3. ds_next_dst()
              1.4.4. ds_next_domain()
              1.4.5. ds_mark_dst()
              1.4.6. ds_mark_dst("s")
              1.4.7. ds_is_from_list()
              1.4.8. ds_is_from_list("group")

        1.5. Exported MI Functions

              1.5.1. ds_set_state
              1.5.2. ds_list
              1.5.3. ds_reload

        1.6. Installation & Running

              1.6.1. Destination List File
              1.6.2. OpenSER config file

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Set the "list_file" parameter
   1-2. Set "db_url" parameter
   1-3. Set "table_name" parameter
   1-4. Set "setid_col" parameter
   1-5. Set "destination_col" parameter
   1-6. Set the "force_dst" parameter
   1-7. Set the "flags" parameter
   1-8. Set the "use_default" parameter
   1-9. Set the "dst_avp" parameter
   1-10. Set the "grp_avp" parameter
   1-11. Set the "cnt_avp" parameter
   1-12. Set the "ds_ping_method" parameter
   1-13. Set the "ds_ping_from" parameter
   1-14. Set the "ds_ping_interval" parameter
   1-15. Set the "ds_probing_threshhold" parameter
   1-16. ds_select_dst usage
   1-17. dispatcher list file
   1-18. OpenSER config script - sample dispatcher usage
     __________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   This modules implements a dispatcher for destination addresses.
   It computes hashes over parts of the request and selects an
   address from a destination set. The selected address is used
   then as outbound proxy.

   The module can be used as a stateless load balancer, having no
   guarantee of fair distribution.
     __________________________________________________________

1.2. Dependencies

1.2.1. OpenSER modules

   The following modules must be loaded before this module:

     * TM - only if active recovery of failed hosts is required.
     __________________________________________________________

1.2.2. External libraries or applications

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

     * none.
     __________________________________________________________

1.3. Exported Parameters

1.3.1. list_file (string)

   Path to the file with destination sets.

   Default value is "/etc/openser/dispatcher.list" or
   "/usr/local/etc/openser/dispatcher.list".

   Example 1-1. Set the "list_file" parameter
...
modparam("dispatcher", "list_file", "/var/run/openser/dispatcher.list")
...
     __________________________________________________________

1.3.2. db_url (string)

   If you want to load the sets of gateways from the database you
   must set this parameter.

   Default value is "NULL" (disable DB support).

   Example 1-2. Set "db_url" parameter
...
modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database
")
...
     __________________________________________________________

1.3.3. table_name (string)

   If you want to load the sets of gateways from the database you
   must set this parameter as the database name.

   Default value is "dispatcher".

   Example 1-3. Set "table_name" parameter
...
modparam("dispatcher", "table_name", "my_dispatcher")
...
     __________________________________________________________

1.3.4. setid_col (string)

   The column's name in the database storing the gateway's group
   id.

   Default value is "setid".

   Example 1-4. Set "setid_col" parameter
...
modparam("dispatcher", "setid_col", "groupid")
...
     __________________________________________________________

1.3.5. destination_col (string)

   The column's name in the database storing the gateway's sip
   uri.

   Default value is "destination".

   Example 1-5. Set "destination_col" parameter
...
modparam("dispatcher", "destination_col", "uri")
...
     __________________________________________________________

1.3.6. force_dst (int)

   If set to 1, force overwriting of destination address when that
   is already set.

   Default value is "0".

   Example 1-6. Set the "force_dst" parameter
...
modparam("dispatcher", "force_dst", 1)
...
     __________________________________________________________

1.3.7. flags (int)

   Various flags that affect dispatcher's behaviour. The flags are
   defined as a bitmask on an integer value. If flag 1 is set only
   the username part of the uri will be used when computing an uri
   based hash. If no flags are set the username, hostname and port
   will be used The port is used only if different from 5060
   (normal sip uri) or 5061 (in the sips case).

   If flag 2 is set, then the failover support is enabled. The
   functions exported by the module will store the rest of
   addresses from the destination set in AVP, and use these AVPs
   to contact next address when the current-tried fails.

   Default value is "0".

   Example 1-7. Set the "flags" parameter
 ...
 modparam("dispatcher", "flags", 3)
 ...
     __________________________________________________________

1.3.8. use_default (int)

   If the parameter is set to 1, the last address in destination
   set is used as last option to send the message. For example, it
   is good when wanting to send the call to an anouncement server
   saying: "the gateways are full, try later".

   Default value is "0".

   Example 1-8. Set the "use_default" parameter
 ...
 modparam("dispatcher", "use_default", 1)
 ...
     __________________________________________________________

1.3.9. dst_avp (str)

   The name of the avp which will hold the list with addresses, in
   the order they have been selected by the chosen algorithm. If
   use_default is 1, the value of last dst_avp_id is the last
   address in destination set. The first dst_avp_id is the
   selected destinations. All the other addresses from the
   destination set will be added in the avp list to be able to
   implement serial forking.

   Note

        You must set this parameter if you want do do load balancing
        fail over.

   Default value is "null" - don't add AVPs.

   Example 1-9. Set the "dst_avp" parameter
 ...
 modparam("dispatcher", "dst_avp", "$avp(i:271)")
 ...
     __________________________________________________________

1.3.10. grp_avp (str)

   The name of the avp storing the group id of the destination
   set. Good to have it for later usage or checks.

   Note

        You must set this parameter if you want do do load balancing
        fail over.

   Default value is "null" - don't add AVP.

   Example 1-10. Set the "grp_avp" parameter
 ...
 modparam("dispatcher", "grp_avp", "$avp(i:272)")
 ...
     __________________________________________________________

1.3.11. cnt_avp (str)

   The name of the avp storing the number of destination addresses
   kept in dst_avp avps.

   Note

        You must set this parameter if you want do do load balancing
        fail over.

   Default value is "null" - don't add AVP.

   Example 1-11. Set the "cnt_avp" parameter
 ...
 modparam("dispatcher", "cnt_avp", "$avp(i:273)")
 ...
     __________________________________________________________

1.3.12. ds_ping_method (string)

   With this Method you can define, with which method you want to
   probe the failed gateways. This method is only available, if
   compiled with the probing of failed gateways enabled.

   Default value is "OPTIONS".

   Example 1-12. Set the "ds_ping_method" parameter
 ...
 modparam("dispatcher", "ds_ping_method", "INFO")
 ...
     __________________________________________________________

1.3.13. ds_ping_from (string)

   With this Method you can define the "From:"-Line for the
   request, sent to the failed gateways. This method is only
   available, if compiled with the probing of failed gateways
   enabled.

   Default value is "sip:dispatcher@localhost".

   Example 1-13. Set the "ds_ping_from" parameter
 ...
 modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
 ...
     __________________________________________________________

1.3.14. ds_ping_interval (int)

   With this Method you can define the interval for sending a
   request to a failed gateway. This parameter is only used, when
   the TM-Module is loaded. If set to "0", the pinging of failed
   requests is disabled.

   Default value is "10".

   Example 1-14. Set the "ds_ping_interval" parameter
 ...
 modparam("dispatcher", "ds_ping_interval", 30)
 ...
     __________________________________________________________

1.3.15. ds_probing_threshhold (int)

   If you want to set a gateway into probing mode, you will need a
   specific number of requests until it will change from "active"
   to probing. The number of attempts can be set with this
   parameter.

   Default value is "3".

   Example 1-15. Set the "ds_probing_threshhold" parameter
 ...
 modparam("dispatcher", "ds_probing_threshhold", 10)
 ...
     __________________________________________________________

1.4. Exported Functions

1.4.1. ds_select_dst(set, alg)

   The method selects a destination from addresses set.

   Meaning of the parameters is as follows:

     * set - the id of the set from where to pick up destination
       address. It is the first column in destination list file.
     * alg - the algorithm used to select the destination address.
          + "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 (using rand()).
          + "X" - if the algorithm is not implemented, the first
            entry in set is chosen.

   If the bit 2 in 'flags' is set, the rest of the addresses from
   the destination set is stored in AVP list. You can use
   'ds_next_dst()' to use next address to achieve serial forking
   to all possible destinations.

   This function can be used from REQUEST_ROUTE.

   Example 1-16. ds_select_dst usage
...
ds_select_dst("1", "0");
...
     __________________________________________________________

1.4.2. ds_select_domain(set, alg)

   The method selects a destination from addresses set and
   rewrites the host and port from R-URI. The parameters have same
   meaning as for ds_select_dst().

   If the bit 2 in 'flags' is set, the rest of the addresses from
   the destination set is stored in AVP list. You can use
   'ds_next_domain()' to use next address to achieve serial
   forking to all possible destinations.

   This function can be used from REQUEST_ROUTE.
     __________________________________________________________

1.4.3. ds_next_dst()

   Takes the next destination address from the AVPs with id
   'dst_avp_id' and sets the dst_uri (outbound proxy address).

   This function can be used from FAILURE_ROUTE.
     __________________________________________________________

1.4.4. ds_next_domain()

   Takes the next destination address from the AVPs with id
   'dst_avp_id' and sets the domain part of the request uri.

   This function can be used from FAILURE_ROUTE.
     __________________________________________________________

1.4.5. ds_mark_dst()

   Mark the last used address from destination set as inactive, in
   order to be ingnored in the future. In this way it can be
   implemented an automatic detection of failed gateways. When an
   address is marked as inactive, it will be ignored by
   'ds_select_dst' and 'ds_select_domain'.

   This function can be used from FAILURE_ROUTE.
     __________________________________________________________

1.4.6. ds_mark_dst("s")

   Mark the last used address from destination set as inactive
   ("i"/"I"/"0"), active ("a"/"A"/"1") or probing ("p"/"P"/"2").
   With this function, an automatic detection of failed gateways
   can be implemented. When an address is marked as inactive or
   probing, it will be ignored by 'ds_select_dst' and
   'ds_select_domain'.

   possible parameters:

     * "i", "I" or "0" - the last destination should be set to
       inactive and will be ignored in future requests.
     * "a", "A" or "1" - the last destination should be set to
       active.
     * "p", "P" or "2" - the last destination will be set to
       probing. Note: You will need to call this function
       "threshhold"-times, before it will be actually set to
       probing.

   This function can be used from FAILURE_ROUTE.
     __________________________________________________________

1.4.7. ds_is_from_list()

   This function returns true, if the current request comes from a
   host from the dispatcher-list; otherwise false.

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

1.4.8. ds_is_from_list("group")

   This function returns true, if the current request comes from a
   host in the given group of the dispatcher-list; otherwise
   false.

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

1.5. Exported MI Functions

1.5.1. ds_set_state

   Sets the status for a destination address (can be use to mark
   the destination as active or inactive).

   Name: ds_set_state

   Parameters:

     * _state_ : state of the destination address
          + "a": active
          + "i": inactive
          + "p": probing
     * _group_: destination group id
     * _address_: address of the destination in the _group_

   MI FIFO Command Format:
                :ds_set_state:_reply_fifo_file_
                _state_
                _group_
                _address_
                _empty_line_
     __________________________________________________________

1.5.2. ds_list

   It lists the groups and included destinations.

   Name: ds_list

   Parameters: none

   MI FIFO Command Format:
                :ds_list:_reply_fifo_file_
                _empty_line_
     __________________________________________________________

1.5.3. ds_reload

   It reloads the groups and included destinations.

   Name: ds_reload

   Parameters: none

   MI DATAGRAM Command Format:
                ":ds_reload:\n."
     __________________________________________________________

1.6. Installation & Running

1.6.1. Destination List File

   Each destination point must be on one line. First token is the
   set id and next is destination address. The set id must be an
   integer value. Destination address must be a valid SIP URI.
   Empty lines or lines starting with "#" are ignored.

   Example 1-17. dispatcher list file
...
# $Id: README 3351 2007-12-13 10:43:52Z bogdan_iancu $
# dispatcher destination sets
#

# proxies
2 sip:127.0.0.1:5080
2 sip:127.0.0.1:5082

# gateways
1 sip:127.0.0.1:7070
1 sip:127.0.0.1:7072
1 sip:127.0.0.1:7074
...
     __________________________________________________________

1.6.2. OpenSER config file

   Next picture displays a sample usage of dispatcher.

   Example 1-18. OpenSER config script - sample dispatcher usage
...
# $Id: README 3351 2007-12-13 10:43:52Z bogdan_iancu $
# sample config file for dispatcher module
#

debug=9          # debug level (cmd line: -dddddddddd)
fork=no
log_stderror=yes  # (cmd line: -E)

children=2
check_via=no      # (cmd. line: -v)
dns=off           # (cmd. line: -r)
rev_dns=off       # (cmd. line: -R)
port=5060

# for more info: sip_router -h

# ------------------ module loading ----------------------------------

loadmodule "modules/maxfwd/maxfwd.so"
loadmodule "modules/sl/sl.so"
loadmodule "modules/dispatcher/dispatcher.so"

# loadmodule "modules/tm/tm.so"

# ----------------- setting module-specific parameters ---------------
# -- dispatcher params --

modparam("dispatcher", "list_file", "../etc/dispatcher.list")
# modparam("dispatcher", "force_dst", 1)

route{
        if ( !mf_process_maxfwd_header("10") )
        {
                sl_send_reply("483","To Many Hops");
                drop();
        };

        ds_select_dst("2", "0");

        forward();
        # t_relay();
}

...
     __________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     __________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Does dispatcher provide a fair distribution?
   3.2. Is dispatcher dialog stateful?
   3.3. Where can I find more about OpenSER?
   3.4. Where can I post a question about this module?
   3.5. How can I report a bug?

   3.1. Does dispatcher provide a fair distribution?

   There is no guarantee of that. You should do some measurements
   to decide what distribution algorithm fits better in your
   environment.

   3.2. Is dispatcher dialog stateful?

   No. Dispatcher is stateless, although some distribution
   algorithms are designed to select same destination for
   subsequent requests of the same dialog (e.g., hashing the
   call-id).

   3.3. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

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

   E-mails regarding any stable version should be sent to
   <users@openser.org> and e-mail regarding development versions
   or CVS snapshots should be send to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.5. How can I report a bug?

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