Mod distributor

From FreeSWITCH Wiki
Jump to: navigation, search

Contents

Introduction

This module is used to create simple round-robin style distributions to gateways.

Installing

Edit modules.conf and add the following line:

applications/mod_distributor

Then,

make mod_distributor
make mod_distributor-install


Tell FreeSWITCH to load the module by adding the line below to modules.conf.xml in /usr/local/freeswitch/conf/autoload_configs:

<load module="mod_distributor"/>

Usage

There are several ways to use the distributor, however it frequently will be used with the bridge app. For example, if you have two gateways defined you can have the distributor fill in the dialstring like this:

<action application="bridge" data="sofia/gateway/${distributor(distributor_list)}/${destination_number}"/>

-- or--

<action application="bridge" data="sofia/external/${destination_number}@${distributor(distributor_list)}"/>


To reload distributor.conf.xml at the CLI:

reloadxml
distributor_ctl reload

Discussion

mod_distributor works by returning node values from the configuration file. Here's a sample:

<configuration name="distributor.conf" description="Distributor Configuration">
  <lists>
    <!-- every 10 calls to test you will get foo1 once and foo2 9 times...yes NINE TIMES! -->
    <!-- this is not the same as 100 with 10 and 90 that would do foo1 10 times in a row then foo2 90 times in a row -->
    <list name="test" total-weight="10">
      <node name="foo1" weight="1"/>
      <node name="foo2" weight="9"/>
    </list>
  </lists>
</configuration>

In the list named "test" the total weight is 10, and the individual nodes each have their weights add up to 10. When the distributor is called for test, it will return foo1 the first time, then it will return foo2 the next nine times. The next call will return foo1 again, and then the next nine will be foo2, and so on.

To do an alternating list use something like this:

  <list name="alternating" total-weight="2">
    <node name="alt_one" weight="1"/>
    <node name="alt_two" weight="1"/>
  </list>

In the above example, each call to distributor(alternating) will alternate between returning alt_one and alt_two.

You can use this to send calls out multiple gateways for simple load-sharing. Let's say you have three different gateways defined as gateway1, gateway2, and gateway3. To send every third call out each gateway you would need to put this in your distributor.conf.xml file:

  <list name="3gw" total-weight="3">
    <node name="gateway1" weight="1"/>
    <node name="gateway2" weight="1"/>
    <node name="gateway3" weight="1"/>
  </list>

Then define a dialplan extension similar to this:

  <extension name="3-way gateway distro">
    <condition field="destination_number" expression="^(.*)$">
      <action application="bridge" data="sofia/gateway/${distributor(3gw)}/$1"/>
    </condition>
  </extension>

The distributor will supply the name of the gateway to use. Each call that comes through diaplan will trigger the distributor which will in turn supply the appropriate response.


Loop in XML Dialplan
New option (r16886): Loop attribute in XML Dialplan.
When you want the dialplan to continue and get executed if the previous bridge failed, you can do the following:

  <extension name="3-way gateway distro">
    <condition field="destination_number" expression="^(.*)$">
      <action application="set" data="continue_on_fail=true"/>
      <action application="set" data="hangup_after_bridge=true"/>
      <action application="bridge" data="sofia/gateway/${distributor(3gw)}/$1" loop="3"/>
    </condition>
  </extension>

To exclude dead gateways in your dialplan

<action application="bridge" data="sofia/gateway/${distributor(<listname> ${sofia(profile <profilename> gwlist down)})}/$1"/>

--or--
Note: based on git head: fdba0e07 (10/08/2010), parentheses are optional on functions as vars: ${foo(bar)} is now the same as ${foo bar}

<action application="bridge" data="sofia/gateway/${distributor <listname> ${sofia profile <profilename> gwlist down}}/$1"/>

--or--

<action application="bridge" data="sofia/gateway/${expand(distributor <listname> \${sofia(profile <profilename> gwlist down)})}/$1"/>
To run it from api command
expand distributor <listname> ${sofia profile <profilename> gwlist down}

See Also