dispatcher Module

The following modules must be loaded before this module:

The following libraries or applications must be installed before running OpenSIPS with this module:

The default DB connection of the module, overriding the global 'db_default_url' setting. Once specified, partitions which are missing the 'db_url' property will inherit their URL from this value.

Default value is “NULL”.

...
modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database")
...

The name of the avp to contain the attributes string of the current destination. When a destination is selected, automatically, this AVP will provide the attributes string - this is an opaque string (from OpenSIPS point of view) : it is loaded from destination definition ( via DB) and blindly provided in the script. Setting this parameter will only change the default partition's attrs_avp. Use the partition parameter to create and alter other partitions.

Default value is “null” - don't provide ATTRIBUTEs.

...
modparam("dispatcher", "attrs_avp", "$avp(272)")
...

Name of the avp to contain the script attributes string of the current destination. When a destination is selected, automatically, this AVP will provide the attributes string - this is an opaque string (from OpenSIPS point of view) : it is provided via the ds_push_script_attrs MI or SCRIPT function.

Default value is “null” - don't provide SCRIPT ATTRIBUTEs.

...
modparam("dispatcher", "attrs_avp", "$avp(script_attrs)")
...

Name of the route to be called when using algo 10. The route will get as param the dst_uri, attrs and script_attrs for the dispatcher entry that currently needs to be evaluated ( available via $param(1), $param(2) and $param(3) or via $param(dst_uri), $param(attrs) and $param(script_attrs) when the route gets called ). The return value of the route is considered by the dispatcher module to be the current weight of the dispatcher entry, and when using the 10 algo, the dispatcher entries are sorted in ascending weight order. If the returned value from the algo route is negative, the current dispatcher entry will be automatically skipped from usage

Default value is “null” - disabled.

...
modparam("dispatcher", "algo_route", "my_dispatcher_logic)")
...
route[my_dispatcher_logic] {
        $var(curent_score) = 0;
        xlog("DISPATCHER - Running logic for $param(dst_uri) with attrs $param(attrs) and script attrs $param(script_attrs) \n");

	# decide to penalize current dispatcher entry, based on your logic
	if (my_condition_here)
		$var(current_score) = $var(current_score) + 10;

        return $var(rc);
}

String with PVs used for the hashing algorithm 7.

Default value is “null” - disabled.

...
modparam("dispatcher", "hash_pvar", "$avp(273)")
...

...
modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
...

The name of the PV where to store the set ID (group ID) when calling ds_is_in_list() without group parameter (third parameter).

Default value is “null” - don't set PV.

...
modparam("dispatcher", "setid_pvar", "$var(setid)")
...

With this Method you can define, with which method you want to probe the failed gateways. This method is only available, if compiled with the probing of failed gateways enabled.

Use the 'partition' parameter if you want to define the ping method other partitions.

Default value is “OPTIONS”.

...
modparam("dispatcher", "ds_ping_method", "INFO")
...

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.

Use the 'partition' parameter if you want to define the "From:" ping header of other partitions.

Default value is “sip:dispatcher@localhost”.

...
modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
...

With this Method you can define the interval for sending a request to a failed gateway. This parameter is only used, when the TM-Module is loaded. If set to “0”, the pinging of failed requests is disabled.

Default value is “0” (disabled).

...
modparam("dispatcher", "ds_ping_interval", 30)
...

This parameter allows you to enforce a specific Max-Forward value for the SIP pinging requests generated by the Dispatcher modules. If not explicitly set, no value will be enforced and it let the Transaction Layer (TM module) to set a default Max-Forward value.

The accepted values are any positive integer values, including the “0” value.

...
modparam("dispatcher", "ds_ping_maxfwd", 2)
...

A socket description [proto:]host[:port] of the local socket (which is used by OpenSIPS for SIP traffic) to be used (if multiple) for sending the probing messages from.

Default value is “NULL(none)”.

...
modparam("dispatcher", "ds_probing_sock", "udp:192.168.1.100:5077")
...

If you want to set a gateway into probing mode, you will need a specific number of requests until it will change from "active" to probing. The number of attempts can be set with this parameter.

Default value is “3”.

...
modparam("dispatcher", "ds_probing_threshold", 10)
...

Controls what gateways are tested to see if they are reachable. If set to 0, only the gateways with state PROBING are tested, if set to 1, all gateways are tested. If set to 1 and the response is 408 (timeout), an active gateway is set to PROBING state.

Default value is “0”.

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

Defines a list of one or more setids that limits which destinations are probed if probing is active. This is useful when multiple proxies share the same dispatcher table, but you want to limit which ones are responsible for probing specific destinations.

Default value is “NULL (probe all sets)”.

...
modparam("dispatcher", "ds_probing_list", "1,2,3")
...

Defines a blacklist based on a dispatching setid from the 'default' partition. This list will contain the IPs (no port, all protocols) of the destinations matching the given setid. Use the 'partition' parameter if you want to define blacklists based on other partitions' sets.

Multiple instances of this param are allowed.

Default value is “NULL”.

...
modparam("dispatcher", "ds_define_blacklist", "list= 1,4,3")
modparam("dispatcher", "ds_define_blacklist", "blist2= 2,10,6")
...

This parameter must contain a list of SIP reply codes separated by comma. The codes defined here will be considered as valid reply codes for OPTIONS messages used for pinging, apart for 200.

Default value is “NULL”.

...
modparam("dispatcher", "options_reply_codes", "501, 403")
...

This is mainly for internal usage and represents 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. Setting this parameter will only change the default partition's dst_avp. Use the partition parameter to create and alter other partitions.

For the 'default' partition the default value is “$avp(ds_dst_failover)”. For any other partition, the default value is “$avp(ds_dst_failover_partitionname)”.

...
modparam("dispatcher", "dst_avp", "$avp(271)")
...

This is mainly for internal usage and represents the name of the avp storing the group id of the destination set. Good to have it for later usage or checks. Setting this parameter will only change the default partition's grp_avp. Use the partition parameter to create and alter other partitions.

For the 'default' partition the default value is “$avp(ds_grp_failover)”. For any other partition, the default value is “$avp(ds_grp_failover_partitionname)”.

...
modparam("dispatcher", "grp_avp", "$avp(273)")
...

This is mainly for internal usage and represents the name of the avp storing the number of destination addresses kept in dst_avp avps. Setting this parameter will only change the default partition's cnt_avp. Use the partition parameter to create and alter other partitions.

For the 'default' partition the default value is “$avp(ds_cnt_failover)”. For any other partition, the default value is “$avp(ds_cnt_failover_partitionname)”.

...
modparam("dispatcher", "cnt_avp", "$avp(274)")
...

This is mainly for internal usage and represents the name of the avp storing the sockets to be used for the destination addresses kept in dst_avp avps. Setting this parameter will only change the default partition's sock_avp. Use the partition parameter to create and alter other partitions.

For the 'default' partition the default value is “$avp(ds_sock_failover)”. For any other partition, the default value is “$avp(ds_sock_failover_partitionname)”.

...
modparam("dispatcher", "sock_avp", "$avp(275)")
...

This parameter is used by the PVAR(9) algorithm to specify the pseudovariable pattern used to detect the load of each destination. The name of the pseudovariable should contain the string “%u”, which will be internally replaced by the module with the uri of the destination. The string “%i” can also be used and will be replaced with the set ID of the destination (useful in cases where same uri exists in multiple sets).

Default value is “none”.

...
modparam("dispatcher", "pvar_algo_pattern", "$stat(load_%u)")
...

Specifies whether the state column should be loaded at startup and flushed during runtime or not for the "default" partition.

Use the 'partition' parameter if you want to define the persistent state of other partitions.

Default value is “1” (enabled).

...
# disable all DB operations with the state of a destination
modparam("dispatcher", "persistent_state", 0)
...

The ID of the cluster the module is part of. The clustering support is used in dispatcher module for two purposes: for sharing the status of the destinations and for controlling the pinging to destinations.

If clustering enbled, the module will automatically share changes over the status of the destinations with the other OpenSIPS instances that are part of a cluster. Whenever such a status changes (following an MI command, a probing result, a script command), the module will replicate this status change to all the nodes in this given cluster.

The clustering with sharing tag support may be used to control which node in the cluster will perform the pinging/probing to destinations. See the cluster_sharing_tag option.

This OpenSIPS cluster exposes the "dispatcher-status-repl" capability in order to mark nodes as eligible for becoming data donors during an arbitrary sync request. Consequently, the cluster must have at least one node marked with the "seed" value as the clusterer.flags column/property in order to be fully functional. Consult the clusterer - Capabilities chapter for more details.

For more info on how to define and populate a cluster (with OpenSIPS nodes) see the clusterer module.

Default value is “0 (none)”.

...
# replicate destination status with all OpenSIPS in cluster ID 9
modparam("dispatcher", "cluster_id", 9)
...

The name of the sharing tag (as defined per clusterer modules) to control which node is responsible for perform the self-triggered actions in the module. Such actions may be the destination probing (see also the cluster_probing_mode parameter) or sharing the changes in the destination status. If defined, only the node with active status of this tag will perform the actions (pinging and sharing status).

The cluster_id must be defined for this option to work.

This is an optional parameter. If not set, all the nodes in the cluster will share the status changes.

Default value is “empty (none)”.

...
# only the node with the active "vip" sharing tag will perform pinging
# and broadcast the status changes
modparam("dispatcher", "cluster_id", 9)
modparam("dispatcher", "cluster_sharing_tag", "vip")
...

This paramter controls how the probing/pinging should be done when using the clustering support. It is about which node in the cluster pings which gateway/destination.

The cluster_id must be defined for this option to work.

The supported probing modes are:

Default value is “"all"”.

...
# only the node with the active "vip" sharing tag will perform pinging
modparam("dispatcher", "cluster_id", 9)
modparam("dispatcher", "cluster_sharing_tag", "vip")
modparam("dispatcher", "cluster_probing_mode", "by-shtag")
...
# the pinging effort is distributed across all the nodes
modparam("dispatcher", "cluster_id", 9)
modparam("dispatcher", "cluster_probing_mode", "distributed")
...

Define a new partition (data source) with the following properties: "db_url", "table_name", "dst_avp", "grp_avp", "cnt_avp", "sock_avp", "attrs_avp", "script_attrs", "ds_define_blacklist". All these properties are optional, having appropriate default values.

The syntax is: "partition_name: param1 = value1; param2 = value2". Each value format is the same as the one used to define a specific parameter using modparam.

This parameter may be set multiple times, thus defining as many partitions as needed. The 'default' partition may also be defined using this parameter.

...
modparam("dispatcher", "partition",
                "voicemail:
                    db_url = mysql://user:passwd@localhost/database;
                    table_name = dispatcher;
                    attrs_avp = $avp(ds_attr_vm);
                    ds_define_blacklist = list2 = 4,6")
...

...
modparam("dispatcher", "partition",
                "trunks:
                    db_url = mysql://user:passwd@localhost/database;
                    table_name = dispatcher_trunks;
                    attrs_avp = $avp(ds_attr_trunks)")
modparam("dispatcher", "partition", "default: trunks")
...

The default name of the table from which to load dispatcher destinations. Partitions which are missing the 'table_name' property will inherit their table name from this value.

Default value is “dispatcher”.

...
modparam("dispatcher", "table_name", "my_dispatcher")
...

The column's name in the database storing the gateway's group id.

Default value is “setid”.

...
modparam("dispatcher", "setid_col", "groupid")
...

The column's name in the database storing the destination's sip uri.

Default value is “destination”.

...
modparam("dispatcher", "destination_col", "uri")
...

The column's name in the database storing the state of the destination uri.

Default value is “state”.

...
modparam("dispatcher", "state_col", "dststate")
...

The column's name in the database storing the weight for destination uri.

Default value is “weight”.

...
modparam("dispatcher", "weight_col", "dstweight")
...

The column's name in the database storing the priority for destination uri.

Default value is “priority”.

...
modparam("dispatcher", "priority_col", "dstprio")
...

The column's name in the database storing the attributes (opaque string) for destination uri.

Default value is “attrs”.

...
modparam("dispatcher", "attrs_col", "dstattrs")
...

The column's name in the database storing the socket (as string) for destination uri.

Default value is “socket”.

...
modparam("dispatcher", "socket_col", "my_sock")
...

The column's name in the database storing the probe_mode (as string) for destination.

Default value is “probe_mode”.

...
modparam("dispatcher", "probe_mode_col", "probing")
...

If enabled, FreeSWITCH destinations may have dynamic dispatching weights, refreshed at runtime, using the FreeSWITCH Event Socket Layer. For these destinations, an Event Socket Layer URL must be provisioned into the "weight" column, instead of an integer string. Some example values: "fs://:password@freeswitch.example.com" or "fs://user:password@127.0.0.1:8021". The default ESL port is 8021.

OpenSIPS will establish a connection with the given socket and periodically calculate/update the weights of these destinations using statistics pushed by the FreeSWITCH box.

The value for an automatically calculated weight ranges between 0 - 100. This is helpful when grouping normal destinations with FreeSWITCH ones.

The dynamic weights are recalculated every event_heartbeat_interval seconds (see the "freeswitch" OpenSIPS module for more details regarding this setting), as the stats from FreeSWITCH are expected to arrive. The update formula is shown below (FreeSWITCH stats are highlighted in bold):

weight = 100 * (Idle-CPU / 100) * (1 - Session-Count / Max-Sessions)

Default value is 0 (disabled).

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

The maximum weight of a FreeSWITCH ESL-enabled destination. This value is also used during startup/reload, when no stats from FreeSWITCH are available yet.

Important: When mixing normal destinations with FreeSWITCH-enabled ones in the same dispatching set, OpenSIPS will truncate any weight values that are larger than max_freeswitch_weight to the value of this parameter!

NOTE: OpenSIPS internally rounds weights to nearest integer, so larger max weight values will more accurately represent the current load on the FreeSWITCH boxes! For example, if you set this parameter to 1, the box will receive no traffic whenever either its CPU or session usage goes past 50%!

Default value is 100.

...
modparam("dispatcher", "max_freeswitch_weight", 1000)
...

The method selects a destination from the given set of addresses. It will overwrite the destination URI ($du) of a SIP request.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and FAILURE_ROUTE.

...
if (!ds_select_dst(1, 0)) {
	xlog("ERROR: no active destinations found!\n");
	send_reply(503, "Service Unavailable");
	exit;
}
...
ds_select_dst(1, 0, , "fs_boxes", 5);
...
ds_select_dst(1, 0, "fUD", "ask_boxes");
...
ds_select_dst(2, 0, "fud", "pstn_gws", 5);
ds_select_dst(3, 1, "fua", "pstn_gws", 2);
...
# using variables
$var(part) = "pstn_gws"
$var(setid) = 1;
$var(alg) = 4;
$var(flags) = "fdu";
$var(max_res) = 2;
ds_select_dst($var(setid), $var(alg), $var(flags), $var(part), $var(max_res));
...

The method selects a destination from addresses set and rewrites the hostname and port parts of the Request-URI ($ru). Its parameters have same meaning as in ds_select_dst().

If the "f" (failover support) flag is present, the rest of the addresses from the destination set will be stored in an internally managed AVP. You may then use ds_next_domain() to switch to the next address in the list, thus achieving serial forking to all possible destinations.

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and FAILURE_ROUTE.

Takes the next destination address from the AVPs with id partition.'dst_avp_id' and sets the dst_uri (outbound proxy address). If "partition" is omitted, the default partition will be used.This function is using the flags set in ds_select_dst or ds_select_domain.

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

Takes the next destination address from the AVPs with id partition.'dst_avp_id' and sets the domain part of the request uri. If "partition" is omitted, the default partition will be used.This function is using the flags set in ds_select_dst or ds_select_domain.

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

Mark the last used address from partition's destination set as inactive ("i"/"I"/"0"), active ("a"/"A"/"1") or probing ("p"/"P"/"2"). With this function, an automatic detection of failed gateways can be implemented. When an address is marked as inactive or probing, it will be ignored by ds_select_dst() and ds_select_domain(). If "partition" is omitted, the default partition will be used. This function is using the flags set in ds_select_dst() or ds_select_domain().

Possible parameters:

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

Returns the number of active, inactive or probing destinations in a partition's set, or combinations between these properties.

Meaning of the parameters:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE, TIMER_ROUTE, EVENT_ROUTE

...
if (ds_count(1, "a", $avp(result))) {
	...
}
...
if (ds_count($avp(set), "ip", $avp(result), $avp(partition))) {
	...
}
...

This function returns true only if "ip" and "port" point to a host from the given dispatcher "set".

Meaning of the parameters:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and ONREPLY_ROUTE.

...
if (ds_is_in_list($si, $sp)) {
	# source IP:PORT is in a dispatcher list
}
...
if (ds_is_in_list($rd, $rp, 2)) {
	# the R-URI (IP and port) is in the dispatcher set 2 of the "default" partition
}
...
if (ds_is_in_list($rd, $rp, 2, "part2")) {
	# the R-URI (IP and port) is in the dispatcher set 2 of the "part2" partition
}
...

Set the script attrs for the dispatcher entry defined by IP, Port, setid and partition.

Meaning of the parameters:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE, TIMER_ROUTE, EVENT_ROUTE

...
if (ds_push_script_attrs($var(my_attributes),$si , $sp, 1, 'my_partition')) {
	...
}
...

Get the script attrs for the dispatcher entry defined by the URI, setid and partition.

Meaning of the parameters:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE, TIMER_ROUTE, EVENT_ROUTE

...
if (ds_push_script_attrs($var(my_attributes),$si , $sp, 1, 'my_partition')) {
	...
}
...

Sets the status for a destination address (can be use to mark the destination as active or inactive).

Name: ds_set_state

Parameters:

MI FIFO Command Format:

opensips-cli -x mi ds_set_state a 2 sip:10.0.0.202

It lists the groups and included destinations of all the partitions.

Name: ds_list

Parameters:

MI FIFO Command Format:

opensips-cli -x mi ds_list

It reloads the groups and included destinations for a specified partition or all partitions.

Name: ds_reload

Parameters:

MI FIFO Command Format:

opensips-cli -x mi ds_reload
opensips-cli -x mi ds_reload inherit_state=n

Pushes script attrs for the dispatcher entry defined by IP, Port, setid, and optionally partition.

Name: ds_push_script_attrs

Parameters:

MI FIFO Command Format:

#opensips-cli -x mi ds_push_script_attrs '{"ping":"30000","load":"50"}' '192.168.0.107' 5091 1 main

This event is raised when the dispatcher module marks a destination as activated or deactivated.

Parameters:

The status of these identifiers reflects the readiness/status of the cached data (if available or not when being loaded from DB):

Reload reporting:

In terms of date reloading, the following events will be reported:

        {
            "Name": "default",
            "Reports": [
                {
                    "Timestamp": 1652373212,
                    "Date": "Thu May 12 19:33:32 2022",
                    "Log": "starting DB data loading"
                },
                {
                    "Timestamp": 1652373212,
                    "Date": "Thu May 12 19:33:32 2022",
                    "Log": "DB data loading successfully completed"
                },
                {
                    "Timestamp": 1652373212,
                    "Date": "Thu May 12 19:33:32 2022",
                    "Log": "2 destinations loaded (0 discarded)"
                }
            ]
        }

	

Destination switching reporting:

For reporting events related to the state changes of the destinations, the module provides separate identifiers (still one per partition). Why separate ones? The reports on state changing may be verbose and there is the risk of loose/discard important reports on reloads due to the high number of logs on state changes;

So, each partition will provide the identified "partition_name;events" for reporting state changes of destinations, along with the reason of the change. This identifiers have a 200 records history before discarding the old ones.

        {
            "Name": "default;events",
            "Reports": [
                {
                    "Timestamp": 1652373308,
                    "Date": "Thu May 12 19:35:08 2022",
                    "Log": "DESTINATION <sip:127.0.1.1>, set 1 switched to [inactive] due to negative probing reply\n"
                },
                {
                    "Timestamp": 1652373308,
                    "Date": "Thu May 12 19:35:08 2022",
                    "Log": "DESTINATION <sip:127.0.1.2>, set 1 switched to [inactive] due to negative probing reply\n"
                }
            ]
        },

	

Next picture displays a sample usage of dispatcher.

...
#
# sample config file for dispatcher module
#

socket= udp:*:5060

udp_workers = 2
check_via = off     # (cmd. line: -v)
dns = off           # (cmd. line: -r)
rev_dns = off       # (cmd. line: -R)

# for more info: opensips -h

# ------------------ module loading ----------------------------------
mpath = "/usr/lib/x86_64-linux-gnu/opensips/modules"

loadmodule "maxfwd.so"
loadmodule "signaling.so"
loadmodule "sl.so"
loadmodule "tm.so"
loadmodule "db_mysql.so"
loadmodule "dispatcher.so"

loadmodule "proto_udp.so"

# ----------------- setting module-specific parameters ---------------
modparam("dispatcher", "db_url", "mysql://opensips:opensipsrw@localhost/opensips")

route {
	if (!mf_process_maxfwd_header(10)) {
		send_reply(483, "Too Many Hops");
		exit;
	}

	if (!ds_select_dst(2, 0)) {
		send_reply(503, "Service Unavailable");
		exit;
	}

	t_relay();
}

...