UAC Module

Ramona-Elena Modroiu

   <ramona@rosdev.ro>

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Ramona-Elena Modroiu

   <ramona@rosdev.ro>

   Copyright © 2009-2010 asipto.com

   Copyright © 2005 Voice Sistem
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. rr_from_store_param (string)
              3.2. rr_to_store_param (string)
              3.3. restore_mode (string)
              3.4. restore_dlg (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 (int)
              3.14. reg_retry_interval (int)
              3.15. reg_random_delay (int)
              3.16. reg_db_table (string)
              3.17. reg_contact_addr (string)
              3.18. reg_keep_callid (int)
              3.19. reg_active (int)
              3.20. reg_gc_interval (int)
              3.21. default_socket (str)
              3.22. event_callback (str)

        4. Functions

              4.1. uac_replace_from(display,uri)
              4.2. uac_replace_from(uri)
              4.3. uac_restore_from()
              4.4. uac_replace_to(display,uri)
              4.5. uac_replace_to(uri)
              4.6. uac_restore_to()
              4.7. uac_auth([mode])
              4.8. uac_auth_mode(vmode)
              4.9. uac_req_send()
              4.10. uac_reg_lookup(uuid, dst)
              4.11. uac_reg_status(uuid)
              4.12. uac_reg_request_to(user, mode)
              4.13. uac_reg_enable(attr, val)
              4.14. uac_reg_disable(attr, val)
              4.15. uac_reg_refresh(luuid)

        5. Pseudo Variables
        6. Event Routes

              6.1. event_route[uac:reply]

        7. Counters
        8. RPC Commands

              8.1. uac.reg_dump
              8.2. uac.reg_info
              8.3. uac.reg_enable
              8.4. uac.reg_disable
              8.5. uac.reg_reload
              8.6. uac.reg_refresh
              8.7. uac.reg_active
              8.8. uac.reg_add
              8.9. uac.reg_remove

        9. Remote Registration

   List of Examples

   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_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_interval parameter
   1.14. Set reg_retry_interval parameter
   1.15. Set reg_random_delay parameter
   1.16. Set reg_db_table parameter
   1.17. Set reg_contact_addr parameter
   1.18. Set reg_keep_callid parameter
   1.19. Set reg_active parameter
   1.20. Set reg_gc_interval parameter
   1.21. Set the “default_socket” parameter
   1.22. Set event_callback parameter
   1.23. uac_replace_from usage
   1.24. uac_replace_from usage
   1.25. uac_restore_from usage
   1.26. uac_replace_to usage
   1.27. uac_replace_to usage
   1.28. uac_restore_to usage
   1.29. uac_auth usage
   1.30. uac_auth_mode usage
   1.31. uac_req_send usage
   1.32. uac_reg_lookup usage
   1.33. uac_reg_status usage
   1.34. uac_reg_request_to usage
   1.35. uac_reg_enable usage
   1.36. uac_reg_disable usage
   1.37. uac_reg_refresh usage
   1.38. event_route[uac:reply] usage
   1.39. uac.reg_dump usage
   1.40. uac.reg_info usage
   1.41. uac.reg_enable usage
   1.42. uac.reg_disable usage
   1.43. uac.reg_reload usage
   1.44. uac.reg_refresh usage
   1.45. uac.reg_active usage
   1.46. uac.reg_add usage
   1.47. uac.reg_remove usage
   1.48. lookup remote registrations usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. rr_from_store_param (string)
        3.2. rr_to_store_param (string)
        3.3. restore_mode (string)
        3.4. restore_dlg (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 (int)
        3.14. reg_retry_interval (int)
        3.15. reg_random_delay (int)
        3.16. reg_db_table (string)
        3.17. reg_contact_addr (string)
        3.18. reg_keep_callid (int)
        3.19. reg_active (int)
        3.20. reg_gc_interval (int)
        3.21. default_socket (str)
        3.22. event_callback (str)

   4. Functions

        4.1. uac_replace_from(display,uri)
        4.2. uac_replace_from(uri)
        4.3. uac_restore_from()
        4.4. uac_replace_to(display,uri)
        4.5. uac_replace_to(uri)
        4.6. uac_restore_to()
        4.7. uac_auth([mode])
        4.8. uac_auth_mode(vmode)
        4.9. uac_req_send()
        4.10. uac_reg_lookup(uuid, dst)
        4.11. uac_reg_status(uuid)
        4.12. uac_reg_request_to(user, mode)
        4.13. uac_reg_enable(attr, val)
        4.14. uac_reg_disable(attr, val)
        4.15. uac_reg_refresh(luuid)

   5. Pseudo Variables
   6. Event Routes

        6.1. event_route[uac:reply]

   7. Counters
   8. RPC Commands

        8.1. uac.reg_dump
        8.2. uac.reg_info
        8.3. uac.reg_enable
        8.4. uac.reg_disable
        8.5. uac.reg_reload
        8.6. uac.reg_refresh
        8.7. uac.reg_active
        8.8. uac.reg_add
        8.9. uac.reg_remove

   9. Remote Registration

1. Overview

   The UAC (User Agent Client) module provides some basic UAC
   functionalities like sending SIP requests, registering with a remote
   service, From: header manipulation (anonymization) and client
   authentication.

   The UAC module also supports sending a SIP request from the
   configuration file. See variable $uac_req(name) and the function
   uac_req_send().

   In addition, the module supports database-driven SIP registration
   functionality. See the uac_reg_lookup() function and dedicated section
   for remote registration configuration.

   Known limitations in this version:
     * Authentication does not support qop auth-int, just qop auth;
     * CSeq is not increased automatically by uac_auth() during
       authentication - the follow up request may be rejected. CSeq can be
       increased when authenticating INVITE requests - dialog module has
       to be used, with CSeq tracking feature enabled (see the readme of
       dialog module).
     * The “uac_replace_*” functions can only be run once on the same SIP
       request. Try to save needed changes in a pseudovariable and apply
       them once.
       There is also a limitation regarding the use of the
       “msg_apply_changes()” function together with the “uac_replace_*”
       functions for messages that are loose-routed (e.g. Re-INVITE
       requests). In this case you need to call the “loose_route()”
       function after the replace and msg_apply_changes. Otherwise
       Kamailio can create replies with wrong From/To headers (e.g. for
       the 100 - Trying reply in the Re-INVITE example).

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   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”.
     * 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
       values of the URIs as dialog variables.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None

3. Parameters

   3.1. rr_from_store_param (string)
   3.2. rr_to_store_param (string)
   3.3. restore_mode (string)
   3.4. restore_dlg (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 (int)
   3.14. reg_retry_interval (int)
   3.15. reg_random_delay (int)
   3.16. reg_db_table (string)
   3.17. reg_contact_addr (string)
   3.18. reg_keep_callid (int)
   3.19. reg_active (int)
   3.20. reg_gc_interval (int)
   3.21. default_socket (str)
   3.22. event_callback (str)

3.1. rr_from_store_param (string)

   Name of Record-Route header parameter that will be used to store an
   encoded version of the original FROM URI.

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

   Example 1.1. Set rr_from_store_param parameter
...
modparam("uac","rr_from_store_param","my_param")
...

3.2. rr_to_store_param (string)

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

   Example 1.2. Set rr_to_store_param parameter
...
modparam("uac","rr_to_store_param","my_param")
...

3.3. restore_mode (string)

   There are 3 modes of restoring the original FROM URI and the original
   TO URI:
     * “none” - no information about original URI is stored; restoration
       is not possible.
     * “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
       updated based on stored original URI. For this option you have to
       set “modparam("rr", "append_fromtag", 1)”.

   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_dlg (int)

   If set to 1, the module uses dialog variables to store initial and 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.

   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.5. Set restore_passwd parameter
...
modparam("uac","restore_passwd","my_secret_passwd")
...

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.
   That makes sense, if the original-uri can not be extracted from the
   original request, e.g. if msg_apply_changes() was used after calling
   uac_replace_from() or uac_replace_to().

   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.

   Default value of this parameter is empty.

   Example 1.6. Set restore_from_avp parameter
...
modparam("uac","restore_from_avp","$avp(original_uri_from)")
...

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
   makes sense if the original-uri can not be extracted from the original
   request, e.g. if msg_apply_changes() was used after calling
   uac_replace_to()

   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.

   Default value of this parameter is empty.

   Example 1.7. Set restore_to_avp parameter
...
modparam("uac","restore_to_avp","$avp(original_uri_to)")
...

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.8. Set credential parameter
...
modparam("uac","credential","username:domain:password")
...

3.9. auth_realm_avp (string)

   The definition of an PV that might contain the realm to be used to
   perform authentication.

   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.

   If you define it, you also need to define “auth_username_avp”
   (Section 3.10, “auth_username_avp (string)”) and “auth_password_avp”
   (Section 3.11, “auth_password_avp (string)”).

   Example 1.9. Set auth_realm_avp parameter
...
modparam("uac","auth_realm_avp","$avp(arealm)")
...

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.9, “auth_realm_avp (string)”) and “auth_password_avp”
   (Section 3.11, “auth_password_avp (string)”).

   Example 1.10. Set auth_username_avp parameter
...
modparam("uac","auth_username_avp","$avp(auser)")
...

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_realm_avp”
   (Section 3.9, “auth_realm_avp (string)”) and “auth_username_avp”
   (Section 3.10, “auth_username_avp (string)”).

   Example 1.11. Set auth_password_avp parameter
...
modparam("uac","auth_password_avp","$avp(apasswd)")
...

3.12. reg_db_url (string)

   DB URL to fetch account profiles for registration. This parameter must
   be set in order to enable remote registrations feature.

   The default value is "" (no value).

   Example 1.12. Set reg_db_url parameter
...
modparam("uac", "reg_db_url",
    "mysql://kamailio:kamailiorw@localhost/kamailio")
...

3.13. reg_timer_interval (int)

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

   The default value is 90 seconds.

   Example 1.13. Set reg_timer_interval parameter
...
modparam("uac", "reg_timer_interval", 60)
...

3.14. reg_retry_interval (int)

   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.

   The default value is 0 sec (disabled)

   Example 1.14. Set reg_retry_interval parameter
...
modparam("uac", "reg_retry_interval", 300)
...

3.15. reg_random_delay (int)

   Set a random reg_delay for each registration that has reg_delay set to
   0 in the database. If set to 0, randomization will be disabled.

   The default value is 0 sec (disabled)

   Example 1.15. Set reg_random_delay parameter
...
modparam("uac", "reg_random_delay", 300)
...

3.16. reg_db_table (string)

   DB table name to fetch user profiles for registration.

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

   Example 1.16. Set reg_db_table parameter
...
modparam("uac", "reg_db_table", "uacreg")
...

3.17. reg_contact_addr (string)

   Address to be used to build contact address. Must be at least host
   part, can have port and parameters. Must not include 'sip:'. The
   username part of the Contact: URI will be the L_UUID field in the
   database.

   Example 1.17. Set reg_contact_addr parameter
...
modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
...

3.18. reg_keep_callid (int)

   If set to 0 (default), a new Call-Id will be generated for each
   registration attempt. If set to non-zero, the same Call-Id will be used
   for re-registrations, as recommended by RFC3261 section 10.2.4. A new
   Call-Id will be generated when a previous registration had failed.

   Example 1.18. Set reg_keep_callid parameter
...
modparam("uac", "reg_keep_callid", 1)
...

3.19. reg_active (int)

   If set to 0, no remote regisrations are done. In other words, it can
   control at once if the module should do remote registratios or not. It
   can be changed at runtime via rpc command 'uac.reg_active 0|1'.

   The default value is 1 (active).

   Example 1.19. Set reg_active parameter
...
modparam("uac", "reg_active", 0)
...

3.20. reg_gc_interval (int)

   Timer interval (in seconds) at which remote registrations are cleaned
   up in case of failure or removed. When setting it take in consideration
   the maximum value for retransmission timeout, this param should be
   greater than it. This value also impacts how ofter the reload for
   remote registrations table can be executed -- the RPC command will fail
   if executed in less than reg_gc_interval value since the last reload.

   The default value is 150 seconds.

   Example 1.20. Set reg_gc_interval parameter
...
modparam("uac", "reg_gc_interval", 60)
...

3.21. default_socket (str)

   Default socket to be used for generating registration requests and
   sending requests with the function uac_req_send(). Useful e.g. when
   several public interfaces are available.

   A send socket in the $uac_reg variable used together with the
   uac_req_send() function will override this parameter. A socket value in
   the uacreg table will also override the parameter for this particular
   entry.

   By default no default socket is defined, the send socket is choosen
   from the “tm” module when the requests is send out.

   If you want to force a certain TCP port (e.g. 5060), you will need to
   set the tcp_reuse_port=yes core parameter as well.

   Example 1.21. Set the “default_socket” parameter
 ...
 modparam("uac", "default_socket", "udp:192.168.0.125:5060")
 ...

3.22. event_callback (str)

   The name of the function in the kemi configuration file (embedded
   scripting language such as Lua, Python, ...) to be executed instead of
   event_route[uac:reply] block.

   The function receives a string parameter with the name of the event,
   the value can be: 'uac:reply'.

   Default value is 'empty' (no function is executed for events).

   Example 1.22. Set event_callback parameter
 ...
modparam("uac", "event_callback", "ksr_uac_event")

function ksr_uac_event(evname)
        KSR.info("===== uac module triggered event: " .. evname .. "\n");
        return 1;
end
 ...

4. Functions

   4.1. uac_replace_from(display,uri)
   4.2. uac_replace_from(uri)
   4.3. uac_restore_from()
   4.4. uac_replace_to(display,uri)
   4.5. uac_replace_to(uri)
   4.6. uac_restore_to()
   4.7. uac_auth([mode])
   4.8. uac_auth_mode(vmode)
   4.9. uac_req_send()
   4.10. uac_reg_lookup(uuid, dst)
   4.11. uac_reg_status(uuid)
   4.12. uac_reg_request_to(user, mode)
   4.13. uac_reg_enable(attr, val)
   4.14. uac_reg_disable(attr, val)
   4.15. uac_reg_refresh(luuid)

4.1.  uac_replace_from(display,uri)

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

   display and URI parameters can include pseudo-variables.

   This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.

   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.

   If you set restore_mode to AUTO, the URI will be modified automatically
   in all subsequent requests and replies in that dialog.

   There are two ways in which the AUTO mode can be achieved.

   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.

   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.

   Example 1.23. uac_replace_from usage
...
# replace both display and uri
uac_replace_from("$avp(s:display)","$avp(s:uri)");
# replace only display and do not touch uri
uac_replace_from("batman","");   # display is replaced with: batman
uac_replace_from("\"batman\"","");  # display is replaced with: "batman"
# remove display and replace uri
uac_replace_from("","sip:robin@gotham.org");
# remove display and do not touch uri
uac_replace_from("","");
...

4.2.  uac_replace_from(uri)

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

   URI parameter can include pseudo-variables.

   This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.

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

4.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
   value.

   This function can be used from REQUEST_ROUTE.

   Example 1.25. uac_restore_from usage
...
uac_restore_from();
...

4.4.  uac_replace_to(display,uri)

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

   display and URI parameters can include pseudo-variables.

   This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.

   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.

   Example 1.26. uac_replace_to usage
...
# replace both display and uri
uac_replace_to("$avp(display)","$avp(uri)");
# replace only display and do not touch uri
uac_replace_to("batman","");   # display is replaced with: batman
uac_replace_to("\"batman\"","");  # display is replaced with: "batman"
# remove display and replace uri
uac_replace_to("","sip:robin@gotham.org");
# remove display and do not touch uri
uac_replace_to("","");
...

4.5.  uac_replace_to(uri)

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

   URI parameter can include pseudo-variables.

   This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.

   If you set restore_mode to AUTO, the URI will be modified automatically
   in all subsequent requests and replies in that dialog.

   There are two ways in which the AUTO mode can be achieved.

   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.

   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.

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

4.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
   value.

   This function can be used from REQUEST_ROUTE.

   Example 1.28. uac_restore_to usage
...
uac_restore_to();
...

4.7.  uac_auth([mode])

   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.

   If mode is set to 1, then the password has to be provided in HA1
   format. The parameter can be a static integer or a variable holding an
   integer value.

   This function can be used from FAILURE_ROUTE.

   Example 1.29. uac_auth usage
...
modparam("uac","auth_username_avp","$avp(auser)")
modparam("uac","auth_password_avp","$avp(apass)")
modparam("uac","auth_realm_avp","$avp(arealm)")

request_route {
   ...
   if(is_method("INVITE")) {
      t_on_failure("TRUNKAUTH");
   }
   ...
}

failure_route[TRUNKAUTH] {

    if (t_is_canceled()) {
        exit;
    }
    if(t_check_status("401|407")) {
        $avp(auser) = "test";
        $avp(apass) = "test";
        # $avp(apass) = "36d0a02793542b4961e8348347236dbf";
        if (uac_auth()) {
            t_relay();
        }
        exit;
    }
}
...

4.8.  uac_auth_mode(vmode)

   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.

   If mode is set to 1, then the password has to be provided in HA1
   format. The parameter can be a static integer or a variable holding an
   integer value.

   This function can be used from FAILURE_ROUTE.

   Example 1.30. uac_auth_mode usage
...
modparam("uac","auth_username_avp","$avp(auser)")
modparam("uac","auth_password_avp","$avp(apass)")
modparam("uac","auth_realm_avp","$avp(arealm)")

request_route {
   ...
   if(is_method("INVITE")) {
      t_on_failure("TRUNKAUTH");
   }
   ...
}

failure_route[TRUNKAUTH] {

    if (t_is_canceled()) {
        exit;
    }
    if(t_check_status("401|407")) {
        $avp(auser) = "test";
        $avp(apass) = "test";
        # $avp(apass) = "36d0a02793542b4961e8348347236dbf";
        if (uac_auth_mode("1")) {
            t_relay();
        }
        exit;
    }
}
...

4.9.  uac_req_send()

   This function sends a SIP message from the configuration file. The
   message is built out of $uac_req(...) pseudo-variable.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.

   Example 1.31. uac_req_send usage
...
$uac_req(method)="OPTIONS";
$uac_req(ruri)="sip:kamailio.org";
$uac_req(furi)="sip:kamailio.org";
$uac_req(turi)="sip:kamailio.org";
$uac_req(callid)=$(mb{s.md5});
uac_req_send();
...

4.10.  uac_reg_lookup(uuid, dst)

   This function sets the PV dst to SIP URI that correspond to uuid in uac
   registrations table. uuid and dst must be pseudo-variables.

   This function can be used from ANY_ROUTE.

   Example 1.32. uac_reg_lookup usage
...

if(uac_reg_lookup("$rU", "$ru"))
{
    lookup("location");
}
...

4.11.  uac_reg_status(uuid)

   This function returns the current registration status for the uuid.

   Return values:
     * 1 - a valid registration exists.
     * -1 - uuid does not exist or an error occurred while executing the
       function.
     * -2 - a registration attempt is ongoing (and currently there is no
       valid registration).
     * -3 - registration is disabled.
     * -99 - no valid registration, waiting for new registration attempt.

   This function can be used from ANY_ROUTE.

   Example 1.33. uac_reg_status usage
...
$var(status) = uac_reg_status("$rU");
...

4.12.  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
   and auth_*_avp variables to the values that correspond to the supplied
   user.

   The mode is a bitwise set of flags controlling how the matching of the
   record is done and what field is used to set auth_password_avp:
     * indicates whether the user should match the local uuid (bit
       value=0), or the username (bit value=1, int value=1).
     * indicates whether the auth_password value is used to set
       auth_password_avp (bit value=0), or the auth_ha1 value (bit
       value=1, int value=2).

   The auth_*_avp module parameters must be set to valid pv's.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE.

   Example 1.34. uac_reg_request_to usage
...

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

4.13.  uac_reg_enable(attr, val)

   Enable a remote registration record based on a filter specified by
   attribute and value. The attribute can be: l_uuid, l_username,
   r_username or auth_username. The value is what should be matched
   against the value of the attribute in the remote registration record.

   The SIP processing is done on the next timer routine.

   Example 1.35. uac_reg_enable usage
...
   uac_reg_enable("l_uuid", "account123");
...

4.14.  uac_reg_disable(attr, val)

   Disable a remote registration record based on a filter specified by
   attribute and value. The attribute can be: l_uuid, l_username,
   r_username or auth_username. The value is what should be matched
   against the value of the attribute in the remote registration record.

   The SIP processing is done on the next timer routine.

   Example 1.36. uac_reg_disable usage
...
   uac_reg_disable("l_uuid", "account123");
...

4.15.  uac_reg_refresh(luuid)

   Refresh the uac remote registration record based on local uuid. If the
   record was already loaded, new values are taken from database,
   otherwise a new record is created.

   Example 1.37. uac_reg_refresh usage
...
   uac_reg_refresh("account123");
...

5. Pseudo Variables

     * $uac_req(key)

   Exported pseudo-variables are documented at
   https://www.kamailio.org/wiki/.

6. Event Routes

   6.1. event_route[uac:reply]

6.1.  event_route[uac:reply]

   Event route executed for the final reply of the branch for the request
   sent with uac_req_send(). The associated $uac_req(evroute) has to be
   set to 1. If the request is challenged for authentication with 401/407,
   then the event_route is executed twice, first for 401/407 and second
   for final reply of the transaction.

   Example 1.38. event_route[uac:reply] usage
...
$uac_req(method)="OPTIONS";
$uac_req(ruri)="sip:kamailio.org";
$uac_req(furi)="sip:kamailio.org";
$uac_req(turi)="sip:kamailio.org";
$uac_req(callid)=$(mb{s.md5});
$uac_req(evroute)=1;
uac_req_send();
...
event_route[uac:reply] {
    xlog("received reply code is: $uac_req(evcode)\n");
}
...

7. Counters

     * regtotal: Total number of registrations
     * regactive: Total number of active registrations (successfully
       registered with service)
     * regdisabled: Total number of disabled registrations (no longer
       active)

8. RPC Commands

   8.1. uac.reg_dump
   8.2. uac.reg_info
   8.3. uac.reg_enable
   8.4. uac.reg_disable
   8.5. uac.reg_reload
   8.6. uac.reg_refresh
   8.7. uac.reg_active
   8.8. uac.reg_add
   8.9. uac.reg_remove

8.1.  uac.reg_dump

   Dump the content of remote registration table from memory.

   Example 1.39. uac.reg_dump usage
...
   kamcmd uac.reg_dump
...

8.2.  uac.reg_info

   Return the details of a remote registration record based on a filter.
   The command has two parameter: attribute and value. The attribute can
   be: l_uuid, l_username, r_username or auth_username. The value is what
   should be matched against the value of the attribute in the remote
   registration record.

   The state of the registration is reflected in the flags field:
     * 1 (2^0) - registration profile is disabled
     * 2 (2^1) - registration in progress
     * 4 (2^2) - registration succeeded
     * 8 (2^3) - registration in progres with authentication
     * 16 (2^4) - registration initialized (after loading from database,
       the registration process was initialized)

   Example 1.40. uac.reg_info usage
...
   kamcmd uac.reg_info l_uuid account123
   kamcmd uac.reg_info l_uuid s:12345678
...

8.3.  uac.reg_enable

   Enable a remote registration record based on a filter. The command has
   two parameter: attribute and value. The attribute can be: l_uuid,
   l_username, r_username or auth_username. The value is what should be
   matched against the value of the attribute in the remote registration
   record.

   Example 1.41. uac.reg_enable usage
...
   kamcmd uac.reg_enable l_uuid account123
   kamcmd uac.reg_enable l_uuid s:12345678
...

8.4.  uac.reg_disable

   Disable a remote registration record based on a filter. The command has
   two parameter: attribute and value. The attribute can be: l_uuid,
   l_username, r_username or auth_username. The value is what should be
   matched against the value of the attribute in the remote registration
   record.

   Example 1.42. uac.reg_disable usage
...
   kamcmd uac.reg_disable l_uuid account123
   kamcmd uac.reg_disable l_uuid s:12345678
...

8.5.  uac.reg_reload

   Reload the records from database for remote registrations. There is a
   limit of how often the reload command can be executed, by default is
   150 seconds between reloads -- see the reg_gc_interval parameter for
   more details.

   Example 1.43. uac.reg_reload usage
...
   kamcmd uac.reg_reload
...

8.6.  uac.reg_refresh

   Load one record by l_uuid from database for remote registrations. If
   the record exists in memory, it will be replaced with the new values
   loaded from database.

   Example 1.44. uac.reg_refresh usage
...
   kamcmd uac.reg_refresh account123
   kamcmd uac.reg_refresh s:12345678
...

8.7.  uac.reg_active

   Control if the module should do remote registrations or not. Setting to
   1 enables remote registrations for all records and 0 disables doing
   them.

   Example 1.45. uac.reg_active usage
...
   kamctl rpc uac.reg_active 0
   kamctl rpc uac.reg_active 1
...

8.8.  uac.reg_add

   Add a new UAC remote registration record. If one with the same unique
   id is found, it is deleted.

   The parameters are:
     * l_uuid
     * l_username
     * l_domain
     * r_username
     * r_domain
     * realm
     * auth_username
     * auth_password
     * auth_ha1
     * auth_proxy
     * expires
     * flags
     * reg_delay
     * socket

   Use a dot (.) if no value should be set for auth_password or auth_ha1.

   Example 1.46. uac.reg_add usage
...
   kamcmd uac.reg_add ...
...

8.9.  uac.reg_remove

   Remove a UAC remote registration record by l_uuid.

   Example 1.47. uac.reg_remove usage
...
   kamcmd uac.reg_remove my_l_uuid
...

9. Remote Registration

   The module can register contact addresses to remote REGISTRAR servers.
   You have to add records to uacreg table. The table stores following
   attributes:
     * l_uuid - local unique user id, e.g.,: 12345678

     * l_username - local user name, e.g.,: test

     * l_domain - local domain, e.g.,: mysipserver.com

     * r_username - remote username, e.g.,: test123

     * r_domain - remote domain, e.g.,: sipprovider.com

     * realm - remote realm, e.g.,: sipprovider.com

     * auth_username - authentication username, e.g.,: test123

     * auth_password - authentication password in clear text, e.g.,:
       xxxxxx

     * auth_ha1 - hashed (HA1) authentication password, it has priority
       over auth_password.

     * auth_proxy - SIP address of authentication proxy, e.g.,:
       sip:sipprovider.com

     * expires - expiration time for registration, in seconds, e.g.,: 360

     * flags - the state of the registration, see Section 8.2, “
       uac.reg_info ”

     * reg_delay - delay initial registration with at least reg_delay
       seconds, e.g.,: 3

     * socket - Used socket for sending out registration requests, e.g.:,
       udp:192.168.0.125:5060

   The module takes care of sending REGISTER and refresh registrations
   before they expire.

   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.

   Example 1.48. lookup remote registrations usage
...
    if(uac_reg_lookup("$rU", "$ru")) {
        xlog("request from a remote SIP provider [$ou => $ru]\n");
    }
    lookup("location");
...