From f99b8731a9e91315f75e584f34f15d3c83f086d5 Mon Sep 17 00:00:00 2001 From: Kamailio Dev Date: Mon, 2 Sep 2019 18:46:48 +0200 Subject: [PATCH] modules: readme files regenerated - uac ... [skip ci] --- src/modules/uac/README | 1099 ---------------------------------------- 1 file changed, 1099 deletions(-) diff --git a/src/modules/uac/README b/src/modules/uac/README index d2f1a180d6a..139597f9cb0 100644 --- a/src/modules/uac/README +++ b/src/modules/uac/README @@ -1,1101 +1,2 @@ -UAC Module -Ramona-Elena Modroiu - - -Daniel-Constantin Mierla - - - -Edited by - -Ramona-Elena Modroiu - - - - 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 - - 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. 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 - - 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: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.23. 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.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: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.26. 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.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.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 -... - -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, e.g.,: xxxxxx - - * 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.44. lookup remote registrations usage -... - if(uac_reg_lookup("$rU", "$ru")) { - xlog("request from a remote SIP provider [$ou => $ru]\n"); - } - lookup("location"); -...