modules/uac/doc/uac_admin.xml
33d03d8d
 <?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 "../../../docbook/entities.xml">
 %docentities;
 
 ]>
9fd7fc4e
 <!-- Module User's Guide -->
 
 <chapter>
033b5989
 	
9fc784c6
 	<title>&adminguide;</title>
9fd7fc4e
 
 
 	<section>
 		<title>Overview</title>
 		<para>
ef0f8fd6
 		The <acronym>UAC</acronym> (User Agent Client) module provides some basic UAC
18220b91
 		functionalities like sending SIP requests, registering with a remote service,
1c35849b
 		From: header manipulation (anonymization) and client authentication.
28e604d1
 		</para>
 		<para>
1c35849b
 		The UAC module also supports sending a SIP request from the
28e604d1
 		configuration file. See variable $uac_req(name) and the function
 		uac_req_send().
 		</para>
 		<para>
1c35849b
 		In addition, the module supports database-driven SIP registration functionality. See
 		the uac_reg_lookup() function and dedicated section for remote
28e604d1
 		registration configuration.
9fd7fc4e
 		</para>
 		<para>
 		Known limitations in this version:
 		</para>
 		<itemizedlist>
 			<listitem>
 			<para>
18220b91
 				Authentication does not support qop auth-int, just qop auth;
4cf00fd7
 			</para>
 			</listitem>
 			<listitem>
 			<para>
18220b91
 				CSeq is not increased during authentication - the response 
4cf00fd7
 				may be rejected.
9fd7fc4e
 			</para>
 			</listitem>
1c35849b
 			<listitem>
 			<para>
 				The <quote>uac_replace_*</quote> functions can only be run once on the same
 				SIP request. Try to save needed changes in a pseudovariable and
 				apply them once.
 			</para>
 			</listitem>
9fd7fc4e
 		</itemizedlist>
 	</section>
ac1ffec9
 
9fd7fc4e
 	<section>
 		<title>Dependencies</title>
 		<section>
a118a328
 			<title>&kamailio; Modules</title>
9fd7fc4e
 			<para>
 			The following modules must be loaded before this module:
 			<itemizedlist>
 			<listitem>
 			<para>
 				<emphasis>TM - Transaction Module</emphasis>
 			</para>
 			</listitem>
ac1ffec9
 			<listitem>
 			<para>
 				<emphasis>RR - Record-Route Module</emphasis>, but only if
1c35849b
 				restore mode for From: URI is set to <quote>auto</quote>.
ac1ffec9
 			</para>
 			</listitem>
0f702f6e
 			<listitem>
 			<para>
 				<emphasis>Dialog Module</emphasis>, but only if
1c35849b
 				restore mode for From: URI is set to <quote>auto</quote> and
0f702f6e
 				you want uac_replace_from or uac_replace_to to store the values
 				of the URIs as dialog variables.
 			</para>
 			</listitem>
9fd7fc4e
 			</itemizedlist>
 			</para>
 		</section>
 		<section>
 			<title>External Libraries or Applications</title>
 			<para>
 				The following libraries or applications must be installed 
a118a328
 				before running &kamailio; with this module loaded:
9fd7fc4e
 				<itemizedlist>
 				<listitem>
 				<para>
 					<emphasis>None</emphasis>
 				</para>
 				</listitem>
 				</itemizedlist>
 			</para>
 		</section>
 	</section>
 
 	<section>
9114eebc
 		<title>Parameters</title>
fed1818b
 		<section id="uac.p.rr_from_store_param">
a14d3a92
 			<title><varname>rr_from_store_param</varname> (string)</title>
9fd7fc4e
 			<para>
ac1ffec9
 			Name of Record-Route header parameter that will be used to store 
18220b91
 			an encoded version of the original FROM URI.
9fd7fc4e
 			</para>
 			<para>
 				<emphasis>
ac1ffec9
 					This parameter is optional, it's default value being 
 					<quote>vsf</quote>.
9fd7fc4e
 				</emphasis>
 			</para>
 			<example>
a14d3a92
 				<title>Set <varname>rr_from_store_param</varname> parameter</title>
9fd7fc4e
 				<programlisting format="linespecific">
 ...
a14d3a92
 modparam("uac","rr_from_store_param","my_param")
9fd7fc4e
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.p.rr_to_store_param">
a14d3a92
 			<title><varname>rr_to_store_param</varname> (string)</title>
9fd7fc4e
 			<para>
a14d3a92
 			Name of Record-Route header parameter that will be used to store 
 			(encoded) the original TO URI.
 			</para>
 			<para>
 				<emphasis>
 					This parameter is optional, it's default value being 
 					<quote>vst</quote>.
 				</emphasis>
 			</para>
 			<example>
 				<title>Set <varname>rr_to_store_param</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
 modparam("uac","rr_to_store_param","my_param")
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.p.restore_mode">
a14d3a92
 			<title><varname>restore_mode</varname> (string)</title>
 			<para>
18220b91
 			There are 3 modes of restoring the original FROM URI and the original TO URI:
9fd7fc4e
 			<itemizedlist>
 			<listitem>
 				<para>
ac1ffec9
 				<quote>none</quote> - no information about original URI is 
0d49f516
 				stored; restoration is not possible.
9fd7fc4e
 				</para>
 			</listitem>
 			<listitem>
 				<para>
ac1ffec9
 				<quote>manual</quote> - all following replies will be restored,
 				but not also the sequential requests - this must be manually 
 				updated based on original URI.
9fd7fc4e
 				</para>
 			</listitem>
 			<listitem>
 				<para>
ac1ffec9
 				<quote>auto</quote> - all sequential requests and replies will 
f350ec8c
 				be automatically updated based on stored original URI. For this
 				option you have to set <quote>modparam("rr", "append_fromtag", 1)</quote>.
9fd7fc4e
 				</para>
 			</listitem>
 			</itemizedlist>
 			</para>
 			<para>
 				<emphasis>
ac1ffec9
 					This parameter is optional, it's default value being 
2a65cc55
 					<quote>auto</quote>.
9fd7fc4e
 				</emphasis>
 			</para>
 			<example>
a14d3a92
 				<title>Set <varname>restore_mode</varname> parameter
9fd7fc4e
 				</title>
 				<programlisting format="linespecific">
 ...
a14d3a92
 modparam("uac","restore_mode","auto")
43e1a792
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.p.restore_dlg">
ef0f8fd6
 			<title><varname>restore_dlg</varname> (int)</title>
43e1a792
 			<para>
 			If set to 1, the module uses dialog variables to store initial and
18220b91
 			new values for From/To headers. The Dialog module has to be loaded and
 			all calls that involve changes to From/To headers must be tracked.
43e1a792
 			</para>
 			<para>
 				<emphasis>
 					Default value of this parameter is 0.
 				</emphasis>
 			</para>
 			<example>
 				<title>Set <varname>restore_dlg</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
 modparam("uac", "restore_dlg", 1)
2a65cc55
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.p.restore_passwd">
a14d3a92
 			<title><varname>restore_passwd</varname> (string)</title>
2a65cc55
 			<para>
a14d3a92
 			String password to be used to encrypt the RR storing parameters. If
2a65cc55
 			empty, no encryption will be used.
 			</para>
 			<para>
 				<emphasis>
 					Default value of this parameter is empty.
 				</emphasis>
 			</para>
 			<example>
a14d3a92
 				<title>Set <varname>restore_passwd</varname> parameter</title>
2a65cc55
 				<programlisting format="linespecific">
 ...
a14d3a92
 modparam("uac","restore_passwd","my_secret_passwd")
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.p.restore_from_avp">
a14d3a92
 			<title><varname>restore_from_avp</varname> (string)</title>
 			<para>
 			If defined and restore_mode is manual or auto, the avp is used to save
 			the original from uri in order to be able to restore it in replies.
 			That makes sense, if the original-uri can not be extracted from the original
0f702f6e
 			request, e.g. if msg_apply_changes() was used after calling uac_replace_from()
 			or uac_replace_to().
 			</para>
 			<para>
 				If you create a dialog ( with dlg_manage() ) before calling uac_replace_from(),
 			this avp will not be needed. The values of the uris will be stored as dialog variables.
a14d3a92
 			</para>
 			<para><emphasis>
 					Default value of this parameter is empty.
 				</emphasis>
 			</para>
 			<example>
 				<title>Set <varname>restore_from_avp</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
0f702f6e
 modparam("uac","restore_from_avp","$avp(original_uri_from)")
a14d3a92
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.p.restore_to_avp">
a14d3a92
 			<title><varname>restore_to_avp</varname> (string)</title>
 			<para>
 			If defined and restore_mode is manual or auto, the avp is used to save
18220b91
 			the original To URI in order to be able to restore it in replies.
 			That makes sense if the original-uri can not be extracted from the original
a14d3a92
 			request, e.g. if msg_apply_changes() was used after calling uac_replace_to()  
 			</para>
0f702f6e
 			<para>
 				If you create a dialog ( with dlg_manage() ) before calling or uac_replace_to(),
 				this avp will not be needed. The values of the uris will be stored as dialog variables.
 			</para>
a14d3a92
 			<para><emphasis>
 					Default value of this parameter is empty.
 				</emphasis>
 			</para>
 			<example>
 				<title>Set <varname>restore_to_avp</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
0f702f6e
 modparam("uac","restore_to_avp","$avp(original_uri_to)")
9fd7fc4e
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.p.credential">
9fd7fc4e
 			<title><varname>credential</varname> (string)</title>
 			<para>
 			Contains a multiple definition of credentials used to perform
 			authentication.
 			</para>
 			<para>
 				<emphasis>
 					This parameter is required if UAC authentication is used.
 				</emphasis>
 			</para>
 			<example>
 				<title>Set <varname>credential</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
 modparam("uac","credential","username:domain:password")
5a24a1d1
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.p.auth-realm-avp-id">
5a24a1d1
 			<title><varname>auth_realm_avp</varname> (string)</title>
 			<para>
0507b848
 			The definition of an PV that might contain the realm to be used
5a24a1d1
 			to perform authentication.
 			</para>
0507b848
 			<para>
 			When the PV value is an empty string or NULL when uac_auth() is called,
 			the realm is taken from the reply and only username matching is done.
 			This can be used if the realm upstream will be using is not known in advance.
 			</para>
5a24a1d1
 			<para><emphasis>
 				If you define it, you also need to define 
 				<quote>auth_username_avp</quote> 
fed1818b
 				(<xref linkend="uac.p.auth-username-avp-id"/>) and 
5a24a1d1
 				<quote>auth_username_avp</quote> 
fed1818b
 				(<xref linkend="uac.p.auth-password-avp-id"/>).
5a24a1d1
 			</emphasis></para>
 			<example>
 				<title>Set <varname>auth_realm_avp</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
 modparam("uac","auth_realm_avp","$avp(i:10)")
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.p.auth-username-avp-id">
5a24a1d1
 			<title><varname>auth_username_avp</varname> (string)</title>
 			<para>
 			The definition of an AVP that might contain the username to be used
 			to perform authentication.
 			</para>
 			<para><emphasis>
 				If you define it, you also need to define 
 				<quote>auth_realm_avp</quote> 
fed1818b
 				(<xref linkend="uac.p.auth-realm-avp-id"/>) and 
5a24a1d1
 				<quote>auth_username_avp</quote> 
fed1818b
 				(<xref linkend="uac.p.auth-password-avp-id"/>).
5a24a1d1
 			</emphasis></para>
 			<example>
 				<title>Set <varname>auth_username_avp</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
 modparam("uac","auth_username_avp","$avp(i:11)")
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.p.auth-password-avp-id">
5a24a1d1
 			<title><varname>auth_password_avp</varname> (string)</title>
 			<para>
 			The definition of an AVP that might contain the password to be used
 			to perform authentication.
 			</para>
 			<para><emphasis>
 				If you define it, you also need to define 
 				<quote>auth_password_avp</quote> 
fed1818b
 				(<xref linkend="uac.p.auth-password-avp-id"/>) and 
5a24a1d1
 				<quote>auth_username_avp</quote> 
fed1818b
 				(<xref linkend="uac.p.auth-password-avp-id"/>).
5a24a1d1
 			</emphasis></para>
 			<example>
 				<title>Set <varname>auth_password_avp</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
 modparam("uac","auth_password_avp","$avp(i:12)")
679a7c11
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.p.reg-db-url-id">
679a7c11
 			<title><varname>reg_db_url</varname> (string)</title>
 			<para>
18220b91
 			DB URL to fetch account profiles for registration.
679a7c11
 			</para>
 			<example>
 				<title>Set <varname>reg_db_url</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
 modparam("uac", "reg_db_url",
0d9eec94
     "&defaultdb;")
679a7c11
 ...
 				</programlisting>
 			</example>
 		</section>
455b6408
 
fed1818b
 		<section id="uac.p.reg-timer-interval-id">
455b6408
 			<title><varname>reg_timer_interval</varname> (string)</title>
 			<para>
 			Timer interval (in seconds) at which registrations are managed, e.g. renewed as needed.  
 			</para>
 			<para>
 				<emphasis>
 				The default value is 90 seconds.
 				</emphasis>
 			</para>
 			
 			<example>
 				<title>Set <varname>reg_timer_inteval</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
 modparam("uac", "reg_timer_interval", 60)
 ...
 				</programlisting>
 			</example>
 		</section>
 
fed1818b
 		<section id="uac.p.reg-retry-interval-id">
f310fd10
 			<title><varname>reg_retry_interval</varname> (int)</title>
 			<para>
 			Failed registration attempts will be retried after this interval
 			(in seconds). The interval is not exact, retries may be
 			attempted as much as reg_timer_interval secs earlier.
 			If set to 0, failed registrations will be disabled permanently.
 			</para>
 			<para>The default value is 0 sec (disabled)</para>
 			<example>
 				<title>Set <varname>reg_retry_interval</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
 modparam("uac", "reg_retry_interval", 300)
 ...
 				</programlisting>
 			</example>
 		</section>
 
fed1818b
 		<section id="uac.p.reg-db-table-id">
eb1abe66
 			<title><varname>reg_db_table</varname> (string)</title>
 			<para>
 			DB table name to fetch user profiles for registration.
 			</para>
 			<para>
 				<emphasis>
 					This parameter is optional, it's default value being
 					<quote>uacreg</quote>.
 				</emphasis>
 			</para>
 			<example>
 				<title>Set <varname>reg_db_table</varname> parameter</title>
 				<programlisting format="linespecific">
 ...
 modparam("uac", "reg_db_table", "uacreg")
 ...
 				</programlisting>
 			</example>
 		</section>
455b6408
 
fed1818b
 		<section id="uac.p.reg-contact-addr-id">
c244c7ae
 			<title><varname>reg_contact_addr</varname> (string)</title>
 			<para>
 			Address to be used to build contact address. Must be at least
 			host part, can have port and parameters. Must not include 'sip:'.
18220b91
 			The username part of the Contact: URI will be the L_UUID field in the database.
c244c7ae
 			</para>
 			<example>
 				<title>Set <varname>reg_contact_addr</varname> parameter</title>
 				<programlisting format="linespecific">
455b6408
 ...
 modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
 ...
c244c7ae
 				</programlisting>
 			</example>
 		</section>
9fd7fc4e
 
c244c7ae
 	</section>
9fd7fc4e
 
 	<section>
9114eebc
 		<title>Functions</title>
fed1818b
 		<section id="uac.f.uac_replace_from">
9fd7fc4e
 			<title>
 				<function moreinfo="none">uac_replace_from(display,uri)</function>
 			</title>
 			<para>
 			Replace in FROM header the <emphasis>display</emphasis> name and
 			the <emphasis>URI</emphasis> part.
 			</para>
de71621a
 			<para>
 			<emphasis>display</emphasis> and <emphasis>URI</emphasis> parameters
 			can include pseudo-variables.
 			</para>
7b56ffd7
 			<para>
a6023f59
 			This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
7b56ffd7
 			</para>
251c0218
 			<para>NOTE: Previous versions of this function added double quotes automatically to 
 			display variable. That is no longer the case, if you expect that behavior, you will 
 			have to add the quotes by yourself.
 			</para>
0f702f6e
 			<para>
 			If you set restore_mode to AUTO, the URI will be modified automatically in
 			all subsequent requests and replies in that dialog.
 			</para>
 			<para>
 				There are two ways in which the AUTO mode can be achieved.
 			</para>
 			<para>
 				One uses the rr module and appends to the Record-Route header a parameter
 				containing some strings from which the original and new URI can be computed.
 				The problem with this mode is that it relies on the fact the parties will
 				send the Route exactly as it was received. In case there is a change, the
 				resulting URIs will not be correct.
 			</para>
 			<para>
 				The other one uses the dialog module to store the original and new URI.
 				If you already use dialog module in your configuration, this is the advisable mode.
 				All you need to do to use this is to call dlg_manage() before calling uac_replace_from().
 				It works by storing the URIs as dialog variables and registering callbacks in dialog 
 				module for in dialog requests.
 			</para>
9fd7fc4e
 			<example>
 				<title><function>uac_replace_from</function> usage</title>
 				<programlisting format="linespecific">
 ...
ac1ffec9
 # replace both display and uri
de71621a
 uac_replace_from("$avp(s:display)","$avp(s:uri)");
ac1ffec9
 # replace only display and do not touch uri
251c0218
 uac_replace_from("batman","");   # display is replaced with: batman
 uac_replace_from("\"batman\"","");  # display is replaced with: "batman"
ac1ffec9
 # remove display and replace uri
 uac_replace_from("","sip:robin@gotham.org");
 # remove display and do not touch uri
 uac_replace_from("","");
9fd7fc4e
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.f.uac_replace_from(uri)">
9fd7fc4e
 			<title>
 				<function moreinfo="none">uac_replace_from(uri)</function>
 			</title>
 			<para>
67d29487
 				Replace in FROM header the <emphasis>URI</emphasis> part
9fd7fc4e
 				without altering the display name.
 			</para>
de71621a
 			<para>
 			<emphasis>URI</emphasis> parameter can include pseudo-variables.
 			</para>
7b56ffd7
 			<para>
a6023f59
 			This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
7b56ffd7
 			</para>
9fd7fc4e
 			<example>
 				<title><function>uac_replace_from</function> usage</title>
 				<programlisting format="linespecific">
 ...
 uac_replace_from("sip:batman@gotham.org");
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.f.uac_restore_from()">
9fd7fc4e
 			<title>
 				<function moreinfo="none">uac_restore_from()</function>
 			</title>
 			<para>
 			This function will check if the FROM URI was modified and will
 			use the information stored in header parameter to restore
 			the original FROM URI value.
 			</para>
7b56ffd7
 			<para>
 			This function can be used from REQUEST_ROUTE.
 			</para>
9fd7fc4e
 			<example>
 				<title><function>uac_restore_from</function> usage</title>
 				<programlisting format="linespecific">
 ...
 uac_restore_from();
a14d3a92
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.f.uac_replace_to(display,uri)">
a14d3a92
 		<title>
 				<function moreinfo="none">uac_replace_to(display,uri)</function>
 			</title>
 			<para>
 			Replace in TO header the <emphasis>display</emphasis> name and
 			the <emphasis>URI</emphasis> part.
 			</para>
 			<para>
 			<emphasis>display</emphasis> and <emphasis>URI</emphasis> parameters
 			can include pseudo-variables.
 			</para>
 			<para>
 			This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
 			</para>
251c0218
 			<para>NOTE: Previous versions of this function added double quotes automatically to 
 			display variable. That is no longer the case, if you expect that behavior, you will 
 			have to add the quotes by yourself.
 			</para>
a14d3a92
 			<example>
 				<title><function>uac_replace_to</function> usage</title>
 				<programlisting format="linespecific">
 ...
 # replace both display and uri
0f702f6e
 uac_replace_to("$avp(display)","$avp(uri)");
a14d3a92
 # replace only display and do not touch uri
251c0218
 uac_replace_to("batman","");   # display is replaced with: batman
 uac_replace_to("\"batman\"","");  # display is replaced with: "batman"
a14d3a92
 # remove display and replace uri
 uac_replace_to("","sip:robin@gotham.org");
 # remove display and do not touch uri
 uac_replace_to("","");
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.f.uac_replace_to(uri)">
a14d3a92
 			<title>
 				<function moreinfo="none">uac_replace_to(uri)</function>
 			</title>
 			<para>
 				Replace in TO header the <emphasis>URI</emphasis> part
 				without altering the display name.
 			</para>
 			<para>
 			<emphasis>URI</emphasis> parameter can include pseudo-variables.
 			</para>
 			<para>
 			This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
 			</para>
0f702f6e
 			<para>
 			If you set restore_mode to AUTO, the URI will be modified automatically in
 			all subsequent requests and replies in that dialog.
 			</para>
 			<para>
 				There are two ways in which the AUTO mode can be achieved.
 			</para>
 			<para>
 				One uses the rr module and appends to the Record-Route header a parameter
 				containing some strings from which the original and new URI can be computed.
 				The problem with this mode is that it relies on the fact the parties will
 				send the Route exactly as it was received. In case there is a change, the
 				resulting URIs will not be correct.
 			</para>
 			<para>
 				The other one uses the dialog module to store the original and new URI.
 				If you already use dialog module in your configuration, this is the advisable mode.
 				All you need to do to use this is to call dlg_manage() before calling uac_replace_to().
 				It works by storing the URIs as dialog variables and registering callbacks in dialog 
 				module for in dialog requests.
 			</para>
 
a14d3a92
 			<example>
 				<title><function>uac_replace_to</function> usage</title>
 				<programlisting format="linespecific">
 ...
 uac_replace_to("sip:batman@gotham.org");
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.f.uac_restore_to()">
a14d3a92
 			<title>
 				<function moreinfo="none">uac_restore_to()</function>
 			</title>
 			<para>
 			This function will check if the TO URI was modified and will
 			use the information stored in header parameter to restore
 			the original TO URI value.
 			</para>
 			<para>
 			This function can be used from REQUEST_ROUTE.
 			</para>
 			<example>
 				<title><function>uac_restore_to</function> usage</title>
 				<programlisting format="linespecific">
 ...
 uac_restore_to();
9fd7fc4e
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.f.uac_auth()">
9fd7fc4e
 			<title>
 				<function moreinfo="none">uac_auth()</function>
 			</title>
 			<para>
 			This function can be called only from failure route and will 
 			build the authentication response header and insert it into the
 			request without sending anything.
 			</para>
7b56ffd7
 			<para>
 			This function can be used from FAILURE_ROUTE.
 			</para>
9fd7fc4e
 			<example>
 				<title><function>uac_auth</function> usage</title>
 				<programlisting format="linespecific">
 ...
 uac_auth();
416b960c
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.f.uac_req_send()">
416b960c
 			<title>
ce5ecd83
 				<function moreinfo="none">uac_req_send()</function>
416b960c
 			</title>
 			<para>
 			This function sends a SIP message from the configuration file.
 			The message is built out of $uac_req(...) pseudo-variable.
 			</para>
 			<para>
 			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
 			BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.
 			</para>
 			<example>
ce5ecd83
 				<title><function>uac_req_send</function> usage</title>
416b960c
 				<programlisting format="linespecific">
 ...
 $uac_req(method)="OPTIONS";
 $uac_req(ruri)="sip:kamailio.org";
 $uac_req(furi)="sip:kamailio.org";
 $uac_req(turi)="sip:kamailio.org";
121c5a49
 $uac_req(callid)=$(mb{s.md5});
ce5ecd83
 uac_req_send();
679a7c11
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.f.uac_reg_lookup(uuid, dst)">
679a7c11
 			<title>
 				<function moreinfo="none">uac_reg_lookup(uuid, dst)</function>
 			</title>
 			<para>
 			This function sets the PV dst to SIP URI that correspond to uuid
 			in uac registations table. uuid and dst must be pseudo-variables.
 			</para>
 			<para>
 			This function can be used from ANY_ROUTE.
 			</para>
 			<example>
 				<title><function>uac_reg_lookup</function> usage</title>
 				<programlisting format="linespecific">
 ...
 
 if(uac_reg_lookup("$rU", "$ru"))
 {
     lookup("location");
 }
30bec8e6
 ...
 				</programlisting>
 			</example>
 		</section>
fed1818b
 		<section id="uac.f.uac_reg_request_to(user, mode)">
30bec8e6
 			<title>
 				<function moreinfo="none">uac_reg_request_to(user, mode)</function>
 			</title>
 			<para>
 			This function can be used to send an authenticated request to a remote user in 
 			the uac registrations table. It sets the request-uri, dst-uri and auth_*_avp
 			pv's to the values that correspond to the supplied user.
 			</para>
 			<para>
 			The mode indicates whether the user should match the local uuid (mode=0), or the username (mode=1).
 			</para>
 			<para>
 			The auth_*_avp module parameters must be set to valid pv&apos;s.
 			</para>
 			<para>
 			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
 			</para>
 			<example>
 				<title><function>uac_reg_request_to</function> usage</title>
 				<programlisting format="linespecific">
 ...
 
 if(uac_reg_request_to("$fU", 0))
 {
 	xlog("L_NOTICE", "Found remote user [$rU] on [$rd] via [$du]");
 	t_on_failure("REMOTE_AUTH");
 
 	t_relay()
 }
 ...
 failure_route[REMOTE_AUTH] {
 	if ($T_reply_code == 401 or $T_reply_code == 407) {
 		xlog("L_NOTICE", "Remote asked for authentication");
 		uac_auth()
 	}
 }
9fd7fc4e
 ...
 				</programlisting>
 			</example>
 		</section>
 	</section>
416b960c
 	<section>
 		<title>Exported pseudo-variables</title>
 		<itemizedlist>
 			<listitem><para>
 				<emphasis>$uac_req(key)</emphasis>
 			</para></listitem>
 		</itemizedlist>
 		<para>
 		Exported pseudo-variables are documented at &kamwikilink;.
 		</para>
 	</section>
28e604d1
 	<section>
 		<title>Remote Registration</title>
 		<para>
 		The module can register contact addresses to remote REGISTRAR servers.
 		You have to add records to uacreg table. The table stores following
 		attributes:
 		</para>
 
 		<itemizedlist>
 			<listitem><para>
 			<emphasis>l_uuid</emphasis> - local unique user id, e.g.,:
 			12345678
 			</para></listitem>
 		</itemizedlist>
 		<itemizedlist>
 			<listitem><para>
 			<emphasis>l_username</emphasis> - local user name, e.g.,: test
 			</para></listitem>
 		</itemizedlist>
 		<itemizedlist>
 			<listitem><para>
 			<emphasis>l_domain</emphasis> - local domain, e.g.,:
 			mysipserver.com
 			</para></listitem>
 		</itemizedlist>
 		<itemizedlist>
 			<listitem><para>
 			<emphasis>r_username</emphasis> - remote username, e.g.,:
 			test123
 			</para></listitem>
 		</itemizedlist>
 		<itemizedlist>
 			<listitem><para>
 			<emphasis>r_domain</emphasis> - remote domain, e.g.,:
 			sipprovider.com
 			</para></listitem>
 		</itemizedlist>
 		<itemizedlist>
 			<listitem><para>
 			<emphasis>realm</emphasis> - remote relam, e.g.,:
 			sipprovider.com
 			</para></listitem>
 		</itemizedlist>
 		<itemizedlist>
 			<listitem><para>
 			<emphasis>auth_username</emphasis> - authentication username,
 			e.g.,: test123
 			</para></listitem>
 		</itemizedlist>
 		<itemizedlist>
 			<listitem><para>
 			<emphasis>auth_password</emphasis> - authentication password,
 			e.g.,: xxxxxx
 			</para></listitem>
 		</itemizedlist>
 		<itemizedlist>
 			<listitem><para>
 			<emphasis>auth_proxy</emphasis> - SIP address of authentication
 			proxy, e.g.,: sip:sipprovider.com
 			</para></listitem>
 		</itemizedlist>
 		<itemizedlist>
 			<listitem><para>
 			<emphasis>expires</emphasis> - expiration time for registration,
 			in seconds, e.g.,: 360
 			</para></listitem>
 		</itemizedlist>
 
 		<para>
 		The module takes care of sending REGISTER and refresh registrations
 		before they expire.
 		</para>
 		<para>
 		When calls come in, you have to run uac_reg_lookup() that will detect
 		if the call is coming from a remote SIP provider and can change the
 		R-URI to local username@domain. Afterwards you can run location lookup.
 		</para>
 
 		<example>
 		<title><function>lookup remote registrations</function> usage</title>
 			<programlisting format="linespecific">
 ...
     if(uac_reg_lookup("$rU", "$ru")) {
         xlog("request from a remote SIP provider [$ou => $ru]\n");
     }
     lookup("location");
 ...
 			</programlisting>
 		</example>
 	</section>
9fd7fc4e
 </chapter>