Table of Contents
List of Examples
default_filter
module parameterdeny_filter
module parameteraccept_filter
module parameteracc_function parameteracc_db_table parameterbflags
module parameterflags_hdr_mode parameterq_value parameterset_deny_filter usageset_accept_filter usageget_redirects usageget_redirects usageTable of Contents
UAC REDIRECT - User Agent Client redirection - module enhances Kamailio with the functionality of being able to handle (interpret, filter, log and follow) redirect responses (3xx replies class).
UAC REDIRECT module offers stateful processing, gathering the contacts from all 3xx branches of a call.
The module provides 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.
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.
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.
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")
...
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 once - multiple definition will
overwrite the previous definitions. If more regular expression
need to be defined, use the
set_deny_filter() scripting
function.
The default value is NULL.
Example 1.2. Set deny_filter
module parameter
...
modparam("uac_redirect","deny_filter",".*@siphub\.net")
...
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 once - multiple definition will
overwrite the previous definitions. If more regular expression
need to be defined, use the
set_accept_filter() scripting
function.
The default value is NULL.
Example 1.3. Set accept_filter
module parameter
...
modparam("uac_redirect","accept_filter",".*@siphub\.net")
...
Specifies the accounting function to be used. Just by defining
this parameter, the accounting is not done automatically, it has to
be requested via parameters of
set_accept_filter()
or other scripting function.
Set it to empty string in order to disable binding to acc module.
Its values may be:
acc_log_request
acc_db_request
acc_request
The default value is “acc_log_request”.
Example 1.4. Set acc_function parameter
...
modparam("uac_redirect","acc_function","acc_db_request")
...
Specifies the accounting table to be used if DB accounting was
chosen (acc_function was set to
“acc_db_request” or “acc_request”).
The default value is “acc”.
Example 1.5. Set acc_db_table parameter
...
modparam("uac_redirect","acc_db_table","acc_redirect")
...
This parameter defines the branch-flags to be set for new, added branch.
The default value is 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");
}
}
Specifies if and how a Contact's flags header parameter must be used. If set, and a flags header parameter is set, its value will be set as branch flags for that contact.
Its values may be:
0 - ignore flags header parameter, just use bflags module parameter
1 - use flags header parameter if present, ignore bflags module parameter
2 - use flags header parameter if present and merge (binary or) it with the bflags module parameter
The default value is “0”.
Specifies the q-value to assign to contacts without one. Because Kamailio doesn't support float parameter types, the value in the parameter is divided by 1000 and stored as float. For example, if you want q value to be 0.38, use value 380 here.
The default value is 10 (0.01).
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.9. set_deny_filter usage
...
set_deny_filter(".*@domain2.net","reset_all");
set_deny_filter(".*@domain1.net","");
...
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.10. set_accept_filter usage
...
set_accept_filter(".*@domain2.net","reset_added");
set_accept_filter(".*@domain1.net","");
...
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.11. 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("*");
...
The function has same functionality as
get_redirects(max)
function, but it will produce accounting records.
The accounting records will be marked 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.13. 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();
}