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)
              4.7. flags_hdr_mode (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 flags_hdr_mode parameter
   1.8. set_deny_filter usage
   1.9. set_accept_filter usage
   1.10. get_redirects usage
   1.11. get_redirects usage
   1.12. 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)
        4.7. flags_hdr_mode (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.7. flags_hdr_mode (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");
        }
}

4.7. flags_hdr_mode (int)

   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”.

   Example 1.7. Set flags_hdr_mode parameter
...
modparam("uac_redirect","flags_hdr_mode",2)
...

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.8. 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.9. 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.10. 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.11. get_redirects usage
...
get_redirects("4:1","Redirected");
...

6. Script Example

   Example 1.12. 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();
}