DISPATCHER Module

Daniel-Constantin Mierla

Edited by

Daniel-Constantin Mierla


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. force_dst (int)
1.3.3. flags (int)
1.3.4. use_default (int)
1.3.5. dst_avp_id (int)
1.3.6. grp_avp_id (int)
1.3.7. cnt_avp_id (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.5. Installation & Running
1.5.1. Destination List File
1.5.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 the "force_dst" parameter
1-3. Set the "flags" parameter
1-4. Set the "use_default" parameter
1-5. Set the "dst_avp_id" parameter
1-6. Set the "grp_avp_id" parameter
1-7. Set the "cnt_avp_id" parameter
1-8. ds_select_dst usage
1-9. dispatcher list file
1-10. 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:

  • none.


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. 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.3.3. 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-3. Set the "flags" parameter

 ...
 modparam("dispatcher", "flags", 3)
 ...
 

1.3.4. 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-4. Set the "use_default" parameter

 ...
 modparam("dispatcher", "use_default", 1)
 ...
 

1.3.5. dst_avp_id (int)

The id 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.

Default value is "271".

Example 1-5. Set the "dst_avp_id" parameter

 ...
 modparam("dispatcher", "dst_avp_id", 100)
 ...
 

1.3.6. grp_avp_id (int)

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

Default value is "272".

Example 1-6. Set the "grp_avp_id" parameter

 ...
 modparam("dispatcher", "grp_avp_id", 101)
 ...
 

1.3.7. cnt_avp_id (int)

The id of the avp storing the number of destination addresses kept in dst_avp_id avps.

Default value is "273".

Example 1-7. Set the "cnt_avp_id" parameter

 ...
 modparam("dispatcher", "cnt_avp_id", 103)
 ...
 

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).

    • "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-8. 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.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-9. dispatcher list file

...
# $Id: dispatcher.list 1007 2006-07-10 17:57:20Z  $
# 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. OpenSER config file

Next picture displays a sample usage of dispatcher.

Example 1-10. OpenSER config script - sample dispatcher usage

...
# $Id: dispatcher.cfg 900 2006-06-06 14:58:04Z 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:

E-mails regarding any stable version should be sent to and e-mail regarding development versions or CVS snapshots should be send to .

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

3.5. How can I report a bug?

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