@@ -14,9 +14,9 @@ Ramona-Elena Modroiu

    <ramona@rosdev.ro>

-   Copyright © 2009-2010 asipto.com

+   Copyright � 2009-2010 asipto.com

-   Copyright © 2005 Voice Sistem

+   Copyright � 2005 Voice Sistem

      __________________________________________________________________

    Table of Contents

@@ -34,15 +34,16 @@ Ramona-Elena Modroiu

               3.1. rr_from_store_param (string)

               3.2. rr_to_store_param (string)

               3.3. restore_mode (string)

-              3.4. restore_passwd (string)

-              3.5. restore_from_avp (string)

-              3.6. restore_to_avp (string)

-              3.7. credential (string)

-              3.8. auth_realm_avp (string)

-              3.9. auth_username_avp (string)

-              3.10. auth_password_avp (string)

-              3.11. reg_db_url (string)

-              3.12. reg_timer_interval (string)

+              3.4. restore_mode (int)

+              3.5. restore_passwd (string)

+              3.6. restore_from_avp (string)

+              3.7. restore_to_avp (string)

+              3.8. credential (string)

+              3.9. auth_realm_avp (string)

+              3.10. auth_username_avp (string)

+              3.11. auth_password_avp (string)

+              3.12. reg_db_url (string)

+              3.13. reg_timer_interval (string)

         4. reg_contact_addr (string)

         5. Functions

@@ -66,27 +67,28 @@ Ramona-Elena Modroiu

    1.1. Set rr_from_store_param parameter

    1.2. Set rr_to_store_param parameter

    1.3. Set restore_mode parameter

-   1.4. Set restore_passwd parameter

-   1.5. Set restore_from_avp parameter

-   1.6. Set restore_to_avp parameter

-   1.7. Set credential parameter

-   1.8. Set auth_realm_avp parameter

-   1.9. Set auth_username_avp parameter

-   1.10. Set auth_password_avp parameter

-   1.11. Set reg_db_url parameter

-   1.12. Set reg_timer_inteval parameter

-   1.13. Set reg_contact_addr parameter

-   1.14. uac_replace_from usage

+   1.4. Set restore_dlg parameter

+   1.5. Set restore_passwd parameter

+   1.6. Set restore_from_avp parameter

+   1.7. Set restore_to_avp parameter

+   1.8. Set credential parameter

+   1.9. Set auth_realm_avp parameter

+   1.10. Set auth_username_avp parameter

+   1.11. Set auth_password_avp parameter

+   1.12. Set reg_db_url parameter

+   1.13. Set reg_timer_inteval parameter

+   1.14. Set reg_contact_addr parameter

    1.15. uac_replace_from usage

-   1.16. uac_restore_from usage

-   1.17. uac_replace_to usage

+   1.16. uac_replace_from usage

+   1.17. uac_restore_from usage

    1.18. uac_replace_to usage

-   1.19. uac_restore_to usage

-   1.20. uac_auth usage

-   1.21. uac_req_send usage

-   1.22. uac_reg_lookup usage

-   1.23. uac_reg_request_to usage

-   1.24. lookup remote registrations usage

+   1.19. uac_replace_to usage

+   1.20. uac_restore_to usage

+   1.21. uac_auth usage

+   1.22. uac_req_send usage

+   1.23. uac_reg_lookup usage

+   1.24. uac_reg_request_to usage

+   1.25. lookup remote registrations usage

 Chapter 1. Admin Guide

@@ -103,15 +105,16 @@ Chapter 1. Admin Guide

         3.1. rr_from_store_param (string)

         3.2. rr_to_store_param (string)

         3.3. restore_mode (string)

-        3.4. restore_passwd (string)

-        3.5. restore_from_avp (string)

-        3.6. restore_to_avp (string)

-        3.7. credential (string)

-        3.8. auth_realm_avp (string)

-        3.9. auth_username_avp (string)

-        3.10. auth_password_avp (string)

-        3.11. reg_db_url (string)

-        3.12. reg_timer_interval (string)

+        3.4. restore_mode (int)

+        3.5. restore_passwd (string)

+        3.6. restore_from_avp (string)

+        3.7. restore_to_avp (string)

+        3.8. credential (string)

+        3.9. auth_realm_avp (string)

+        3.10. auth_username_avp (string)

+        3.11. auth_password_avp (string)

+        3.12. reg_db_url (string)

+        3.13. reg_timer_interval (string)

    4. reg_contact_addr (string)

    5. Functions

@@ -158,9 +161,9 @@ Chapter 1. Admin Guide

    The following modules must be loaded before this module:

      * TM - Transaction Module

      * RR - Record-Route Module, but only if restore mode for FROM URI is

-       set to “auto”.

+       set to "auto".

      * Dialog Module, but only if restore mode for FROM URI is set to

-       “auto” and you want uac_replace_from or uac_replace_to to store the

+       "auto" and you want uac_replace_from or uac_replace_to to store the

        values of the URIs as dialog variables.

 2.2. External Libraries or Applications

@@ -174,22 +177,23 @@ Chapter 1. Admin Guide

    3.1. rr_from_store_param (string)

    3.2. rr_to_store_param (string)

    3.3. restore_mode (string)

-   3.4. restore_passwd (string)

-   3.5. restore_from_avp (string)

-   3.6. restore_to_avp (string)

-   3.7. credential (string)

-   3.8. auth_realm_avp (string)

-   3.9. auth_username_avp (string)

-   3.10. auth_password_avp (string)

-   3.11. reg_db_url (string)

-   3.12. reg_timer_interval (string)

+   3.4. restore_mode (int)

+   3.5. restore_passwd (string)

+   3.6. restore_from_avp (string)

+   3.7. restore_to_avp (string)

+   3.8. credential (string)

+   3.9. auth_realm_avp (string)

+   3.10. auth_username_avp (string)

+   3.11. auth_password_avp (string)

+   3.12. reg_db_url (string)

+   3.13. reg_timer_interval (string)

 3.1. rr_from_store_param (string)

    Name of Record-Route header parameter that will be used to store

    (encoded) the original FROM URI.

-   This parameter is optional, it's default value being “vsf”.

+   This parameter is optional, it's default value being "vsf".

    Example 1.1. Set rr_from_store_param parameter

 ...

@@ -201,7 +205,7 @@ modparam("uac","rr_from_store_param","my_param")

    Name of Record-Route header parameter that will be used to store

    (encoded) the original TO URI.

-   This parameter is optional, it's default value being “vst”.

+   This parameter is optional, it's default value being "vst".

    Example 1.2. Set rr_to_store_param parameter

 ...

@@ -212,34 +216,47 @@ modparam("uac","rr_to_store_param","my_param")

    There are 3 mode of restoring the original FROM URI and the original TO

    URI:

-     * “none” - no information about original URI is stored; restoration

+     * "none" - no information about original URI is stored; restoration

        is not possible.

-     * “manual” - all following replies will be restored, but not also the

+     * "manual" - all following replies will be restored, but not also the

        sequential requests - this must be manually updated based on

        original URI.

-     * “auto” - all sequential requests and replies will be automatically

+     * "auto" - all sequential requests and replies will be automatically

        updated based on stored original URI.

-   This parameter is optional, it's default value being “auto”.

+   This parameter is optional, it's default value being "auto".

    Example 1.3. Set restore_mode parameter

 ...

 modparam("uac","restore_mode","auto")

 ...

-3.4. restore_passwd (string)

+3.4. restore_mode (int)

+

+   If set to 1, the module uses dialog variables to store initial and new

+   values for From/To headers. Dialog module has to be loaded and all

+   calls that involve chages to From/To headers must be tracked.

+

+   Default value of this parameter is 0.

+

+   Example 1.4. Set restore_dlg parameter

+...

+modparam("uac", "restore_dlg", 1)

+...

+

+3.5. restore_passwd (string)

    String password to be used to encrypt the RR storing parameters. If

    empty, no encryption will be used.

    Default value of this parameter is empty.

-   Example 1.4. Set restore_passwd parameter

+   Example 1.5. Set restore_passwd parameter

 ...

 modparam("uac","restore_passwd","my_secret_passwd")

 ...

-3.5. restore_from_avp (string)

+3.6. restore_from_avp (string)

    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.

@@ -253,12 +270,12 @@ modparam("uac","restore_passwd","my_secret_passwd")

    Default value of this parameter is empty.

-   Example 1.5. Set restore_from_avp parameter

+   Example 1.6. Set restore_from_avp parameter

 ...

 modparam("uac","restore_from_avp","$avp(original_uri_from)")

 ...

-3.6. restore_to_avp (string)

+3.7. restore_to_avp (string)

    If defined and restore_mode is manual or auto, the avp is used to save

    the original to uri in order to be able to restore it in replies. That

@@ -272,83 +289,83 @@ modparam("uac","restore_from_avp","$avp(original_uri_from)")

    Default value of this parameter is empty.

-   Example 1.6. Set restore_to_avp parameter

+   Example 1.7. Set restore_to_avp parameter

 ...

 modparam("uac","restore_to_avp","$avp(original_uri_to)")

 ...

-3.7. credential (string)

+3.8. credential (string)

    Contains a multiple definition of credentials used to perform

    authentication.

    This parameter is required if UAC authentication is used.

-   Example 1.7. Set credential parameter

+   Example 1.8. Set credential parameter

 ...

 modparam("uac","credential","username:domain:password")

 ...

-3.8. auth_realm_avp (string)

+3.9. auth_realm_avp (string)

    The definition of an AVP that might contain the realm to be used to

    perform authentication.

-   If you define it, you also need to define “auth_username_avp”

-   (Section 3.9, “auth_username_avp (string)”) and “auth_username_avp”

-   (Section 3.10, “auth_password_avp (string)”).

+   If you define it, you also need to define "auth_username_avp"

+   (Section 3.10, "auth_username_avp (string)") and "auth_username_avp"

+   (Section 3.11, "auth_password_avp (string)").

-   Example 1.8. Set auth_realm_avp parameter

+   Example 1.9. Set auth_realm_avp parameter

 ...

 modparam("uac","auth_realm_avp","$avp(i:10)")

 ...

-3.9. auth_username_avp (string)

+3.10. auth_username_avp (string)

    The definition of an AVP that might contain the username to be used to

    perform authentication.

-   If you define it, you also need to define “auth_realm_avp”

-   (Section 3.8, “auth_realm_avp (string)”) and “auth_username_avp”

-   (Section 3.10, “auth_password_avp (string)”).

+   If you define it, you also need to define "auth_realm_avp"

+   (Section 3.9, "auth_realm_avp (string)") and "auth_username_avp"

+   (Section 3.11, "auth_password_avp (string)").

-   Example 1.9. Set auth_username_avp parameter

+   Example 1.10. Set auth_username_avp parameter

 ...

 modparam("uac","auth_username_avp","$avp(i:11)")

 ...

-3.10. auth_password_avp (string)

+3.11. auth_password_avp (string)

    The definition of an AVP that might contain the password to be used to

    perform authentication.

-   If you define it, you also need to define “auth_password_avp”

-   (Section 3.10, “auth_password_avp (string)”) and “auth_username_avp”

-   (Section 3.10, “auth_password_avp (string)”).

+   If you define it, you also need to define "auth_password_avp"

+   (Section 3.11, "auth_password_avp (string)") and "auth_username_avp"

+   (Section 3.11, "auth_password_avp (string)").

-   Example 1.10. Set auth_password_avp parameter

+   Example 1.11. Set auth_password_avp parameter

 ...

 modparam("uac","auth_password_avp","$avp(i:12)")

 ...

-3.11. reg_db_url (string)

+3.12. reg_db_url (string)

    DB URL to fetch user profiles for registration.

-   Example 1.11. Set reg_db_url parameter

+   Example 1.12. Set reg_db_url parameter

 ...

 modparam("uac", "reg_db_url",

     "mysql://openser:openserrw@localhost/openser")

 ...

-3.12. reg_timer_interval (string)

+3.13. reg_timer_interval (string)

    Timer interval (in seconds) at which registrations are managed, e.g.

    renewed as needed.

    The default value is 90 seconds.

-   Example 1.12. Set reg_timer_inteval parameter

+   Example 1.13. Set reg_timer_inteval parameter

 ...

 modparam("uac", "reg_timer_interval", 60)

 ...

@@ -358,7 +375,7 @@ modparam("uac", "reg_timer_interval", 60)

    Address to be used to build contact address. Must be at least host

    part, can have port and parameters. Must not include 'sip:'.

-   Example 1.13. Set reg_contact_addr parameter

+   Example 1.14. Set reg_contact_addr parameter

 ...

 modparam("uac", "reg_contact_addr", "192.168.1.2:5080")

 ...

@@ -376,7 +393,7 @@ modparam("uac", "reg_contact_addr", "192.168.1.2:5080")

    5.9. uac_reg_lookup(uuid, dst)

    5.10. uac_reg_request_to(user, mode)

-5.1.  uac_replace_from(display,uri)

+5.1. uac_replace_from(display,uri)

    Replace in FROM header the display name and the URI part.

@@ -402,7 +419,7 @@ modparam("uac", "reg_contact_addr", "192.168.1.2:5080")

    dialog variables and registering callbacks in dialog module for in

    dialog requests.

-   Example 1.14. uac_replace_from usage

+   Example 1.15. uac_replace_from usage

 ...

 # replace both display and uri

 uac_replace_from("$avp(s:display)","$avp(s:uri)");

@@ -414,7 +431,7 @@ uac_replace_from("","sip:robin@gotham.org");

 uac_replace_from("","");

 ...

-5.2.  uac_replace_from(uri)

+5.2. uac_replace_from(uri)

    Replace in FROM header the URI part without altering the display name.

@@ -422,12 +439,12 @@ uac_replace_from("","");

    This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.

-   Example 1.15. uac_replace_from usage

+   Example 1.16. uac_replace_from usage

 ...

 uac_replace_from("sip:batman@gotham.org");

 ...

-5.3.  uac_restore_from()

+5.3. uac_restore_from()

    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

@@ -435,12 +452,12 @@ uac_replace_from("sip:batman@gotham.org");

    This function can be used from REQUEST_ROUTE.

-   Example 1.16. uac_restore_from usage

+   Example 1.17. uac_restore_from usage

 ...

 uac_restore_from();

 ...

-5.4.  uac_replace_to(display,uri)

+5.4. uac_replace_to(display,uri)

    Replace in TO header the display name and the URI part.

@@ -448,7 +465,7 @@ uac_restore_from();

    This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.

-   Example 1.17. uac_replace_to usage

+   Example 1.18. uac_replace_to usage

 ...

 # replace both display and uri

 uac_replace_to("$avp(display)","$avp(uri)");

@@ -460,7 +477,7 @@ uac_replace_to("","sip:robin@gotham.org");

 uac_replace_to("","");

 ...

-5.5.  uac_replace_to(uri)

+5.5. uac_replace_to(uri)

    Replace in TO header the URI part without altering the display name.

@@ -486,12 +503,12 @@ uac_replace_to("","");

    variables and registering callbacks in dialog module for in dialog

    requests.

-   Example 1.18. uac_replace_to usage

+   Example 1.19. uac_replace_to usage

 ...

 uac_replace_to("sip:batman@gotham.org");

 ...

-5.6.  uac_restore_to()

+5.6. uac_restore_to()

    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

@@ -499,12 +516,12 @@ uac_replace_to("sip:batman@gotham.org");

    This function can be used from REQUEST_ROUTE.

-   Example 1.19. uac_restore_to usage

+   Example 1.20. uac_restore_to usage

 ...

 uac_restore_to();

 ...

-5.7.  uac_auth()

+5.7. uac_auth()

    This function can be called only from failure route and will build the

    authentication response header and insert it into the request without

@@ -512,12 +529,12 @@ uac_restore_to();

    This function can be used from FAILURE_ROUTE.

-   Example 1.20. uac_auth usage

+   Example 1.21. uac_auth usage

 ...

 uac_auth();

 ...

-5.8.  uac_req_send()

+5.8. uac_req_send()

    This function sends a SIP message from the configuration file. The

    message is built out of $uac_req(...) pseudo-variable.

@@ -525,7 +542,7 @@ uac_auth();

    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,

    BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.

-   Example 1.21. uac_req_send usage

+   Example 1.22. uac_req_send usage

 ...

 $uac_req(method)="OPTIONS";

 $uac_req(ruri)="sip:kamailio.org";

@@ -534,14 +551,14 @@ $uac_req(turi)="sip:kamailio.org";

 uac_req_send();

 ...

-5.9.  uac_reg_lookup(uuid, dst)

+5.9. uac_reg_lookup(uuid, dst)

    This function sets the PV dst to SIP URI that correspond to uuid in uac

    registations table. uuid and dst must be pseudo-variables.

    This function can be used from ANY_ROUTE.

-   Example 1.22. uac_reg_lookup usage

+   Example 1.23. uac_reg_lookup usage

 ...

 if(uac_reg_lookup("$rU", "$ru"))

@@ -550,7 +567,7 @@ if(uac_reg_lookup("$rU", "$ru"))

 }

 ...

-5.10.  uac_reg_request_to(user, mode)

+5.10. uac_reg_request_to(user, mode)

    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

@@ -564,7 +581,7 @@ if(uac_reg_lookup("$rU", "$ru"))

    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,

    BRANCH_ROUTE.

-   Example 1.23. uac_reg_request_to usage

+   Example 1.24. uac_reg_request_to usage

 ...

 if(uac_reg_request_to("$fU", 0))

@@ -623,7 +640,7 @@ failure_route[REMOTE_AUTH] {

    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.

-   Example 1.24. lookup remote registrations usage

+   Example 1.25. lookup remote registrations usage

 ...

     if(uac_reg_lookup("$rU", "$ru")) {

         xlog("request from a remote SIP provider [$ou => $ru]\n");

@@ -176,6 +176,27 @@ modparam("uac","rr_to_store_param","my_param")

 				<programlisting format="linespecific">

 ...

 modparam("uac","restore_mode","auto")

+...

+				</programlisting>

+			</example>

+		</section>

+		<section>

+			<title><varname>restore_mode</varname> (int)</title>

+			<para>

+			If set to 1, the module uses dialog variables to store initial and

+			new values for From/To headers. Dialog module has to be loaded and

+			all calls that involve chages to From/To headers must be tracked.

+			</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)

 ...

 				</programlisting>

 			</example>