kamailio/modules_s/dispatcher

Dispatcher Module

Daniel-Constantin Mierla

   FhG FOKUS

   Copyright © 2004 FhG FOKUS
   Revision History
   Revision $Revision$ $Date$
     __________________________________________________________________

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.

   The dispatcher module offers reloads on the fly using sercmd.

Parameters

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. Set the "list_file" parameter
...
modparam("dispatcher", "list_file", "/var/run/ser/dispatcher.list")
...

force_dst (int)

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

   Default value is "0".

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

flags (int)

   Various flags that affect the hashing behaviour. For now only the flag
   1 and 2 are defined. If flag 1 is set only the username part of the uri
   will be used when computing an uri based hash. If flag 2 is set the
   username part of the uri will be used and if no username part is
   present the hostname part will be used. 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).

   Default value is "0".

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

Functions

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

   Example 4. ds_select_dst usage
...
ds_select_dst("1", "0");
...

FIFO Interface

   The module allows dumping the current configuration as well as
   dispatcher list reloading via the FIFO interface.

   There are two FIFO commands to use with dispatcher.
     * dispatcher.dump - dump the current dispatcher sets
     * dispatcher.reload - reload the dispatcher list text file

Dumping the current configuration

   The command dispatcher.dump can be used to dump the currently deployed
   dispatcher list in the SER internal notation.

   Example 5. dumping the active dispatcher list
# sercmd dispatcher.dump
flags: DI_MAX_SETS: 16 DI_MAX_NODES: 16 DI_MAX_URILEN: 256
Active dispatcher list: 0
Set '0'
  node  0 sip:10.1.1.1:5060
  node  1 sip:10.1.1.2:5060
  node  2 sip:10.1.1.3:5060
  node  3 sip:10.1.1.4:5060
Set '1' is empty
Set '2' is empty
Set '3' is empty
Set '4' is empty
Set '5' is empty
Set '6' is empty
Set '7' is empty
Set '8' is empty
Set '9' is empty
Set '10' is empty
Set '11' is empty
Set '12' is empty
Set '13' is empty
Set '14' is empty
Set '15' is empty

End of dispatcher list
#

Reloading the dispatcher list

   The command dispatcher.reload can be used to update the dispatcher list
   while running SER.

   Example 6. Reloading the dispatcher list
# sercmd fifo dispatcher.reload
dispatcher list 1 activated
#

Installation And Running

   Example 7. 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.
# $Id$
# 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

   Example 8. SER Configuration File
# $Id$
# 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();
}