uac_redirect_admin.xml

<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>


	<section>
		<title>Overview</title>
		<para>
		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).
		</para>
		<para>
		UAC REDIRECT module offers stateful processing, gathering the
		contacts from all 3xx branches of a call.
		</para>
		<para>
		The module provides a powerful mechanism for selecting and filtering 
		the contacts to be used for the new redirect:
		</para>
		<itemizedlist>
			<listitem>
			<para><emphasis>number based</emphasis> - limits like the 
			number of total contacts to be used or the maximum number of 
			contacts per branch to be selected.
			</para>
			</listitem>
			<listitem>
			<para><emphasis>Regular Expression based</emphasis> - combinations
			of deny and accept filters allow a strict control of the 
			contacts to be used for redirection.
			</para>
			</listitem>
		</itemizedlist>
		<para>
		When selecting from a 3xx branch the contacts to be used, the contacts
		will be ordered and prioritized based on the <quote>q</quote> value.
		</para>
	</section>

	<section>
		<title>Accounting</title>
		<para>
		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.
		</para>
		<para>
		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:
		</para>
		<itemizedlist>
			<listitem>
			<para><emphasis>reason phrase</emphasis> - which will be
			dynamically set by the redirection function;
			</para>
			</listitem>
			<listitem>
			<para><emphasis>outgoing URI</emphasis> - which will be the
			redirect URI.
			</para>
			</listitem>
		</itemizedlist>
		<para>
		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.
		</para>
	</section>


	<section>
		<title>Dependencies</title>
		<section>
			<title>&kamailio; Modules</title>
			<para>
			The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>TM</emphasis> - Transaction Module, for accessing
				replies.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>ACC</emphasis> - Accounting Module, but only if the
				logging feature is used.
			</para>
			</listitem>
			</itemizedlist>
			</para>
		</section>
		<section>
			<title>External Libraries or Applications</title>
			<para>
				The following libraries or applications must be installed 
				before running &kamailio; with this module loaded:
				<itemizedlist>
				<listitem>
				<para>
					<emphasis>None</emphasis>
				</para>
				</listitem>
				</itemizedlist>
			</para>
		</section>
	</section>

	<section>
		<title>Parameters</title>
		<section id="uac_redirect.p.default_filter">
			<title><varname>default_filter</varname> (string)</title>
			<para>
			The default behavior in filtering contacts. It may be 
			<quote>accept</quote> or <quote>deny</quote>.
			</para>
			<para>
				<emphasis>
					The default value is <quote>accept</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>default_filter</varname> 
					module parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_redirect","default_filter","deny")
...
				</programlisting>
			</example>
		</section>
		<section id="uac_redirect.p.deny_filter">
			<title><varname>deny_filter</varname> (string)</title>
			<para>
			The regular expression for default deny filtering. It makes sense
			to be defined only if the <varname>default_filter</varname>
			parameter is set to <quote>accept</quote>. All contacts matching
			the <varname>deny_filter</varname> will be rejected; the rest 
			of them will be accepted for redirection.
			</para>
			<para>
			The parameter may be defined only once - multiple definition will
			overwrite the previous definitions. If more regular expression 
			need to be defined, use the 
			<function moreinfo="none">set_deny_filter()</function> scripting
			function.
			</para>
			<para>
				<emphasis>
					The default value is NULL.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>deny_filter</varname> 
					module parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_redirect","deny_filter",".*@siphub\.net")
...
				</programlisting>
			</example>
		</section>
		<section id="uac_redirect.p.accept_filter">
			<title><varname>accept_filter</varname> (string)</title>
			<para>
			The regular expression for default accept filtering. It makes sense
			to be defined only if the <varname>default_filter</varname>
			parameter is set to <quote>deny</quote>. All contacts matching
			the <varname>accept_filter</varname> will be accepted; the rest 
			of them will be rejected for redirection.
			</para>
			<para>
			The parameter may be defined only once - multiple definition will
			overwrite the previous definitions. If more regular expression 
			need to be defined, use the 
			<function moreinfo="none">set_accept_filter()</function> scripting
			function.
			</para>
			<para>
				<emphasis>
					The default value is NULL.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>accept_filter</varname> 
					module parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_redirect","accept_filter",".*@siphub\.net")
...
				</programlisting>
			</example>
		</section>
		<section id="uac_redirect.p.acc_function">
			<title><varname>acc_function</varname> (string)</title>
			<para>
			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
			<function moreinfo="none">set_accept_filter()</function>
			or other scripting function.
			</para>
			<para>
			Set it to empty string in order to disable binding to acc module.
			</para>
			<para>
			Its values may be:
			</para>
			<itemizedlist>
				<listitem>
				<para><emphasis>acc_log_request</emphasis></para>
				</listitem>
				<listitem>
				<para><emphasis>acc_db_request</emphasis></para>
				</listitem>
				<listitem>
				<para><emphasis>acc_request</emphasis></para>
				</listitem>
			</itemizedlist>
			<para>
				<emphasis>
					The default value is <quote>acc_log_request</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>acc_function</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_redirect","acc_function","acc_db_request")
...
				</programlisting>
			</example>
		</section>
		<section id="uac_redirect.p.acc_db_table">
			<title><varname>acc_db_table</varname> (string)</title>
			<para>
			Specifies the accounting table to be used if DB accounting was
			chosen (<varname>acc_function</varname> was set to
			<quote>acc_db_request</quote> or <quote>acc_request</quote>).
			</para>
			<para>
				<emphasis>
					The default value is <quote>acc</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>acc_db_table</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_redirect","acc_db_table","acc_redirect")
...
				</programlisting>
			</example>
		</section>
		<section id="uac_redirect.p.bflags">
			<title><varname>bflags</varname> (int)</title>
			<para>
			This parameter defines the branch-flags to be set for new, added branch.
			</para>
			<para>
				<emphasis>
					The default value is 0.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>bflags</varname> 
					module parameter</title>
				<programlisting format="linespecific">
...
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");
	}
}
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>flags_hdr_mode</varname> (int)</title>
			<para>
			Specifies if and how a Contact&apos;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.
			</para>
			<para>
			Its values may be:
			</para>
			<itemizedlist>
				<listitem>
				<para><emphasis>0</emphasis> - ignore flags header parameter,
				just use bflags module parameter</para>
				</listitem>
				<listitem>
				<para><emphasis>1</emphasis> - use flags header parameter if
				present, ignore bflags module parameter</para>
				</listitem>
				<listitem>
				<para><emphasis>2</emphasis> - use flags header parameter if
				present and merge (binary or) it with the bflags module
				parameter</para>
				</listitem>
			</itemizedlist>
			<para>
				<emphasis>
					The default value is <quote>0</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>flags_hdr_mode</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_redirect","flags_hdr_mode",2)
...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>q_value</varname> (int)</title>
			<para>
			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.
			</para>
			<para>
				<emphasis>
					The default value is 10 (0.01).
				</emphasis>
			</para>
			<example>
				<title>Set <varname>q_value</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_redirect","q_value",0)
...
				</programlisting>
			</example>
		</section>
	</section>
	<section>
		<title>Functions</title>
		<section id="uac_redirect.f.set_deny_filter">
			<title>
				<function moreinfo="none">set_deny_filter(filter, flags)
					</function>
			</title>
			<para>
			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.
			</para>
			<para>
			Default or previous added deny filter may be reset depending of
			the <emphasis>flag</emphasis> parameter value:
			</para>
			<itemizedlist>
				<listitem>
				<para><emphasis>reset_all</emphasis> - reset both default
				and previous added deny filters;
				</para>
				</listitem>
				<listitem>
				<para><emphasis>reset_default</emphasis> - reset only the
				default deny filter;
				</para>
				</listitem>
				<listitem>
				<para><emphasis>reset_added</emphasis> - reset only the 
				previous added deny filters;
				</para>
				</listitem>
				<listitem>
				<para><emphasis>empty</emphasis> - no reset, just add the
				filter.
				</para>
				</listitem>
			</itemizedlist>
			<para>
			This function can be used from FAILURE_ROUTE.
			</para>
			<example>
				<title><function>set_deny_filter</function> usage</title>
				<programlisting format="linespecific">
...
set_deny_filter(".*@domain2.net","reset_all");
set_deny_filter(".*@domain1.net","");
...
				</programlisting>
			</example>
		</section>

		<section id="uac_redirect.f.set_accept_filter">
			<title>
				<function moreinfo="none">set_accept_filter(filter, flags)
					</function>
			</title>
			<para>
			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.
			</para>
			<para>
			Default or previous added deny filter may be reset depending of
			the <emphasis>flag</emphasis> parameter value:
			</para>
			<itemizedlist>
				<listitem>
				<para><emphasis>reset_all</emphasis> - reset both default
				and previous added accept filters;
				</para>
				</listitem>
				<listitem>
				<para><emphasis>reset_default</emphasis> - reset only the
				default accept filter;
				</para>
				</listitem>
				<listitem>
				<para><emphasis>reset_added</emphasis> - reset only the 
				previous added accept filters;
				</para>
				</listitem>
				<listitem>
				<para><emphasis>empty</emphasis> - no reset, just add
				the filter.
				</para>
				</listitem>
			</itemizedlist>
			<para>
			This function can be used from FAILURE_ROUTE.
			</para>
			<example>
				<title><function>set_accept_filter</function> usage</title>
				<programlisting format="linespecific">
...
set_accept_filter(".*@domain2.net","reset_added");
set_accept_filter(".*@domain1.net","");
...
				</programlisting>
			</example>
		</section>

		<section id="uac_redirect.f.get_redirects1">
			<title>
				<function moreinfo="none">get_redirects(max)</function>
			</title>
			<para>
				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.
			</para>
			<para>
				How many contacts (in total and per branch) are selected 
				depends of the <emphasis>max</emphasis> parameter values.
				Its syntax is:
			</para>
			<itemizedlist>
				<listitem><para>
				max = max_total [":" max_branch]
				</para></listitem>
				<listitem><para>
				max_total = number of total contacts to be selected
				</para></listitem>
				<listitem><para>
				max_branch = number of contacts per branch to be selected
				</para></listitem>
			</itemizedlist>
			<para>
				Both <quote>max_total</quote> and <quote>max_branch</quote>
				are positive integer. To specify unlimited values, use 0 value
				or "*" character.
			</para>
			<para>
				NOTE that during the selection process, each set of contacts 
				from a specific branch are ordered based on <quote>q</quote> 
				value.
			</para>
			<para>
				This function will produce no accounting records.
			</para>
			<para>
				This function can be used from FAILURE_ROUTE.
			</para>
			<example>
				<title><function>get_redirects</function> usage</title>
				<programlisting format="linespecific">
...
# 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("*");
...
				</programlisting>
			</example>
		</section>

		<section id="uac_redirect.f.get_redirects2">
			<title>
				<function moreinfo="none">get_redirects(max, reason)</function>
			</title>
			<para>
				The function has same functionality as 
				<function moreinfo="none">get_redirects(max)</function>
				function, but it will produce accounting records.
			</para>
			<para>
				The accounting records will be marked by the 
				<emphasis>reason</emphasis> phrase.
			</para>
			<para>
				If this function appears in the script, at startup, the module
				will import the accounting function. Otherwise not.
			</para>
			<para>
			This function can be used from FAILURE_ROUTE.
			</para>
			<example>
				<title><function>get_redirects</function> usage</title>
				<programlisting format="linespecific">
...
get_redirects("4:1","Redirected");
...
				</programlisting>
			</example>
		</section>
	</section>

	<section>
		<title>Script Example</title>
		<example>
			<title>Redirection script example</title>
				<programlisting format="linespecific">
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();
}
				</programlisting>
			</example>

	</section>

</chapter>