diff --git a/modules/dispatcher/README b/modules/dispatcher/README index 23515d88c1a..a6cfe538fe1 100644 --- a/modules/dispatcher/README +++ b/modules/dispatcher/README @@ -22,13 +22,21 @@ Olle E. Johansson Edvina AB - Copyright © 2004 FhG FOKUS +Edited by + +Alessandro Arrichiello + + Hewlett Packard - Copyright © 2005 Voice Sistem + Copyright © 2004 FhG FOKUS - Copyright © 2010 Daniel-Constantin Mierla (asipto.com) + Copyright © 2005 Voice Sistem - Copyright © 2014 Olle E. Johansson, Edvina AB + Copyright © 2010 Daniel-Constantin Mierla (asipto.com) + + Copyright © 2014 Olle E. Johansson, Edvina AB + + Copyright © 2015 Alessandro Arrichiello, Hewlett Packard __________________________________________________________________ Table of Contents @@ -66,14 +74,15 @@ Olle E. Johansson 3.21. ds_ping_from (string) 3.22. ds_ping_interval (int) 3.23. ds_probing_threshold (int) - 3.24. ds_ping_reply_codes (string) - 3.25. ds_probing_mode (int) - 3.26. ds_hash_size (int) - 3.27. ds_hash_expire (int) - 3.28. ds_hash_initexpire (int) - 3.29. ds_hash_check_interval (int) - 3.30. outbound_proxy (str) - 3.31. ds_default_socket (str) + 3.24. ds_inactive_threshold (int) + 3.25. ds_ping_reply_codes (string) + 3.26. ds_probing_mode (int) + 3.27. ds_hash_size (int) + 3.28. ds_hash_expire (int) + 3.29. ds_hash_initexpire (int) + 3.30. ds_hash_check_interval (int) + 3.31. outbound_proxy (str) + 3.32. ds_default_socket (str) 4. Functions @@ -117,45 +126,46 @@ Olle E. Johansson 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_threshhold" parameter - 1.25. Set the "ds_ping_reply_codes" parameter - 1.26. Set the "ds_probing_mode" parameter - 1.27. Set the "ds_hash_size" parameter - 1.28. Set the "ds_hash_expire" parameter - 1.29. Set the "ds_hash_initexpire" parameter - 1.30. Set the "ds_hash_check_interval" parameter - 1.31. Set the "outbound_proxy" parameter - 1.32. Set the "ds_default_socket" parameter - 1.33. ds_select_dst usage - 1.34. ds_mark_dst usage - 1.35. ds_list_exist usage - 1.36. ds_mark_dst usage - 1.37. ds_load_unset usage - 1.38. dispatcher list file - 1.39. Kamailio config script - sample dispatcher usage + 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 + 1.37. ds_mark_dst usage + 1.38. ds_load_unset usage + 1.39. dispatcher list file + 1.40. Kamailio config script - sample dispatcher usage Chapter 1. Admin Guide @@ -192,14 +202,15 @@ Chapter 1. Admin Guide 3.21. ds_ping_from (string) 3.22. ds_ping_interval (int) 3.23. ds_probing_threshold (int) - 3.24. ds_ping_reply_codes (string) - 3.25. ds_probing_mode (int) - 3.26. ds_hash_size (int) - 3.27. ds_hash_expire (int) - 3.28. ds_hash_initexpire (int) - 3.29. ds_hash_check_interval (int) - 3.30. outbound_proxy (str) - 3.31. ds_default_socket (str) + 3.24. ds_inactive_threshold (int) + 3.25. ds_ping_reply_codes (string) + 3.26. ds_probing_mode (int) + 3.27. ds_hash_size (int) + 3.28. ds_hash_expire (int) + 3.29. ds_hash_initexpire (int) + 3.30. ds_hash_check_interval (int) + 3.31. outbound_proxy (str) + 3.32. ds_default_socket (str) 4. Functions @@ -298,23 +309,24 @@ Chapter 1. Admin Guide 3.21. ds_ping_from (string) 3.22. ds_ping_interval (int) 3.23. ds_probing_threshold (int) - 3.24. ds_ping_reply_codes (string) - 3.25. ds_probing_mode (int) - 3.26. ds_hash_size (int) - 3.27. ds_hash_expire (int) - 3.28. ds_hash_initexpire (int) - 3.29. ds_hash_check_interval (int) - 3.30. outbound_proxy (str) - 3.31. ds_default_socket (str) + 3.24. ds_inactive_threshold (int) + 3.25. ds_ping_reply_codes (string) + 3.26. ds_probing_mode (int) + 3.27. ds_hash_size (int) + 3.28. ds_hash_expire (int) + 3.29. ds_hash_initexpire (int) + 3.30. ds_hash_check_interval (int) + 3.31. outbound_proxy (str) + 3.32. ds_default_socket (str) 3.1. list_file (string) 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") ... @@ -324,9 +336,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") ... @@ -336,9 +348,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") ... @@ -347,9 +359,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") ... @@ -358,9 +370,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") ... @@ -370,9 +382,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") ... @@ -382,9 +394,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") ... @@ -395,9 +407,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) ... @@ -416,9 +428,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) ... @@ -430,9 +442,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) ... @@ -450,9 +462,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)") ... @@ -466,9 +478,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)") ... @@ -482,9 +494,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)") ... @@ -499,9 +511,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)") ... @@ -512,9 +524,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)") ... @@ -529,9 +541,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)") ... @@ -545,7 +557,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: ... @@ -562,9 +574,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)") ... @@ -574,9 +586,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)") ... @@ -587,9 +599,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") ... @@ -600,9 +612,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:proxy@sip.somehost.com") ... @@ -612,11 +624,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) ... @@ -630,14 +642,29 @@ 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 + ... + modparam("dispatcher", "ds_probing_threshold", 10) + ... + +3.24. ds_inactive_threshold (int) + + If you want to set a gateway into active mode (after being inactive), + there can be a specific number of successful requests until it will + change from "inactive" to "active". The number of attempts can be set + with this parameter. This parameter can be modified via ser config + framework. + + Default value is “1” (set active with first success). - Example 1.24. Set the "ds_probing_threshhold" parameter + Example 1.25. Set the “ds_inactive_threshold” parameter ... - modparam("dispatcher", "ds_probing_threshhold", 10) + modparam("dispatcher", "ds_inactive_threshold", 10) ... -3.24. ds_ping_reply_codes (string) +3.25. ds_ping_reply_codes (string) This parameter defines the valid response codes, which are accepted as a valid reply to the PING-Method. It is a list separated by colons, @@ -647,15 +674,15 @@ 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.25. 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") + modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class +=3") ... -3.25. ds_probing_mode (int) +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 @@ -663,76 +690,76 @@ Note 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". + Default value is “0”. - Example 1.26. Set the "ds_probing_mode" parameter + Example 1.27. Set the “ds_probing_mode” parameter ... modparam("dispatcher", "ds_probing_mode", 1) ... -3.26. ds_hash_size (int) +3.27. ds_hash_size (int) The value to be used as power of two to set the number of slots to hash table storing data for call load dispatching (e.g., value 8 will create 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.27. Set the "ds_hash_size" parameter + Example 1.28. Set the “ds_hash_size” parameter ... modparam("dispatcher", "ds_hash_size", 9) ... -3.27. ds_hash_expire (int) +3.28. ds_hash_expire (int) 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.28. Set the "ds_hash_expire" parameter + Example 1.29. Set the “ds_hash_expire” parameter ... modparam("dispatcher", "ds_hash_expire", 3600) ... -3.28. ds_hash_initexpire (int) +3.29. ds_hash_initexpire (int) Expiration time in seconds to remove the load on a destination if no 200 for INVITE was received meanwhile and state updated with ds_load_update(). - Default value is "7200". + Default value is “7200”. - Example 1.29. Set the "ds_hash_initexpire" parameter + Example 1.30. Set the “ds_hash_initexpire” parameter ... modparam("dispatcher", "ds_hash_initexpire", 60) ... -3.29. ds_hash_check_interval (int) +3.30. ds_hash_check_interval (int) 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.30. Set the "ds_hash_check_interval" parameter + Example 1.31. Set the “ds_hash_check_interval” parameter ... modparam("dispatcher", "ds_hash_check_interval", 60) ... -3.30. outbound_proxy (str) +3.31. outbound_proxy (str) SIP URI of outbound proxy to be used when sending pings. By default no outbound proxy is defined. - Example 1.31. Set the "outbound_proxy" parameter + Example 1.32. Set the “outbound_proxy” parameter ... modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com") ... -3.31. ds_default_socket (str) +3.32. ds_default_socket (str) Default socket to be used for sending pings and dispatching requests when a gateway has no send socket configured. @@ -740,7 +767,7 @@ Note By default no default socket is defined, the first configuration script listen directive is used. - Example 1.32. 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") ... @@ -757,7 +784,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 @@ -776,21 +803,21 @@ 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 (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'. @@ -805,7 +832,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. * limit - the maximum number of items to be stored in AVP list for further failovers (the first selected destination and default @@ -818,7 +845,7 @@ Note This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. - Example 1.33. ds_select_dst usage + Example 1.34. ds_select_dst usage ... ds_select_dst("1", "0"); ... @@ -828,7 +855,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 @@ -841,21 +868,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 @@ -882,7 +909,7 @@ ds_select_dst("1", "4", "3"); This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. - Example 1.34. ds_mark_dst usage + Example 1.35. ds_mark_dst usage ... failure_route[tryagain] { ... @@ -892,21 +919,21 @@ 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. This function can be used from ANY_ROUTE. - Example 1.35. ds_list_exist usage + Example 1.36. ds_list_exist usage ... 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; @@ -942,7 +969,7 @@ if(ds_list_exist("10")) { This function can be used from ANY_ROUTE. - Example 1.36. ds_mark_dst usage + Example 1.37. ds_mark_dst usage ... if(ds_is_from_list()) { ... @@ -955,7 +982,7 @@ if(ds_is_from_list("10", "sip:127.0.0.1:5080", "3")) { } ... -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 @@ -966,14 +993,14 @@ if(ds_is_from_list("10", "sip:127.0.0.1:5080", "3")) { 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. This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and ONREPLY_ROUTE. - Example 1.37. ds_load_unset usage + Example 1.38. ds_load_unset usage ... route { ... @@ -1003,7 +1030,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). @@ -1012,11 +1039,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_ @@ -1028,7 +1055,7 @@ onreply_route { _address_ _empty_line_ -5.2. ds_list +5.2. ds_list It lists the groups and included destinations. @@ -1040,7 +1067,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 @@ -1060,7 +1087,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). @@ -1069,11 +1096,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_ @@ -1084,7 +1111,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. @@ -1095,7 +1122,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 @@ -1166,15 +1193,15 @@ 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.38. dispatcher list file + Example 1.39. dispatcher list file ... # $Id$ # dispatcher destination sets # # line format -# setit(int) destination(sip uri) flags(int,opt) priority(int,opt) attributes(st -r,opt) +# setit(int) destination(sip uri) flags(int,opt) priority(int,opt) attributes(s +tr,opt) # proxies 2 sip:127.0.0.1:5080 @@ -1191,7 +1218,7 @@ r,opt) Next picture shows a sample usage of the dispatcher module. - Example 1.39. Kamailio config script - sample dispatcher usage + Example 1.40. Kamailio config script - sample dispatcher usage ... #!KAMAILIO # @@ -1297,8 +1324,8 @@ modparam("rr", "append_fromtag", 0) modparam("acc", "log_flag", 1) modparam("acc", "failed_transaction_flag", 3) modparam("acc", "log_extra", - "src_user=$fU;src_domain=$fd;dst_ouser=$tU;dst_user=$rU;dst_domain=$rd;s -rc_ip=$si") + "src_user=$fU;src_domain=$fd;dst_ouser=$tU;dst_user=$rU;dst_domain=$rd; +src_ip=$si") # ----- tm params ----- modparam("tm", "fr_timer", 2000) @@ -1408,13 +1435,13 @@ route[WITHINDLG] { if ( is_method("ACK") ) { if ( t_check_trans() ) { # non loose-route, but stateful ACK; - # must be ACK after a 487 or e.g. 404 fr -om upstream server + # must be ACK after a 487 or e.g. 404 f +rom upstream server t_relay(); exit; } else { - # ACK without matching transaction ... i -gnore and discard. + # ACK without matching transaction ... +ignore and discard. exit; } } @@ -1482,7 +1509,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 @@ -1493,7 +1520,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 diff --git a/modules/dispatcher/config.c b/modules/dispatcher/config.c index 8d07da1c53f..92a18857c8a 100644 --- a/modules/dispatcher/config.c +++ b/modules/dispatcher/config.c @@ -31,15 +31,18 @@ #include "config.h" struct cfg_group_dispatcher default_dispatcher_cfg = { - 3, /* Probing threshhold */ + 1, /* Probing threshold */ + 1, /* Inactive threshold */ {0,0} /* reply codes */ }; void *dispatcher_cfg = &default_dispatcher_cfg; cfg_def_t dispatcher_cfg_def[] = { - {"probing_threshhold", CFG_VAR_INT | CFG_ATOMIC, 0, 0, 0, 0, + {"probing_threshold", CFG_VAR_INT | CFG_ATOMIC, 0, 0, 0, 0, "Number of failed requests, before a destination is set to probing."}, + {"inactive_threshold", CFG_VAR_INT | CFG_ATOMIC, 0, 0, 0, 0, + "Number of successful requests, before a destination is set to active."}, {"ping_reply_codes", CFG_VAR_STR | CFG_CB_ONLY_ONCE , 0, 0, 0, ds_ping_reply_codes_update, "Additional, valid reply codes for the OPTIONS Pinger. Default is \"\""}, {0, 0, 0, 0, 0, 0} diff --git a/modules/dispatcher/config.h b/modules/dispatcher/config.h index 9f028af814a..3216d1b2162 100644 --- a/modules/dispatcher/config.h +++ b/modules/dispatcher/config.h @@ -27,7 +27,8 @@ #include "../../str.h" struct cfg_group_dispatcher { - int probing_threshhold; + int probing_threshold; + int inactive_threshold; str ds_ping_reply_codes_str; }; diff --git a/modules/dispatcher/dispatch.c b/modules/dispatcher/dispatch.c index c17d7a3ee53..ff3871f8baf 100644 --- a/modules/dispatcher/dispatch.c +++ b/modules/dispatcher/dispatch.c @@ -38,6 +38,8 @@ * 2007-07-18 removed index stuff * added DB support to load/reload data(ancuta) * 2007-09-17 added list-file support for reload data (carstenbock) + * 2014-12-23 Corrected misspelled words in some variables' name (alezzandro) + * 2014-12-23 Added support for custom number of successful probing requests before moving a destination from 'inactive' to 'active' state (alezzandro) */ /*! \file @@ -2187,12 +2189,49 @@ int ds_mark_dst(struct sip_msg *msg, int state) } /** - * + * Get state for given destination + */ +int ds_get_state(int group, str *address) +{ + int i=0; + int state = 0; + ds_set_t *idx = NULL; + + if(_ds_list==NULL || _ds_list_nr<=0) + { + LM_ERR("the list is null\n"); + return -1; + } + + /* get the index of the set */ + if(ds_get_index(group, &idx)!=0) + { + LM_ERR("destination set [%d] not found\n", group); + return -1; + } + + while(inr) + { + if(idx->dlist[i].uri.len==address->len + && strncasecmp(idx->dlist[i].uri.s, address->s, + address->len)==0) + { + /* destination address found */ + state = idx->dlist[i].flags; + } + i++; + } + return state; +} + +/** + * Update destionation's state */ int ds_update_state(sip_msg_t *msg, int group, str *address, int state) { int i=0; int old_state = 0; + int init_state = 0; ds_set_t *idx = NULL; if(_ds_list==NULL || _ds_list_nr<=0) @@ -2219,7 +2258,10 @@ int ds_update_state(sip_msg_t *msg, int group, str *address, int state) /* reset the bits used for states */ idx->dlist[i].flags &= ~(DS_STATES_ALL); - + + /* we need the initial state for inactive counter */ + init_state = state; + if((state & DS_TRYING_DST) && (old_state & DS_INACTIVE_DST)) { /* old state is inactive, new state is trying => keep it inactive @@ -2235,18 +2277,33 @@ int ds_update_state(sip_msg_t *msg, int group, str *address, int state) } else { idx->dlist[i].flags |= state; } - + if(state & DS_TRYING_DST) { - idx->dlist[i].failure_count++; - if (idx->dlist[i].failure_count >= probing_threshhold) + idx->dlist[i].message_count++; + /* Destination is not replying.. Increasing failure counter */ + if (idx->dlist[i].message_count >= probing_threshold) { + /* Destionation has too much lost messages.. Bringing it to inactive state */ idx->dlist[i].flags &= ~DS_TRYING_DST; idx->dlist[i].flags |= DS_INACTIVE_DST; - idx->dlist[i].failure_count = 0; + idx->dlist[i].message_count = 0; } } else { - idx->dlist[i].failure_count = 0; + if(!(init_state & DS_TRYING_DST) && (old_state & DS_INACTIVE_DST)){ + idx->dlist[i].message_count++; + /* Destination was inactive but it is just replying.. Increasing successful counter */ + if (idx->dlist[i].message_count < inactive_threshold) + { + /* Destination has not enough successful replies.. Leaving it into inactive state */ + idx->dlist[i].flags |= DS_INACTIVE_DST; + }else{ + /* Destination has enough replied messages.. Bringing it to active state */ + idx->dlist[i].message_count = 0; + } + }else{ + idx->dlist[i].message_count = 0; + } } if (!ds_skip_dst(old_state) && ds_skip_dst(idx->dlist[i].flags)) @@ -2375,10 +2432,10 @@ int ds_print_list(FILE *fout) else if (list->dlist[j].flags&DS_TRYING_DST) { fprintf(fout, " Trying"); /* print the tries for this host. */ - if (list->dlist[j].failure_count > 0) { + if (list->dlist[j].message_count > 0) { fprintf(fout, " (Fail %d/%d)", - list->dlist[j].failure_count, - probing_threshhold); + list->dlist[j].message_count, + probing_threshold); } else { fprintf(fout, " "); } @@ -2607,7 +2664,8 @@ static void ds_options_callback( struct cell *t, int type, state = 0; if (ds_probing_mode==DS_PROBE_ALL) state |= DS_PROBING_DST; - if (ds_update_state(fmsg, group, &uri, state) != 0) + /* 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) { LM_ERR("Setting the state failed (%.*s, group %d)\n", uri.len, uri.s, group); @@ -2616,8 +2674,8 @@ static void ds_options_callback( struct cell *t, int type, state = DS_TRYING_DST; if (ds_probing_mode!=DS_PROBE_NONE) state |= DS_PROBING_DST; - - if (ds_update_state(fmsg, group, &uri, state) != 0) + /* 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) { LM_ERR("Setting the probing state failed (%.*s, group %d)\n", uri.len, uri.s, group); diff --git a/modules/dispatcher/dispatch.h b/modules/dispatcher/dispatch.h index e7ac8ae23d0..d991fd78ccf 100644 --- a/modules/dispatcher/dispatch.h +++ b/modules/dispatcher/dispatch.h @@ -30,6 +30,8 @@ * re-enabling of destinations * 2007-05-08 Ported the changes to SVN-Trunk and renamed ds_is_domain * to ds_is_from_list. + * 2014-12-23 Corrected misspelled words in some variables' name (alezzandro) + * 2014-12-23 Added support for custom number of successful probing requests before moving a destination from 'inactive' to 'active' state (alezzandro) */ /*! \file @@ -100,8 +102,10 @@ extern pv_spec_t ds_attrs_pv; extern struct tm_binds tmb; extern str ds_ping_method; extern str ds_ping_from; -extern int probing_threshhold; /*!< number of failed requests, - before a destination is taken into probing */ +extern int probing_threshold; /*!< number of failed requests, + before a destination is taken into probing */ +extern int inactive_threshold; /*!< number of successful requests, + before a destination is taken into active */ extern int ds_probing_mode; extern str ds_outbound_proxy; extern str ds_default_socket; @@ -172,7 +176,7 @@ typedef struct _ds_dest struct ip_addr ip_address; /*!< IP-Address of the entry */ unsigned short int port; /*!< Port of the URI */ unsigned short int proto; /*!< Protocol of the URI */ - int failure_count; + int message_count; struct _ds_dest *next; } ds_dest_t; diff --git a/modules/dispatcher/dispatcher.c b/modules/dispatcher/dispatcher.c index f0d89a85d95..bb67adc6514 100644 --- a/modules/dispatcher/dispatcher.c +++ b/modules/dispatcher/dispatcher.c @@ -34,6 +34,8 @@ * 2007-07-18 Added support for load/reload groups from DB * reload triggered from ds_reload MI_Command (ancuta) * 2014-12-12 Added "ds_list_exist" function + * 2014-12-23 Corrected misspelled words in some variables' name (alezzandro) + * 2014-12-23 Added support for custom number of successful probing requests before moving a destination from 'inactive' to 'active' state (alezzandro) */ /*! \file @@ -108,7 +110,7 @@ unsigned short sock_avp_type; pv_elem_t * hash_param_model = NULL; -int probing_threshhold = 1; /* number of failed requests, before a destination +int probing_threshold = 1; /* number of failed requests, before a destination is taken into probing */ str ds_ping_method = str_init("OPTIONS"); str ds_ping_from = str_init("sip:dispatcher@localhost"); @@ -240,7 +242,7 @@ static param_export_t params[]={ {"hash_pvar", PARAM_STR, &hash_pvar_param}, {"setid_pvname", PARAM_STR, &ds_setid_pvname}, {"attrs_pvname", PARAM_STR, &ds_attrs_pvname}, - {"ds_probing_threshhold", INT_PARAM, &probing_threshhold}, + {"ds_probing_threshold", INT_PARAM, &probing_threshold}, {"ds_ping_method", PARAM_STR, &ds_ping_method}, {"ds_ping_from", PARAM_STR, &ds_ping_from}, {"ds_ping_interval", INT_PARAM, &ds_ping_interval}, @@ -321,8 +323,8 @@ static int mod_init(void) } } /* Copy Threshhold to Config */ - cfg_get(dispatcher, dispatcher_cfg, probing_threshhold) - = probing_threshhold; + cfg_get(dispatcher, dispatcher_cfg, probing_threshold) + = probing_threshold; if(init_data()!= 0) @@ -549,7 +551,7 @@ static int mod_init(void) } /*! \brief - * Initialize childreng + * Initialize children */ static int child_init(int rank) { diff --git a/modules/dispatcher/doc/dispatcher.xml b/modules/dispatcher/doc/dispatcher.xml index 55ab58cce34..471ebbe0370 100644 --- a/modules/dispatcher/doc/dispatcher.xml +++ b/modules/dispatcher/doc/dispatcher.xml @@ -39,6 +39,14 @@ oej@edvina.net + + Alessandro + Arrichiello + Hewlett Packard +
+ alezzandro@gmail.com +
+ 2004 @@ -56,6 +64,10 @@ 2014 Olle E. Johansson, Edvina AB + + 2015 + Alessandro Arrichiello, Hewlett Packard + diff --git a/modules/dispatcher/doc/dispatcher_admin.xml b/modules/dispatcher/doc/dispatcher_admin.xml index 404bbd2fb94..1a86eabecec 100644 --- a/modules/dispatcher/doc/dispatcher_admin.xml +++ b/modules/dispatcher/doc/dispatcher_admin.xml @@ -598,14 +598,36 @@ modparam("dispatcher", "force_dst", 1) - Set the <quote>ds_probing_threshhold</quote> parameter + Set the <quote>ds_probing_threshold</quote> parameter ... - modparam("dispatcher", "ds_probing_threshhold", 10) + modparam("dispatcher", "ds_probing_threshold", 10) ... +
+ <varname>ds_inactive_threshold</varname> (int) + + If you want to set a gateway into active mode (after being inactive), there can be + a specific number of successful requests until it will change from "inactive" + to "active". The number of attempts can be set with this parameter. + This parameter can be modified via ser config framework. + + + + Default value is 1 (set active with first success). + + + + Set the <quote>ds_inactive_threshold</quote> parameter + + ... + modparam("dispatcher", "ds_inactive_threshold", 10) + ... + + +
<varname>ds_ping_reply_codes</varname> (string)