Merge pull request #881 from mslehto/doctypo
[sip-router] / 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 "../../../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 dispaching 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.
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 sets 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:passwb@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 sets 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 group id.
144                 </para>
145                 <para>
146                 <emphasis>
147                         Default value is <quote>setid</quote>.
148                 </emphasis>
149                 </para>
150                 <example>
151                 <title>Set <quote>setid_col</quote> parameter</title>
152                 <programlisting format="linespecific">
153 ...
154 modparam("dispatcher", "setid_col", "groupid")
155 ...
156 </programlisting>
157                 </example>
158         </section>
159
160         <section id="dispatcher.p.destination_col">
161                 <title><varname>destination_col</varname> (string)</title>
162                 <para>
163                         The column's name in the database storing the destination
164                         sip URI.
165                 </para>
166                 <para>
167                 <emphasis>
168                         Default value is <quote>destination</quote>.
169                 </emphasis>
170                 </para>
171                 <example>
172                 <title>Set <quote>destination_col</quote> parameter</title>
173                 <programlisting format="linespecific">
174 ...
175 modparam("dispatcher", "destination_col", "uri")
176 ...
177 </programlisting>
178                 </example>
179         </section>
180
181         <section id="dispatcher.p.flags_col">
182                 <title><varname>flags_col</varname> (string)</title>
183                 <para>
184                         The column's name in the database storing the flags for
185                         the destination URI.
186                 </para>
187                 <para>
188                 <emphasis>
189                         Default value is <quote>flags</quote>.
190                 </emphasis>
191                 </para>
192                 <example>
193                 <title>Set <quote>flags_col</quote> parameter</title>
194                 <programlisting format="linespecific">
195 ...
196 modparam("dispatcher", "flags_col", "dstflags")
197 ...
198 </programlisting>
199                 </example>
200         </section>
201
202         <section id="dispatcher.p.priority_col">
203                 <title><varname>priority_col</varname> (string)</title>
204                 <para>
205                         The column's name in the database storing the priority for
206                         destination URI.
207                 </para>
208                 <para>
209                 <emphasis>
210                         Default value is <quote>priority</quote>.
211                 </emphasis>
212                 </para>
213                 <example>
214                 <title>Set <quote>priority_col</quote> parameter</title>
215                 <programlisting format="linespecific">
216 ...
217 modparam("dispatcher", "priority_col", "dstpriority")
218 ...
219 </programlisting>
220                 </example>
221         </section>
222
223         <section id="dispatcher.p.force_dst">
224                 <title><varname>force_dst</varname> (int)</title>
225                 <para>
226                 If set to 1, force overwriting of destination address (outbound proxy)
227                 when that is already set. If set to 0, will return error when the
228                 destination address is already set.
229                 </para>
230                 <para>
231                 <emphasis>
232                         Default value is <quote>1</quote>.
233                 </emphasis>
234                 </para>
235                 <example>
236                 <title>Set the <quote>force_dst</quote> parameter</title>
237 <programlisting format="linespecific">
238 ...
239 modparam("dispatcher", "force_dst", 1)
240 ...
241 </programlisting>
242                 </example>
243         </section>
244         <section id="dispatcher.p.flags">
245                 <title><varname>flags</varname> (int)</title>
246                 <para>
247                 Various flags that affect dispatcher's behaviour. The flags are defined
248                 as a bitmask on an integer value.
249                 If flag 1 is set only the username
250                 part of the URI will be used when computing an URI based hash.
251                 If no flags are set the username, hostname and port will be used.
252                 The port is used only if different from 5060 (normal sip URI) or 5061
253                 (in the sips: case).
254                 </para>
255                 <para>
256                 If flag 2 is set, then failover support is enabled. The functions
257                 exported by the module will store the rest of addresses from the
258                 destination set in the AVP, and use these AVPs to contact next address if
259                 the current-tried destination fails.
260                 </para>
261                 <para>
262                 <emphasis>
263                         Default value is <quote>0</quote>.
264                 </emphasis>
265                 </para>
266                 <example>
267                 <title>Set the <quote>flags</quote> parameter</title>
268  <programlisting format="linespecific">
269  ...
270  modparam("dispatcher", "flags", 3)
271  ...
272  </programlisting>
273                 </example>
274         </section>
275         <section id="dispatcher.p.use_default">
276                 <title><varname>use_default</varname> (int)</title>
277                 <para>
278                 If the parameter is set to 1, the last address in destination set
279                 is used as a final option to send the request to. For example, it is useful
280                 when wanting to send the call to an anouncement server saying:
281                 "the gateways are full, try later".
282                 </para>
283                 <para>
284                 <emphasis>
285                         Default value is <quote>0</quote>.
286                 </emphasis>
287                 </para>
288                 <example>
289                 <title>Set the <quote>use_default</quote> parameter</title>
290  <programlisting format="linespecific">
291  ...
292  modparam("dispatcher", "use_default", 1)
293  ...
294  </programlisting>
295                 </example>
296         </section>
297         <section id="dispatcher.p.dst_avp">
298                 <title><varname>dst_avp</varname> (str)</title>
299                 <para>
300                 The name of the avp which will hold the list with addresses, in the
301                 order
302                 they have been selected by the chosen algorithm. If use_default is 1,
303                 the value of last dst_avp_id is the last address in destination set. The
304                 first dst_avp_id is the selected destinations. All the other addresses
305                 from the destination set will be added in the avp list to be able to
306                 implement serial forking.
307                 </para>
308                 <note>
309                 <para>
310                 You must set this parameter if you want to do load balancing fail over.
311                 </para>
312                 </note>
313                 <para>
314                 <emphasis>
315                         Default value is <quote>null</quote> - don't add AVPs.
316                 </emphasis>
317                 </para>
318                 <example>
319                 <title>Set the <quote>dst_avp</quote> parameter</title>
320  <programlisting format="linespecific">
321  ...
322  modparam("dispatcher", "dst_avp", "$avp(dsdst)")
323  ...
324  </programlisting>
325                 </example>
326         </section>
327         <section id="dispatcher.p.grp_avp">
328                 <title><varname>grp_avp</varname> (str)</title>
329                 <para>
330                 The name of the avp storing the group id of the destination set. Good
331                 to have it for later usage or checks.
332                 </para>
333                 <note>
334                 <para>
335                 You must set this parameter if you want to do load balancing fail over.
336                 </para>
337                 </note>
338                 <para>
339                 <emphasis>
340                         Default value is <quote>null</quote> - don't add AVP.
341                 </emphasis>
342                 </para>
343                 <example>
344                 <title>Set the <quote>grp_avp</quote> parameter</title>
345  <programlisting format="linespecific">
346  ...
347  modparam("dispatcher", "grp_avp", "$avp(dsgrp)")
348  ...
349  </programlisting>
350                 </example>
351         </section>
352         <section id="dispatcher.p.cnt_avp">
353                 <title><varname>cnt_avp</varname> (str)</title>
354                 <para>
355                 The name of the avp storing the number of destination addresses kept in
356                 dst_avp AVPs.
357                 </para>
358                 <note>
359                 <para>
360                 You must set this parameter if you want to do load balancing fail over.
361                 </para>
362                 </note>
363                 <para>
364                 <emphasis>
365                         Default value is <quote>null</quote> - don't add AVP.
366                 </emphasis>
367                 </para>
368                 <example>
369                 <title>Set the <quote>cnt_avp</quote> parameter</title>
370  <programlisting format="linespecific">
371  ...
372  modparam("dispatcher", "cnt_avp", "$avp(dscnt)")
373  ...
374  </programlisting>
375                 </example>
376         </section>
377         <section id="dispatcher.p.dstid_avp">
378                 <title><varname>dstid_avp</varname> (str)</title>
379                 <para>
380                 The name of the avp storing the destination unique ID used for
381                 call load based dispatching.
382                 </para>
383                 <note>
384                 <para>
385                 You must set this parameter if you want to do load balancing on
386                 call load (alg 10).
387                 </para>
388                 </note>
389                 <para>
390                 <emphasis>
391                         Default value is <quote>null</quote> - don't add AVP.
392                 </emphasis>
393                 </para>
394                 <example>
395                 <title>Set the <quote>dstid_avp</quote> parameter</title>
396  <programlisting format="linespecific">
397  ...
398  modparam("dispatcher", "dstid_avp", "$avp(dsdstid)")
399  ...
400  </programlisting>
401                 </example>
402         </section>
403         <section id="dispatcher.p.attrs_avp">
404                 <title><varname>attrs_avp</varname> (str)</title>
405                 <para>
406                 The name of the avp storing destination's attributes value.
407                 </para>
408                 <note>
409                 </note>
410                 <para>
411                 <emphasis>
412                         Default value is <quote>null</quote> - don't add AVP.
413                 </emphasis>
414                 </para>
415                 <example>
416                 <title>Set the <quote>attrs_avp</quote> parameter</title>
417  <programlisting format="linespecific">
418  ...
419  modparam("dispatcher", "attrs_avp", "$avp(dsattrs)")
420  ...
421  </programlisting>
422                 </example>
423         </section>
424         <section id="dispatcher.p.sock_avp">
425                 <title><varname>sock_avp</varname> (str)</title>
426                 <para>
427                         The name of the avp which will hold the list with the sockets associated to the addresses stored in dst_avp avp.
428                 </para>
429                 <note>
430                 <para>
431                         If you want to do load balancing fail over, you have to set this parameter to use the correct socket for each gateway.
432                 </para>
433                 </note>
434                 <para>
435                 <emphasis>
436                         Default value is <quote>null</quote> - don't add AVPs.
437                 </emphasis>
438                 </para>
439                 <example>
440                 <title>Set the <quote>sock_avp</quote> parameter</title>
441  <programlisting format="linespecific">
442  ...
443  modparam("dispatcher", "sock_avp", "$avp(dssocket)")
444  ...
445  </programlisting>
446                 </example>
447         </section>
448         <section id="dispatcher.p.hash_pvar">
449                 <title><varname>hash_pvar</varname> (str)</title>
450                 <para>
451                 String with PVs used for the hashing algorithm 7.
452                 </para>
453                 <note>
454                 <para>
455                 You must set this parameter if you want do hashing over custom message
456                 parts.
457                 </para>
458                 </note>
459                 <para>
460                 <emphasis>
461                         Default value is <quote>null</quote> - disabled.
462                 </emphasis>
463                 </para>
464                 <example>
465                 <title>Use $avp(i:273) for hashing:</title>
466  <programlisting format="linespecific">
467  ...
468  modparam("dispatcher", "hash_pvar", "$avp(i:273)")
469  ...
470  </programlisting>
471                 </example>
472                 <example>
473                 <title>Use combination of PVs for hashing:</title>
474  <programlisting format="linespecific">
475  ...
476  modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
477  ...
478  </programlisting>
479                 </example>
480         </section>
481         <section id="dispatcher.p.setid_pvname">
482                 <title><varname>setid_pvname</varname> (str)</title>
483                 <para>
484                 The name of the PV where to store the set ID (group ID) when calling
485                 ds_is_from_list() with no parameter.
486                 </para>
487                 <para>
488                 <emphasis>
489                         Default value is <quote>null</quote> - don't set PV.
490                 </emphasis>
491                 </para>
492                 <example>
493                 <title>Set the <quote>setid_pvname</quote> parameter</title>
494  <programlisting format="linespecific">
495  ...
496  modparam("dispatcher", "setid_pvname", "$var(setid)")
497  ...
498  </programlisting>
499                 </example>
500         </section>
501         <section id="dispatcher.p.attrs_pvname">
502                 <title><varname>attrs_pvname</varname> (str)</title>
503                 <para>
504                 The name of the PV where to store the attributes of matching address
505                 when calling ds_is_from_list().
506                 </para>
507                 <para>
508                 <emphasis>
509                         Default value is <quote>null</quote> - don't set PV.
510                 </emphasis>
511                 </para>
512                 <example>
513                 <title>Set the <quote>attrs_pvname</quote> parameter</title>
514  <programlisting format="linespecific">
515  ...
516  modparam("dispatcher", "attrs_pvname", "$var(attrs)")
517  ...
518  </programlisting>
519                 </example>
520         </section>
521         <section id="dispatcher.p.ds_ping_method">
522                 <title><varname>ds_ping_method</varname> (string)</title>
523                 <para>
524                 With this method you can define, with which method you want to probe the gateways.
525                 Pinging gateways feature depends on ds_ping_interval parameter.
526                 </para>
527                 <para>
528                 <emphasis>
529                         Default value is <quote>OPTIONS</quote>.
530                 </emphasis>
531                 </para>
532                 <example>
533                 <title>Set the <quote>ds_ping_method</quote> parameter</title>
534  <programlisting format="linespecific">
535  ...
536  modparam("dispatcher", "ds_ping_method", "INFO")
537  ...
538  </programlisting>
539                 </example>
540         </section>
541         <section id="dispatcher.p.ds_ping_from">
542                 <title><varname>ds_ping_from</varname> (string)</title>
543                 <para>
544                 With this Method you can define the "From:"-Line for the request, sent to the failed gateways.
545                 This method is only available, if compiled with the probing of failed gateways enabled.
546                 </para>
547                 <para>
548                 <emphasis>
549                         Default value is <quote>sip:dispatcher@localhost</quote>.
550                 </emphasis>
551                 </para>
552                 <example>
553                 <title>Set the <quote>ds_ping_from</quote> parameter</title>
554  <programlisting format="linespecific">
555  ...
556  modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
557  ...
558  </programlisting>
559                 </example>
560         </section>
561
562         <section id="dispatcher.p.ds_ping_interval">
563                 <title><varname>ds_ping_interval</varname> (int)</title>
564                 <para>
565                 With this parameter you can define the interval for sending a request
566                 to a gateway marked as inactive upon a failed request routing to it.
567                 This parameter is only used, when the TM-Module is loaded.
568                 If set to <quote>0</quote>, the pinging of inactive gateway is disabled.
569                 </para>
570                 <para>
571                 <emphasis>
572                         Default value is <quote>0</quote>.
573                 </emphasis>
574                 </para>
575                 <example>
576                 <title>Set the <quote>ds_ping_interval</quote> parameter</title>
577  <programlisting format="linespecific">
578  ...
579  modparam("dispatcher", "ds_ping_interval", 30)
580  ...
581  </programlisting>
582                 </example>
583         </section>
584
585         <section id="dispatcher.p.ds_probing_threshold">
586                 <title><varname>ds_probing_threshold</varname> (int)</title>
587                 <para>
588                 If you want to set a gateway into inactive mode, there can be
589                 a specific number of failed requests until it will change from "active"
590                 to "inactive". It is using the state "trying", that allows selection
591                 of gateway but indicates there was a failure previously with the
592                 gateway. The number of attempts can be set with this parameter.
593                 This parameter can be modified via ser config framework.
594                 </para>
595                 <para>
596                 <emphasis>
597                 Default value is <quote>1</quote> (set inactive with first failure).
598                 </emphasis>
599                 </para>
600                 <example>
601                 <title>Set the <quote>ds_probing_threshold</quote> parameter</title>
602  <programlisting format="linespecific">
603  ...
604  modparam("dispatcher", "ds_probing_threshold", 10)
605  ...
606  </programlisting>
607                 </example>
608         </section>
609         <section id="dispatcher.p.ds_inactive_threshold">
610                 <title><varname>ds_inactive_threshold</varname> (int)</title>
611                 <para>
612                 If you want to set a gateway into active mode (after being inactive), there can be
613                 a specific number of successful requests until it will change from "inactive"
614                 to "active". The number of attempts can be set with this parameter.
615                 This parameter can be modified via ser config framework.
616                 </para>
617                 <para>
618                 <emphasis>
619                 Default value is <quote>1</quote> (set active with first success).
620                 </emphasis>
621                 </para>
622                 <example>
623                 <title>Set the <quote>ds_inactive_threshold</quote> parameter</title>
624  <programlisting format="linespecific">
625  ...
626  modparam("dispatcher", "ds_inactive_threshold", 10)
627  ...
628  </programlisting>
629                 </example>
630         </section>
631         <section id="dispatcher.p.ds_ping_reply_codes">
632                 <title><varname>ds_ping_reply_codes</varname> (string)</title>
633                 <para>
634                 This parameter defines the valid response codes, which are accepted as a valid reply to the PING-Method.
635                 It is a list separated by colons, whery you may define either a single code (e.g. "code=202" would accept 202 as an additional, valid response) or a class of responses, you want to accept (e.g. "class=2" would accept everything from 200 to 299 as valid response).
636                 This parameter can be modified via ser config framework.
637                 </para>
638                 <para>
639                         Please note that the response codes the module accepts as valid reply to the
640                         PING-Method are not only the ones generated from the remote servers, but also those
641                         that are generated locally. E.g.: setting code=408 or class=400 will never set
642                         a backend down even if it is, because internally the Kamailio transaction layer
643                         generates a 408 in the case of no response from the remote server, and this
644                         internal code 408 is accepted as valid value.
645                 </para>
646                 <para>
647                 <emphasis>
648                         Default value is <quote></quote> (only 200 OK is accepted).
649                 </emphasis>
650                 </para>
651                 <example>
652                 <title>Set the <quote>ds_ping_reply_codes</quote> parameter</title>
653  <programlisting format="linespecific">
654  ...
655  modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=3")
656  ...
657  </programlisting>
658                 </example>
659         </section>
660         <section id="dispatcher.p.ds_probing_mode">
661                 <title><varname>ds_probing_mode</varname> (int)</title>
662                 <para>
663                 Controls what gateways are tested to see if they are reachable.
664                 </para>
665
666                 <itemizedlist>
667                 <listitem>
668                         <para>Value 0: If set to 0, only the gateways with state PROBING are tested.
669                               After a gateway is probed, the PROBING state is cleared in this mode.</para>
670                 </listitem>
671                 <listitem>
672                         <para>Value 1: If set to 1, all gateways are tested.  If set to 1 and there is a failure of keepalive
673                                 to an active gateway, then it is set to TRYING state.</para>
674                 </listitem>
675                 <listitem>
676                         <para>Value 2: if set to 2, only gateways in inactive state with probing mode set are tested.</para>
677                 </listitem>
678                 <listitem>
679                         <para>Value 3: If set to 3, any gateway with state PROBING is continually probed
680                                 without modifying/removing the PROBING state.  This allows selected gateways
681                                 to be probed continually, regardless of state changes.</para>
682                 </listitem>
683                 </itemizedlist>
684
685                 <para>
686                 <emphasis>
687                         Default value is <quote>0</quote>.
688                 </emphasis>
689                 </para>
690                 <example>
691                 <title>Set the <quote>ds_probing_mode</quote> parameter</title>
692  <programlisting format="linespecific">
693  ...
694  modparam("dispatcher", "ds_probing_mode", 1)
695  ...
696  </programlisting>
697                 </example>
698         </section>
699
700         <section id="dispatcher.p.ds_hash_size">
701                 <title><varname>ds_hash_size</varname> (int)</title>
702                 <para>
703                 The value to be used as power of two to set the number of slots
704                 to hash table storing data for call load dispatching (e.g., value
705                 8 will create a hash table with 256 slots).
706                 It must be greater than 0 to enable call load dispatching feature
707                 (alg 10).
708                 </para>
709                 <para>
710                 <emphasis>
711                         Default value is <quote>0</quote>.
712                 </emphasis>
713                 </para>
714                 <example>
715                 <title>Set the <quote>ds_hash_size</quote> parameter</title>
716  <programlisting format="linespecific">
717  ...
718  modparam("dispatcher", "ds_hash_size", 9)
719  ...
720  </programlisting>
721                 </example>
722         </section>
723         <section id="dispatcher.p.ds_hash_expire">
724                 <title><varname>ds_hash_expire</varname> (int)</title>
725                 <para>
726                 Expiration time in seconds to remove the load on a destination if no
727                 BYE was received meanwhile.
728                 </para>
729                 <para>
730                 <emphasis>
731                         Default value is <quote>7200</quote>.
732                 </emphasis>
733                 </para>
734                 <example>
735                 <title>Set the <quote>ds_hash_expire</quote> parameter</title>
736  <programlisting format="linespecific">
737  ...
738  modparam("dispatcher", "ds_hash_expire", 3600)
739  ...
740  </programlisting>
741                 </example>
742         </section>
743         <section id="dispatcher.p.ds_hash_initexpires">
744                 <title><varname>ds_hash_initexpire</varname> (int)</title>
745                 <para>
746                 Expiration time in seconds to remove the load on a destination if no
747                 200 for INVITE was received meanwhile and state updated with
748                 ds_load_update().
749                 </para>
750                 <para>
751                 <emphasis>
752                         Default value is <quote>7200</quote>.
753                 </emphasis>
754                 </para>
755                 <example>
756                 <title>Set the <quote>ds_hash_initexpire</quote> parameter</title>
757  <programlisting format="linespecific">
758  ...
759  modparam("dispatcher", "ds_hash_initexpire", 60)
760  ...
761  </programlisting>
762                 </example>
763         </section>
764         <section id="dispatcher.p.ds_hash_check_interval">
765                 <title><varname>ds_hash_check_interval</varname> (int)</title>
766                 <para>
767                 Time interval in seconds to scan internal hash table with call load
768                 dispatching data for expired items.
769                 </para>
770                 <para>
771                 <emphasis>
772                         Default value is <quote>30</quote>.
773                 </emphasis>
774                 </para>
775                 <example>
776                 <title>Set the <quote>ds_hash_check_interval</quote> parameter</title>
777  <programlisting format="linespecific">
778  ...
779  modparam("dispatcher", "ds_hash_check_interval", 60)
780  ...
781  </programlisting>
782                 </example>
783         </section>
784         <section id="dispatcher.p.outbound_proxy">
785                 <title><varname>outbound_proxy</varname> (str)</title>
786                 <para>
787                 SIP URI of outbound proxy to be used when sending pings.
788                 </para>
789                 <para>
790                 <emphasis>
791                         By default no outbound proxy is defined.
792                 </emphasis>
793                 </para>
794                 <example>
795                 <title>Set the <quote>outbound_proxy</quote> parameter</title>
796  <programlisting format="linespecific">
797  ...
798  modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
799  ...
800  </programlisting>
801                 </example>
802         </section>
803
804         <section id="dispatcher.p.ds_default_socket">
805                 <title><varname>ds_default_socket</varname> (str)</title>
806                 <para>
807                         Default socket to be used for sending pings and dispatching requests
808                         when a gateway has no send socket configured.
809                 </para>
810                 <para>
811                 <emphasis>
812                         By default no default socket is defined, the first configuration
813                         script <emphasis>listen</emphasis> directive is used.
814                 </emphasis>
815                 </para>
816                 <example>
817                 <title>Set the <quote>ds_default_socket</quote> parameter</title>
818  <programlisting format="linespecific">
819  ...
820  modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
821  ...
822  </programlisting>
823                 </example>
824         </section>
825
826         <section id="dispatcher.p.ds_timer_mode">
827                 <title><varname>ds_timer_mode</varname> (int)</title>
828                 <para>
829                         Specify the timer process to be used by the module for
830                         keepalives and active dialogs tracking.
831                 </para>
832                 <para>
833                         It can be set to:
834                 </para>
835                 <itemizedlist>
836                 <listitem>
837                         <para>0 - use main timer process.</para>
838                 </listitem>
839                 <listitem>
840                         <para>1 - use secondary timer process.</para>
841                 </listitem>
842                 </itemizedlist>
843
844                 <para>
845                         On a server with a lot of traffic, using secondary
846                         timer can help with performances, because the main timer
847                         can be overloaded by taking care of transactions retransmissions
848                         and expirations of items in memory.
849                 </para>
850                 <para>
851                 <emphasis>
852                         Default value is <quote>0</quote>.
853                 </emphasis>
854                 </para>
855                 <example>
856                 <title>Set the <quote>ds_timer_mode</quote> parameter</title>
857  <programlisting format="linespecific">
858  ...
859  modparam("dispatcher", "ds_timer_mode", 1)
860  ...
861  </programlisting>
862                 </example>
863         </section>
864
865         </section>
866
867         <section>
868         <title>Functions</title>
869         <section id="dispatcher.f.ds_select_dst">
870                 <title>
871                 <function moreinfo="none">ds_select_dst(set, alg[, limit])</function>
872                 </title>
873                 <para>
874                 The method selects a destination from addresses set. It returns true if
875                 a new destination is set. The selected address is set to dst_uri field
876                 (aka the outbound proxy address or the $du variable), not being visible
877                 in the SIP request.
878                 </para>
879                 <para>
880                 If the bit 2 in 'flags' parameter is set, the rest of the addresses from
881                 the destination set is stored in AVP list (limited with an optional 'limit'
882                 parameter). You can use 'ds_next_dst()' to use next address in order to
883                 achieve serial forking to all possible destinations.
884                 </para>
885                 <para>Meaning of the parameters is as follows:</para>
886                 <itemizedlist>
887                 <listitem>
888                         <para>
889                         <emphasis>set</emphasis> - the id of the set from where to pick
890                         up destination address. It is the first column in destination
891                         list file. The parameter can be an integer or a variable holding
892                         an integer.
893                         </para>
894                 </listitem>
895                 <listitem>
896                         <para>
897                         <emphasis>alg</emphasis> - the algorithm used to select the
898                         destination address. The parameter can be an integer or a
899                         variable holding an interger.
900                         </para>
901                         <itemizedlist>
902                         <listitem>
903                                 <para>
904                                 <quote>0</quote> - hash over callid
905                                 </para>
906                         </listitem>
907                         <listitem>
908                                 <para>
909                                 <quote>1</quote> - hash over from URI.
910                                 </para>
911                         </listitem>
912                         <listitem>
913                                 <para>
914                                 <quote>2</quote> - hash over to URI.
915                                 </para>
916                         </listitem>
917                         <listitem>
918                                 <para>
919                                 <quote>3</quote> - hash over request-URI.
920                                 </para>
921                         </listitem>
922                         <listitem>
923                                 <para>
924                                 <quote>4</quote> - round-robin (next destination).
925                                 </para>
926                         </listitem>
927                         <listitem>
928                                 <para>
929                                 <quote>5</quote> - hash over authorization-username
930                                 (Proxy-Authorization or "normal" authorization). If no
931                                 username is found, round robin is used.
932                                 </para>
933                         </listitem>
934                         <listitem>
935                                 <para>
936                                 <quote>6</quote> - random destination (using rand()).
937                                 </para>
938                         </listitem>
939                         <listitem>
940                                 <para>
941                                 <quote>7</quote> - hash over the content of PVs string.
942                                 Note: This works only when the parameter hash_pvar is set.
943                                 </para>
944                         </listitem>
945                         <listitem>
946                                 <para>
947                                 <quote>8</quote> - select destination sorted by priority
948                                 attribute value (serial forking ordered by priority).
949                                 </para>
950                         </listitem>
951                         <listitem>
952                                 <para>
953                                 <quote>9</quote> - use weight based load distribution. You
954                                 have to set the attribute 'weight' per each address in
955                                 destination set.
956                                 </para>
957                         </listitem>
958                         <listitem>
959                                 <para>
960                                 <quote>10</quote> - use call load distribution. You have
961                                 to set the attribute 'duid' (as an unique string id)
962                                 per each address in destination set. Also, you must set
963                                 parameters 'dstid_avp' and 'ds_hash_size'.
964                                 </para>
965                                 <para>
966                                 The algorithm can be used even with stateless proxy mode,
967                                 there is no SIP dialog tracking depending on other modules,
968                                 just an internal lightweight call tracking by Call-Id, thus
969                                 is fast and suitable even for embedded systems.
970                                 </para>
971                                 <para>
972                                 The first destination selected by this algorithm is the one
973                                 that has the least number of calls associated. The rest of
974                                 the destination list is taken in order of the entries in set
975                                 - anyhow, until a re-route to next destination happens, the
976                                 load on each address can change.
977                                 </para>
978                                 <para>
979                                 This algorithm can be used only for dispatching INVITE
980                                 requests as it is the only SIP method creating a SIP call.
981                                 </para>
982                         </listitem>
983                         <listitem>
984                                 <para>
985                                 <quote>11</quote> - use relative weight based load distribution.
986                                 You have to set the attribute 'rweight' per each address in
987                                 destination set. Active host usage probability is
988                                 rweight/(SUM of all active host rweights in destination group).
989                                 </para>
990                                 <para>
991                                 The major difference from the weight distribution is the
992                                 probability recalculation according to rweight value in case of
993                                 host enabling/disabling
994                                 </para>
995                                 <para>
996                                 For example, 100 calls in 3-hosts group with rweight params 1/2/1
997                                 will be distributed as 25/50/25. After third host failing
998                                 distribution will be changed to 33/67/0.
999                                 </para>
1000                         </listitem>
1001                         <listitem>
1002                                 <para>
1003                                 <quote>X</quote> - if the algorithm is not implemented, the
1004                                 first entry in set is chosen.
1005                                 </para>
1006                         </listitem>
1007                         </itemizedlist>
1008                 </listitem>
1009                 <listitem>
1010                         <para>
1011                         <emphasis>limit</emphasis> - the maximum number of items to be
1012                         stored in AVP list for further failovers (the first selected
1013                         destination and default destination are the first to be put in
1014                         the list)
1015                         </para>
1016                 </listitem>
1017                 </itemizedlist>
1018                 <para>
1019                 If the bit 2 in 'flags' is set, the rest of the addresses from the
1020                 destination set is stored in AVP list. You can use 'ds_next_dst()' to
1021                 use next address to achieve serial forking to all possible
1022                 destinations.
1023                 </para>
1024                 <para>
1025                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1026                 </para>
1027                 <example>
1028                 <title><function>ds_select_dst</function> usage</title>
1029                 <programlisting format="linespecific">
1030 ...
1031 ds_select_dst("1", "0");
1032 ...
1033 $var(a) = 4;
1034 ds_select_dst("1", "$var(a)");
1035 ...
1036 ds_select_dst("1", "4", "3");
1037 ...
1038 </programlisting>
1039                 </example>
1040         </section>
1041         <section id="dispatcher.f.ds_select_domain">
1042                 <title>
1043                 <function moreinfo="none">ds_select_domain(set, alg[, limit])</function>
1044                 </title>
1045                 <para>
1046                 The method selects a destination from addresses set and rewrites the
1047                 host and port from R-URI. The parameters have same meaning as for
1048                 ds_select_dst().
1049                 </para>
1050                 <para>
1051                 If the bit 2 in 'flags' is set, the rest of the addresses from the
1052                 destination set is stored in AVP list (limited with an optional 'limit'
1053                 parameter). You can use 'ds_next_domain()' to use next address to
1054                 achieve serial forking to all possible destinations.
1055                 </para>
1056                 <para>
1057                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1058                 </para>
1059                 <example>
1060                 <title><function>ds_select_domain</function> usage</title>
1061                 <programlisting format="linespecific">
1062 ...
1063 $var(a) = 4;
1064 if(ds_select_domain("1", "$var(a)")) {
1065     t_relay();
1066     exit;
1067 }
1068 ...
1069 </programlisting>
1070                 </example>
1071         </section>
1072         <section id="dispatcher.f.ds_select">
1073                 <title>
1074                 <function moreinfo="none">ds_select(set, alg [, limit])</function>
1075                 </title>
1076                 <para>
1077                 The method selects a destination from addresses set and adds it
1078                 in the AVPs specified for this module. It is not updating R-URI
1079                 nor the destination URI. The parameters have same
1080                 meaning as for ds_select_dst().
1081                 </para>
1082                 <para>
1083                 If the bit 2 in 'flags' is set, the rest of the addresses from the
1084                 destination set is stored in AVP list (limited with an optional 'limit'
1085                 parameter). You can execute 'ds_next_domain()' or 'ds_next_dst()' to use
1086                 next address to achieve serial forking to all possible destinations.
1087                 </para>
1088                 <para>
1089                 This function can be used from ANY_ROUTE.
1090                 </para>
1091                 <example>
1092                 <title><function>ds_select</function> usage</title>
1093                 <programlisting format="linespecific">
1094 ...
1095 $var(a) = 4;
1096 if(ds_select("1", "$var(a)")) {
1097     ds_next_domain();
1098     t_relay();
1099     exit;
1100 }
1101 ...
1102 </programlisting>
1103                 </example>
1104         </section>
1105         <section>
1106                 <title>
1107                 <function moreinfo="none">ds_next_dst()</function>
1108                 </title>
1109                 <para>
1110                 Takes the next destination address from the AVPs with id 'dst_avp_id'
1111                 and sets the dst_uri (outbound proxy address).
1112                 </para>
1113                 <para>
1114                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1115                 </para>
1116         </section>
1117         <section>
1118                 <title>
1119                 <function moreinfo="none">ds_next_domain()</function>
1120                 </title>
1121                 <para>
1122                 Takes the next destination address from the AVPs with id 'dst_avp_id'
1123                 and sets the domain part of the request URI.
1124                 </para>
1125                 <para>
1126                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1127                 </para>
1128         </section>
1129         <section id="dispatcher.f.ds_mark_dst">
1130                 <title>
1131                 <function moreinfo="none">ds_mark_dst([state])</function>
1132                 </title>
1133                 <para>
1134                 Mark the last used address from destination set as inactive
1135                 ("i"/"I"), active ("a"/"A"), disabled ("d"/"D") or trying ("t"/"T").
1136                 Apart of disabled state, a destination can be set in probing mode by
1137                 adding ("p"/"P") flag. With this function, an automatic detection
1138                 of failed gateways can be implemented. When an address is marked as
1139                 inactive or disabled, it will be ignored by 'ds_select_dst' and
1140                 'ds_select_domain'.
1141                 </para>
1142                 <para>
1143                 The parameter state is optional, when it is missing, then
1144                 the destination will be marked inactive (i.e., same as 'i').
1145                 </para>
1146                 <para>Possible values for state parameter:</para>
1147                 <itemizedlist>
1148                 <listitem>
1149                         <para><emphasis>"a" or "A"</emphasis> - the last destination
1150                                 should be set to active and the error-counter should set to "0".
1151                         </para>
1152                 </listitem>
1153                 <listitem>
1154                         <para><emphasis>"i" or "I"</emphasis> - the last destination
1155                                 should be set to inactive and will be ignored in future
1156                                 requests.</para>
1157                 </listitem>
1158                 <listitem>
1159                         <para><emphasis>"t" or "T"</emphasis> - the last destination
1160                                 should be set to temporary trying state and failure counter
1161                                 is incremented. When the failure counter reaches the threshold,
1162                                 the destination will be set inactive.
1163                         </para>
1164                 </listitem>
1165                 <listitem>
1166                         <para><emphasis>"p" and "P"</emphasis> - this has to be used in
1167                                 addition to one of the previous flags - the last destination
1168                                 will be set to probing. This mean the destination will be pinged
1169                                 with SIP OPTIONS requests from time to time to detect if it is
1170                                 up or down.</para>
1171                 </listitem>
1172                 </itemizedlist>
1173                 <para>
1174                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1175                 </para>
1176                 <example>
1177                 <title><function>ds_mark_dst</function> usage</title>
1178                 <programlisting format="linespecific">
1179 ...
1180 failure_route[tryagain] {
1181 ...
1182    if(t_check_status("500"))
1183       ds_mark_dst("ip"); # set to inactive and probing
1184 ...
1185 }
1186 ...
1187 </programlisting>
1188                 </example>
1189         </section>
1190         <section  id="dispatcher.f.ds_list_exist">
1191                 <title>
1192                 <function moreinfo="none">ds_list_exist(groupid)</function>
1193                 </title>
1194                 <para>
1195                 Check if a specific group is defined in dispatcher list
1196                 or database.
1197                 </para>
1198                 <itemizedlist>
1199                 <listitem>
1200                         <para><emphasis>groupid</emphasis> - A group ID to check.
1201                         </para>
1202                 </listitem>
1203                 </itemizedlist>
1204                 <para>
1205                         This function can be used from ANY_ROUTE.
1206                 </para>
1207                 <example>
1208                 <title><function>ds_list_exist</function> usage</title>
1209                 <programlisting format="linespecific">
1210 ...
1211 if(ds_list_exist("10")) {
1212     ...
1213 }
1214 ...
1215 </programlisting>
1216         </example>
1217         </section>
1218         <section  id="dispatcher.f.ds_is_from_list">
1219                 <title>
1220                 <function moreinfo="none">ds_is_from_list([groupid [, mode [, uri] ] ])</function>
1221                 </title>
1222                 <para>
1223                 This function returns true, if there is a match of source address or uri
1224                 with an address in the given group of the dispatcher-list; otherwise false.
1225                 </para>
1226                 <para>Description of parameters:</para>
1227                 <itemizedlist>
1228                 <listitem>
1229                         <para><emphasis>groupid</emphasis> (optional) - if not given or its
1230                                 value is -1, the matching will be done over all addresses in
1231                                 all dispacher groups. Otherwise the matching will be done only
1232                                 against the addresses in the specific group id. The parameter
1233                                 can be an integer or a variable holding an integer value.
1234                         </para>
1235                 </listitem>
1236                 <listitem>
1237                         <para><emphasis>mode</emphasis> - (optional) - a bitmask to specify
1238                                 how the matching should be done. If is 0, all ip, port and
1239                                 proto are matched. If bit one is set, then port is ignored.
1240                                 If bit two is set, then protocol is ignored. The parameter
1241                                 can be an integer or a variable holding an integer value.
1242                                 It must be provided if the uri parameter is provided.
1243                         </para>
1244                 </listitem>
1245         <listitem>
1246             <para><emphasis>uri</emphasis> (optional) - if is empty or missing,
1247                 the matching is done against source IP, port and protocol.
1248                 Otherwise the value has to be a valid SIP URI, used to match
1249                 against addresses in the dispatcher list. Only IP, port and
1250                 protocol are matches, any additional parameters are ignored.
1251                 The parameter can be a static or dynamic (with variables)
1252                 string. The domain part of the URI can be an IP address or
1253                 a hostname.
1254             </para>
1255         </listitem>
1256                 </itemizedlist>
1257
1258                 <para>
1259                 Upon a match, the variable specified by 'setid_pvname' parameter will
1260                 be set to groupid of matching address and the attributes will be set in
1261                 variable specified by 'attrs_pvname'.
1262                 </para>
1263                 <para>
1264                 Note that for backward compatibility mode, when no parameter is given
1265                 or only groupid is given, the matching is done only for IP address
1266                 and port (protocol is ignored).
1267                 </para>
1268                 <para>
1269                         This function can be used from ANY_ROUTE.
1270                 </para>
1271                 <example>
1272                 <title><function>ds_is_from_list</function> usage</title>
1273                 <programlisting format="linespecific">
1274 ...
1275 if(ds_is_from_list()) {
1276     ...
1277 }
1278 if(ds_is_from_list("10")) {
1279     ...
1280 }
1281 if(ds_is_from_list("10", "3")) {
1282     ...
1283 }
1284 if(ds_is_from_list("10", "3", "sip:127.0.0.1:5080")) {
1285     ...
1286 }
1287 ...
1288 </programlisting>
1289                 </example>
1290         </section>
1291         <section id="dispatcher.f.ds_load_update">
1292                 <title>
1293                 <function moreinfo="none">ds_load_update()</function>
1294                 </title>
1295                 <para>
1296                 Updates the load state:
1297                 </para>
1298                 <itemizedlist>
1299                 <listitem>
1300                         <para>if it is a BYE or CANCEL - remove the load from
1301                         destination address used to forward the INVITE</para>
1302                 </listitem>
1303                 <listitem>
1304                         <para>if it is a reply to INVITE - set internal state
1305                                 to confirmed for call load structure when reply code is
1306                                 2xx.</para>
1307                 </listitem>
1308                 </itemizedlist>
1309                 <para>
1310                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
1311                         BRANCH_ROUTE and ONREPLY_ROUTE.
1312                 </para>
1313         </section>
1314         <section>
1315                 <title>
1316                 <function moreinfo="none">ds_load_unset()</function>
1317                 </title>
1318                 <para>
1319                 Remove the call load for the destination that routed the call.
1320                 </para>
1321                 <para>
1322                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
1323                         BRANCH_ROUTE and ONREPLY_ROUTE.
1324                 </para>
1325                 <example>
1326                 <title><function>ds_load_unset</function> usage</title>
1327                 <programlisting format="linespecific">
1328 ...
1329 route {
1330     ...
1331         if(is_method("BYE|CANCEL"))
1332         ds_load_update();
1333     ...
1334         ds_select_dst("1", "10");
1335     ...
1336 }
1337
1338 onreply_route {
1339     ...
1340     if(is_method("INVITE")
1341         {
1342         if(status=~"2[0-9][0-9]")
1343             ds_load_update();
1344         else if(status=~"[3-7][0-9][0-9]")
1345             ds_load_unset();
1346     }
1347     ...
1348 }
1349 ...
1350 </programlisting>
1351                 </example>
1352         </section>
1353         <section id="dispatcher.f.ds_reload">
1354                 <title>
1355                 <function moreinfo="none">ds_reload()</function>
1356                 </title>
1357                 <para>
1358                 Reloads the groups and included destinations.
1359                 </para>
1360                 <para>
1361                 Name: <emphasis>ds_reload</emphasis>
1362                 </para>
1363                 <para>Parameters: <emphasis>none</emphasis></para>
1364                 <para>
1365                 This function can be used from ANY_ROUTE.
1366                 </para>
1367         </section>
1368         </section>
1369
1370         <section>
1371         <title>MI Commands</title>
1372         <section id="dispatcher.mi.ds_set_state">
1373                 <title>
1374                 <function moreinfo="none">ds_set_state</function>
1375                 </title>
1376                 <para>
1377         Sets the status for a destination address (can be use to mark the destination
1378                 as active or inactive).
1379                 </para>
1380                 <para>
1381                 Name: <emphasis>ds_set_state</emphasis>
1382                 </para>
1383                 <para>Parameters:</para>
1384                 <itemizedlist>
1385                         <listitem><para>_state_ : state of the destination address</para>
1386                               <itemizedlist>
1387                          <listitem><para> <quote>a</quote>: active</para></listitem> 
1388                                  <listitem><para> <quote>i</quote>: inactive</para></listitem>
1389                                  <listitem><para> <quote>t</quote>: trying</para></listitem>
1390                                  <listitem><para> <quote>d</quote>: disabled</para></listitem>
1391                                   </itemizedlist>
1392                                   <para>The states <quote>a</quote>, <quote>i</quote> or
1393                                           <quote>t</quote> can be followed by <quote>p</quote>
1394                                           to set probing mode (e.g. 'ap', 'ip' or 'tp').</para>
1395                         </listitem>
1396
1397                         <listitem><para>_group_: destination group id</para></listitem>
1398
1399                         <listitem><para>_address_: address of the destination in the _group_</para></listitem>
1400                 </itemizedlist>
1401                 <para>
1402                 MI FIFO Command Format:
1403                 </para>
1404         <programlisting  format="linespecific">
1405                 :ds_set_state:_reply_fifo_file_
1406                 _state_
1407                 _group_
1408                 _address_
1409                 _empty_line_
1410                 </programlisting>
1411     </section>
1412         <section id="dispatcher.mi.ds_list">
1413                 <title>
1414                 <function moreinfo="none">ds_list</function>
1415                 </title>
1416                 <para>
1417                 It lists the groups and included destinations.
1418                 </para>
1419                 <para>
1420                 Name: <emphasis>ds_list</emphasis>
1421                 </para>
1422                 <para>Parameters: <emphasis>none</emphasis></para>
1423                 <para>
1424                 MI FIFO Command Format:
1425                 </para>
1426         <programlisting  format="linespecific">
1427                 :ds_list:_reply_fifo_file_
1428                 _empty_line_
1429                 </programlisting>
1430     </section>
1431         <section id="dispatcher.mi.ds_reload">
1432                 <title>
1433                 <function moreinfo="none">ds_reload</function>
1434                 </title>
1435                 <para>
1436                 It reloads the groups and included destinations. For algorithm 10
1437                 (call load distribution), old internal list of active calls is
1438                 destroyed (because it is bould to the previous list of gateways),
1439                 meaning that the module is starting to count active calls again
1440                 from 0.
1441                 </para>
1442                 <para>
1443                 Name: <emphasis>ds_reload</emphasis>
1444                 </para>
1445                 <para>Parameters: <emphasis>none</emphasis></para>
1446                 <para>
1447                 MI DATAGRAM Command Format:
1448                 </para>
1449         <programlisting  format="linespecific">
1450                 ":ds_reload:\n."
1451                 </programlisting>
1452     </section>
1453
1454     </section>
1455
1456         <section>
1457         <title>RPC Commands</title>
1458         <section id="dispatcher.rpc.set_state">
1459                 <title>
1460                 <function moreinfo="none">dispatcher.set_state</function>
1461                 </title>
1462                 <para>
1463                 Sets the state for a destination address (can be use to mark the destination
1464                 as active or inactive).
1465                 </para>
1466                 <para>
1467                 Name: <emphasis>dispatcher.set_state</emphasis>
1468                 </para>
1469                 <para>Parameters:</para>
1470                 <itemizedlist>
1471                         <listitem><para>_state_ : state of the destination address</para>
1472                               <itemizedlist>
1473                          <listitem><para> <quote>a</quote>: active</para></listitem>
1474                                  <listitem><para> <quote>i</quote>: inactive</para></listitem>
1475                                  <listitem><para> <quote>t</quote>: trying</para></listitem>
1476                                  <listitem><para> <quote>d</quote>: disabled</para></listitem>
1477                                   </itemizedlist>
1478                                   <para>The states <quote>a</quote>, <quote>i</quote> or
1479                                           <quote>t</quote> can be followed by <quote>p</quote>
1480                                           to set probing mode (e.g. 'ap', 'ip' or 'tp').</para>
1481                         </listitem>
1482
1483                         <listitem><para>_group_: destination group id</para></listitem>
1484
1485                         <listitem><para>_address_: address of the destination in the _group_</para></listitem>
1486                 </itemizedlist>
1487                 <para>
1488                 Example:
1489                 </para>
1490 <programlisting  format="linespecific">
1491 ...
1492 # prototype: &sercmd; dispatcher.set_state _state_ _group_ _address_
1493 &sercmd; dispatcher.set_state ip 2 sip:127.0.0.1:5080
1494 ...
1495 </programlisting>
1496     </section>
1497         <section id="dispatcher.rpc.list">
1498                 <title>
1499                 <function moreinfo="none">dispatcher.list</function>
1500                 </title>
1501                 <para>
1502                 Lists the groups and included destinations.
1503                 </para>
1504                 <para>
1505                 Name: <emphasis>dispatcher.list</emphasis>
1506                 </para>
1507                 <para>Parameters: <emphasis>none</emphasis></para>
1508                 <para>
1509                 Example:
1510                 </para>
1511         <programlisting  format="linespecific">
1512                 &sercmd; dispatcher.list
1513                 </programlisting>
1514     </section>
1515         <section id="dispatcher.f.reload">
1516                 <title>
1517                 <function moreinfo="none">dispatcher.reload</function>
1518                 </title>
1519                 <para>
1520                 Reloads the groups and included destinations. The command is
1521                 disabled for call load based dispatching (algorithm 10) since
1522                 removal of destinations may leave the list of active
1523                 calls with broken references.
1524                 </para>
1525                 <para>
1526                 Name: <emphasis>dispatcher.reload</emphasis>
1527                 </para>
1528                 <para>Parameters: <emphasis>none</emphasis></para>
1529                 <para>
1530                 Example
1531                 </para>
1532         <programlisting  format="linespecific">
1533                 &sercmd; dispatcher.reload
1534                 </programlisting>
1535     </section>
1536
1537         <section id="dispatcher.rpc.ping_active">
1538                 <title>
1539                 <function moreinfo="none">dispatcher.ping_active</function>
1540                 </title>
1541                 <para>
1542                 Sets the global state for sending keepalive requests to destinations.
1543                 </para>
1544                 <para>
1545                 Name: <emphasis>dispatcher.ping_active</emphasis>
1546                 </para>
1547                 <para>Parameters:</para>
1548                 <itemizedlist>
1549                         <listitem><para>_state_ : state of sending keepalives</para>
1550                             <itemizedlist>
1551                        <listitem><para> <quote>0</quote>: inactive (don't send)</para></listitem>
1552                                <listitem><para> <quote>1</quote>: active (send)</para></listitem>
1553                                 </itemizedlist>
1554                         </listitem>
1555                 </itemizedlist>
1556                 <para>
1557                         If the state parameter is missing, the current state is returned.
1558                         When state is changed, new and old values of the state are returned.
1559                         Default value for state is 1.
1560                 </para>
1561                 <para>
1562                 Example:
1563                 </para>
1564 <programlisting  format="linespecific">
1565 ...
1566 # prototype: &kamcmd; dispatcher.ping_active _state_
1567 &kamcmd; dispatcher.ping_active 0
1568 ...
1569 </programlisting>
1570     </section>
1571
1572    </section>
1573
1574         <section id="dispatcher.ex.install">
1575         <title>Installation and Running</title>
1576         <section>
1577                 <title>Destination List File</title>
1578                 <para>
1579                 Each destination point must be on one line. First token is the set
1580                 id (an integer value), followed by destination address
1581                 (s string value in SIP URI format).
1582                 </para>
1583                 <para>
1584                 Optionally, these fields can be followed by:
1585                 </para>
1586                 <itemizedlist>
1587                         <listitem>
1588                         <para>flags (listed by index - can be bitwise mask of values):
1589                         0 (value 1) - inactive destination; 1 (value 2) - temporary trying
1590                         destination (in the way to become inactive if it does not reply to
1591                         keepalives - there is a module parameter to set the threshold of
1592                         failures); 2 (value 4)  - admin disabled destination; 3 (value 8)
1593                         - probing destination (sending keep alives);</para>
1594                         </listitem>
1595                         <listitem>
1596                         <para>priority: sets the priority in destination list (based on it
1597                         is done the initial ordering inside the set)</para>
1598                         </listitem>
1599                         <listitem>
1600                         <para>attributes: extra fields in form of
1601                                 name1=value1;...;nameN=valueN.
1602                         </para>
1603                         </listitem>
1604                 </itemizedlist>
1605                 <section id="dispatcher.ex.attributes">
1606                         <title>Special Attributes</title>
1607                         <para>
1608                         There are some predefined names:
1609                         <itemizedlist>
1610                                 <listitem>
1611                                         'duid' - used for call load dispatching. It must be an
1612                                         unique value to identify a destination (gateway address).
1613                                         Practically the load within the group is associated with
1614                                         this value.
1615                                 </listitem>
1616                                 <listitem>
1617                                         'maxload' - used for call load dispatching. It must be
1618                                         a positive integer, defining the upper limit of active
1619                                         calls per destination. When the limit is reached, then
1620                                         the gateway is no longer selected for new calls until
1621                                         an exiting call via that gateway is terminated. If set
1622                                         to 0, then no active call limit is used.
1623                                 </listitem>
1624                                 <listitem>
1625                                         'weight' - used for weight based load distribution. It
1626                                         must be set to a positive integer value beteen 0 and
1627                                         100. The value represents the percent of calls to be
1628                                         sent to that gateways.
1629                                 </listitem>
1630                                 <listitem>
1631                                         'rweight' - used for relative weight based load
1632                                         distribution. It must be set to a positive integer value
1633                                         between 1 and 100 (otherwise host will be excluded from
1634                                         relative weight distribution type).
1635                                 </listitem>
1636                                 <listitem>
1637                                         'socket' - used to set the sending socket for the gateway.
1638                                         It is used for sending the SIP traffic as well as
1639                                         OPTIONS keepalives.
1640                                 </listitem>
1641                         </itemizedlist>
1642                 </para>
1643                 </section>
1644                 <section id="dispatcher.ex.fileforma">
1645                         <title>File Format</title>
1646                 <para>
1647                 Line format is:
1648                 </para>
1649                 <programlisting format="linespecific">
1650 ...
1651 setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
1652 ...
1653 </programlisting>
1654
1655                 <para>
1656                 Full line example:
1657                 </para>
1658                 <programlisting format="linespecific">
1659 ...
1660 1 sip:127.0.0.1:5080 0 0 duid=abc;socket=udp:192.168.0.125:5060;my=xyz
1661 ...
1662 </programlisting>
1663
1664                 <para>
1665                 For database, each element of a line resides in a different column.
1666                 Next is a dispatcher.list file example:
1667                 </para>
1668                 <example>
1669                 <title>dispatcher list file</title>
1670                 <programlisting format="linespecific">
1671 ...
1672 <xi:include href="dispatcher.list" parse="text"/>
1673 ...
1674 </programlisting>
1675                 </example>
1676                 </section>
1677                 </section>
1678
1679                 <section id="dispatcher.ex.config">
1680                 <title>&kamailio; config file</title>
1681                 <para>
1682                 Next listing shows a sample config for using the dispatcher module.
1683                 </para>
1684                 <example>
1685                 <title>&kamailio; config script - sample dispatcher usage</title>
1686                 <programlisting format="linespecific">
1687 ...
1688 <xi:include href="dispatcher.cfg" parse="text"/>
1689 ...
1690                 </programlisting>
1691                 </example>
1692         </section>
1693         </section>
1694
1695         <section id="dispatcher.ex.event_routes">
1696         <title>Event routes</title>
1697         <section>
1698                 <title>
1699                 <function moreinfo="none">dispatcher:dst-down</function>
1700                 </title>
1701                 <para>
1702                         When defined, the module calls event_route[dispatcher:ds-down]
1703                         when a destination goes down (becomes probing). A typical use
1704                         case is to update NMC equipment as to the status of a destination.
1705                 </para>
1706         <programlisting  format="linespecific">
1707 ...
1708 event_route[dispatcher:dst-down] {
1709     xlog("L_ERR", "Destination down: $rm $ru ($du)\n");
1710 }
1711 ...
1712                 </programlisting>
1713         </section>
1714         <section>
1715                 <title>
1716                 <function moreinfo="none">dispatcher:dst-up</function>
1717                 </title>
1718                 <para>
1719                         When defined, the module calls event_route[dispatcher:ds-up]
1720                         when a destination that was previously down (probing) comes up.
1721                         A typical use case is to update NMC equipment as to the status
1722                         of a destination.
1723                 </para>
1724         <programlisting  format="linespecific">
1725 ...
1726 event_route[dispatcher:dst-up] {
1727     xlog("L_ERR", "Destination up: $rm $ru\n");
1728 }
1729 ...
1730                 </programlisting>
1731     </section>
1732     </section>
1733
1734 </chapter>
1735