Merge pull request #297 from evolvetsi/master

dispatcher: add new probing_mode=3 to always probe flagged gateways

modules/dispatcher/README

@@ -28,15 +28,15 @@ Alessandro Arrichiello
 
    Hewlett Packard
 
-   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)
 
-   Copyright © 2014 Olle E. Johansson, Edvina AB
+   Copyright © 2014 Olle E. Johansson, Edvina AB
 
-   Copyright © 2015 Alessandro Arrichiello, Hewlett Packard
+   Copyright © 2015 Alessandro Arrichiello, Hewlett Packard
      __________________________________________________________________
 
    Table of Contents
@@ -126,39 +126,39 @@ Alessandro Arrichiello
 
    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.16. Set the "sock_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. Set the “sock_avp� parameter
    1.17. Use $avp(i:273) for hashing:
    1.18. Use combination of PVs for hashing:
-   1.19. Set the "setid_pvname" parameter
-   1.20. Set the "attrs_pvname" parameter
-   1.21. Set the "ds_ping_method" parameter
-   1.22. Set the "ds_ping_from" parameter
-   1.23. Set the "ds_ping_interval" parameter
-   1.24. Set the "ds_probing_threshold" parameter
-   1.25. Set the "ds_inactive_threshold" parameter
-   1.26. Set the "ds_ping_reply_codes" parameter
-   1.27. Set the "ds_probing_mode" parameter
-   1.28. Set the "ds_hash_size" parameter
-   1.29. Set the "ds_hash_expire" parameter
-   1.30. Set the "ds_hash_initexpire" parameter
-   1.31. Set the "ds_hash_check_interval" parameter
-   1.32. Set the "outbound_proxy" parameter
-   1.33. Set the "ds_default_socket" parameter
+   1.19. Set the “setid_pvname� parameter
+   1.20. Set the “attrs_pvname� parameter
+   1.21. Set the “ds_ping_method� parameter
+   1.22. Set the “ds_ping_from� parameter
+   1.23. Set the “ds_ping_interval� parameter
+   1.24. Set the “ds_probing_threshold� parameter
+   1.25. Set the “ds_inactive_threshold� parameter
+   1.26. Set the “ds_ping_reply_codes� parameter
+   1.27. Set the “ds_probing_mode� parameter
+   1.28. Set the “ds_hash_size� parameter
+   1.29. Set the “ds_hash_expire� parameter
+   1.30. Set the “ds_hash_initexpire� parameter
+   1.31. Set the “ds_hash_check_interval� parameter
+   1.32. Set the “outbound_proxy� parameter
+   1.33. Set the “ds_default_socket� parameter
    1.34. ds_select_dst usage
    1.35. ds_mark_dst usage
    1.36. ds_list_exist usage
@@ -324,10 +324,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")
 ...
@@ -337,9 +337,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")
 ...
@@ -349,9 +349,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")
 ...
@@ -360,9 +360,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")
 ...
@@ -371,9 +371,9 @@ modparam("dispatcher", "setid_col", "groupid")
 
    The column's name in the database storing the destination 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")
 ...
@@ -383,9 +383,9 @@ modparam("dispatcher", "destination_col", "uri")
    The column's name in the database storing the flags for the 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")
 ...
@@ -395,9 +395,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")
 ...
@@ -408,9 +408,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)
 ...
@@ -429,9 +429,9 @@ modparam("dispatcher", "force_dst", 1)
    destination set in the AVP, and use these AVPs to contact next address
    if the current-tried destination 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)
  ...
@@ -443,9 +443,9 @@ modparam("dispatcher", "force_dst", 1)
    useful when 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)
  ...
@@ -463,9 +463,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)")
  ...
@@ -479,9 +479,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)")
  ...
@@ -495,9 +495,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)")
  ...
@@ -512,9 +512,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)")
  ...
@@ -525,9 +525,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)")
  ...
@@ -542,9 +542,9 @@ Note
    If you want to do load balancing fail over, you have to set this
    parameter to use the correct socket for each gateway.
 
-   Default value is "null" - don't add AVPs.
+   Default value is “null� - don't add AVPs.
 
-   Example 1.16. Set the "sock_avp" parameter
+   Example 1.16. Set the “sock_avp� parameter
  ...
  modparam("dispatcher", "sock_avp", "$avp(dssocket)")
  ...
@@ -558,7 +558,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.17. Use $avp(i:273) for hashing:
  ...
@@ -575,9 +575,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.19. Set the "setid_pvname" parameter
+   Example 1.19. Set the “setid_pvname� parameter
  ...
  modparam("dispatcher", "setid_pvname", "$var(setid)")
  ...
@@ -587,9 +587,9 @@ Note
    The name of the PV where to store the attributes of matching address
    when calling ds_is_from_list().
 
-   Default value is "null" - don't set PV.
+   Default value is “null� - don't set PV.
 
-   Example 1.20. Set the "attrs_pvname" parameter
+   Example 1.20. Set the “attrs_pvname� parameter
  ...
  modparam("dispatcher", "attrs_pvname", "$var(attrs)")
  ...
@@ -600,9 +600,9 @@ Note
    the gateways. Pinging gateways feature depends on ds_ping_interval
    parameter.
 
-   Default value is "OPTIONS".
+   Default value is “OPTIONS�.
 
-   Example 1.21. Set the "ds_ping_method" parameter
+   Example 1.21. Set the “ds_ping_method� parameter
  ...
  modparam("dispatcher", "ds_ping_method", "INFO")
  ...
@@ -613,9 +613,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.22. Set the "ds_ping_from" parameter
+   Example 1.22. Set the “ds_ping_from� parameter
  ...
  modparam("dispatcher", "ds_ping_from", "sip:[email protected]")
  ...
@@ -625,11 +625,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.23. Set the "ds_ping_interval" parameter
+   Example 1.23. Set the “ds_ping_interval� parameter
  ...
  modparam("dispatcher", "ds_ping_interval", 30)
  ...
@@ -643,9 +643,9 @@ Note
    The number of attempts can be set with this parameter. This parameter
    can be modified via ser config framework.
 
-   Default value is "1" (set inactive with first failure).
+   Default value is “1� (set inactive with first failure).
 
-   Example 1.24. Set the "ds_probing_threshold" parameter
+   Example 1.24. Set the “ds_probing_threshold� parameter
  ...
  modparam("dispatcher", "ds_probing_threshold", 10)
  ...
@@ -658,9 +658,9 @@ Note
    with this parameter. This parameter can be modified via ser config
    framework.
 
-   Default value is "1" (set active with first success).
+   Default value is “1� (set active with first success).
 
-   Example 1.25. Set the "ds_inactive_threshold" parameter
+   Example 1.25. Set the “ds_inactive_threshold� parameter
  ...
  modparam("dispatcher", "ds_inactive_threshold", 10)
  ...
@@ -675,9 +675,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.26. Set the "ds_ping_reply_codes" parameter
+   Example 1.26. Set the “ds_ping_reply_codes� parameter
  ...
  modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=
 3")
@@ -685,15 +685,23 @@ Note
 
 3.26. ds_probing_mode (int)
 
-   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 2, only gateways in inactive state with
-   probing mode set are tested. If set to 1 and there is a failure of
-   keepalive to an active gateway, then it is set to TRYING state.
-
-   Default value is "0".
-
-   Example 1.27. Set the "ds_probing_mode" parameter
+   Controls what gateways are tested to see if they are reachable.
+     * Value 0: If set to 0, only the gateways with state PROBING are
+       tested. After a gateway is probed, the PROBING state is cleared in
+       this mode.
+     * Value 1: If set to 1, all gateways are tested. If set to 1 and
+       there is a failure of keepalive to an active gateway, then it is
+       set to TRYING state.
+     * Value 2: if set to 2, only gateways in inactive state with probing
+       mode set are tested.
+     * Value 3: If set to 3, any gateway with state PROBING is continually
+       probed without modifying/removing the PROBING state. This allows
+       selected gateways to be probed continually, regardless of state
+       changes.
+
+   Default value is “0�.
+
+   Example 1.27. Set the “ds_probing_mode� parameter
  ...
  modparam("dispatcher", "ds_probing_mode", 1)
  ...
@@ -705,9 +713,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.28. Set the "ds_hash_size" parameter
+   Example 1.28. Set the “ds_hash_size� parameter
  ...
  modparam("dispatcher", "ds_hash_size", 9)
  ...
@@ -717,9 +725,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.29. Set the "ds_hash_expire" parameter
+   Example 1.29. Set the “ds_hash_expire� parameter
  ...
  modparam("dispatcher", "ds_hash_expire", 3600)
  ...
@@ -730,9 +738,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.30. Set the "ds_hash_initexpire" parameter
+   Example 1.30. Set the “ds_hash_initexpire� parameter
  ...
  modparam("dispatcher", "ds_hash_initexpire", 60)
  ...
@@ -742,9 +750,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.31. Set the "ds_hash_check_interval" parameter
+   Example 1.31. Set the “ds_hash_check_interval� parameter
  ...
  modparam("dispatcher", "ds_hash_check_interval", 60)
  ...
@@ -755,7 +763,7 @@ Note
 
    By default no outbound proxy is defined.
 
-   Example 1.32. Set the "outbound_proxy" parameter
+   Example 1.32. Set the “outbound_proxy� parameter
  ...
  modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
  ...
@@ -768,7 +776,7 @@ Note
    By default no default socket is defined, the first configuration script
    listen directive is used.
 
-   Example 1.33. Set the "ds_default_socket" parameter
+   Example 1.33. Set the “ds_default_socket� parameter
  ...
  modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
  ...
@@ -785,7 +793,7 @@ Note
    4.8. ds_load_update()
    4.9. ds_load_unset()
 
-4.1. ds_select_dst(set, alg[, limit])
+4.1.  ds_select_dst(set, alg[, limit])
 
    The method selects a destination from addresses set. It returns true if
    a new destination is set. The selected address is set to dst_uri field
@@ -804,22 +812,22 @@ Note
        be an integer or a variable holding an integer.
      * 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 destination (using rand()).
-          + "7" - hash over the content of PVs string. Note: This works
+          + “6� - random destination (using rand()).
+          + “7� - hash over the content of PVs string. Note: This works
             only when the parameter hash_pvar is set.
-          + "8" - select destination sorted by priority attribute value
+          + “8� - select destination sorted by priority attribute value
             (serial forking ordered by priority).
-          + "9" - use weight based load distribution. You have to set the
+          + “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'.
@@ -834,7 +842,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.
-          + "11" - use relative weight based load distribution. You have
+          + “11� - use relative weight based load distribution. You have
             to set the attribute 'rweight' per each address in destination
             set. Active host usage probability is rweight/(SUM of all
             active host rweights in destination group).
@@ -844,7 +852,7 @@ Note
             For example, 100 calls in 3-hosts group with rweight params
             1/2/1 will be distributed as 25/50/25. After third host
             failing distribution will be changed to 33/67/0.
-          + "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.
      * limit - the maximum number of items to be stored in AVP list for
        further failovers (the first selected destination and default
@@ -867,7 +875,7 @@ ds_select_dst("1", "$var(a)");
 ds_select_dst("1", "4", "3");
 ...
 
-4.2. ds_select_domain(set, alg[, limit])
+4.2.  ds_select_domain(set, alg[, limit])
 
    The method selects a destination from addresses set and rewrites the
    host and port from R-URI. The parameters have same meaning as for
@@ -880,21 +888,21 @@ ds_select_dst("1", "4", "3");
 
    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([state])
+4.5.  ds_mark_dst([state])
 
    Mark the last used address from destination set as inactive ("i"/"I"),
    active ("a"/"A"), disabled ("d"/"D") or trying ("t"/"T"). Apart of
@@ -931,7 +939,7 @@ failure_route[tryagain] {
 }
 ...
 
-4.6. ds_list_exist(groupid)
+4.6.  ds_list_exist(groupid)
 
    Check if a specific group is defined in dispatcher list or database.
      * groupid - A group ID to check.
@@ -945,7 +953,7 @@ if(ds_list_exist("10")) {
 }
 ...
 
-4.7. ds_is_from_list([groupid [, mode [, uri] ] ])
+4.7.  ds_is_from_list([groupid [, mode [, uri] ] ])
 
    This function returns true, if there is a match of source address or
    uri with an address in the given group of the dispatcher-list;
@@ -997,7 +1005,7 @@ if(ds_is_from_list("10", "3", "sip:127.0.0.1:5080")) {
 }
 ...
 
-4.8. ds_load_update()
+4.8.  ds_load_update()
 
    Updates the load state:
      * if it is a BYE or CANCEL - remove the load from destination address
@@ -1008,7 +1016,7 @@ if(ds_is_from_list("10", "3", "sip:127.0.0.1:5080")) {
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE and ONREPLY_ROUTE.
 
-4.9. ds_load_unset()
+4.9.  ds_load_unset()
 
    Remove the call load for the destination that routed the call.
 
@@ -1045,7 +1053,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).
@@ -1054,11 +1062,11 @@ onreply_route {
 
    Parameters:
      * _state_ : state of the destination address
-          + "a": active
-          + "i": inactive
-          + "t": trying
-          + "d": disabled
-       The states "a", "i" or "t" can be followed by "p" to set probing
+          + “a�: active
+          + “i�: inactive
+          + “t�: trying
+          + “d�: disabled
+       The states “a�, “i� or “t� can be followed by “p� to set probing
        mode (e.g. 'ap', 'ip' or 'tp').
      * _group_: destination group id
      * _address_: address of the destination in the _group_
@@ -1070,7 +1078,7 @@ onreply_route {
                 _address_
                 _empty_line_
 
-5.2. ds_list
+5.2.  ds_list
 
    It lists the groups and included destinations.
 
@@ -1082,7 +1090,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. For algorithm 10 (call
    load distribution), old internal list of active calls is destroyed
@@ -1102,7 +1110,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).
@@ -1111,11 +1119,11 @@ onreply_route {
 
    Parameters:
      * _state_ : state of the destination address
-          + "a": active
-          + "i": inactive
-          + "t": trying
-          + "d": disabled
-       The states "a", "i" or "t" can be followed by "p" to set probing
+          + “a�: active
+          + “i�: inactive
+          + “t�: trying
+          + “d�: disabled
+       The states “a�, “i� or “t� can be followed by “p� to set probing
        mode (e.g. 'ap', 'ip' or 'tp').
      * _group_: destination group id
      * _address_: address of the destination in the _group_
@@ -1126,7 +1134,7 @@ onreply_route {
 kamcmd dispatcher.set_state ip 2 sip:127.0.0.1:5080
 ...
 
-6.2. dispatcher.list
+6.2.  dispatcher.list
 
    Lists the groups and included destinations.
 
@@ -1137,7 +1145,7 @@ kamcmd dispatcher.set_state ip 2 sip:127.0.0.1:5080
    Example:
                 kamcmd dispatcher.list
 
-6.3. dispatcher.reload
+6.3.  dispatcher.reload
 
    Reloads the groups and included destinations. The command is disabled
    for call load based dispatching (algorithm 10) since removal of
@@ -1528,7 +1536,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
@@ -1539,7 +1547,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

modules/dispatcher/dispatch.c

@@ -2753,8 +2753,10 @@ static void ds_options_callback( struct cell *t, int type,
 	{
 		/* Set the according entry back to "Active" */
 		state = 0;
-		if (ds_probing_mode==DS_PROBE_ALL)
+		if (ds_probing_mode==DS_PROBE_ALL || 
+                    (ds_probing_mode == DS_PROBE_ONLYFLAGGED && ds_get_state(group, &uri) & DS_PROBING_DST))
 			state |= DS_PROBING_DST;
+
 		/* Check if in the meantime someone disabled the target through RPC or MI */
 		if (!(ds_get_state(group, &uri) & DS_DISABLED_DST) && ds_update_state(fmsg, group, &uri, state) != 0)
 		{

modules/dispatcher/dispatch.h

@@ -48,6 +48,7 @@
 #define DS_PROBE_NONE		0
 #define DS_PROBE_ALL		1
 #define DS_PROBE_INACTIVE	2
+#define DS_PROBE_ONLYFLAGGED	3
 
 #define DS_MATCH_ALL		0
 #define DS_MATCH_NOPORT		1

modules/dispatcher/doc/dispatcher_admin.xml

@@ -652,12 +652,28 @@ modparam("dispatcher", "force_dst", 1)
  	<section id="dispatcher.p.ds_probing_mode">
  		<title><varname>ds_probing_mode</varname> (int)</title>
  		<para>
-		Controls what gateways are tested to see if they are reachable. If set
-		to 0, only the gateways with state PROBING are tested; if set to 1, all
-		gateways are tested; if set to 2, only gateways in inactive state with
-		probing mode set are tested. If set to 1 and there is a failure of keepalive
-		to an active gateway, then it is set to TRYING state.
- 		</para>
+		Controls what gateways are tested to see if they are reachable. 
+		</para>
+
+		<itemizedlist>
+		<listitem>
+			<para>Value 0: If set to 0, only the gateways with state PROBING are tested.
+                              After a gateway is probed, the PROBING state is cleared in this mode.</para>
+		</listitem>
+		<listitem>
+			<para>Value 1: If set to 1, all gateways are tested.  If set to 1 and there is a failure of keepalive
+		    		to an active gateway, then it is set to TRYING state.</para>
+		</listitem>
+		<listitem>
+			<para>Value 2: if set to 2, only gateways in inactive state with probing mode set are tested.</para>
+		</listitem>
+		<listitem>
+			<para>Value 3: If set to 3, any gateway with state PROBING is continually probed
+ 				without modifying/removing the PROBING state.  This allows selected gateways
+				to be probed continually, regardless of state changes.</para>
+		</listitem>
+		</itemizedlist>
+
  		<para>
  		<emphasis>
  			Default value is <quote>0</quote>.