
DISPATCHER Module

Daniel-Constantin Mierla

   FhG FOKUS

Edited by

Daniel-Constantin Mierla

   Copyright  2004 FhG FOKUS
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. SER modules
              1.2.2. External libraries or applications

        1.3. Exported Parameters

              1.3.1. list_file (string)
              1.3.2. force_dst (int)

        1.4. Exported Functions

              1.4.1. ds_select_dst(set, alg)

        1.5. Installation & Running

              1.5.1. Destination List File
              1.5.2. SER config file

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Set the "list_file" parameter
   1-2. Set the "force_dst" parameter
   1-3. ds_select_dst usage
   1-4. dispatcher list file
   1-5. SER 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. SER modules

   The following modules must be loaded before this module:

     * none.
     _________________________________________________________

1.2.2. External libraries or applications

   The following libraries or applications must be installed
   before running SER 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/ser/dispatcher.list" or
   "/usr/local/etc/ser/dispatcher.list". 

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

1.3.2. force_dst (int)

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

   Default value is "0". 

   Example 1-2. Set the "force_dst" parameter
...
modparam("dispatcher", "force_dst", 1)
...
     _________________________________________________________

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.
          + "X" - if the algorithm is not implemented, the first
            entry in set is chosen.

   Example 1-3. ds_select_dst usage
...
ds_select_dst("1", "0");
...
     _________________________________________________________

1.5. Installation & Running

1.5.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-4. dispatcher list file
...
# $Id: README,v 1.2.2.1 2005/06/22 23:12:01 janakj Exp $
# 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.5.2. SER config file

   Next picture displays a sample usage of dispatcher.

   Example 1-5. SER config script - sample dispatcher usage
...
# $Id: README,v 1.2.2.1 2005/06/22 23:12:01 janakj Exp $
# 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 "../sip_router/modules/maxfwd/maxfwd.so"
loadmodule "../sip_router/modules/sl/sl.so"
# loadmodule "../sip_router/modules/tm/tm.so"
loadmodule "../sip_router/modules/dispatcher/dispatcher.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(uri:host, uri:port);
        # t_relay();
}

...
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any sort of API to use in other
   SER 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 SER?
   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 SER?

   Take a look at http://iptel.org/ser.

   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:

     * http://mail.iptel.org/mailman/listinfo/serusers
     * http://mail.iptel.org/mailman/listinfo/serdev

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

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

   3.5. How can I report a bug?

   Please follow the guidelines provided at:
   http://iptel.org/ser/bugs
