9754e3f3208c92fae527e038214bd493fea0fc76
[sip-router] / src / modules / dispatcher / doc / dispatcher_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4  
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter xmlns:xi="http://www.w3.org/2001/XInclude">
13
14         <title>&adminguide;</title>
15
16         <section>
17         <title>Overview</title>
18         <para>
19                 This module offers SIP load balancer functionality and it can be
20                 used as SIP traffic dispatcher. There are many load balancing and
21                 traffic dispatching algorithms that you can choose from, for example:
22                 round-robin, weight based load balancing, call load distribution,
23                 and hashing over SIP message attributes.
24         </para>
25         <para>
26                 The module can be used as a stateless load balancer; it does not
27                 depend on any call state tracking module. It requires the TM module if
28                 you enable auto-discovery of active/inactive gateways.
29         </para>
30         <para>
31                 It is very lightweight, therefore suitable for handling heavy SIP
32                 traffic. As the module has a small footprint and the ability to load
33                 balancing rules from a plain text file, it is suitable for embedded systems.
34         </para>
35         </section>
36         <section>
37         <title>Dependencies</title>
38         <section>
39                 <title>&kamailio; modules</title>
40                 <para>
41                 The following modules must be loaded before this module:
42                         <itemizedlist>
43                         <listitem>
44                         <para>
45                                 <emphasis>TM - only if active recovery of failed hosts
46                                         is required</emphasis>.
47                         </para>
48                         </listitem>
49                         <listitem>
50                         <para>
51                                 <emphasis>database engine - only if you want to load
52                                         balancing routes from database instead of plain text file.
53                                 </emphasis>.
54                         </para>
55                         </listitem>
56                         </itemizedlist>
57                 </para>
58         </section>
59         <section>
60                 <title>External libraries or applications</title>
61                 <para>
62                 The following libraries or applications must be installed before
63                 running &kamailio; with this module:
64                         <itemizedlist>
65                         <listitem>
66                         <para>
67                                 <emphasis>none</emphasis>.
68                         </para>
69                         </listitem>
70                         </itemizedlist>
71                 </para>
72         </section>
73         </section>
74
75         <section>
76         <title>Parameters</title>
77         <section id="dispatcher.p.list_file">
78                 <title><varname>list_file</varname> (string)</title>
79                 <para>
80                 Path to the file with destination sets (destination groups).
81                 </para>
82                 <para>
83                 <emphasis>
84                         Default value is <quote>/etc/kamailio/dispatcher.list</quote> or
85                         <quote>/usr/local/etc/kamailio/dispatcher.list</quote>.
86                 </emphasis>
87                 </para>
88                 <example>
89                 <title>Set the <quote>list_file</quote> parameter</title>
90                 <programlisting format="linespecific">
91 ...
92 modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
93 ...
94 </programlisting>
95                 </example>
96         </section>
97
98         <section id="dispatcher.p.db_url">
99                 <title><varname>db_url</varname> (string)</title>
100                 <para>
101                 If you want to load the list of gateways from the database you must set
102                 this parameter.
103                 </para>
104                 <para>
105                 <emphasis>
106                         Default value is <quote>NULL</quote> (disable DB support).
107                 </emphasis>
108                 </para>
109                 <example>
110                 <title>Set <quote>db_url</quote> parameter</title>
111                 <programlisting format="linespecific">
112 ...
113 modparam("dispatcher", "db_url", "mysql://user:passwd@localhost/database")
114 ...
115 </programlisting>
116                 </example>
117         </section>
118
119         <section id="dispatcher.p.table_name">
120                 <title><varname>table_name</varname> (string)</title>
121                 <para>
122                 If you want to load the list of gateways from the database you must set
123                 this parameter as the database name.
124                 </para>
125                 <para>
126                 <emphasis>
127                         Default value is <quote>dispatcher</quote>.
128                 </emphasis>
129                 </para>
130                 <example>
131                 <title>Set <quote>table_name</quote> parameter</title>
132                 <programlisting format="linespecific">
133 ...
134 modparam("dispatcher", "table_name", "my_dispatcher")
135 ...
136 </programlisting>
137                 </example>
138         </section>
139
140         <section id="dispatcher.p.setid_col">
141                 <title><varname>setid_col</varname> (string)</title>
142                 <para>
143                         The column's name in the database storing the gateway's set (group)
144                         id.
145                 </para>
146                 <para>
147                 <emphasis>
148                         Default value is <quote>setid</quote>.
149                 </emphasis>
150                 </para>
151                 <example>
152                 <title>Set <quote>setid_col</quote> parameter</title>
153                 <programlisting format="linespecific">
154 ...
155 modparam("dispatcher", "setid_col", "groupid")
156 ...
157 </programlisting>
158                 </example>
159         </section>
160
161         <section id="dispatcher.p.destination_col">
162                 <title><varname>destination_col</varname> (string)</title>
163                 <para>
164                         The column's name in the database storing the destination
165                         sip URI.
166                 </para>
167                 <para>
168                 <emphasis>
169                         Default value is <quote>destination</quote>.
170                 </emphasis>
171                 </para>
172                 <example>
173                 <title>Set <quote>destination_col</quote> parameter</title>
174                 <programlisting format="linespecific">
175 ...
176 modparam("dispatcher", "destination_col", "uri")
177 ...
178 </programlisting>
179                 </example>
180         </section>
181
182         <section id="dispatcher.p.flags_col">
183                 <title><varname>flags_col</varname> (string)</title>
184                 <para>
185                         The column's name in the database storing the flags for
186                         the destination URI.
187                 </para>
188                 <para>
189                 <emphasis>
190                         Default value is <quote>flags</quote>.
191                 </emphasis>
192                 </para>
193                 <example>
194                 <title>Set <quote>flags_col</quote> parameter</title>
195                 <programlisting format="linespecific">
196 ...
197 modparam("dispatcher", "flags_col", "dstflags")
198 ...
199 </programlisting>
200                 </example>
201         </section>
202
203         <section id="dispatcher.p.priority_col">
204                 <title><varname>priority_col</varname> (string)</title>
205                 <para>
206                         The column's name in the database storing the priority for
207                         destination URI.
208                 </para>
209                 <para>
210                 <emphasis>
211                         Default value is <quote>priority</quote>.
212                 </emphasis>
213                 </para>
214                 <example>
215                 <title>Set <quote>priority_col</quote> parameter</title>
216                 <programlisting format="linespecific">
217 ...
218 modparam("dispatcher", "priority_col", "dstpriority")
219 ...
220 </programlisting>
221                 </example>
222         </section>
223
224         <section id="dispatcher.p.force_dst">
225                 <title><varname>force_dst</varname> (int)</title>
226                 <para>
227                 If set to 1, force overwriting of destination address (outbound proxy)
228                 when that is already set. If set to 0, will return error when the
229                 destination address is already set.
230                 </para>
231                 <para>
232                 <emphasis>
233                         Default value is <quote>1</quote>.
234                 </emphasis>
235                 </para>
236                 <example>
237                 <title>Set the <quote>force_dst</quote> parameter</title>
238 <programlisting format="linespecific">
239 ...
240 modparam("dispatcher", "force_dst", 1)
241 ...
242 </programlisting>
243                 </example>
244         </section>
245         <section id="dispatcher.p.flags">
246                 <title><varname>flags</varname> (int)</title>
247                 <para>
248                 Various flags that affect dispatcher's behaviour. The flags are defined
249                 as a bitmask on an integer value.
250                 If flag 1 is set only the username
251                 part of the URI will be used when computing an URI based hash.
252                 If no flags are set the username, hostname and port will be used.
253                 The port is used only if different from 5060 (normal sip URI) or 5061
254                 (in the sips: case).
255                 </para>
256                 <para>
257                 If flag 2 is set, then failover support is enabled. The functions
258                 exported by the module will store the rest of addresses from the
259                 destination set in XAPVs, and use these XAVPs to try next address if
260                 the current-tried destination fails.
261                 </para>
262                 <para>
263                 <emphasis>
264                         Default value is <quote>0</quote>.
265                 </emphasis>
266                 </para>
267                 <example>
268                 <title>Set the <quote>flags</quote> parameter</title>
269  <programlisting format="linespecific">
270  ...
271  modparam("dispatcher", "flags", 3)
272  ...
273  </programlisting>
274                 </example>
275         </section>
276         <section id="dispatcher.p.use_default">
277                 <title><varname>use_default</varname> (int)</title>
278                 <para>
279                 If the parameter is set to 1, the last address in destination set
280                 is used as a final option to send the request to. For example, it is useful
281                 when wanting to send the call to an announcement server saying:
282                 "the gateways are full, try later".
283                 </para>
284                 <para>
285                 <emphasis>
286                         Default value is <quote>0</quote>.
287                 </emphasis>
288                 </para>
289                 <example>
290                 <title>Set the <quote>use_default</quote> parameter</title>
291  <programlisting format="linespecific">
292  ...
293  modparam("dispatcher", "use_default", 1)
294  ...
295  </programlisting>
296                 </example>
297         </section>
298         <section id="dispatcher.p.xavp_dst">
299                 <title><varname>xavp_dst</varname> (str)</title>
300                 <para>
301                 The name of the XAVP which will hold the list with addresses and
302                 associated properties, in the order they have been selected by the
303                 chosen algorithm. If use_default is 1, the values of last XAVP correspond
304                 to the last address in destination set. In case of using dispatcher.list file,
305                 you have to set the priority field for each destination to ensure a particular order there.
306                 The first XAVP is the current selected destination. All the other addresses
307                 from the destination set will be added in the XAVP list to be able to implement serial forking.
308                 </para>
309                 <note>
310                 <para>
311                 You must set this parameter if you want to do load balancing fail over.
312                 </para>
313                 </note>
314                 <para>
315                 <emphasis>
316                         Default value is <quote>_dsdst_</quote>.
317                 </emphasis>
318                 </para>
319                 <example>
320                 <title>Set the <quote>xavp_dst</quote> parameter</title>
321  <programlisting format="linespecific">
322  ...
323  modparam("dispatcher", "xavp_dst", "_dsdst_")
324  ...
325  </programlisting>
326                 </example>
327         </section>
328         <section id="dispatcher.p.xavp_dst_mode">
329                 <title><varname>xavp_dst_mode</varname> (int)</title>
330                 <para>
331                 Control what fields are added to the XAVP specified by xavp_dst
332                 parameter.
333                 </para>
334                 <para>
335                 The addeded fields are:
336                 <itemizedlist>
337                         <listitem>
338                         grp - the set id (group id).
339                         </listitem>
340                         <listitem>
341                         uri - the URI address.
342                         </listitem>
343                         <listitem>
344                         sock - the socket pointer.
345                         </listitem>
346                         <listitem>
347                         dstid - the destination unique id (in case of call load distribution algorithm).
348                         </listitem>
349                         <listitem>
350                         attrs - the attributes - they are added if xavp_dst_mode does not have the bit 1 set.
351                         </listitem>
352                 </itemizedlist>
353                 </para>
354                 <para>
355                 <emphasis>
356                         Default value is <quote>0</quote> (add all fields).
357                 </emphasis>
358                 </para>
359                 <example>
360                 <title>Set the <quote>xavp_dst_mode</quote> parameter</title>
361  <programlisting format="linespecific">
362  ...
363  modparam("dispatcher", "xavp_dst_mode", 1)
364  ...
365  </programlisting>
366                 </example>
367         </section>
368         <section id="dispatcher.p.xavp_ctx">
369                 <title><varname>xavp_ctx</varname> (str)</title>
370                 <para>
371                 The name of the XAVP which will hold some attributes specific to
372                 dispatcher routing context. The XAVP can hold the next fields: cnt -
373                 the number of addresses selected for routing.
374                 </para>
375                 <para>
376                 <emphasis>
377                         Default value is <quote>_dsctx_</quote>.
378                 </emphasis>
379                 </para>
380                 <example>
381                 <title>Set the <quote>xavp_ctx</quote> parameter</title>
382  <programlisting format="linespecific">
383  ...
384  modparam("dispatcher", "xavp_ctx", "_dsctx_")
385  ...
386  </programlisting>
387                 </example>
388         </section>
389         <section id="dispatcher.p.xavp_ctx_mode">
390                 <title><varname>xavp_ctx_mode</varname> (int)</title>
391                 <para>
392                 Control what fields are added to the XAVP specified by xavp_ctx
393                 parameter. The cnt field is added if xavp_cnt_mode does not have the
394                 bit 1 set.
395                 </para>
396                 <para>
397                 <emphasis>
398                         Default value is <quote>0</quote> (add all fields).
399                 </emphasis>
400                 </para>
401                 <example>
402                 <title>Set the <quote>xavp_ctx_mode</quote> parameter</title>
403  <programlisting format="linespecific">
404  ...
405  modparam("dispatcher", "xavp_ctx_mode", 1)
406  ...
407  </programlisting>
408                 </example>
409         </section>
410         <section id="dispatcher.p.hash_pvar">
411                 <title><varname>hash_pvar</varname> (str)</title>
412                 <para>
413                 String with PVs used for the hashing algorithm 7.
414                 </para>
415                 <note>
416                 <para>
417                 You must set this parameter if you want do hashing over custom message
418                 parts.
419                 </para>
420                 </note>
421                 <para>
422                 <emphasis>
423                         Default value is <quote>null</quote> - disabled.
424                 </emphasis>
425                 </para>
426                 <example>
427                 <title>Use $avp(hash) for hashing:</title>
428  <programlisting format="linespecific">
429  ...
430  modparam("dispatcher", "hash_pvar", "$avp(hash)")
431  ...
432  </programlisting>
433                 </example>
434                 <example>
435                 <title>Use combination of PVs for hashing:</title>
436  <programlisting format="linespecific">
437  ...
438  modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
439  ...
440  </programlisting>
441                 </example>
442         </section>
443         <section id="dispatcher.p.setid_pvname">
444                 <title><varname>setid_pvname</varname> (str)</title>
445                 <para>
446                 The name of the PV where to store the set ID (group ID) when calling
447                 ds_is_from_list() with no parameter.
448                 </para>
449                 <para>
450                 <emphasis>
451                         Default value is <quote>null</quote> - don't set PV.
452                 </emphasis>
453                 </para>
454                 <example>
455                 <title>Set the <quote>setid_pvname</quote> parameter</title>
456  <programlisting format="linespecific">
457  ...
458  modparam("dispatcher", "setid_pvname", "$var(setid)")
459  ...
460  </programlisting>
461                 </example>
462         </section>
463         <section id="dispatcher.p.attrs_pvname">
464                 <title><varname>attrs_pvname</varname> (str)</title>
465                 <para>
466                 The name of the PV where to store the attributes of matching address
467                 when calling ds_is_from_list().
468                 </para>
469                 <para>
470                 <emphasis>
471                         Default value is <quote>null</quote> - don't set PV.
472                 </emphasis>
473                 </para>
474                 <example>
475                 <title>Set the <quote>attrs_pvname</quote> parameter</title>
476  <programlisting format="linespecific">
477  ...
478  modparam("dispatcher", "attrs_pvname", "$var(attrs)")
479  ...
480  </programlisting>
481                 </example>
482         </section>
483         <section id="dispatcher.p.ds_ping_method">
484                 <title><varname>ds_ping_method</varname> (string)</title>
485                 <para>
486                 With this method you can define, with which method you want to probe the gateways.
487                 Pinging gateways feature depends on ds_ping_interval parameter.
488                 </para>
489                 <para>
490                 <emphasis>
491                         Default value is <quote>OPTIONS</quote>.
492                 </emphasis>
493                 </para>
494                 <example>
495                 <title>Set the <quote>ds_ping_method</quote> parameter</title>
496  <programlisting format="linespecific">
497  ...
498  modparam("dispatcher", "ds_ping_method", "INFO")
499  ...
500  </programlisting>
501                 </example>
502         </section>
503         <section id="dispatcher.p.ds_ping_from">
504                 <title><varname>ds_ping_from</varname> (string)</title>
505                 <para>
506                 With this Method you can define the "From:"-Line for the request, sent to the failed gateways.
507                 This method is only available, if compiled with the probing of failed gateways enabled.
508                 </para>
509                 <para>
510                 <emphasis>
511                         Default value is <quote>sip:dispatcher@localhost</quote>.
512                 </emphasis>
513                 </para>
514                 <example>
515                 <title>Set the <quote>ds_ping_from</quote> parameter</title>
516  <programlisting format="linespecific">
517  ...
518  modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
519  ...
520  </programlisting>
521                 </example>
522         </section>
523
524         <section id="dispatcher.p.ds_ping_interval">
525                 <title><varname>ds_ping_interval</varname> (int)</title>
526                 <para>
527                 With this parameter you can define the interval for sending a request
528                 to a gateway marked as inactive upon a failed request routing to it.
529                 This parameter is only used, when the TM-Module is loaded.
530                 If set to <quote>0</quote>, the pinging of inactive gateway is disabled.
531                 </para>
532                 <para>
533                 <emphasis>
534                         Default value is <quote>0</quote>.
535                 </emphasis>
536                 </para>
537                 <example>
538                 <title>Set the <quote>ds_ping_interval</quote> parameter</title>
539  <programlisting format="linespecific">
540  ...
541  modparam("dispatcher", "ds_ping_interval", 30)
542  ...
543  </programlisting>
544                 </example>
545         </section>
546
547         <section id="dispatcher.p.ds_probing_threshold">
548                 <title><varname>ds_probing_threshold</varname> (int)</title>
549                 <para>
550                 If you want to set a gateway into inactive mode, there can be
551                 a specific number of failed requests until it will change from "active"
552                 to "inactive". It is using the state "trying", that allows selection
553                 of gateway but indicates there was a failure previously with the
554                 gateway. The number of attempts can be set with this parameter.
555                 This parameter can be modified via ser config framework.
556                 </para>
557                 <para>
558                 <emphasis>
559                 Default value is <quote>1</quote> (set inactive with first failure).
560                 </emphasis>
561                 </para>
562                 <example>
563                 <title>Set the <quote>ds_probing_threshold</quote> parameter</title>
564  <programlisting format="linespecific">
565  ...
566  modparam("dispatcher", "ds_probing_threshold", 10)
567  ...
568  </programlisting>
569                 </example>
570         </section>
571         <section id="dispatcher.p.ds_inactive_threshold">
572                 <title><varname>ds_inactive_threshold</varname> (int)</title>
573                 <para>
574                 If you want to set a gateway into active mode (after being inactive), there can be
575                 a specific number of successful requests until it will change from "inactive"
576                 to "active". The number of attempts can be set with this parameter.
577                 This parameter can be modified via ser config framework.
578                 </para>
579                 <para>
580                 <emphasis>
581                 Default value is <quote>1</quote> (set active with first success).
582                 </emphasis>
583                 </para>
584                 <example>
585                 <title>Set the <quote>ds_inactive_threshold</quote> parameter</title>
586  <programlisting format="linespecific">
587  ...
588  modparam("dispatcher", "ds_inactive_threshold", 10)
589  ...
590  </programlisting>
591                 </example>
592         </section>
593         <section id="dispatcher.p.ds_ping_reply_codes">
594                 <title><varname>ds_ping_reply_codes</varname> (string)</title>
595                 <para>
596                         This parameter defines the valid response codes, which are accepted
597                         as a valid reply to the PING-Method. It is a list separated by
598                         colons, where you may define either a single code (e.g. "code=202"
599                         would accept 202 as an additional, valid response) or a class of
600                         responses, you want to accept (e.g. "class=2" would accept
601                         everything from 200 to 299 as valid response). This parameter can
602                         be modified via config framework.
603                 </para>
604                 <para>
605                         Please note that the response codes the module accepts as valid reply to the
606                         PING-Method are not only the ones generated from the remote servers, but also those
607                         that are generated locally. E.g.: setting code=408 or class=400 will never set
608                         a backend down even if it is, because internally the Kamailio transaction layer
609                         generates a 408 in the case of no response from the remote server, and this
610                         internal code 408 is accepted as valid value.
611                 </para>
612                 <para>
613                 <emphasis>
614                         Default value is <quote></quote> (only 200 OK is accepted).
615                 </emphasis>
616                 </para>
617                 <example>
618                 <title>Set the <quote>ds_ping_reply_codes</quote> parameter</title>
619  <programlisting format="linespecific">
620  ...
621  modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=3")
622  ...
623  </programlisting>
624                 </example>
625         </section>
626         <section id="dispatcher.p.ds_probing_mode">
627                 <title><varname>ds_probing_mode</varname> (int)</title>
628                 <para>
629                 Controls what gateways are tested to see if they are reachable.
630                 </para>
631
632                 <itemizedlist>
633                 <listitem>
634                         <para>Value 0: If set to 0, only the gateways with state PROBING are tested.
635             After a gateway is probed, the PROBING state is cleared in this mode.
636                         This means that no probing will be executed at all only if flag in config file is set to 8/PROBING
637                         (please check destination list file syntaxis for more details), it will probe only one time at startup or 
638                         after dispatcher reload.</para>
639                 </listitem>
640                 <listitem>
641                         <para>Value 1: If set to 1, all gateways are tested.  If set to 1 and
642                         there is a failure of keepalive to an active gateway, then it is
643                         set to TRYING state. This means that probing will be executed all the time,
644                         but you can skip some servers with flag 4 in destination list file, for example.</para>
645                 </listitem>
646                 <listitem>
647                         <para>Value 2: if set to 2, only gateways in inactive state with
648                         probing mode set are tested.</para>
649                 </listitem>
650                 <listitem>
651                         <para>Value 3: If set to 3, any gateway with state PROBING is continually probed
652                                 without modifying/removing the PROBING state.  This allows selected gateways
653                                 to be probed continually, regardless of state changes.</para>
654                 </listitem>
655                 </itemizedlist>
656
657                 <para>
658                 <emphasis>
659                         Default value is <quote>0</quote>.
660                 </emphasis>
661                 </para>
662                 <example>
663                 <title>Set the <quote>ds_probing_mode</quote> parameter</title>
664  <programlisting format="linespecific">
665  ...
666  modparam("dispatcher", "ds_probing_mode", 1)
667  ...
668  </programlisting>
669                 </example>
670         </section>
671
672         <section id="dispatcher.p.ds_ping_latency_stats">
673                 <title><varname>ds_ping_latency_stats</varname> (int)</title>
674                 <para>
675                 Enable latency measurement when pinging nodes
676                 </para>
677
678                 <itemizedlist>
679                 <listitem>
680                         <para>If set to 0, disable latency measurement.</para>
681                 </listitem>
682                 <listitem>
683                         <para>If set to 1, enable latency measurement.
684                         </para>
685                 </listitem>
686                 </itemizedlist>
687                 <para>
688                 <emphasis>
689                         Default value is <quote>0</quote>.
690                 </emphasis>
691                 </para>
692                 <example>
693                 <title>accessing the metrics</title>
694  <programlisting format="linespecific">
695 # using the command :
696 kamcmd dispatcher.list
697  ...
698 DEST: {
699         URI: sip:1.2.3.4
700         FLAGS: AX
701         PRIORITY: 9
702         LATENCY: {
703                 AVG: 24.250000 # weighted moving average for the last few weeks
704                 STD: 1.035000  # standard deviation of AVG
705                 EST: 25.000000 # short term estimate, see parameter: ds_latency_estimator_alpha
706                 MAX: 26        # maximum value seen
707                 TIMEOUT: 0     # count of ping timeouts
708         }
709 }
710  ...
711  </programlisting>
712                 </example>
713                 <example>
714                 <title>Set the <quote>ds_ping_latency_stats</quote> parameter</title>
715  <programlisting format="linespecific">
716  ...
717  modparam("dispatcher", "ds_ping_latency_stats", 1)
718  ...
719  </programlisting>
720                 </example>
721         </section>
722         <section id="dispatcher.p.ds_latency_estimator_alpha">
723                 <title><varname>ds_latency_estimator_alpha</varname> (int)</title>
724                 <para>
725                 The value to be used to control the memory of the estimator EWMA "exponential weighted moving average" or
726                 "the speed at which the older samples are dampened"
727                 a good explanation can be found here : http://www.itl.nist.gov/div898/handbook/pmc/section3/pmc324.htm
728                 Because Kamailio doesn't support float parameter types, the value in the parameter is divided by 1000 and stored as float.
729                 For example, if you want to set the alpha to be 0.75, use value 750 here.
730                 </para>
731                 <para>
732                 <emphasis>
733                         Default value is <quote>900 => 0.9</quote>.
734                 </emphasis>
735                 </para>
736                 <example>
737                 <title>Set the <quote>ds_hash_size</quote> parameter</title>
738  <programlisting format="linespecific">
739  ...
740  modparam("dispatcher", "ds_latency_estimator_alpha", 900)
741  ...
742  </programlisting>
743                 </example>
744         </section>
745         <section id="dispatcher.p.ds_hash_size">
746                 <title><varname>ds_hash_size</varname> (int)</title>
747                 <para>
748                 The value to be used as power of two to set the number of slots
749                 to hash table storing data for call load dispatching (e.g., value
750                 8 will create a hash table with 256 slots).
751                 It must be greater than 0 to enable call load dispatching feature
752                 (alg 10).
753                 </para>
754                 <para>
755                 <emphasis>
756                         Default value is <quote>0</quote>.
757                 </emphasis>
758                 </para>
759                 <example>
760                 <title>Set the <quote>ds_hash_size</quote> parameter</title>
761  <programlisting format="linespecific">
762  ...
763  modparam("dispatcher", "ds_hash_size", 9)
764  ...
765  </programlisting>
766                 </example>
767         </section>
768         <section id="dispatcher.p.ds_hash_expire">
769                 <title><varname>ds_hash_expire</varname> (int)</title>
770                 <para>
771                 Expiration time in seconds to remove the load on a destination if no
772                 BYE was received meanwhile.
773                 </para>
774                 <para>
775                 <emphasis>
776                         Default value is <quote>7200</quote>.
777                 </emphasis>
778                 </para>
779                 <example>
780                 <title>Set the <quote>ds_hash_expire</quote> parameter</title>
781  <programlisting format="linespecific">
782  ...
783  modparam("dispatcher", "ds_hash_expire", 3600)
784  ...
785  </programlisting>
786                 </example>
787         </section>
788         <section id="dispatcher.p.ds_hash_initexpires">
789                 <title><varname>ds_hash_initexpire</varname> (int)</title>
790                 <para>
791                 Expiration time in seconds to remove the load on a destination if no
792                 200 for INVITE was received meanwhile and state updated with
793                 ds_load_update().
794                 </para>
795                 <para>
796                 <emphasis>
797                         Default value is <quote>7200</quote>.
798                 </emphasis>
799                 </para>
800                 <example>
801                 <title>Set the <quote>ds_hash_initexpire</quote> parameter</title>
802  <programlisting format="linespecific">
803  ...
804  modparam("dispatcher", "ds_hash_initexpire", 60)
805  ...
806  </programlisting>
807                 </example>
808         </section>
809         <section id="dispatcher.p.ds_hash_check_interval">
810                 <title><varname>ds_hash_check_interval</varname> (int)</title>
811                 <para>
812                 Time interval in seconds to scan internal hash table with call load
813                 dispatching data for expired items.
814                 </para>
815                 <para>
816                 <emphasis>
817                         Default value is <quote>30</quote>.
818                 </emphasis>
819                 </para>
820                 <example>
821                 <title>Set the <quote>ds_hash_check_interval</quote> parameter</title>
822  <programlisting format="linespecific">
823  ...
824  modparam("dispatcher", "ds_hash_check_interval", 60)
825  ...
826  </programlisting>
827                 </example>
828         </section>
829         <section id="dispatcher.p.outbound_proxy">
830                 <title><varname>outbound_proxy</varname> (str)</title>
831                 <para>
832                 SIP URI of outbound proxy to be used when sending pings.
833                 </para>
834                 <para>
835                 <emphasis>
836                         By default no outbound proxy is defined.
837                 </emphasis>
838                 </para>
839                 <example>
840                 <title>Set the <quote>outbound_proxy</quote> parameter</title>
841  <programlisting format="linespecific">
842  ...
843  modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
844  ...
845  </programlisting>
846                 </example>
847         </section>
848
849         <section id="dispatcher.p.ds_default_socket">
850                 <title><varname>ds_default_socket</varname> (str)</title>
851                 <para>
852                         Default socket to be used for sending pings and dispatching requests
853                         when a gateway has no send socket configured.
854                 </para>
855                 <para>
856                 <emphasis>
857                         By default no default socket is defined, the first configuration
858                         script <emphasis>listen</emphasis> directive is used.
859                 </emphasis>
860                 </para>
861                 <example>
862                 <title>Set the <quote>ds_default_socket</quote> parameter</title>
863  <programlisting format="linespecific">
864  ...
865  modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
866  ...
867  </programlisting>
868                 </example>
869         </section>
870
871         <section id="dispatcher.p.ds_timer_mode">
872                 <title><varname>ds_timer_mode</varname> (int)</title>
873                 <para>
874                         Specify the timer process to be used by the module for
875                         keepalives and active dialogs tracking.
876                 </para>
877                 <para>
878                         It can be set to:
879                 </para>
880                 <itemizedlist>
881                 <listitem>
882                         <para>0 - use main timer process.</para>
883                 </listitem>
884                 <listitem>
885                         <para>1 - use secondary timer process.</para>
886                 </listitem>
887                 </itemizedlist>
888
889                 <para>
890                         On a server with a lot of traffic, using secondary
891                         timer can help with performances, because the main timer
892                         can be overloaded by taking care of transactions retransmissions
893                         and expirations of items in memory.
894                 </para>
895                 <para>
896                 <emphasis>
897                         Default value is <quote>0</quote>.
898                 </emphasis>
899                 </para>
900                 <example>
901                 <title>Set the <quote>ds_timer_mode</quote> parameter</title>
902  <programlisting format="linespecific">
903  ...
904  modparam("dispatcher", "ds_timer_mode", 1)
905  ...
906  </programlisting>
907                 </example>
908         </section>
909         <section id="dispatcher.p.event_callback">
910                 <title><varname>event_callback</varname> (str)</title>
911                 <para>
912                         The name of the function in the kemi configuration file (embedded
913                         scripting language such as Lua, Python, ...) to be executed instead
914                         of event_route[...] blocks.
915                 </para>
916                 <para>
917                         The function receives a string parameter with the name of the event,
918                         the values are: 'dispatcher:dst-down', 'dispatcher:dst-up'.
919                 </para>
920                 <para>
921                 <emphasis>
922                         Default value is 'empty' (no function is executed for events).
923                 </emphasis>
924                 </para>
925                 <example>
926                 <title>Set <varname>event_callback</varname> parameter</title>
927                 <programlisting format="linespecific">
928 ...
929 modparam("dispatcher", "event_callback", "ksr_dispatcher_event")
930 ...
931 -- event callback function implemented in Lua
932 function ksr_dispatcher_event(evname)
933         KSR.info("===== dispatcher module triggered event: " .. evname .. "\n");
934         return 1;
935 end
936 ...
937 </programlisting>
938                 </example>
939         </section>
940
941         <section id="dispatcher.p.ds_attrs_none">
942                 <title><varname>ds_attrs_none</varname> (int)</title>
943                 <para>
944                 If set to 1, "none=yes" is set in the attrs for those records that
945                 have no attrs value, to ensure that corresponding XAVP fields for
946                 records do not get mixed up.
947                 </para>
948                 <para>
949                 <emphasis>
950                         Default value is <quote>0</quote>.
951                 </emphasis>
952                 </para>
953                 <example>
954                 <title>Set the <quote>ds_attrs_none</quote> parameter</title>
955  <programlisting format="linespecific">
956  ...
957  modparam("dispatcher", "ds_attrs_none", 1)
958  ...
959  </programlisting>
960                 </example>
961         </section>
962
963         <section id="dispatcher.p.ds_db_extra_attrs">
964                 <title><varname>ds_db_extra_attrs</varname> (str)</title>
965                 <para>
966                 Set a list of column names to be loaded from database dispatcher table
967                 and be concatenated to 'attrs' field. The format is:
968                 'aname1=cname1;aname2=cname2;...;anameN=cnameN'.
969                 </para>
970                 <para>
971                 The 'anameX' is the attribute name and 'cnameX' is column name. The
972                 additional columns must be added to database dispatcher table and their
973                 type must be VARCHAR (string).
974                 </para>
975                 <para>
976                 <emphasis>
977                         Default value is <quote>empty</quote>.
978                 </emphasis>
979                 </para>
980                 <example>
981                 <title>Set the <quote>ds_db_extra_attrs</quote> parameter</title>
982 <programlisting format="linespecific">
983 ...
984 modparam("dispatcher", "ds_db_extra_attrs", "socket=socket;pref=prefix")
985 ...
986 </programlisting>
987                 </example>
988         </section>
989
990         <section id="dispatcher.p.ds_load_mode">
991                 <title><varname>ds_load_mode</varname> (int)</title>
992                 <para>
993                 If set to 1, the module throws error when failing to add a destination
994                 address (e.g., invalid URI). If set to 0, it skips the failing address
995                 and continues with the next ones.
996                 </para>
997                 <para>
998                 <emphasis>
999                         Default value is <quote>0</quote>.
1000                 </emphasis>
1001                 </para>
1002                 <example>
1003                 <title>Set the <quote>ds_load_mode</quote> parameter</title>
1004  <programlisting format="linespecific">
1005  ...
1006  modparam("dispatcher", "ds_load_mode", 1)
1007  ...
1008  </programlisting>
1009                 </example>
1010         </section>
1011
1012         <section id="dispatcher.p.reload_delta">
1013                 <title><varname>reload_delta</varname> (int)</title>
1014                 <para>
1015                 The number of seconds that have to be waited before executing a new reload
1016                 of dispatcher records. By default there is a rate limiting of maximum
1017                 one reload in five seconds.
1018                 </para>
1019                 <para>
1020                 If set to 0, no rate limit is configured. Note carefully: use this
1021                 configuration only in tests environments because executing many RPC
1022                 reload commands at the same time can cause unexpected behavior.
1023                 </para>
1024                 <para>
1025                 <emphasis>
1026                         Default value is <quote>5</quote>.
1027                 </emphasis>
1028                 </para>
1029                 <example>
1030                 <title>Set <varname>reload_delta</varname> parameter</title>
1031                 <programlisting format="linespecific">
1032 ...
1033 modparam("dispatcher", "reload_delta", 1)
1034 ...
1035                 </programlisting>
1036                 </example>
1037         </section>
1038         </section>
1039
1040         <section>
1041         <title>Functions</title>
1042         <section id="dispatcher.f.ds_select_dst">
1043                 <title>
1044                 <function moreinfo="none">ds_select_dst(set, alg[, limit])</function>
1045                 </title>
1046                 <para>
1047                 The method selects a destination from addresses set. It returns true if
1048                 a new destination is set. The selected address is set to dst_uri field
1049                 (aka the outbound proxy address or the $du variable), not being visible
1050                 in the SIP request.
1051                 </para>
1052                 <para>
1053                 If the bit 2 in 'flags' parameter is set, the rest of the addresses from
1054                 the destination set are stored in XAVP list (limited with an optional 'limit'
1055                 parameter). You can use 'ds_next_dst()' to use next address in order to
1056                 achieve serial forking to all possible destinations.
1057                 </para>
1058                 <para>Meaning of the parameters is as follows:</para>
1059                 <itemizedlist>
1060                 <listitem>
1061                         <para>
1062                         <emphasis>set</emphasis> - the id of the set from where to pick
1063                         up destination address. It is the first column in destination
1064                         list file. The parameter can be an integer or a variable holding
1065                         an integer.
1066                         </para>
1067                 </listitem>
1068                 <listitem>
1069                         <para>
1070                         <emphasis>alg</emphasis> - the algorithm used to select the
1071                         destination address. The parameter can be an integer or a
1072                         variable holding an integer.
1073                         </para>
1074                         <itemizedlist>
1075                         <listitem>
1076                                 <para>
1077                                 <quote>0</quote> - hash over callid
1078                                 </para>
1079                         </listitem>
1080                         <listitem>
1081                                 <para>
1082                                 <quote>1</quote> - hash over from URI.
1083                                 </para>
1084                         </listitem>
1085                         <listitem>
1086                                 <para>
1087                                 <quote>2</quote> - hash over to URI.
1088                                 </para>
1089                         </listitem>
1090                         <listitem>
1091                                 <para>
1092                                 <quote>3</quote> - hash over request-URI.
1093                                 </para>
1094                         </listitem>
1095                         <listitem>
1096                                 <para>
1097                                 <quote>4</quote> - round-robin (next destination).
1098                                 </para>
1099                         </listitem>
1100                         <listitem>
1101                                 <para>
1102                                 <quote>5</quote> - hash over authorization-username
1103                                 (Proxy-Authorization or "normal" authorization). If no
1104                                 username is found, round robin is used.
1105                                 </para>
1106                         </listitem>
1107                         <listitem>
1108                                 <para>
1109                                 <quote>6</quote> - random destination (using rand()).
1110                                 </para>
1111                         </listitem>
1112                         <listitem>
1113                                 <para>
1114                                 <quote>7</quote> - hash over the content of PVs string.
1115                                 Note: This works only when the parameter hash_pvar is set.
1116                                 </para>
1117                         </listitem>
1118                         <listitem>
1119                                 <para>
1120                                 <quote>8</quote> - select destination sorted by priority
1121                                 attribute value (serial forking ordered by priority).
1122                                 </para>
1123                         </listitem>
1124                         <listitem>
1125                                 <para>
1126                                 <quote>9</quote> - use weight based load distribution. You
1127                                 have to set the attribute 'weight' per each address in
1128                                 destination set.
1129                                 </para>
1130                         </listitem>
1131                         <listitem>
1132                                 <para>
1133                                 <quote>10</quote> - use call load distribution. You have
1134                                 to set the attribute 'duid' (as an unique string id)
1135                                 per each address in destination set. Also, you must set
1136                                 the parameter 'ds_hash_size'.
1137                                 </para>
1138                                 <para>
1139                                 The algorithm can be used even with stateless proxy mode,
1140                                 there is no SIP dialog tracking depending on other modules,
1141                                 just an internal lightweight call tracking by Call-Id, thus
1142                                 is fast and suitable even for embedded systems.
1143                                 </para>
1144                                 <para>
1145                                 The first destination selected by this algorithm is the one
1146                                 that has the least number of calls associated. The rest of
1147                                 the destination list is taken in order of the entries in set
1148                                 - anyhow, until a re-route to next destination happens, the
1149                                 load on each address can change.
1150                                 </para>
1151                                 <para>
1152                                 This algorithm can be used only for dispatching INVITE
1153                                 requests as it is the only SIP method creating a SIP call.
1154                                 </para>
1155                         </listitem>
1156                         <listitem>
1157                                 <para>
1158                                 <quote>11</quote> - use relative weight based load distribution.
1159                                 You have to set the attribute 'rweight' per each address in
1160                                 destination set. Active host usage probability is
1161                                 rweight/(SUM of all active host rweights in destination group).
1162                                 </para>
1163                                 <para>
1164                                 The major difference from the weight distribution is the
1165                                 probability recalculation according to rweight value in case of
1166                                 host enabling/disabling
1167                                 </para>
1168                                 <para>
1169                                 For example, 100 calls in 3-hosts group with rweight params 1/2/1
1170                                 will be distributed as 25/50/25. After third host failing
1171                                 distribution will be changed to 33/67/0.
1172                                 </para>
1173                                 <para>
1174                                 Using this algorithm, you can also enable congestion control by setting the
1175                                 attibute 'cc=1', when 'cc' is enabled the 'rweight' attribute will also be
1176                                 used to control congestion tolerance. When facing congestion the weight of
1177                                 a gateway is lowered by 1 for every ms of estimated congestion, a 'rweight'
1178                                 value of 50 is recommended. See the example "configuring load balancing with
1179                                 congestion detection" below.
1180                                 </para>
1181                                 <para>
1182                                 The congestion estimation is done using an EWMA (see ds_latency_estimator_alpha).
1183                                 If all the gateways in a set are above their congestion threshold(weight), the
1184                                 load distribution is instead done using the ratio of estimated congestion ms.
1185                                 </para>
1186                         </listitem>
1187                         <listitem>
1188                                 <para>
1189                                 <quote>12</quote> - dispatch to all destination in setid at
1190                                 once (parallel forking). Note that the XAVPs are no longer set
1191                                 with the values of the destination records, no re-routing
1192                                 making sense in this case.
1193                                 </para>
1194                         </listitem>
1195                         <listitem>
1196                                 <para>
1197                                 <quote>X</quote> - if the algorithm is not implemented, the
1198                                 first entry in set is chosen.
1199                                 </para>
1200                         </listitem>
1201                         </itemizedlist>
1202                 </listitem>
1203                 <listitem>
1204                         <para>
1205                         <emphasis>limit</emphasis> - the maximum number of items to be
1206                         stored in XAVP list for further fail-overs (the first selected
1207                         destination and default destination are the first to be put in
1208                         the list)
1209                         </para>
1210                 </listitem>
1211                 </itemizedlist>
1212                 <para>
1213                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1214                 </para>
1215                 <example>
1216                 <title><function>ds_select_dst</function> usage</title>
1217                 <programlisting format="linespecific">
1218 ...
1219 ds_select_dst("1", "0");
1220 ...
1221 $var(a) = 4;
1222 ds_select_dst("1", "$var(a)");
1223 ...
1224 ds_select_dst("1", "4", "3");
1225 ...
1226 </programlisting>
1227                 </example>
1228                 <example>
1229                 <title>configuring load balancing with congestion detection</title>
1230                 <programlisting format="linespecific">
1231 ...
1232 # sample of SQL provisionning statements
1233 INSERT INTO "dispatcher" 
1234 VALUES(1,1,'sip:192.168.0.1:5060',0,12,'rweight=50;weight=50;cc=1;','');
1235 INSERT INTO "dispatcher" 
1236 VALUES(2,1,'sip:192.168.0.2:5060',0,12,'rweight=50;weight=50;cc=1;','');
1237 ...
1238 modparam("dispatcher", "ds_ping_interval", 1) # ping gateways once/second
1239 modparam("dispatcher", "ds_ping_latency_stats", 1) # update congestion metrics
1240 # configure the latency estimator
1241 modparam("dispatcher", "ds_latency_estimator_alpha", 900)
1242 ...
1243 if (!ds_select_dst("1", "11")) { # use relative weight based load distribution
1244 ...
1245 # sample of output from 'kamcmd dispatcher.list'
1246 DEST: {
1247         URI: sip:192.168.0.1:5060
1248         FLAGS: AP
1249         PRIORITY: 12
1250         ATTRS: {
1251                 BODY: rweight=50;weight=50;cc=1 # configuration values
1252                 DUID: 
1253                 MAXLOAD: 0
1254                 WEIGHT: 50
1255                 RWEIGHT: 50
1256                 SOCKET: 
1257         }
1258         LATENCY: {
1259                 AVG: 20.104000
1260                 STD: 1.273000
1261                 # estimated congestion is currently 25ms = 45ms(EST) -20ms(AVG)
1262                 EST: 45.005000
1263                 MAX: 132
1264                 TIMEOUT: 3
1265         }
1266 }
1267 ...
1268 </programlisting>
1269                 </example>
1270         </section>
1271         <section id="dispatcher.f.ds_select_domain">
1272                 <title>
1273                 <function moreinfo="none">ds_select_domain(set, alg[, limit])</function>
1274                 </title>
1275                 <para>
1276                 The method selects a destination from addresses set and rewrites the
1277                 host and port from R-URI. The parameters have same meaning as for
1278                 ds_select_dst().
1279                 </para>
1280                 <para>
1281                 If the bit 2 in 'flags' is set, the rest of the addresses from the
1282                 destination set are stored in XAVP list (limited with an optional 'limit'
1283                 parameter). You can use 'ds_next_domain()' to use next address to
1284                 achieve serial forking to all possible destinations.
1285                 </para>
1286                 <para>
1287                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1288                 </para>
1289                 <example>
1290                 <title><function>ds_select_domain</function> usage</title>
1291                 <programlisting format="linespecific">
1292 ...
1293 $var(a) = 4;
1294 if(ds_select_domain("1", "$var(a)")) {
1295     t_relay();
1296     exit;
1297 }
1298 ...
1299 </programlisting>
1300                 </example>
1301         </section>
1302         <section id="dispatcher.f.ds_select">
1303                 <title>
1304                 <function moreinfo="none">ds_select(set, alg [, limit])</function>
1305                 </title>
1306                 <para>
1307                 The method selects a destination from addresses set and adds it
1308                 in the XAVP specified for this module. It is not updating R-URI
1309                 nor the destination URI. The parameters have same
1310                 meaning as for ds_select_dst().
1311                 </para>
1312                 <para>
1313                 If the bit 2 in 'flags' is set, the rest of the addresses from the
1314                 destination set are stored in XAVP list (limited with an optional 'limit'
1315                 parameter). You can execute 'ds_next_domain()' or 'ds_next_dst()' to use
1316                 next address to achieve serial forking to all possible destinations.
1317                 </para>
1318                 <para>
1319                 This function can be used from ANY_ROUTE.
1320                 </para>
1321                 <example>
1322                 <title><function>ds_select</function> usage</title>
1323                 <programlisting format="linespecific">
1324 ...
1325 $var(a) = 4;
1326 if(ds_select("1", "$var(a)")) {
1327     ds_next_domain();
1328     t_relay();
1329     exit;
1330 }
1331 ...
1332 </programlisting>
1333                 </example>
1334         </section>
1335         <section id="dispatcher.f.ds_select_routes">
1336                 <title>
1337                 <function moreinfo="none">ds_select_routes(rules, mode [, limit])</function>
1338                 </title>
1339                 <para>
1340                 The method selects destinations following the rules combining groups add
1341                 algorithms, controlling where the first destination address is pushed,
1342                 and optionally setting a limit of selected addresses.
1343                 </para>
1344                 <para>Parameters:</para>
1345                 <itemizedlist>
1346                 <listitem>
1347                         <para><emphasis>rules</emphasis> - a string in the format
1348                         "grp1=alg1;grp2=alg2;...grpN=algN", where grpX is an integer number
1349                         identifying a dispatcher set id and algN is a dispatcher algorithm
1350                         identifier. No white spaces should be given in the parameter value.
1351                         The parameter can contain pseudo-variables.
1352                         </para>
1353                 </listitem>
1354                 <listitem>
1355                         <para><emphasis>mode</emphasis> - control where to push the first
1356                         selected target address. Valid values are: '0', 'd' or 'D' to push
1357                         the address in destination URI; '1', 'r' or 'R' to push the address
1358                         in R-URI; '2', 'x' or 'X' to push the address only in the XAVP when
1359                         failure rerouting is enabled. Note that only first character of the
1360                         parameter matters, therefore one can use a more meaningful value
1361                         such as 'ruri' instead of 'r'. The parameter can contain pseudo
1362                         variables.
1363                         </para>
1364                 </listitem>
1365                 <listitem>
1366                         <para><emphasis>limit</emphasis> - a positive integer value to
1367                         restrict the number of selected target addresses. If it is 0, then
1368                         no limit is considered. The parameter can be a static integer or
1369                         a variable holding an integer value.
1370                         </para>
1371                 </listitem>
1372                 </itemizedlist>
1373                 <para>
1374                 If the bit 2 in 'flags' is set, the rest of the addresses from the
1375                 destination groups are stored in XAVP list (limited with an optional 'limit'
1376                 parameter). You can execute 'ds_next_domain()' or 'ds_next_dst()' to use
1377                 next address to achieve serial forking to all possible destinations.
1378                 </para>
1379                 <para>
1380                 This function can be used from ANY_ROUTE.
1381                 </para>
1382                 <example>
1383                 <title><function>ds_select_routes</function> usage</title>
1384                 <programlisting format="linespecific">
1385 ...
1386 $var(alg) = 4;
1387 $var(limit) = 8;
1388 if(ds_select_routes("1=4;2=$var(alg)", "ruri", "$var(limit)")) {
1389     t_on_failure("REROUTE");
1390     t_relay();
1391     exit;
1392 }
1393 failure_route[REROUTE] {
1394     if(t_check_status("408|5[0-9][0-9]")) {
1395         if(ds_next_domain()) {
1396             t_on_failure("REROUTE");
1397             t_relay();
1398             exit;
1399         }
1400     }
1401 }
1402 ...
1403 </programlisting>
1404                 </example>
1405         </section>
1406         <section>
1407                 <title>
1408                 <function moreinfo="none">ds_next_dst()</function>
1409                 </title>
1410                 <para>
1411                 Takes the next destination address from the corresponding XAVPs
1412                 and sets the dst_uri (outbound proxy address).
1413                 </para>
1414                 <para>
1415                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1416                 </para>
1417         </section>
1418         <section>
1419                 <title>
1420                 <function moreinfo="none">ds_next_domain()</function>
1421                 </title>
1422                 <para>
1423                 Takes the next destination address from the corresponding XAVPs
1424                 and sets the domain part of the request URI.
1425                 </para>
1426                 <para>
1427                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1428                 </para>
1429         </section>
1430         <section id="dispatcher.f.ds_set_dst">
1431                 <title>
1432                 <function moreinfo="none">ds_set_dst()</function>
1433                 </title>
1434                 <para>
1435                 Takes the current destination address from the corresponding XAVPs
1436                 and sets the dst_uri (outbound proxy address).
1437                 </para>
1438                 <para>
1439                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1440                 </para>
1441         </section>
1442         <section id="dispatcher.f.ds_set_domain">
1443                 <title>
1444                 <function moreinfo="none">ds_set_domain()</function>
1445                 </title>
1446                 <para>
1447                 Takes the current destination address from the corresponding XAVPs
1448                 and sets the domain part of the request URI.
1449                 </para>
1450                 <para>
1451                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1452                 </para>
1453         </section>
1454         <section id="dispatcher.f.ds_mark_dst">
1455                 <title>
1456                 <function moreinfo="none">ds_mark_dst([state])</function>
1457                 </title>
1458                 <para>
1459                 Mark the last used address from destination set as inactive
1460                 ("i"/"I"), active ("a"/"A"), disabled ("d"/"D") or trying ("t"/"T").
1461                 Apart of disabled state, a destination can be set in probing mode by
1462                 adding ("p"/"P") flag. With this function, an automatic detection
1463                 of failed gateways can be implemented. When an address is marked as
1464                 inactive or disabled, it will be ignored by 'ds_select_dst' and
1465                 'ds_select_domain'.
1466                 </para>
1467                 <para>
1468                 The parameter state is optional, when it is missing, then
1469                 the destination will be marked inactive (i.e., same as 'i').
1470                 </para>
1471                 <para>Possible values for state parameter:</para>
1472                 <itemizedlist>
1473                 <listitem>
1474                         <para><emphasis>"a" or "A"</emphasis> - the last destination
1475                                 should be set to active and the error-counter should set to "0".
1476                         </para>
1477                 </listitem>
1478                 <listitem>
1479                         <para><emphasis>"i" or "I"</emphasis> - the last destination
1480                                 should be set to inactive and will be ignored in future
1481                                 requests.</para>
1482                 </listitem>
1483                 <listitem>
1484                         <para><emphasis>"t" or "T"</emphasis> - the last destination
1485                                 should be set to temporary trying state and failure counter
1486                                 is incremented. When the failure counter reaches the threshold,
1487                                 the destination will be set inactive.
1488                         </para>
1489                 </listitem>
1490                 <listitem>
1491                         <para><emphasis>"p" and "P"</emphasis> - this has to be used in
1492                                 addition to one of the previous flags - the last destination
1493                                 will be set to probing. This mean the destination will be pinged
1494                                 with SIP OPTIONS requests from time to time to detect if it is
1495                                 up or down.</para>
1496                 </listitem>
1497                 </itemizedlist>
1498                 <para>
1499                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1500                 </para>
1501                 <example>
1502                 <title><function>ds_mark_dst</function> usage</title>
1503                 <programlisting format="linespecific">
1504 ...
1505 failure_route[tryagain] {
1506 ...
1507    if(t_check_status("500"))
1508       ds_mark_dst("ip"); # set to inactive and probing
1509 ...
1510 }
1511 ...
1512 </programlisting>
1513                 </example>
1514         </section>
1515         <section  id="dispatcher.f.ds_list_exists">
1516                 <title>
1517                 <function moreinfo="none">ds_list_exists(groupid)</function>
1518                 </title>
1519                 <para>
1520                 Function alias: ds_list_exist(groupid)
1521                 </para>
1522                 <para>
1523                 Check if a specific group is defined in dispatcher list
1524                 or database.
1525                 </para>
1526                 <itemizedlist>
1527                 <listitem>
1528                         <para><emphasis>groupid</emphasis> - A group ID to check.
1529                         </para>
1530                 </listitem>
1531                 </itemizedlist>
1532                 <para>
1533                         This function can be used from ANY_ROUTE.
1534                 </para>
1535                 <example>
1536                 <title><function>ds_list_exists</function> usage</title>
1537                 <programlisting format="linespecific">
1538 ...
1539 if(ds_list_exists("10")) {
1540     ...
1541 }
1542 ...
1543 </programlisting>
1544         </example>
1545         </section>
1546         <section  id="dispatcher.f.ds_is_from_list">
1547                 <title>
1548                 <function moreinfo="none">ds_is_from_list([groupid [, mode [, uri] ] ])</function>
1549                 </title>
1550                 <para>
1551                 This function returns true, if there is a match of source address or uri
1552                 with an address in the given group of the dispatcher-list; otherwise false.
1553                 </para>
1554                 <para>Description of parameters:</para>
1555                 <itemizedlist>
1556                 <listitem>
1557                         <para><emphasis>groupid</emphasis> (optional) - if not given or its
1558                                 value is -1, the matching will be done over all addresses in
1559                                 all dispacher groups. Otherwise the matching will be done only
1560                                 against the addresses in the specific group id. The parameter
1561                                 can be an integer or a variable holding an integer value.
1562                         </para>
1563                 </listitem>
1564                 <listitem>
1565                         <para><emphasis>mode</emphasis> - (optional) - a bitmask to specify
1566                                 how the matching should be done. If is 0, all ip, port and
1567                                 proto are matched. If bit one is set, then port is ignored.
1568                                 If bit two is set, then protocol is ignored. The parameter
1569                                 can be an integer or a variable holding an integer value.
1570                                 It must be provided if the uri parameter is provided.
1571                         </para>
1572                 </listitem>
1573         <listitem>
1574             <para><emphasis>uri</emphasis> (optional) - if is empty or missing,
1575                 the matching is done against source IP, port and protocol.
1576                 Otherwise the value has to be a valid SIP URI, used to match
1577                 against addresses in the dispatcher list. Only IP, port and
1578                 protocol are matches, any additional parameters are ignored.
1579                 The parameter can be a static or dynamic (with variables)
1580                 string. The domain part of the URI can be an IP address or
1581                 a hostname.
1582             </para>
1583         </listitem>
1584                 </itemizedlist>
1585
1586                 <para>
1587                 Upon a match, the variable specified by 'setid_pvname' parameter will
1588                 be set to groupid of matching address and the attributes will be set in
1589                 variable specified by 'attrs_pvname'.
1590                 </para>
1591                 <para>
1592                 Note that for backward compatibility mode, when no parameter is given
1593                 or only groupid is given, the matching is done only for IP address
1594                 and port (protocol is ignored).
1595                 </para>
1596                 <para>
1597                         This function can be used from ANY_ROUTE.
1598                 </para>
1599                 <example>
1600                 <title><function>ds_is_from_list</function> usage</title>
1601                 <programlisting format="linespecific">
1602 ...
1603 if(ds_is_from_list()) {
1604     ...
1605 }
1606 if(ds_is_from_list("10")) {
1607     ...
1608 }
1609 if(ds_is_from_list("10", "3")) {
1610     ...
1611 }
1612 if(ds_is_from_list("10", "3", "sip:127.0.0.1:5080")) {
1613     ...
1614 }
1615 ...
1616 </programlisting>
1617                 </example>
1618         </section>
1619         <section id="dispatcher.f.ds_load_update">
1620                 <title>
1621                 <function moreinfo="none">ds_load_update()</function>
1622                 </title>
1623                 <para>
1624                 Updates the load state:
1625                 </para>
1626                 <itemizedlist>
1627                 <listitem>
1628                         <para>if it is a BYE or CANCEL - remove the load from
1629                         destination address used to forward the INVITE</para>
1630                 </listitem>
1631                 <listitem>
1632                         <para>if it is a reply to INVITE - set internal state
1633                                 to confirmed for call load structure when reply code is
1634                                 2xx.</para>
1635                 </listitem>
1636                 </itemizedlist>
1637                 <para>
1638                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
1639                         BRANCH_ROUTE and ONREPLY_ROUTE.
1640                 </para>
1641         </section>
1642         <section>
1643                 <title>
1644                 <function moreinfo="none">ds_load_unset()</function>
1645                 </title>
1646                 <para>
1647                 Remove the call load for the destination that routed the call.
1648                 </para>
1649                 <para>
1650                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
1651                         BRANCH_ROUTE and ONREPLY_ROUTE.
1652                 </para>
1653                 <example>
1654                 <title><function>ds_load_unset</function> usage</title>
1655                 <programlisting format="linespecific">
1656 ...
1657 route {
1658     ...
1659         if(is_method("BYE|CANCEL"))
1660         ds_load_update();
1661     ...
1662         ds_select_dst("1", "10");
1663     ...
1664 }
1665
1666 onreply_route {
1667     ...
1668     if(is_method("INVITE")
1669         {
1670         if(status=~"2[0-9][0-9]")
1671             ds_load_update();
1672         else if(status=~"[3-7][0-9][0-9]")
1673             ds_load_unset();
1674     }
1675     ...
1676 }
1677 ...
1678 </programlisting>
1679                 </example>
1680         </section>
1681         <section id="dispatcher.f.ds_reload">
1682                 <title>
1683                 <function moreinfo="none">ds_reload()</function>
1684                 </title>
1685                 <para>
1686                 Reloads the groups and included destinations.
1687                 </para>
1688                 <para>
1689                 Name: <emphasis>ds_reload</emphasis>
1690                 </para>
1691                 <para>Parameters: <emphasis>none</emphasis></para>
1692                 <para>
1693                 This function can be used from ANY_ROUTE.
1694                 </para>
1695         </section>
1696         </section>
1697
1698         <section>
1699         <title>RPC Commands</title>
1700         <section id="dispatcher.r.set_state">
1701                 <title>
1702                 <function moreinfo="none">dispatcher.set_state</function>
1703                 </title>
1704                 <para>
1705                 Sets the state for a destination address (can be use to mark the destination
1706                 as active or inactive).
1707                 </para>
1708                 <para>
1709                 Name: <emphasis>dispatcher.set_state</emphasis>
1710                 </para>
1711                 <para>Parameters:</para>
1712                 <itemizedlist>
1713                         <listitem><para>_state_ : state of the destination address</para>
1714                               <itemizedlist>
1715                          <listitem><para> <quote>a</quote>: active</para></listitem>
1716                                  <listitem><para> <quote>i</quote>: inactive</para></listitem>
1717                                  <listitem><para> <quote>t</quote>: trying</para></listitem>
1718                                  <listitem><para> <quote>d</quote>: disabled</para></listitem>
1719                                   </itemizedlist>
1720                                   <para>The states <quote>a</quote>, <quote>i</quote> or
1721                                           <quote>t</quote> can be followed by <quote>p</quote>
1722                                           to set probing mode (e.g. 'ap', 'ip' or 'tp').</para>
1723                         </listitem>
1724
1725                         <listitem><para>_group_: destination group id</para></listitem>
1726
1727                         <listitem><para>_address_: address of the destination in the _group_
1728                                         or 'all' to update all destinations in the group</para></listitem>
1729                 </itemizedlist>
1730                 <para>
1731                 Example:
1732                 </para>
1733 <programlisting  format="linespecific">
1734 ...
1735 # prototype: &sercmd; dispatcher.set_state _state_ _group_ _address_
1736 &sercmd; dispatcher.set_state ip 2 sip:127.0.0.1:5080
1737 &sercmd; dispatcher.set_state ip 3 all
1738 ...
1739 </programlisting>
1740     </section>
1741         <section id="dispatcher.r.list">
1742                 <title>
1743                 <function moreinfo="none">dispatcher.list</function>
1744                 </title>
1745                 <para>
1746                 Lists the groups and included destinations.
1747                 </para>
1748                 <para>
1749                 Name: <emphasis>dispatcher.list</emphasis>
1750                 </para>
1751                 <para>Parameters: <emphasis>none</emphasis></para>
1752                 <para>
1753                 Example:
1754                 </para>
1755         <programlisting  format="linespecific">
1756                 &sercmd; dispatcher.list
1757  ...
1758 DEST: {
1759         URI: sip:192.168.0.1:5060
1760         FLAGS: AP
1761         PRIORITY: 12
1762 }
1763  ...
1764 </programlisting>
1765                 <para>FLAGS consist out of 2 letters. First letter describe status of
1766                 destination: A-active, I – inactive, T – trying, D – disabled. Second
1767                 letter might be P or X. P is for probing, so AP means destination
1768                 is active and it is tested by SIP options continuously. X means that
1769                 there are no probing or sip pinging. So AX means that destination is
1770                 assumed as active and it is not tested by SIP options. DX
1771                 respectively is disabled destination that is not tested, etc.
1772                 </para>
1773         </section>
1774         <section id="dispatcher.r.reload">
1775                 <title>
1776                 <function moreinfo="none">dispatcher.reload</function>
1777                 </title>
1778                 <para>
1779                 Reloads the groups and included destinations. The command is
1780                 disabled for call load based dispatching (algorithm 10) since
1781                 removal of destinations may leave the list of active
1782                 calls with broken references.
1783                 </para>
1784                 <para>
1785                 Name: <emphasis>dispatcher.reload</emphasis>
1786                 </para>
1787                 <para>Parameters: <emphasis>none</emphasis></para>
1788                 <para>
1789                 Example
1790                 </para>
1791         <programlisting  format="linespecific">
1792                 &sercmd; dispatcher.reload
1793                 </programlisting>
1794     </section>
1795
1796         <section id="dispatcher.r.ping_active">
1797                 <title>
1798                 <function moreinfo="none">dispatcher.ping_active</function>
1799                 </title>
1800                 <para>
1801                 Sets the global state for sending keepalive requests to destinations.
1802                 </para>
1803                 <para>
1804                 Name: <emphasis>dispatcher.ping_active</emphasis>
1805                 </para>
1806                 <para>Parameters:</para>
1807                 <itemizedlist>
1808                         <listitem><para>_state_ : state of sending keepalives</para>
1809                             <itemizedlist>
1810                        <listitem><para> <quote>0</quote>: inactive (don't send)</para></listitem>
1811                                <listitem><para> <quote>1</quote>: active (send)</para></listitem>
1812                                 </itemizedlist>
1813                         </listitem>
1814                 </itemizedlist>
1815                 <para>
1816                         If the state parameter is missing, the current state is returned.
1817                         When state is changed, new and old values of the state are returned.
1818                         Default value for state is 1.
1819                 </para>
1820                 <para>
1821                 Example:
1822                 </para>
1823 <programlisting  format="linespecific">
1824 ...
1825 # prototype: &kamcmd; dispatcher.ping_active _state_
1826 &kamcmd; dispatcher.ping_active 0
1827 ...
1828 </programlisting>
1829     </section>
1830                 <section id="dispatcher.r.add">
1831                 <title>
1832                 <function moreinfo="none">dispatcher.add</function>
1833                 </title>
1834                 <para>
1835                 Add a destination address to the in-memory dispatcher list. Reloading the dispatcher will remove
1836                 any destinations that are only added to the in-memory dispatcher list.
1837                 </para>
1838                 <para>
1839                 Name: <emphasis>dispatcher.add</emphasis>
1840                 </para>
1841                 <para>Parameters:</para>
1842                 <itemizedlist>
1843                         <listitem><para>_group_: destination group id</para></listitem>
1844
1845                         <listitem><para>_address_: address of the destination in the _group_</para></listitem>
1846
1847                         <listitem><para>_flags_ (optional): as described in the list file format,
1848                         default 0</para></listitem>
1849
1850                 </itemizedlist>
1851                 <para>
1852                 Example:
1853                 </para>
1854 <programlisting  format="linespecific">
1855 ...
1856 # prototype: &sercmd; dispatcher.add _group_ _address_ _flags_
1857 &sercmd; dispatcher.add 2 sip:127.0.0.1:5080
1858 &sercmd; dispatcher.add 3 sip:127.0.0.1:5075 8
1859 ...
1860 </programlisting>
1861     </section>
1862                 <section id="dispatcher.r.remove">
1863                 <title>
1864                 <function moreinfo="none">dispatcher.remove</function>
1865                 </title>
1866                 <para>
1867                 Remove a destination address from the in-memory dispatcher list. Reloading
1868                 the dispatcher from file or database will re-add destinations that are
1869                 removed using this command.
1870                 </para>
1871                 <para>
1872                 This command will remove all entries that match the group and address.
1873                 </para>
1874                 <para>
1875                 Name: <emphasis>dispatcher.remove</emphasis>
1876                 </para>
1877                 <para>Parameters:</para>
1878                 <itemizedlist>
1879                         <listitem><para>_group_: destination group id</para></listitem>
1880
1881                         <listitem><para>_address_: address of the destination in the _group_</para></listitem>
1882
1883                 </itemizedlist>
1884                 <para>
1885                 Example:
1886                 </para>
1887 <programlisting  format="linespecific">
1888 ...
1889 # prototype: &sercmd; dispatcher.remove _group_ _address_
1890 &sercmd; dispatcher.remove 2 sip:127.0.0.1:5080
1891 &sercmd; dispatcher.remove 3 sip:127.0.0.1:5075;transport=udp
1892 ...
1893 </programlisting>
1894     </section>
1895
1896    </section>
1897
1898         <section id="dispatcher.ex.install">
1899         <title>Installation and Running</title>
1900         <section>
1901                 <title>Destination List File</title>
1902                 <para>
1903                 Each destination point must be on one line. First token is the set
1904                 id (an integer value, also referenced by group id), followed by
1905                 destination address (string value in full SIP URI format).
1906                 </para>
1907                 <para>
1908                 Optionally, these fields can be followed by:
1909                 </para>
1910                 <itemizedlist>
1911                         <listitem>
1912                         <para>flags - control the mode of using the destination address and
1913                         sending keepalives. It is a bitwise value that can be built using
1914                         the folowing flags:
1915                         <itemizedlist>
1916                                 <listitem><para>1 (bit at index 0 - 1 &lt;&lt;0) - inactive destination</para>
1917                                 </listitem>
1918                                 <listitem><para>2 (bit at index 1 - 1 &lt;&lt;1) - temporary trying
1919                                 destination (in the way to become inactive if it does not reply to
1920                                 keepalives - there is a module parameter to set the threshold of
1921                                 failures)</para>
1922                                 </listitem>
1923                                 <listitem><para>4 (bit at index 2 - 1 &lt;&lt;2) - admin disabled destination</para>
1924                                 </listitem>
1925                                 <listitem><para>8 (bit at index 3 - 1 &lt;&lt;3) - probing destination (sending keep alives);</para>
1926                                 </listitem>
1927                                 <listitem><para>16 (bit at index 4 - 1 &lt;&lt;4) - skip DNS A/AAAA resolve at startup,
1928                                 useful when the hostname of the destination address is a NAPTR or SRV record only.
1929                                 Such addresses cannot be matched anymore with ds_is_from_list(...).</para>
1930                                 </listitem>
1931                         </itemizedlist>
1932                         </para>
1933                         </listitem>
1934                         <listitem>
1935                         <para>priority: sets the priority in destination list (based on it
1936                         is done the initial ordering inside the set)</para>
1937                         </listitem>
1938                         <listitem>
1939                         <para>attributes: extra fields in form of
1940                                 name1=value1;...;nameN=valueN.
1941                         </para>
1942                         </listitem>
1943                 </itemizedlist>
1944                 <section id="dispatcher.ex.attributes">
1945                         <title>Special Attributes</title>
1946                         <para>
1947                         There are some predefined names:
1948                         <itemizedlist>
1949                                 <listitem>
1950                                         'duid' - used for call load dispatching. It must be an
1951                                         unique value to identify a destination (gateway address).
1952                                         Practically the load within the group is associated with
1953                                         this value.
1954                                 </listitem>
1955                                 <listitem>
1956                                         'maxload' - used for call load dispatching. It must be
1957                                         a positive integer, defining the upper limit of active
1958                                         calls per destination. When the limit is reached, then
1959                                         the gateway is no longer selected for new calls until
1960                                         an exiting call via that gateway is terminated. If set
1961                                         to 0, then no active call limit is used.
1962                                 </listitem>
1963                                 <listitem>
1964                                         'weight' - used for weight based load distribution. It
1965                                         must be set to a positive integer value beteen 0 and
1966                                         100. The value represents the percent of calls to be
1967                                         sent to that gateways.
1968                                 </listitem>
1969                                 <listitem>
1970                                         'rweight' - used for relative weight based load
1971                                         distribution. It must be set to a positive integer value
1972                                         between 1 and 100 (otherwise host will be excluded from
1973                                         relative weight distribution type).
1974                                 </listitem>
1975                                 <listitem>
1976                                         'socket' - used to set the sending socket for the gateway.
1977                                         It is used for sending the SIP traffic as well as
1978                                         OPTIONS keepalives.
1979                                 </listitem>
1980                                 <listitem>
1981                                         'ping_from' - used to set the From URI in OPTIONS keepalives.
1982                                         It overwrites the general ds_ping_from parameter.
1983                                 </listitem>
1984                         </itemizedlist>
1985                 </para>
1986                 </section>
1987                 <section id="dispatcher.ex.fileforma">
1988                         <title>File Format</title>
1989                 <para>
1990                 Line format is:
1991                 </para>
1992                 <programlisting format="linespecific">
1993 ...
1994 setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
1995 ...
1996 </programlisting>
1997
1998                 <para>
1999                 Full line example:
2000                 </para>
2001                 <programlisting format="linespecific">
2002 ...
2003 1 sip:127.0.0.1:5080 0 0 duid=abc;socket=udp:192.168.0.125:5060;my=xyz;ping_from=sip:myproxy.com
2004 ...
2005 </programlisting>
2006
2007                 <para>
2008                 For database, each element of a line resides in a different column.
2009                 Next is a dispatcher.list file example:
2010                 </para>
2011                 <example>
2012                 <title>dispatcher list file</title>
2013                 <programlisting format="linespecific">
2014 ...
2015 <xi:include href="dispatcher.list" parse="text"/>
2016 ...
2017 </programlisting>
2018                 </example>
2019                 </section>
2020                 </section>
2021
2022                 <section id="dispatcher.ex.config">
2023                 <title>&kamailio; config file</title>
2024                 <para>
2025                 Next listing shows a sample config for using the dispatcher module.
2026                 </para>
2027                 <example>
2028                 <title>&kamailio; config script - sample dispatcher usage</title>
2029                 <programlisting format="linespecific">
2030 ...
2031 <xi:include href="dispatcher.cfg" parse="text"/>
2032 ...
2033                 </programlisting>
2034                 </example>
2035         </section>
2036         </section>
2037
2038         <section id="dispatcher.ex.event_routes">
2039         <title>Event routes</title>
2040         <section>
2041                 <title>
2042                 <function moreinfo="none">dispatcher:dst-down</function>
2043                 </title>
2044                 <para>
2045                         When defined, the module calls event_route[dispatcher:ds-down]
2046                         when a destination goes down (becomes probing). A typical use
2047                         case is to update NMC equipment as to the status of a destination.
2048                 </para>
2049         <programlisting  format="linespecific">
2050 ...
2051 event_route[dispatcher:dst-down] {
2052     xlog("L_ERR", "Destination down: $rm $ru ($du)\n");
2053 }
2054 ...
2055                 </programlisting>
2056         </section>
2057         <section>
2058                 <title>
2059                 <function moreinfo="none">dispatcher:dst-up</function>
2060                 </title>
2061                 <para>
2062                         When defined, the module calls event_route[dispatcher:ds-up]
2063                         when a destination that was previously down (probing) comes up.
2064                         A typical use case is to update NMC equipment as to the status
2065                         of a destination.
2066                 </para>
2067         <programlisting  format="linespecific">
2068 ...
2069 event_route[dispatcher:dst-up] {
2070     xlog("L_ERR", "Destination up: $rm $ru\n");
2071 }
2072 ...
2073                 </programlisting>
2074     </section>
2075     </section>
2076
2077 </chapter>
2078