dispatcher(k): clarified notes about probing mode

modules_k/dispatcher/README

@@ -16,11 +16,11 @@ Carsten Bock
 
    ng-voice.com
 
-   Copyright © 2004 FhG FOKUS
+   Copyright © 2004 FhG FOKUS
 
-   Copyright © 2005 Voice Sistem
+   Copyright © 2005 Voice Sistem
 
-   Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
+   Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
      __________________________________________________________________
 
    Table of Contents
@@ -69,12 +69,10 @@ Carsten Bock
               4.2. ds_select_domain(set, alg)
               4.3. ds_next_dst()
               4.4. ds_next_domain()
-              4.5. ds_mark_dst()
-              4.6. ds_mark_dst("s")
-              4.7. ds_is_from_list()
-              4.8. ds_is_from_list("group")
-              4.9. ds_load_update()
-              4.10. ds_load_unset()
+              4.5. ds_mark_dst([state])
+              4.6. ds_is_from_list([groupid])
+              4.7. ds_load_update()
+              4.8. ds_load_unset()
 
         5. MI Commands
 
@@ -102,38 +100,40 @@ Carsten Bock
 
    List of Examples
 
-   1.1. Set the “list_file� parameter
-   1.2. Set “db_url� parameter
-   1.3. Set “table_name� parameter
-   1.4. Set “setid_col� parameter
-   1.5. Set “destination_col� parameter
-   1.6. Set “flags_col� parameter
-   1.7. Set “priority_col� parameter
-   1.8. Set the “force_dst� parameter
-   1.9. Set the “flags� parameter
-   1.10. Set the “use_default� parameter
-   1.11. Set the “dst_avp� parameter
-   1.12. Set the “grp_avp� parameter
-   1.13. Set the “cnt_avp� parameter
-   1.14. Set the “dstid_avp� parameter
-   1.15. Set the “attrs_avp� parameter
+   1.1. Set the "list_file" parameter
+   1.2. Set "db_url" parameter
+   1.3. Set "table_name" parameter
+   1.4. Set "setid_col" parameter
+   1.5. Set "destination_col" parameter
+   1.6. Set "flags_col" parameter
+   1.7. Set "priority_col" parameter
+   1.8. Set the "force_dst" parameter
+   1.9. Set the "flags" parameter
+   1.10. Set the "use_default" parameter
+   1.11. Set the "dst_avp" parameter
+   1.12. Set the "grp_avp" parameter
+   1.13. Set the "cnt_avp" parameter
+   1.14. Set the "dstid_avp" parameter
+   1.15. Set the "attrs_avp" parameter
    1.16. Use $avp(i:273) for hashing:
    1.17. Use combination of PVs for hashing:
-   1.18. Set the “setid_pvar� parameter
-   1.19. Set the “ds_ping_method� parameter
-   1.20. Set the “ds_ping_from� parameter
-   1.21. Set the “ds_ping_interval� parameter
-   1.22. Set the “ds_probing_threshhold� parameter
-   1.23. Set the “ds_ping_reply_codes� parameter
-   1.24. Set the “ds_probing_mode� parameter
-   1.25. Set the “ds_hash_size� parameter
-   1.26. Set the “ds_hash_expire� parameter
-   1.27. Set the “ds_hash_initexpire� parameter
-   1.28. Set the “ds_hash_check_interval� parameter
+   1.18. Set the "setid_pvar" parameter
+   1.19. Set the "ds_ping_method" parameter
+   1.20. Set the "ds_ping_from" parameter
+   1.21. Set the "ds_ping_interval" parameter
+   1.22. Set the "ds_probing_threshhold" parameter
+   1.23. Set the "ds_ping_reply_codes" parameter
+   1.24. Set the "ds_probing_mode" parameter
+   1.25. Set the "ds_hash_size" parameter
+   1.26. Set the "ds_hash_expire" parameter
+   1.27. Set the "ds_hash_initexpire" parameter
+   1.28. Set the "ds_hash_check_interval" parameter
    1.29. ds_select_dst usage
-   1.30. ds_load_unset usage
-   1.31. dispatcher list file
-   1.32. Kamailio config script - sample dispatcher usage
+   1.30. ds_mark_dst usage
+   1.31. ds_mark_dst usage
+   1.32. ds_load_unset usage
+   1.33. dispatcher list file
+   1.34. Kamailio config script - sample dispatcher usage
 
 Chapter 1. Admin Guide
 
@@ -181,12 +181,10 @@ Chapter 1. Admin Guide
         4.2. ds_select_domain(set, alg)
         4.3. ds_next_dst()
         4.4. ds_next_domain()
-        4.5. ds_mark_dst()
-        4.6. ds_mark_dst("s")
-        4.7. ds_is_from_list()
-        4.8. ds_is_from_list("group")
-        4.9. ds_load_update()
-        4.10. ds_load_unset()
+        4.5. ds_mark_dst([state])
+        4.6. ds_is_from_list([groupid])
+        4.7. ds_load_update()
+        4.8. ds_load_unset()
 
    5. MI Commands
 
@@ -278,10 +276,10 @@ Chapter 1. Admin Guide
 
    Path to the file with destination sets.
 
-   Default value is “/etc/kamailio/dispatcher.list� or
-   “/usr/local/etc/kamailio/dispatcher.list�.
+   Default value is "/etc/kamailio/dispatcher.list" or
+   "/usr/local/etc/kamailio/dispatcher.list".
 
-   Example 1.1. Set the “list_file� parameter
+   Example 1.1. Set the "list_file" parameter
 ...
 modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
 ...
@@ -291,9 +289,9 @@ modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
    If you want to load the sets of gateways from the database you must set
    this parameter.
 
-   Default value is “NULL� (disable DB support).
+   Default value is "NULL" (disable DB support).
 
-   Example 1.2. Set “db_url� parameter
+   Example 1.2. Set "db_url" parameter
 ...
 modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database")
 ...
@@ -303,9 +301,9 @@ modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database")
    If you want to load the sets of gateways from the database you must set
    this parameter as the database name.
 
-   Default value is “dispatcher�.
+   Default value is "dispatcher".
 
-   Example 1.3. Set “table_name� parameter
+   Example 1.3. Set "table_name" parameter
 ...
 modparam("dispatcher", "table_name", "my_dispatcher")
 ...
@@ -314,9 +312,9 @@ modparam("dispatcher", "table_name", "my_dispatcher")
 
    The column's name in the database storing the gateway's group id.
 
-   Default value is “setid�.
+   Default value is "setid".
 
-   Example 1.4. Set “setid_col� parameter
+   Example 1.4. Set "setid_col" parameter
 ...
 modparam("dispatcher", "setid_col", "groupid")
 ...
@@ -325,9 +323,9 @@ modparam("dispatcher", "setid_col", "groupid")
 
    The column's name in the database storing the destination's sip uri.
 
-   Default value is “destination�.
+   Default value is "destination".
 
-   Example 1.5. Set “destination_col� parameter
+   Example 1.5. Set "destination_col" parameter
 ...
 modparam("dispatcher", "destination_col", "uri")
 ...
@@ -337,9 +335,9 @@ modparam("dispatcher", "destination_col", "uri")
    The column's name in the database storing the flags for destination
    uri.
 
-   Default value is “flags�.
+   Default value is "flags".
 
-   Example 1.6. Set “flags_col� parameter
+   Example 1.6. Set "flags_col" parameter
 ...
 modparam("dispatcher", "flags_col", "dstflags")
 ...
@@ -349,9 +347,9 @@ modparam("dispatcher", "flags_col", "dstflags")
    The column's name in the database storing the priority for destination
    uri.
 
-   Default value is “priority�.
+   Default value is "priority".
 
-   Example 1.7. Set “priority_col� parameter
+   Example 1.7. Set "priority_col" parameter
 ...
 modparam("dispatcher", "priority_col", "dstpriority")
 ...
@@ -362,9 +360,9 @@ modparam("dispatcher", "priority_col", "dstpriority")
    when that is already set. If set to 0, will return error when the
    destination address is already set.
 
-   Default value is “1�.
+   Default value is "1".
 
-   Example 1.8. Set the “force_dst� parameter
+   Example 1.8. Set the "force_dst" parameter
 ...
 modparam("dispatcher", "force_dst", 1)
 ...
@@ -383,9 +381,9 @@ modparam("dispatcher", "force_dst", 1)
    destination set in AVP, and use these AVPs to contact next address when
    the current-tried fails.
 
-   Default value is “0�.
+   Default value is "0".
 
-   Example 1.9. Set the “flags� parameter
+   Example 1.9. Set the "flags" parameter
  ...
  modparam("dispatcher", "flags", 3)
  ...
@@ -397,9 +395,9 @@ modparam("dispatcher", "force_dst", 1)
    wanting to send the call to an anouncement server saying: "the gateways
    are full, try later".
 
-   Default value is “0�.
+   Default value is "0".
 
-   Example 1.10. Set the “use_default� parameter
+   Example 1.10. Set the "use_default" parameter
  ...
  modparam("dispatcher", "use_default", 1)
  ...
@@ -417,9 +415,9 @@ Note
 
    You must set this parameter if you want to do load balancing fail over.
 
-   Default value is “null� - don't add AVPs.
+   Default value is "null" - don't add AVPs.
 
-   Example 1.11. Set the “dst_avp� parameter
+   Example 1.11. Set the "dst_avp" parameter
  ...
  modparam("dispatcher", "dst_avp", "$avp(dsdst)")
  ...
@@ -433,9 +431,9 @@ Note
 
    You must set this parameter if you want to do load balancing fail over.
 
-   Default value is “null� - don't add AVP.
+   Default value is "null" - don't add AVP.
 
-   Example 1.12. Set the “grp_avp� parameter
+   Example 1.12. Set the "grp_avp" parameter
  ...
  modparam("dispatcher", "grp_avp", "$avp(dsgrp)")
  ...
@@ -449,9 +447,9 @@ Note
 
    You must set this parameter if you want to do load balancing fail over.
 
-   Default value is “null� - don't add AVP.
+   Default value is "null" - don't add AVP.
 
-   Example 1.13. Set the “cnt_avp� parameter
+   Example 1.13. Set the "cnt_avp" parameter
  ...
  modparam("dispatcher", "cnt_avp", "$avp(dscnt)")
  ...
@@ -466,9 +464,9 @@ Note
    You must set this parameter if you want to do load balancing on call
    load (alg 10).
 
-   Default value is “null� - don't add AVP.
+   Default value is "null" - don't add AVP.
 
-   Example 1.14. Set the “dstid_avp� parameter
+   Example 1.14. Set the "dstid_avp" parameter
  ...
  modparam("dispatcher", "dstid_avp", "$avp(dsdstid)")
  ...
@@ -479,9 +477,9 @@ Note
 
 Note
 
-   Default value is “null� - don't add AVP.
+   Default value is "null" - don't add AVP.
 
-   Example 1.15. Set the “attrs_avp� parameter
+   Example 1.15. Set the "attrs_avp" parameter
  ...
  modparam("dispatcher", "attrs_avp", "$avp(dsattrs)")
  ...
@@ -495,7 +493,7 @@ Note
    You must set this parameter if you want do hashing over custom message
    parts.
 
-   Default value is “null� - disabled.
+   Default value is "null" - disabled.
 
    Example 1.16. Use $avp(i:273) for hashing:
  ...
@@ -512,9 +510,9 @@ Note
    The name of the PV where to store the set ID (group ID) when calling
    ds_is_from_list() with no parameter.
 
-   Default value is “null� - don't set PV.
+   Default value is "null" - don't set PV.
 
-   Example 1.18. Set the “setid_pvar� parameter
+   Example 1.18. Set the "setid_pvar" parameter
  ...
  modparam("dispatcher", "setid_pvar", "$var(setid)")
  ...
@@ -525,9 +523,9 @@ Note
    the gateways. Pinging gateways feature depends on ds_ping_interval
    parameter.
 
-   Default value is “OPTIONS�.
+   Default value is "OPTIONS".
 
-   Example 1.19. Set the “ds_ping_method� parameter
+   Example 1.19. Set the "ds_ping_method" parameter
  ...
  modparam("dispatcher", "ds_ping_method", "INFO")
  ...
@@ -538,9 +536,9 @@ Note
    to the failed gateways. This method is only available, if compiled with
    the probing of failed gateways enabled.
 
-   Default value is “sip:dispatcher@localhost�.
+   Default value is "sip:dispatcher@localhost".
 
-   Example 1.20. Set the “ds_ping_from� parameter
+   Example 1.20. Set the "ds_ping_from" parameter
  ...
  modparam("dispatcher", "ds_ping_from", "sip:[email protected]")
  ...
@@ -550,11 +548,11 @@ Note
    With this parameter you can define the interval for sending a request
    to a gateway marked as inactive upon a failed request routing to it.
    This parameter is only used, when the TM-Module is loaded. If set to
-   “0�, the pinging of inactive gateway is disabled.
+   "0", the pinging of inactive gateway is disabled.
 
-   Default value is “0�.
+   Default value is "0".
 
-   Example 1.21. Set the “ds_ping_interval� parameter
+   Example 1.21. Set the "ds_ping_interval" parameter
  ...
  modparam("dispatcher", "ds_ping_interval", 30)
  ...
@@ -566,9 +564,9 @@ Note
    probing. The number of attempts can be set with this parameter. This
    parameter can be modified via ser config framework.
 
-   Default value is “3�.
+   Default value is "3".
 
-   Example 1.22. Set the “ds_probing_threshhold� parameter
+   Example 1.22. Set the "ds_probing_threshhold" parameter
  ...
  modparam("dispatcher", "ds_probing_threshhold", 10)
  ...
@@ -583,9 +581,9 @@ Note
    valid response). This parameter can be modified via ser config
    framework.
 
-   Default value is “� (only 200 OK is accepted).
+   Default value is "" (only 200 OK is accepted).
 
-   Example 1.23. Set the “ds_ping_reply_codes� parameter
+   Example 1.23. Set the "ds_ping_reply_codes" parameter
  ...
  modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=
 3")
@@ -595,12 +593,12 @@ Note
 
    Controls what gateways are tested to see if they are reachable. If set
    to 0, only the gateways with state PROBING are tested, if set to 1, all
-   gateways are tested. If set to 1 and the response is 408 (timeout), an
-   active gateway is set to PROBING state.
+   gateways are tested. If set to 1 and the is failure to the above list,
+   an active gateway is set to PROBING state.
 
-   Default value is “0�.
+   Default value is "0".
 
-   Example 1.24. Set the “ds_probing_mode� parameter
+   Example 1.24. Set the "ds_probing_mode" parameter
  ...
  modparam("dispatcher", "ds_probing_mode", 1)
  ...
@@ -612,9 +610,9 @@ Note
    a hash table with 256 slots). It must be greater than 0 to enable call
    load dispatching feature (alg 10).
 
-   Default value is “0�.
+   Default value is "0".
 
-   Example 1.25. Set the “ds_hash_size� parameter
+   Example 1.25. Set the "ds_hash_size" parameter
  ...
  modparam("dispatcher", "ds_hash_size", 9)
  ...
@@ -624,9 +622,9 @@ Note
    Expiration time in seconds to remove the load on a destination if no
    BYE was received meanwhile.
 
-   Default value is “7200�.
+   Default value is "7200".
 
-   Example 1.26. Set the “ds_hash_expire� parameter
+   Example 1.26. Set the "ds_hash_expire" parameter
  ...
  modparam("dispatcher", "ds_hash_expire", 3600)
  ...
@@ -637,9 +635,9 @@ Note
    200 for INVITE was received meanwhile and state updated with
    ds_load_update().
 
-   Default value is “7200�.
+   Default value is "7200".
 
-   Example 1.27. Set the “ds_hash_initexpire� parameter
+   Example 1.27. Set the "ds_hash_initexpire" parameter
  ...
  modparam("dispatcher", "ds_hash_initexpire", 60)
  ...
@@ -649,9 +647,9 @@ Note
    Time interval in seconds to scan internal hash table with call load
    dispatching data for expired items.
 
-   Default value is “30�.
+   Default value is "30".
 
-   Example 1.28. Set the “ds_hash_check_interval� parameter
+   Example 1.28. Set the "ds_hash_check_interval" parameter
  ...
  modparam("dispatcher", "ds_hash_check_interval", 60)
  ...
@@ -662,14 +660,12 @@ Note
    4.2. ds_select_domain(set, alg)
    4.3. ds_next_dst()
    4.4. ds_next_domain()
-   4.5. ds_mark_dst()
-   4.6. ds_mark_dst("s")
-   4.7. ds_is_from_list()
-   4.8. ds_is_from_list("group")
-   4.9. ds_load_update()
-   4.10. ds_load_unset()
+   4.5. ds_mark_dst([state])
+   4.6. ds_is_from_list([groupid])
+   4.7. ds_load_update()
+   4.8. ds_load_unset()
 
-4.1.  ds_select_dst(set, alg)
+4.1. ds_select_dst(set, alg)
 
    The method selects a destination from addresses set.
 
@@ -679,21 +675,21 @@ Note
        be an integer or a variable holding an interger.
      * alg - the algorithm used to select the destination address. The
        parameter can be an integer or a variable holding an interger.
-          + “0� - hash over callid
-          + “1� - hash over from uri.
-          + “2� - hash over to uri.
-          + “3� - hash over request-uri.
-          + “4� - round-robin (next destination).
-          + “5� - hash over authorization-username (Proxy-Authorization or
+          + "0" - hash over callid
+          + "1" - hash over from uri.
+          + "2" - hash over to uri.
+          + "3" - hash over request-uri.
+          + "4" - round-robin (next destination).
+          + "5" - hash over authorization-username (Proxy-Authorization or
             "normal" authorization). If no username is found, round robin
             is used.
-          + “6� - random (using rand()).
-          + “7� - hash over the content of PVs string. Note: This works
+          + "6" - random (using rand()).
+          + "7" - hash over the content of PVs string. Note: This works
             only when the parameter hash_pvar is set.
-          + “8� - use first destination (good for failover).
-          + “9� - use weight based load distribution. You have to set the
+          + "8" - use first destination (good for failover).
+          + "9" - use weight based load distribution. You have to set the
             attribute 'weight' per each address in destination set.
-          + “10� - use call load distribution. You have to set the
+          + "10" - use call load distribution. You have to set the
             attribute 'duid' (as an unique string id) per each address in
             destination set. Also, you must set parameters 'dstid_avp' and
             'ds_hash_size'.
@@ -708,7 +704,7 @@ Note
             on each address can change.
             This algorithm can be used only for dispatching INVITE
             requests as it is the only SIP method creating a SIP call.
-          + “X� - if the algorithm is not implemented, the first entry in
+          + "X" - if the algorithm is not implemented, the first entry in
             set is chosen.
 
    If the bit 2 in 'flags' is set, the rest of the addresses from the
@@ -726,7 +722,7 @@ $var(a) = 4;
 ds_select_dst("1", "$var(a)");
 ...
 
-4.2.  ds_select_domain(set, alg)
+4.2. ds_select_domain(set, alg)
 
    The method selects a destination from addresses set and rewrites the
    host and port from R-URI. The parameters have same meaning as for
@@ -739,65 +735,73 @@ ds_select_dst("1", "$var(a)");
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-4.3.  ds_next_dst()
+4.3. ds_next_dst()
 
    Takes the next destination address from the AVPs with id 'dst_avp_id'
    and sets the dst_uri (outbound proxy address).
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-4.4.  ds_next_domain()
+4.4. ds_next_domain()
 
    Takes the next destination address from the AVPs with id 'dst_avp_id'
    and sets the domain part of the request uri.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-4.5.  ds_mark_dst()
-
-   Mark the last used address from destination set as inactive, in order
-   to be ingnored in the future. In this way it can be implemented an
-   automatic detection of failed gateways. When an address is marked as
-   inactive, it will be ignored by 'ds_select_dst' and 'ds_select_domain'.
-
-   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
-
-4.6.  ds_mark_dst("s")
+4.5. ds_mark_dst([state])
 
    Mark the last used address from destination set as inactive
    ("i"/"I"/"0"), active ("a"/"A"/"1") or probing ("p"/"P"/"2"). With this
    function, an automatic detection of failed gateways can be implemented.
-   When an address is marked as inactive or probing, it will be ignored by
+   When an address is marked as inactive, it will be ignored by
    'ds_select_dst' and 'ds_select_domain'.
 
-   possible parameters:
+   The parameter state is optional, when it is missing, then the
+   destination will be marked inactive (i.e., same as 'i').
+
+   Possible values for state parameter:
      * "i", "I" or "0" - the last destination should be set to inactive
        and will be ignored in future requests.
      * "a", "A" or "1" - the last destination should be set to active and
        the error-counter should set to "0".
-     * "p", "P" or "2" - the last destination will be set to probing.
-       Note: You will need to call this function "threshhold"-times,
-       before it will be actually set to probing.
+     * "p", "P" or "2" - the last destination will be set to probing. This
+       mean the destination will be pinged with SIP OPTIONS requests from
+       time to time to detect if it is up running or down. Note: You will
+       need to call this function "threshhold"-times, before it will be
+       actually set to probing.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-4.7.  ds_is_from_list()
-
-   This function returns true, if the current request comes from a host
-   from the dispatcher-list; otherwise false.
-
-   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
-   BRANCH_ROUTE and ONREPLY_ROUTE.
+   Example 1.30. ds_mark_dst usage
+...
+failure_route[tryagain] {
+...
+   if(t_check_status("500"))
+      ds_mark_dst("i");
+...
+}
+...
 
-4.8.  ds_is_from_list("group")
+4.6. ds_is_from_list([groupid])
 
    This function returns true, if the current request comes from a host in
    the given group of the dispatcher-list; otherwise false.
 
-   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
-   BRANCH_ROUTE and ONREPLY_ROUTE.
+   Parameter groupid is optional, when it is missing, then the matching
+   will be done against all addresses in all groups. Upon a match, the
+   'grp_avp' will be set to groupid of matching address.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.31. ds_mark_dst usage
+...
+if(ds_is_from_list("10")) {
+    ...
+}
+...
 
-4.9.  ds_load_update()
+4.7. ds_load_update()
 
    Updates the load state:
      * if it is a BYE or CANCEL - remove the load from destination address
@@ -808,14 +812,14 @@ ds_select_dst("1", "$var(a)");
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE and ONREPLY_ROUTE.
 
-4.10.  ds_load_unset()
+4.8. ds_load_unset()
 
    Remove the call load for the destination that routed the call.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE and ONREPLY_ROUTE.
 
-   Example 1.30. ds_load_unset usage
+   Example 1.32. ds_load_unset usage
 ...
 route {
     ...
@@ -845,7 +849,7 @@ onreply_route {
    5.2. ds_list
    5.3. ds_reload
 
-5.1.  ds_set_state
+5.1. ds_set_state
 
    Sets the status for a destination address (can be use to mark the
    destination as active or inactive).
@@ -854,10 +858,10 @@ onreply_route {
 
    Parameters:
      * _state_ : state of the destination address
-          + “a�: active
-          + “i�: inactive
-          + “d�: disabled
-       The states “a� or “i� can be followed by “p� to set probing mode
+          + "a": active
+          + "i": inactive
+          + "d": disabled
+       The states "a" or "i" can be followed by "p" to set probing mode
        (e.g. 'ap' or 'ip')
      * _group_: destination group id
      * _address_: address of the destination in the _group_
@@ -869,7 +873,7 @@ onreply_route {
                 _address_
                 _empty_line_
 
-5.2.  ds_list
+5.2. ds_list
 
    It lists the groups and included destinations.
 
@@ -881,7 +885,7 @@ onreply_route {
                 :ds_list:_reply_fifo_file_
                 _empty_line_
 
-5.3.  ds_reload
+5.3. ds_reload
 
    It reloads the groups and included destinations. The command is
    disabled for call load based dispatching (algorithm 10) since removal
@@ -901,7 +905,7 @@ onreply_route {
    6.2. dispatcher.list
    6.3. dispatcher.reload
 
-6.1.  dispatcher.set_state
+6.1. dispatcher.set_state
 
    Sets the state for a destination address (can be use to mark the
    destination as active or inactive).
@@ -910,10 +914,10 @@ onreply_route {
 
    Parameters:
      * _state_ : state of the destination address
-          + “a�: active
-          + “i�: inactive
-          + “d�: disabled
-       The states “a� or “i� can be followed by “p� to set probing mode
+          + "a": active
+          + "i": inactive
+          + "d": disabled
+       The states "a" or "i" can be followed by "p" to set probing mode
        (e.g. 'ap' or 'ip')
      * _group_: destination group id
      * _address_: address of the destination in the _group_
@@ -921,7 +925,7 @@ onreply_route {
    Example:
                 sercmd dispatcher.set_state _state_ _group_ _address_
 
-6.2.  dispatcher.list
+6.2. dispatcher.list
 
    It lists the groups and included destinations.
 
@@ -932,7 +936,7 @@ onreply_route {
    Example:
                 sercmd dispatcher.list
 
-6.3.  dispatcher.reload
+6.3. dispatcher.reload
 
    It reloads the groups and included destinations. The command is
    disabled for call load based dispatching (algorithm 10) since removal
@@ -979,7 +983,7 @@ setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
    For database, each element of a line resides in a different column.
    Next is a dispatcher.list file example:
 
-   Example 1.31. dispatcher list file
+   Example 1.33. dispatcher list file
 ...
 # $Id$
 # dispatcher destination sets
@@ -1004,7 +1008,7 @@ r,opt)
 
    Next picture displays a sample usage of dispatcher.
 
-   Example 1.32. Kamailio config script - sample dispatcher usage
+   Example 1.34. Kamailio config script - sample dispatcher usage
 ...
 # $Id$
 # sample config file for dispatcher module
@@ -1085,7 +1089,7 @@ failure_route[RTF_DISPATCH] {
    8.1. dispatcher:dst-down
    8.2. dispatcher:dst-up
 
-8.1.  dispatcher:dst-down
+8.1. dispatcher:dst-down
 
    When defined, the module calls event_route[dispatcher:ds-down] when a
    destination goes down (becomes probing). A typical use case is to
@@ -1096,7 +1100,7 @@ event_route[dispatcher:dst-down] {
 }
 ...
 
-8.2.  dispatcher:dst-up
+8.2. dispatcher:dst-up
 
    When defined, the module calls event_route[dispatcher:ds-up] when a
    destination that was previously down (probing) comes up. A typical use
@@ -1117,46 +1121,46 @@ Chapter 2. Frequently Asked Questions
 
    2.1.
 
-       Does dispatcher provide a fair distribution?
+   Does dispatcher provide a fair distribution?
 
-       There is no guarantee of that. You should do some measurements to
-       decide what distribution algorithm fits better in your environment.
+   There is no guarantee of that. You should do some measurements to
+   decide what distribution algorithm fits better in your environment.
 
    2.2.
 
-       Is dispatcher dialog stateful?
+   Is dispatcher dialog stateful?
 
-       No. Dispatcher is stateless, although some distribution algorithms are
-       designed to select same destination for subsequent requests of the same
-       dialog (e.g., hashing the call-id).
+   No. Dispatcher is stateless, although some distribution algorithms are
+   designed to select same destination for subsequent requests of the same
+   dialog (e.g., hashing the call-id).
 
    2.3.
 
-       Where can I find more about Kamailio?
+   Where can I find more about Kamailio?
 
-       Take a look at http://www.kamailio.org/.
+   Take a look at http://www.kamailio.org/.
 
    2.4.
 
-       Where can I post a question about this module?
+   Where can I post a question about this module?
 
-       First at all check if your question was already answered on one of our
-       mailing lists:
-         * User Mailing List -
-           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
-         * Developer Mailing List -
-           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
+   First at all check if your question was already answered on one of our
+   mailing lists:
+     * User Mailing List -
+       http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
+     * Developer Mailing List -
+       http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
 
-       E-mails regarding any stable version should be sent to
-       <[email protected]> and e-mail regarding development
-       versions or CVS snapshots should be send to
-       <[email protected]>.
+   E-mails regarding any stable version should be sent to
+   <[email protected]> and e-mail regarding development
+   versions or CVS snapshots should be send to
+   <[email protected]>.
 
-       If you want to keep the mail private, send it to
-       <[email protected]>.
+   If you want to keep the mail private, send it to
+   <[email protected]>.
 
    2.5.
 
-       How can I report a bug?
+   How can I report a bug?
 
-       Please follow the guidelines provided at: http://sip-router.org/tracker
+   Please follow the guidelines provided at: http://sip-router.org/tracker

modules_k/dispatcher/doc/dispatcher_admin.xml

@@ -872,31 +872,21 @@ ds_select_dst("1", "$var(a)");
  	</section>
   	<section>
  		<title>
- 		<function moreinfo="none">ds_mark_dst()</function>
- 		</title>
- 		<para>
- 		Mark the last used address from destination set as inactive, in order
-		to be ingnored in the future. In this way it can be implemented an
-		automatic detection of failed gateways. When an address is marked as
-		inactive, it will be ignored by 'ds_select_dst' and 'ds_select_domain'.
- 		</para>
-		<para>
-		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
-		</para>
- 	</section>
-  	<section>
- 		<title>
- 		<function moreinfo="none">ds_mark_dst("s")</function>
+ 		<function moreinfo="none">ds_mark_dst([state])</function>
  		</title>
  		<para>
 		Mark the last used address from destination set as inactive
 		("i"/"I"/"0"), active ("a"/"A"/"1") or probing ("p"/"P"/"2").
 		With this function, an automatic detection of failed gateways
 		can be implemented. When an address is marked as
-		inactive or probing, it will be ignored by 'ds_select_dst' and
+		inactive, it will be ignored by 'ds_select_dst' and
 		'ds_select_domain'.
  		</para>
-		<para>possible parameters:</para>
+ 		<para>
+		The parameter state is optional, when it is missing, then
+		the destination will be marked inactive (i.e., same as 'i').
+ 		</para>
+		<para>Possible values for state parameter:</para>
 		<itemizedlist>
 		<listitem>
 			<para><emphasis>"i", "I" or "0"</emphasis> - the last destination
@@ -909,7 +899,9 @@ ds_select_dst("1", "$var(a)");
 		</listitem>
 		<listitem>
 			<para><emphasis>"p", "P" or "2"</emphasis> - the last destination
-				will be set to probing. Note: You will need to call this
+				will be set to probing. This mean the destination will be pinged
+				with SIP OPTIONS requests from time to time to detect if it is
+				up running or down. Note: You will need to call this
 				function "threshhold"-times, before it will be actually set
 				to probing.</para>
 		</listitem>
@@ -917,32 +909,46 @@ ds_select_dst("1", "$var(a)");
 		<para>
 		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 		</para>
+		<example>
+		<title><function>ds_mark_dst</function> usage</title>
+		<programlisting format="linespecific">
+...
+failure_route[tryagain] {
+...
+   if(t_check_status("500"))
+      ds_mark_dst("i");
+...
+}
+...
+</programlisting>
+		</example>
  	</section>
   	<section>
  		<title>
- 		<function moreinfo="none">ds_is_from_list()</function>
- 		</title>
- 		<para>
-			This function returns true, if the current request comes from a
-			host from the dispatcher-list; otherwise false.
- 		</para>
-		<para>
-			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
-			BRANCH_ROUTE and ONREPLY_ROUTE.
-		</para>
- 	</section>
-  	<section>
- 		<title>
- 		<function moreinfo="none">ds_is_from_list("group")</function>
+ 		<function moreinfo="none">ds_is_from_list([groupid])</function>
  		</title>
  		<para>
 		This function returns true, if the current request comes from a host
 		in the given group of the dispatcher-list; otherwise false.
  		</para>
 		<para>
-			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
-			BRANCH_ROUTE and ONREPLY_ROUTE.
+		Parameter groupid is optional, when it is missing, then the matching
+		will be done against all addresses in all groups. Upon a match, the
+		'grp_avp' will be set to groupid of matching address.
+ 		</para>
+		<para>
+			This function can be used from ANY_ROUTE.
 		</para>
+		<example>
+		<title><function>ds_mark_dst</function> usage</title>
+		<programlisting format="linespecific">
+...
+if(ds_is_from_list("10")) {
+    ...
+}
+...
+</programlisting>
+		</example>
  	</section>
   	<section>
  		<title>