From fb79f4cb136acc8ab3ec9b4af5c97d925d767a2e Mon Sep 17 00:00:00 2001 From: Kamailio Dev Date: Mon, 17 Dec 2018 10:01:38 +0100 Subject: [PATCH] modules: readme files regenerated - uac_redirect ... [skip ci] --- src/modules/uac_redirect/README | 403 ++++++++++++++++++++++++++++++++ 1 file changed, 403 insertions(+) diff --git a/src/modules/uac_redirect/README b/src/modules/uac_redirect/README index 139597f9cb0..0da60f08ad5 100644 --- a/src/modules/uac_redirect/README +++ b/src/modules/uac_redirect/README @@ -1,2 +1,405 @@ +UAC_REDIRECT Module +Bogdan-Andrei Iancu + Voice System + +Edited by + +Bogdan-Andrei Iancu + + Copyright © 2005 Voice Sistem + __________________________________________________________________ + + Table of Contents + + 1. Admin Guide + + 1. Overview + 2. Accounting + 3. Dependencies + + 3.1. Kamailio Modules + 3.2. External Libraries or Applications + + 4. Parameters + + 4.1. default_filter (string) + 4.2. deny_filter (string) + 4.3. accept_filter (string) + 4.4. acc_function (string) + 4.5. acc_db_table (string) + 4.6. bflags (int) + + 5. Functions + + 5.1. set_deny_filter(filter,flags) + 5.2. set_accept_filter(filter,flags) + 5.3. get_redirects(max) + 5.4. get_redirects(max,reason) + + 6. Script Example + + List of Examples + + 1.1. Set default_filter module parameter + 1.2. Set deny_filter module parameter + 1.3. Set accept_filter module parameter + 1.4. Set acc_function parameter + 1.5. Set acc_db_table parameter + 1.6. Set bflags module parameter + 1.7. set_deny_filter usage + 1.8. set_accept_filter usage + 1.9. get_redirects usage + 1.10. get_redirects usage + 1.11. Redirection script example + +Chapter 1. Admin Guide + + Table of Contents + + 1. Overview + 2. Accounting + 3. Dependencies + + 3.1. Kamailio Modules + 3.2. External Libraries or Applications + + 4. Parameters + + 4.1. default_filter (string) + 4.2. deny_filter (string) + 4.3. accept_filter (string) + 4.4. acc_function (string) + 4.5. acc_db_table (string) + 4.6. bflags (int) + + 5. Functions + + 5.1. set_deny_filter(filter,flags) + 5.2. set_accept_filter(filter,flags) + 5.3. get_redirects(max) + 5.4. get_redirects(max,reason) + + 6. Script Example + +1. Overview + + UAC REDIRECT - User Agent Client redirection - module enhance Kamailio + with the functionality of being able to handle (interpret, filter, log + and follow) redirect responses ( 3xx replies class). + + UAC REDIRECT module offer stateful processing, gathering the contacts + from all 3xx branches of a call. + + The module provide a powerful mechanism for selecting and filtering the + contacts to be used for the new redirect: + * number based - limits like the number of total contacts to be used + or the maximum number of contacts per branch to be selected. + * Regular Expression based - combinations of deny and accept filters + allow a strict control of the contacts to be used for redirection. + + When selecting from a 3xx branch the contacts to be used, the contacts + will be ordered and prioritized based on the “q” value. + +2. Accounting + + UAC REDIRECT module allows to log all the redirection (to be later used + for CDR aggregation). This functionality may be dynamically enabled for + each redirection situation. + + The logging will be done via the accounting module functions (all are + supported). The information to be logged will be the same as the normal + logged information directly via ACC module, but with following + differences: + * reason phrase - which will be dynamically set by the redirection + function; + * outgoing URI - which will be the redirect URI. + + For each redirect contact, a separate record will be logged. For + example, if a call is redirected to three new contacts, the module will + log three additional records corresponding to each redirect URI. + +3. Dependencies + + 3.1. Kamailio Modules + 3.2. External Libraries or Applications + +3.1. Kamailio Modules + + The following modules must be loaded before this module: + * TM - Transaction Module, for accessing replies. + * ACC - Accounting Module, but only if the logging feature is used. + +3.2. External Libraries or Applications + + The following libraries or applications must be installed before + running Kamailio with this module loaded: + * None + +4. Parameters + + 4.1. default_filter (string) + 4.2. deny_filter (string) + 4.3. accept_filter (string) + 4.4. acc_function (string) + 4.5. acc_db_table (string) + 4.6. bflags (int) + +4.1. default_filter (string) + + The default behavior in filtering contacts. It may be “accept” or + “deny”. + + The default value is “accept”. + + Example 1.1. Set default_filter module parameter +... +modparam("uac_redirect","default_filter","deny") +... + +4.2. deny_filter (string) + + The regular expression for default deny filtering. It makes sense to be + defined only if the default_filter parameter is set to “accept”. All + contacts matching the deny_filter will be rejected; the rest of them + will be accepted for redirection. + + The parameter may be defined only one - multiple definition will + overwrite the previous definitions. If more regular expression need to + be defined, use the set_deny_filter() scripting function. + + This parameter is optional, it's default value being NULL. + + Example 1.2. Set deny_filter module parameter +... +modparam("uac_redirect","deny_filter",".*@siphub\.net") +... + +4.3. accept_filter (string) + + The regular expression for default accept filtering. It makes sense to + be defined only if the default_filter parameter is set to “deny”. All + contacts matching the accept_filter will be accepted; the rest of them + will be rejected for redirection. + + The parameter may be defined only one - multiple definition will + overwrite the previous definitions. If more regular expression need to + be defined, use the set_accept_filter() scripting function. + + This parameter is optional, it's default value being NULL. + + Example 1.3. Set accept_filter module parameter +... +modparam("uac_redirect","accept_filter",".*@siphub\.net") +... + +4.4. acc_function (string) + + Specifies the accounting function to be used. Just by defining this + parameter, the accounting support will not be enabled. Accounting may + only be enabled via two parameters set_accept_filter() scripting + function. + + Its values may be: + * acc_log_request + * acc_db_request + * acc_rad_request + * acc_diam_request + + The default value is “acc_log_request”. + + Example 1.4. Set acc_function parameter +... +modparam("uac_redirect","acc_function","acc_db_request") +... + +4.5. acc_db_table (string) + + Specifies the accounting table to be used if DB accounting was chosen + (acc_function was set to “acc_db_request”). Just by defining this + parameter, the accounting support will not be enabled. Accounting may + only be enabled via two parameters set_accept_filter() scripting + function. + + The default value is “acc”. + + Example 1.5. Set acc_db_table parameter +... +modparam("uac_redirect","acc_db_table","acc_redirect") +... + +4.6. bflags (int) + + This parameter defines the branch-flags to be set for new, added + branch. + + This parameter is optional, it's default value being 0. + + Example 1.6. Set bflags module parameter +... +modparam("uac_redirect","bflags", 1) +... + +branch_route[1] { + if (isbflagset(1)) { + log(1, "This branch comes from a 302 Forward Request.\n"); + } else { + log(1, "This is a regular branch.\n"); + } +} + +5. Functions + + 5.1. set_deny_filter(filter,flags) + 5.2. set_accept_filter(filter,flags) + 5.3. get_redirects(max) + 5.4. get_redirects(max,reason) + +5.1. set_deny_filter(filter,flags) + + Sets additional deny filters. Maximum 6 may be combined. This + additional filter will apply only to the current message - it will not + have a global effect. + + Default or previous added deny filter may be reset depending of the + flag parameter value: + * reset_all - reset both default and previous added deny filters; + * reset_default - reset only the default deny filter; + * reset_added - reset only the previous added deny filters; + * empty - no reset, just add the filter. + + This function can be used from FAILURE_ROUTE. + + Example 1.7. set_deny_filter usage +... +set_deny_filter(".*@domain2.net","reset_all"); +set_deny_filter(".*@domain1.net",""); +... + +5.2. set_accept_filter(filter,flags) + + Sets additional accept filters. Maximum 6 may be combined. This + additional filter will apply only to the current message - it will not + have a global effect. + + Default or previous added deny filter may be reset depending of the + flag parameter value: + * reset_all - reset both default and previous added accept filters; + * reset_default - reset only the default accept filter; + * reset_added - reset only the previous added accept filters; + * empty - no reset, just add the filter. + + This function can be used from FAILURE_ROUTE. + + Example 1.8. set_accept_filter usage +... +set_accept_filter(".*@domain2.net","reset_added"); +set_accept_filter(".*@domain1.net",""); +... + +5.3. get_redirects(max) + + The function may be called only from failure routes. It will extract + the contacts from all 3xx branches and append them as new branches. + Note that the function will not forward the new branches, this must be + done explicitly from script. + + How many contacts (in total and per branch) are selected depends of the + max parameter values. Its syntax is: + * max = max_total [":" max_branch] + * max_total = number of total contacts to be selected + * max_branch = number of contacts per branch to be selected + + Both “max_total” and “max_branch” are positive integer. To specify + unlimited values, use 0 value or "*" character. + + NOTE that during the selection process, each set of contacts from a + specific branch are ordered based on “q” value. + + This function will produce no accounting records. + + This function can be used from FAILURE_ROUTE. + + Example 1.9. get_redirects usage +... +# max 2 contacts per branch, but no overall limit +get_redirects("*:2"); +... +# no limits per branch, but not more than 6 overall contacts +get_redirects("6:*"); +... +# no restrictions +get_redirects("*"); +... + +5.4. get_redirects(max,reason) + + The function has same functionality as get_redirects(max) function, but + it will produce accounting records. + + The accounting records will be mark by the reason phrase. + + If this function appears in the script, at startup, the module will + import the accounting function. Otherwise not. + + This function can be used from FAILURE_ROUTE. + + Example 1.10. get_redirects usage +... +get_redirects("4:1","Redirected"); +... + +6. Script Example + + Example 1.11. Redirection script example +loadmodule "modules/sl/sl.so" +loadmodule "modules/usrloc/usrloc.so" +loadmodule "modules/registrar/registrar.so" +loadmodule "modules/tm/tm.so" +loadmodule "modules/acc/acc.so" +loadmodule "modules/uac_redirect/uac_redirect.so" + +modparam("usrloc", "db_mode", 0) + +request_route{ + if (uri==myself) { + + if (method=="REGISTER") { + save("location"); + exit; + } + + if (!lookup("location")) { + sl_send_reply("404", "Not Found"); + exit; + } + # do redirect with accounting + t_on_failure("REDIRECT_ACC"); + } else { + # just do redirect + t_on_failure("REDIRECT_NOACC"); + } + + if (!t_relay()) { + sl_reply_error(); + } +} + +# redirect without storing acc record +failure_route[REDIRECT_NOACC] { + if(!t_check_status("3[0-9][0-9]")) { + exit; + } + get_redirects("3:1"); + t_relay(); +} + +# redirect with storing acc record +failure_route[REDIRECT_ACC] { + if(!t_check_status("3[0-9][0-9]")) { + exit; + } + get_redirects("6:2", "redirect"); + t_relay(); +}