modules: readme files regenerated - uac ... [skip ci]

src/modules/uac/README

@@ -1,2 +1,1135 @@
+UAC Module
 
+Ramona-Elena Modroiu
 
+   <[email protected]>
+
+Daniel-Constantin Mierla
+
+   <[email protected]>
+
+Edited by
+
+Ramona-Elena Modroiu
+
+   <[email protected]>
+
+   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)
+
+        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()
+              4.8. uac_req_send()
+              4.9. uac_reg_lookup(uuid, dst)
+              4.10. uac_reg_status(uuid)
+              4.11. uac_reg_request_to(user, mode)
+              4.12. uac_reg_enable(attr, val)
+              4.13. uac_reg_disable(attr, val)
+              4.14. 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.
+
+        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. uac_replace_from usage
+   1.23. uac_replace_from usage
+   1.24. uac_restore_from usage
+   1.25. uac_replace_to usage
+   1.26. uac_replace_to usage
+   1.27. uac_restore_to usage
+   1.28. uac_auth usage
+   1.29. uac_req_send usage
+   1.30. uac_reg_lookup usage
+   1.31. uac_reg_status usage
+   1.32. uac_reg_request_to usage
+   1.33. uac_reg_enable usage
+   1.34. uac_reg_disable usage
+   1.35. uac_reg_refresh usage
+   1.36. event_route[uac:reply] usage
+   1.37. uac.reg_dump usage
+   1.38. uac.reg_info usage
+   1.39. uac.reg_enable usage
+   1.40. uac.reg_disable usage
+   1.41. uac.reg_reload usage
+   1.42. uac.reg_refresh usage
+   1.43. uac.reg_active usage
+   1.44. uac.reg_add usage
+   1.45. 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)
+
+   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()
+        4.8. uac_req_send()
+        4.9. uac_reg_lookup(uuid, dst)
+        4.10. uac_reg_status(uuid)
+        4.11. uac_reg_request_to(user, mode)
+        4.12. uac_reg_enable(attr, val)
+        4.13. uac_reg_disable(attr, val)
+        4.14. 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.
+
+   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.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(i:10)")
+...
+
+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(i:11)")
+...
+
+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(i:12)")
+...
+
+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")
+ ...
+
+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()
+   4.8. uac_req_send()
+   4.9. uac_reg_lookup(uuid, dst)
+   4.10. uac_reg_status(uuid)
+   4.11. uac_reg_request_to(user, mode)
+   4.12. uac_reg_enable(attr, val)
+   4.13. uac_reg_disable(attr, val)
+   4.14. 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.22. 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:[email protected]");
+# 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.23. uac_replace_from usage
+...
+uac_replace_from("sip:[email protected]");
+...
+
+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.24. 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.25. 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:[email protected]");
+# 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.26. uac_replace_to usage
+...
+uac_replace_to("sip:[email protected]");
+...
+
+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.27. uac_restore_to usage
+...
+uac_restore_to();
+...
+
+4.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
+   sending anything.
+
+   This function can be used from FAILURE_ROUTE.
+
+   Example 1.28. 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";
+        uac_auth();
+        t_relay();
+        exit;
+    }
+}
+...
+
+4.8.  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.29. 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.9.  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.30. uac_reg_lookup usage
+...
+
+if(uac_reg_lookup("$rU", "$ru"))
+{
+    lookup("location");
+}
+...
+
+4.10.  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.31. uac_reg_status usage
+...
+$var(status) = uac_reg_status("$rU");
+...
+
+4.11.  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 pv's to the values that correspond to the supplied user.
+
+   The mode indicates whether the user should match the local uuid
+   (mode=0), or the username (mode=1).
+
+   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.32. 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.12.  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.33. uac_reg_enable usage
+...
+   uac_reg_enable("l_uuid", "account123");
+...
+
+4.13.  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.34. uac_reg_disable usage
+...
+   uac_reg_disable("l_uuid", "account123");
+...
+
+4.14.  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.35. 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.36. 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.
+
+8.1.  uac.reg_dump
+
+   Dump the content of remote registration table from memory.
+
+   Example 1.37. 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.38. 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.39. 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.40. 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.41. 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.42. 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.43. uac.reg_active usage
+...
+   kamctl rpc uac.reg_active 0
+   kamctl rpc uac.reg_active 1
+...
+
+   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.44. uac.reg_add usage
+...
+   kamcmd uac.reg_add ...
+...
+
+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 relam, 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.45. lookup remote registrations usage
+...
+    if(uac_reg_lookup("$rU", "$ru")) {
+        xlog("request from a remote SIP provider [$ou => $ru]\n");
+    }
+    lookup("location");
+...