mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1676 lines
49 KiB
1676 lines
49 KiB
<?xml version="1.0" encoding='ISO-8859-1'?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
|
|
|
|
<!-- Include general documentation entities -->
|
|
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
|
|
%docentities;
|
|
|
|
]>
|
|
<!-- Module User's Guide -->
|
|
|
|
<chapter xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<title>&adminguide;</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<para>
|
|
This module offers SIP load balancer functionality and it can be
|
|
used as SIP traffic dispatcher. There are many load balancing and
|
|
traffic dispaching algorithms that you can choose from, for example:
|
|
round-robin, weight based load balancing, call load distribution,
|
|
and hashing over SIP message attributes.
|
|
</para>
|
|
<para>
|
|
The module can be used as a stateless load balancer; it does not
|
|
depend on any call state tracking module. It requires the TM module if
|
|
you enable auto-discovery of active/inactive gateways.
|
|
</para>
|
|
<para>
|
|
It is very lightweight, therefore suitable for handling heavy SIP
|
|
traffic. As the module has a small footprint and the ability to load
|
|
balancing rules from a plain text file, it is suitable for embedded systems.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; modules</title>
|
|
<para>
|
|
The following modules must be loaded before this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>TM - only if active recovery of failed hosts
|
|
is required</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>database engine - only if you want to load
|
|
balancing routes from database instead of plain text file.
|
|
</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>External libraries or applications</title>
|
|
<para>
|
|
The following libraries or applications must be installed before
|
|
running &kamailio; with this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>none</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section id="dispatcher.p.list_file">
|
|
<title><varname>list_file</varname> (string)</title>
|
|
<para>
|
|
Path to the file with destination sets.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>/etc/kamailio/dispatcher.list</quote> or
|
|
<quote>/usr/local/etc/kamailio/dispatcher.list</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>list_file</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.db_url">
|
|
<title><varname>db_url</varname> (string)</title>
|
|
<para>
|
|
If you want to load the sets of gateways from the database you must set
|
|
this parameter.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>NULL</quote> (disable DB support).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <quote>db_url</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.table_name">
|
|
<title><varname>table_name</varname> (string)</title>
|
|
<para>
|
|
If you want to load the sets of gateways from the database you must set
|
|
this parameter as the database name.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>dispatcher</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <quote>table_name</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "table_name", "my_dispatcher")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.setid_col">
|
|
<title><varname>setid_col</varname> (string)</title>
|
|
<para>
|
|
The column's name in the database storing the gateway's group id.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>setid</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <quote>setid_col</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "setid_col", "groupid")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.destination_col">
|
|
<title><varname>destination_col</varname> (string)</title>
|
|
<para>
|
|
The column's name in the database storing the destination
|
|
sip URI.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>destination</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <quote>destination_col</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "destination_col", "uri")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.flags_col">
|
|
<title><varname>flags_col</varname> (string)</title>
|
|
<para>
|
|
The column's name in the database storing the flags for
|
|
the destination URI.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>flags</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <quote>flags_col</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "flags_col", "dstflags")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.priority_col">
|
|
<title><varname>priority_col</varname> (string)</title>
|
|
<para>
|
|
The column's name in the database storing the priority for
|
|
destination URI.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>priority</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <quote>priority_col</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "priority_col", "dstpriority")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.force_dst">
|
|
<title><varname>force_dst</varname> (int)</title>
|
|
<para>
|
|
If set to 1, force overwriting of destination address (outbound proxy)
|
|
when that is already set. If set to 0, will return error when the
|
|
destination address is already set.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>1</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>force_dst</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "force_dst", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.flags">
|
|
<title><varname>flags</varname> (int)</title>
|
|
<para>
|
|
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).
|
|
</para>
|
|
<para>
|
|
If flag 2 is set, then failover support is enabled. The functions
|
|
exported by the module will store the rest of addresses from the
|
|
destination set in the AVP, and use these AVPs to contact next address if
|
|
the current-tried destination fails.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>flags</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "flags", 3)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.use_default">
|
|
<title><varname>use_default</varname> (int)</title>
|
|
<para>
|
|
If the parameter is set to 1, the last address in destination set
|
|
is used as a final option to send the request to. For example, it is useful
|
|
when wanting to send the call to an anouncement server saying:
|
|
"the gateways are full, try later".
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>use_default</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "use_default", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.dst_avp">
|
|
<title><varname>dst_avp</varname> (str)</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
You must set this parameter if you want to do load balancing fail over.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote> - don't add AVPs.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>dst_avp</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "dst_avp", "$avp(dsdst)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.grp_avp">
|
|
<title><varname>grp_avp</varname> (str)</title>
|
|
<para>
|
|
The name of the avp storing the group id of the destination set. Good
|
|
to have it for later usage or checks.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
You must set this parameter if you want to do load balancing fail over.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote> - don't add AVP.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>grp_avp</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "grp_avp", "$avp(dsgrp)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.cnt_avp">
|
|
<title><varname>cnt_avp</varname> (str)</title>
|
|
<para>
|
|
The name of the avp storing the number of destination addresses kept in
|
|
dst_avp AVPs.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
You must set this parameter if you want to do load balancing fail over.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote> - don't add AVP.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>cnt_avp</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "cnt_avp", "$avp(dscnt)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.dstid_avp">
|
|
<title><varname>dstid_avp</varname> (str)</title>
|
|
<para>
|
|
The name of the avp storing the destination unique ID used for
|
|
call load based dispatching.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
You must set this parameter if you want to do load balancing on
|
|
call load (alg 10).
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote> - don't add AVP.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>dstid_avp</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "dstid_avp", "$avp(dsdstid)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.attrs_avp">
|
|
<title><varname>attrs_avp</varname> (str)</title>
|
|
<para>
|
|
The name of the avp storing destination's attributes value.
|
|
</para>
|
|
<note>
|
|
</note>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote> - don't add AVP.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>attrs_avp</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "attrs_avp", "$avp(dsattrs)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.sock_avp">
|
|
<title><varname>sock_avp</varname> (str)</title>
|
|
<para>
|
|
The name of the avp which will hold the list with the sockets associated to the addresses stored in dst_avp avp.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
If you want to do load balancing fail over, you have to set this parameter to use the correct socket for each gateway.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote> - don't add AVPs.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>sock_avp</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "sock_avp", "$avp(dssocket)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.hash_pvar">
|
|
<title><varname>hash_pvar</varname> (str)</title>
|
|
<para>
|
|
String with PVs used for the hashing algorithm 7.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
You must set this parameter if you want do hashing over custom message
|
|
parts.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote> - disabled.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Use $avp(i:273) for hashing:</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "hash_pvar", "$avp(i:273)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Use combination of PVs for hashing:</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.setid_pvname">
|
|
<title><varname>setid_pvname</varname> (str)</title>
|
|
<para>
|
|
The name of the PV where to store the set ID (group ID) when calling
|
|
ds_is_from_list() with no parameter.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote> - don't set PV.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>setid_pvname</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "setid_pvname", "$var(setid)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.attrs_pvname">
|
|
<title><varname>attrs_pvname</varname> (str)</title>
|
|
<para>
|
|
The name of the PV where to store the attributes of matching address
|
|
when calling ds_is_from_list().
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote> - don't set PV.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>attrs_pvname</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "attrs_pvname", "$var(attrs)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.ds_ping_method">
|
|
<title><varname>ds_ping_method</varname> (string)</title>
|
|
<para>
|
|
With this method you can define, with which method you want to probe the gateways.
|
|
Pinging gateways feature depends on ds_ping_interval parameter.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>OPTIONS</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_ping_method</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_ping_method", "INFO")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.ds_ping_from">
|
|
<title><varname>ds_ping_from</varname> (string)</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>sip:dispatcher@localhost</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_ping_from</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.ds_ping_interval">
|
|
<title><varname>ds_ping_interval</varname> (int)</title>
|
|
<para>
|
|
With this parameter you can define the interval for sending a request
|
|
to a gateway marked as inactive upon a failed request routing to it.
|
|
This parameter is only used, when the TM-Module is loaded.
|
|
If set to <quote>0</quote>, the pinging of inactive gateway is disabled.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_ping_interval</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_ping_interval", 30)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.ds_probing_threshold">
|
|
<title><varname>ds_probing_threshold</varname> (int)</title>
|
|
<para>
|
|
If you want to set a gateway into inactive mode, there can be
|
|
a specific number of failed requests until it will change from "active"
|
|
to "inactive". It is using the state "trying", that allows selection
|
|
of gateway but indicates there was a failure previously with the
|
|
gateway. The number of attempts can be set with this parameter.
|
|
This parameter can be modified via ser config framework.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>1</quote> (set inactive with first failure).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_probing_threshold</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_probing_threshold", 10)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.ds_inactive_threshold">
|
|
<title><varname>ds_inactive_threshold</varname> (int)</title>
|
|
<para>
|
|
If you want to set a gateway into active mode (after being inactive), there can be
|
|
a specific number of successful requests until it will change from "inactive"
|
|
to "active". The number of attempts can be set with this parameter.
|
|
This parameter can be modified via ser config framework.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>1</quote> (set active with first success).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_inactive_threshold</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_inactive_threshold", 10)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.ds_ping_reply_codes">
|
|
<title><varname>ds_ping_reply_codes</varname> (string)</title>
|
|
<para>
|
|
This parameter defines the valid response codes, which are accepted as a valid reply to the PING-Method.
|
|
It is a list separated by colons, whery you may define either a single code (e.g. "code=202" would accept 202 as an additional, valid response) or a class of responses, you want to accept (e.g. "class=2" would accept everything from 200 to 299 as valid response).
|
|
This parameter can be modified via ser config framework.
|
|
</para>
|
|
<para>
|
|
Please note that the response codes the module accepts as valid reply to the
|
|
PING-Method are not only the ones generated from the remote servers, but also those
|
|
that are generated locally. E.g.: setting code=408 or class=400 will never set
|
|
a backend down even if it is, because internally the Kamailio transaction layer
|
|
generates a 408 in the case of no response from the remote server, and this
|
|
internal code 408 is accepted as valid value.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote></quote> (only 200 OK is accepted).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_ping_reply_codes</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=3")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.ds_probing_mode">
|
|
<title><varname>ds_probing_mode</varname> (int)</title>
|
|
<para>
|
|
Controls what gateways are tested to see if they are reachable.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Value 0: If set to 0, only the gateways with state PROBING are tested.
|
|
After a gateway is probed, the PROBING state is cleared in this mode.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Value 1: If set to 1, all gateways are tested. If set to 1 and there is a failure of keepalive
|
|
to an active gateway, then it is set to TRYING state.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Value 2: if set to 2, only gateways in inactive state with probing mode set are tested.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Value 3: If set to 3, any gateway with state PROBING is continually probed
|
|
without modifying/removing the PROBING state. This allows selected gateways
|
|
to be probed continually, regardless of state changes.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_probing_mode</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_probing_mode", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.ds_hash_size">
|
|
<title><varname>ds_hash_size</varname> (int)</title>
|
|
<para>
|
|
The value to be used as power of two to set the number of slots
|
|
to hash table storing data for call load dispatching (e.g., value
|
|
8 will create a hash table with 256 slots).
|
|
It must be greater than 0 to enable call load dispatching feature
|
|
(alg 10).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_hash_size</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_hash_size", 9)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.ds_hash_expire">
|
|
<title><varname>ds_hash_expire</varname> (int)</title>
|
|
<para>
|
|
Expiration time in seconds to remove the load on a destination if no
|
|
BYE was received meanwhile.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>7200</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_hash_expire</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_hash_expire", 3600)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.ds_hash_initexpires">
|
|
<title><varname>ds_hash_initexpire</varname> (int)</title>
|
|
<para>
|
|
Expiration time in seconds to remove the load on a destination if no
|
|
200 for INVITE was received meanwhile and state updated with
|
|
ds_load_update().
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>7200</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_hash_initexpire</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_hash_initexpire", 60)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.ds_hash_check_interval">
|
|
<title><varname>ds_hash_check_interval</varname> (int)</title>
|
|
<para>
|
|
Time interval in seconds to scan internal hash table with call load
|
|
dispatching data for expired items.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>30</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_hash_check_interval</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_hash_check_interval", 60)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.p.outbound_proxy">
|
|
<title><varname>outbound_proxy</varname> (str)</title>
|
|
<para>
|
|
SIP URI of outbound proxy to be used when sending pings.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
By default no outbound proxy is defined.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>outbound_proxy</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.ds_default_socket">
|
|
<title><varname>ds_default_socket</varname> (str)</title>
|
|
<para>
|
|
Default socket to be used for sending pings and dispatching requests
|
|
when a gateway has no send socket configured.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
By default no default socket is defined, the first configuration
|
|
script <emphasis>listen</emphasis> directive is used.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_default_socket</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="dispatcher.p.ds_timer_mode">
|
|
<title><varname>ds_timer_mode</varname> (int)</title>
|
|
<para>
|
|
Specify the timer process to be used by the module for
|
|
keepalives and active dialogs tracking.
|
|
</para>
|
|
<para>
|
|
It can be set to:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>0 - use main timer process.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>1 - use secondary timer process.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
On a server with a lot of traffic, using secondary
|
|
timer can help with performances, because the main timer
|
|
can be overloaded by taking care of transactions retransmissions
|
|
and expirations of items in memory.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set the <quote>ds_timer_mode</quote> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("dispatcher", "ds_timer_mode", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Functions</title>
|
|
<section id="dispatcher.f.ds_select_dst">
|
|
<title>
|
|
<function moreinfo="none">ds_select_dst(set, alg[, limit])</function>
|
|
</title>
|
|
<para>
|
|
The method selects a destination from addresses set. It returns true if
|
|
a new destination is set. The selected address is set to dst_uri field
|
|
(aka the outbound proxy address or the $du variable), not being visible
|
|
in the SIP request.
|
|
</para>
|
|
<para>
|
|
If the bit 2 in 'flags' parameter is set, the rest of the addresses from
|
|
the destination set is stored in AVP list (limited with an optional 'limit'
|
|
parameter). You can use 'ds_next_dst()' to use next address in order to
|
|
achieve serial forking to all possible destinations.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>set</emphasis> - the id of the set from where to pick
|
|
up destination address. It is the first column in destination
|
|
list file. The parameter can be an integer or a variable holding
|
|
an integer.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>alg</emphasis> - the algorithm used to select the
|
|
destination address. The parameter can be an integer or a
|
|
variable holding an interger.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<quote>0</quote> - hash over callid
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>1</quote> - hash over from URI.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>2</quote> - hash over to URI.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>3</quote> - hash over request-URI.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>4</quote> - round-robin (next destination).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>5</quote> - hash over authorization-username
|
|
(Proxy-Authorization or "normal" authorization). If no
|
|
username is found, round robin is used.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>6</quote> - random destination (using rand()).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>7</quote> - hash over the content of PVs string.
|
|
Note: This works only when the parameter hash_pvar is set.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>8</quote> - select destination sorted by priority
|
|
attribute value (serial forking ordered by priority).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>9</quote> - use weight based load distribution. You
|
|
have to set the attribute 'weight' per each address in
|
|
destination set.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>10</quote> - use call load distribution. You have
|
|
to set the attribute 'duid' (as an unique string id)
|
|
per each address in destination set. Also, you must set
|
|
parameters 'dstid_avp' and 'ds_hash_size'.
|
|
</para>
|
|
<para>
|
|
The algorithm can be used even with stateless proxy mode,
|
|
there is no SIP dialog tracking depending on other modules,
|
|
just an internal lightweight call tracking by Call-Id, thus
|
|
is fast and suitable even for embedded systems.
|
|
</para>
|
|
<para>
|
|
The first destination selected by this algorithm is the one
|
|
that has the least number of calls associated. The rest of
|
|
the destination list is taken in order of the entries in set
|
|
- anyhow, until a re-route to next destination happens, the
|
|
load on each address can change.
|
|
</para>
|
|
<para>
|
|
This algorithm can be used only for dispatching INVITE
|
|
requests as it is the only SIP method creating a SIP call.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>11</quote> - use relative weight based load distribution.
|
|
You have to set the attribute 'rweight' per each address in
|
|
destination set. Active host usage probability is
|
|
rweight/(SUM of all active host rweights in destination group).
|
|
</para>
|
|
<para>
|
|
The major difference from the weight distribution is the
|
|
probability recalculation according to rweight value in case of
|
|
host enabling/disabling
|
|
</para>
|
|
<para>
|
|
For example, 100 calls in 3-hosts group with rweight params 1/2/1
|
|
will be distributed as 25/50/25. After third host failing
|
|
distribution will be changed to 33/67/0.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<quote>X</quote> - if the algorithm is not implemented, the
|
|
first entry in set is chosen.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>limit</emphasis> - the maximum number of items to be
|
|
stored in AVP list for further failovers (the first selected
|
|
destination and default destination are the first to be put in
|
|
the list)
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>ds_select_dst</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
ds_select_dst("1", "0");
|
|
...
|
|
$var(a) = 4;
|
|
ds_select_dst("1", "$var(a)");
|
|
...
|
|
ds_select_dst("1", "4", "3");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.f.ds_select_domain">
|
|
<title>
|
|
<function moreinfo="none">ds_select_domain(set, alg[, limit])</function>
|
|
</title>
|
|
<para>
|
|
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().
|
|
</para>
|
|
<para>
|
|
If the bit 2 in 'flags' is set, the rest of the addresses from the
|
|
destination set is stored in AVP list (limited with an optional 'limit'
|
|
parameter). You can use 'ds_next_domain()' to use next address to
|
|
achieve serial forking to all possible destinations.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">ds_next_dst()</function>
|
|
</title>
|
|
<para>
|
|
Takes the next destination address from the AVPs with id 'dst_avp_id'
|
|
and sets the dst_uri (outbound proxy address).
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">ds_next_domain()</function>
|
|
</title>
|
|
<para>
|
|
Takes the next destination address from the AVPs with id 'dst_avp_id'
|
|
and sets the domain part of the request URI.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
</section>
|
|
<section id="dispatcher.f.ds_mark_dst">
|
|
<title>
|
|
<function moreinfo="none">ds_mark_dst([state])</function>
|
|
</title>
|
|
<para>
|
|
Mark the last used address from destination set as inactive
|
|
("i"/"I"), active ("a"/"A"), disabled ("d"/"D") or trying ("t"/"T").
|
|
Apart of disabled state, a destination can be set in probing mode by
|
|
adding ("p"/"P") flag. With this function, an automatic detection
|
|
of failed gateways can be implemented. When an address is marked as
|
|
inactive or disabled, it will be ignored by 'ds_select_dst' and
|
|
'ds_select_domain'.
|
|
</para>
|
|
<para>
|
|
The parameter state is optional, when it is missing, then
|
|
the destination will be marked inactive (i.e., same as 'i').
|
|
</para>
|
|
<para>Possible values for state parameter:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>"a" or "A"</emphasis> - the last destination
|
|
should be set to active and the error-counter should set to "0".
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>"i" or "I"</emphasis> - the last destination
|
|
should be set to inactive and will be ignored in future
|
|
requests.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>"t" or "T"</emphasis> - the last destination
|
|
should be set to temporary trying state and failure counter
|
|
is incremented. When the failure counter reaches the threshold,
|
|
the destination will be set inactive.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>"p" and "P"</emphasis> - this has to be used in
|
|
addition to one of the previous flags - the last destination
|
|
will be set to probing. This mean the destination will be pinged
|
|
with SIP OPTIONS requests from time to time to detect if it is
|
|
up or down.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>ds_mark_dst</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
failure_route[tryagain] {
|
|
...
|
|
if(t_check_status("500"))
|
|
ds_mark_dst("ip"); # set to inactive and probing
|
|
...
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.f.ds_list_exist">
|
|
<title>
|
|
<function moreinfo="none">ds_list_exist(groupid)</function>
|
|
</title>
|
|
<para>
|
|
Check if a specific group is defined in dispatcher list
|
|
or database.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>groupid</emphasis> - A group ID to check.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>ds_list_exist</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if(ds_list_exist("10")) {
|
|
...
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.f.ds_is_from_list">
|
|
<title>
|
|
<function moreinfo="none">ds_is_from_list([groupid [, mode [, uri] ] ])</function>
|
|
</title>
|
|
<para>
|
|
This function returns true, if there is a match of source address or uri
|
|
with an address in the given group of the dispatcher-list; otherwise false.
|
|
</para>
|
|
<para>Description of parameters:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>groupid</emphasis> (optional) - if not given or its
|
|
value is -1, the matching will be done over all addresses in
|
|
all dispacher groups. Otherwise the matching will be done only
|
|
against the addresses in the specific group id. The parameter
|
|
can be an integer or a variable holding an integer value.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>mode</emphasis> - (optional) - a bitmask to specify
|
|
how the matching should be done. If is 0, all ip, port and
|
|
proto are matched. If bit one is set, then port is ignored.
|
|
If bit two is set, then protocol is ignored. The parameter
|
|
can be an integer or a variable holding an integer value.
|
|
It must be provided if the uri parameter is provided.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>uri</emphasis> (optional) - if is empty or missing,
|
|
the matching is done against source IP, port and protocol.
|
|
Otherwise the value has to be a valid SIP URI, used to match
|
|
against addresses in the dispatcher list. Only IP, port and
|
|
protocol are matches, any additional parameters are ignored.
|
|
The parameter can be a static or dynamic (with variables)
|
|
string. The domain part of the URI can be an IP address or
|
|
a hostname.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Upon a match, the variable specified by 'setid_pvname' parameter will
|
|
be set to groupid of matching address and the attributes will be set in
|
|
variable specified by 'attrs_pvname'.
|
|
</para>
|
|
<para>
|
|
Note that for backward compatibility mode, when no parameter is given
|
|
or only groupid is given, the matching is done only for IP address
|
|
and port (protocol is ignored).
|
|
</para>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>ds_is_from_list</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if(ds_is_from_list()) {
|
|
...
|
|
}
|
|
if(ds_is_from_list("10")) {
|
|
...
|
|
}
|
|
if(ds_is_from_list("10", "3")) {
|
|
...
|
|
}
|
|
if(ds_is_from_list("10", "3", "sip:127.0.0.1:5080")) {
|
|
...
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="dispatcher.f.ds_load_update">
|
|
<title>
|
|
<function moreinfo="none">ds_load_update()</function>
|
|
</title>
|
|
<para>
|
|
Updates the load state:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>if it is a BYE or CANCEL - remove the load from
|
|
destination address used to forward the INVITE</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>if it is a reply to INVITE - set internal state
|
|
to confirmed for call load structure when reply code is
|
|
2xx.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
|
|
BRANCH_ROUTE and ONREPLY_ROUTE.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">ds_load_unset()</function>
|
|
</title>
|
|
<para>
|
|
Remove the call load for the destination that routed the call.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
|
|
BRANCH_ROUTE and ONREPLY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>ds_load_unset</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
route {
|
|
...
|
|
if(is_method("BYE|CANCEL"))
|
|
ds_load_update();
|
|
...
|
|
ds_select_dst("1", "10");
|
|
...
|
|
}
|
|
|
|
onreply_route {
|
|
...
|
|
if(is_method("INVITE")
|
|
{
|
|
if(status=~"2[0-9][0-9]")
|
|
ds_load_update();
|
|
else if(status=~"[3-7][0-9][0-9]")
|
|
ds_load_unset();
|
|
}
|
|
...
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>MI Commands</title>
|
|
<section id="dispatcher.mi.ds_set_state">
|
|
<title>
|
|
<function moreinfo="none">ds_set_state</function>
|
|
</title>
|
|
<para>
|
|
Sets the status for a destination address (can be use to mark the destination
|
|
as active or inactive).
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>ds_set_state</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>_state_ : state of the destination address</para>
|
|
<itemizedlist>
|
|
<listitem><para> <quote>a</quote>: active</para></listitem>
|
|
<listitem><para> <quote>i</quote>: inactive</para></listitem>
|
|
<listitem><para> <quote>t</quote>: trying</para></listitem>
|
|
<listitem><para> <quote>d</quote>: disabled</para></listitem>
|
|
</itemizedlist>
|
|
<para>The states <quote>a</quote>, <quote>i</quote> or
|
|
<quote>t</quote> can be followed by <quote>p</quote>
|
|
to set probing mode (e.g. 'ap', 'ip' or 'tp').</para>
|
|
</listitem>
|
|
|
|
<listitem><para>_group_: destination group id</para></listitem>
|
|
|
|
<listitem><para>_address_: address of the destination in the _group_</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:ds_set_state:_reply_fifo_file_
|
|
_state_
|
|
_group_
|
|
_address_
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
<section id="dispatcher.mi.ds_list">
|
|
<title>
|
|
<function moreinfo="none">ds_list</function>
|
|
</title>
|
|
<para>
|
|
It lists the groups and included destinations.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>ds_list</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:ds_list:_reply_fifo_file_
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
<section id="dispatcher.mi.ds_reload">
|
|
<title>
|
|
<function moreinfo="none">ds_reload</function>
|
|
</title>
|
|
<para>
|
|
It reloads the groups and included destinations. For algorithm 10
|
|
(call load distribution), old internal list of active calls is
|
|
destroyed (because it is bould to the previous list of gateways),
|
|
meaning that the module is starting to count active calls again
|
|
from 0.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>ds_reload</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
MI DATAGRAM Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
":ds_reload:\n."
|
|
</programlisting>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>RPC Commands</title>
|
|
<section id="dispatcher.rpc.set_state">
|
|
<title>
|
|
<function moreinfo="none">dispatcher.set_state</function>
|
|
</title>
|
|
<para>
|
|
Sets the state for a destination address (can be use to mark the destination
|
|
as active or inactive).
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>dispatcher.set_state</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>_state_ : state of the destination address</para>
|
|
<itemizedlist>
|
|
<listitem><para> <quote>a</quote>: active</para></listitem>
|
|
<listitem><para> <quote>i</quote>: inactive</para></listitem>
|
|
<listitem><para> <quote>t</quote>: trying</para></listitem>
|
|
<listitem><para> <quote>d</quote>: disabled</para></listitem>
|
|
</itemizedlist>
|
|
<para>The states <quote>a</quote>, <quote>i</quote> or
|
|
<quote>t</quote> can be followed by <quote>p</quote>
|
|
to set probing mode (e.g. 'ap', 'ip' or 'tp').</para>
|
|
</listitem>
|
|
|
|
<listitem><para>_group_: destination group id</para></listitem>
|
|
|
|
<listitem><para>_address_: address of the destination in the _group_</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# prototype: &sercmd; dispatcher.set_state _state_ _group_ _address_
|
|
&sercmd; dispatcher.set_state ip 2 sip:127.0.0.1:5080
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section id="dispatcher.rpc.list">
|
|
<title>
|
|
<function moreinfo="none">dispatcher.list</function>
|
|
</title>
|
|
<para>
|
|
Lists the groups and included destinations.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>dispatcher.list</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
&sercmd; dispatcher.list
|
|
</programlisting>
|
|
</section>
|
|
<section id="dispatcher.f.reload">
|
|
<title>
|
|
<function moreinfo="none">dispatcher.reload</function>
|
|
</title>
|
|
<para>
|
|
Reloads the groups and included destinations. The command is
|
|
disabled for call load based dispatching (algorithm 10) since
|
|
removal of destinations may leave the list of active
|
|
calls with broken references.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>dispatcher.reload</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
Example
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
&sercmd; dispatcher.reload
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section id="dispatcher.rpc.ping_active">
|
|
<title>
|
|
<function moreinfo="none">dispatcher.ping_active</function>
|
|
</title>
|
|
<para>
|
|
Sets the global state for sending keepalive requests to destinations.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>dispatcher.ping_active</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>_state_ : state of sending keepalives</para>
|
|
<itemizedlist>
|
|
<listitem><para> <quote>0</quote>: inactive (don't send)</para></listitem>
|
|
<listitem><para> <quote>1</quote>: active (send)</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
If the state parameter is missing, the current state is returned.
|
|
When state is changed, new and old values of the state are returned.
|
|
Default value for state is 1.
|
|
</para>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# prototype: &kamcmd; dispatcher.ping_active _state_
|
|
&kamcmd; dispatcher.ping_active 0
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="dispatcher.ex.install">
|
|
<title>Installation and Running</title>
|
|
<section>
|
|
<title>Destination List File</title>
|
|
<para>
|
|
Each destination point must be on one line. First token is the set
|
|
id (an integer value), followed by destination address
|
|
(s string value in SIP URI format).
|
|
</para>
|
|
<para>
|
|
Optionally, these fields can be followed by:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>flags (listed by index - can be bitwise mask of values):
|
|
0 (value 1) - inactive destination; 1 (value 2) - temporary trying
|
|
destination (in the way to become inactive if it does not reply to
|
|
keepalives - there is a module parameter to set the threshold of
|
|
failures); 2 (value 4) - admin disabled destination; 3 (value 8)
|
|
- probing destination (sending keep alives);</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>priority: sets the priority in destination list (based on it
|
|
is done the initial ordering inside the set)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>attributes: extra fields in form of
|
|
name1=value1;...;nameN=valueN.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<section id="dispatcher.ex.attributes">
|
|
<title>Special Attributes</title>
|
|
<para>
|
|
There are some predefined names:
|
|
<itemizedlist>
|
|
<listitem>
|
|
'duid' - used for call load dispatching. It must be an
|
|
unique value to identify a destination (gateway address).
|
|
Practically the load within the group is associated with
|
|
this value.
|
|
</listitem>
|
|
<listitem>
|
|
'maxload' - used for call load dispatching. It must be
|
|
a positive integer, defining the upper limit of active
|
|
calls per destination. When the limit is reached, then
|
|
the gateway is no longer selected for new calls until
|
|
an exiting call via that gateway is terminated. If set
|
|
to 0, then no active call limit is used.
|
|
</listitem>
|
|
<listitem>
|
|
'weight' - used for weight based load distribution. It
|
|
must be set to a positive integer value beteen 0 and
|
|
100. The value represents the percent of calls to be
|
|
sent to that gateways.
|
|
</listitem>
|
|
<listitem>
|
|
'rweight' - used for relative weight based load
|
|
distribution. It must be set to a positive integer value
|
|
between 1 and 100 (otherwise host will be excluded from
|
|
relative weight distribution type).
|
|
</listitem>
|
|
<listitem>
|
|
'socket' - used to set the sending socket for the gateway.
|
|
It is used for sending the SIP traffic as well as
|
|
OPTIONS keepalives.
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section id="dispatcher.ex.fileforma">
|
|
<title>File Format</title>
|
|
<para>
|
|
Line format is:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
|
|
...
|
|
</programlisting>
|
|
|
|
<para>
|
|
Full line example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
1 sip:127.0.0.1:5080 0 0 duid=abc;socket=udp:192.168.0.125:5060;my=xyz
|
|
...
|
|
</programlisting>
|
|
|
|
<para>
|
|
For database, each element of a line resides in a different column.
|
|
Next is a dispatcher.list file example:
|
|
</para>
|
|
<example>
|
|
<title>dispatcher list file</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
<xi:include href="dispatcher.list" parse="text"/>
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="dispatcher.ex.config">
|
|
<title>&kamailio; config file</title>
|
|
<para>
|
|
Next listing shows a sample config for using the dispatcher module.
|
|
</para>
|
|
<example>
|
|
<title>&kamailio; config script - sample dispatcher usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
<xi:include href="dispatcher.cfg" parse="text"/>
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="dispatcher.ex.event_routes">
|
|
<title>Event routes</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dispatcher:dst-down</function>
|
|
</title>
|
|
<para>
|
|
When defined, the module calls event_route[dispatcher:ds-down]
|
|
when a destination goes down (becomes probing). A typical use
|
|
case is to update NMC equipment as to the status of a destination.
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
event_route[dispatcher:dst-down] {
|
|
xlog("L_ERR", "Destination down: $rm $ru ($du)\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dispatcher:dst-up</function>
|
|
</title>
|
|
<para>
|
|
When defined, the module calls event_route[dispatcher:ds-up]
|
|
when a destination that was previously down (probing) comes up.
|
|
A typical use case is to update NMC equipment as to the status
|
|
of a destination.
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
event_route[dispatcher:dst-up] {
|
|
xlog("L_ERR", "Destination up: $rm $ru\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
|
|
</chapter>
|
|
|