mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
421 lines
11 KiB
421 lines
11 KiB
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. Exported Parameters
|
|
|
|
3.1. rr_store_param (string)
|
|
3.2. from_restore_mode (string)
|
|
3.3. from_passwd (string)
|
|
3.4. credential (string)
|
|
3.5. auth_realm_avp (string)
|
|
3.6. auth_username_avp (string)
|
|
3.7. auth_password_avp (string)
|
|
3.8. reg_db_url (string)
|
|
3.9. reg_contact_addr (string)
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. uac_replace_from(display,uri)
|
|
4.2. uac_replace_from(uri)
|
|
4.3. uac_restore_from()
|
|
4.4. uac_auth()
|
|
4.5. uac_req_send()
|
|
4.6. uac_reg_lookup(uuid, dst)
|
|
|
|
5. Exported pseudo-variables
|
|
6. Remote Registration
|
|
|
|
List of Examples
|
|
|
|
1.1. Set rr_store_param parameter
|
|
1.2. Set from_restore_mode parameter
|
|
1.3. Set from_passwd parameter
|
|
1.4. Set credential parameter
|
|
1.5. Set auth_realm_avp parameter
|
|
1.6. Set auth_username_avp parameter
|
|
1.7. Set auth_password_avp parameter
|
|
1.8. Set reg_db_url parameter
|
|
1.9. Set reg_contact_addr parameter
|
|
1.10. uac_replace_from usage
|
|
1.11. uac_replace_from usage
|
|
1.12. uac_restore_from usage
|
|
1.13. uac_auth usage
|
|
1.14. uac_req_send usage
|
|
1.15. uac_reg_lookup usage
|
|
1.16. 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. Exported Parameters
|
|
|
|
3.1. rr_store_param (string)
|
|
3.2. from_restore_mode (string)
|
|
3.3. from_passwd (string)
|
|
3.4. credential (string)
|
|
3.5. auth_realm_avp (string)
|
|
3.6. auth_username_avp (string)
|
|
3.7. auth_password_avp (string)
|
|
3.8. reg_db_url (string)
|
|
3.9. reg_contact_addr (string)
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. uac_replace_from(display,uri)
|
|
4.2. uac_replace_from(uri)
|
|
4.3. uac_restore_from()
|
|
4.4. uac_auth()
|
|
4.5. uac_req_send()
|
|
4.6. uac_reg_lookup(uuid, dst)
|
|
|
|
5. Exported pseudo-variables
|
|
6. Remote Registration
|
|
|
|
1. Overview
|
|
|
|
UAC (User Agent Client) module provides some basic UAC functionalities
|
|
like FROM header manipulation (anonymization) or client authentication.
|
|
|
|
From version 1.5.0 it has function to send SIP message from
|
|
configuration file. See variable $uac_req(name) and the function
|
|
uac_req_send().
|
|
|
|
Version 3.1.0 adds user registration functionality. See
|
|
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 not increased during authentication - the response may be
|
|
rejected.
|
|
|
|
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”.
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* None
|
|
|
|
3. Exported Parameters
|
|
|
|
3.1. rr_store_param (string)
|
|
3.2. from_restore_mode (string)
|
|
3.3. from_passwd (string)
|
|
3.4. credential (string)
|
|
3.5. auth_realm_avp (string)
|
|
3.6. auth_username_avp (string)
|
|
3.7. auth_password_avp (string)
|
|
3.8. reg_db_url (string)
|
|
3.9. reg_contact_addr (string)
|
|
|
|
3.1. rr_store_param (string)
|
|
|
|
Name of Record-Route header parameter that will be used to store
|
|
(encoded) the original FROM URI.
|
|
|
|
This parameter is optional, it's default value being “vsf”.
|
|
|
|
Example 1.1. Set rr_store_param parameter
|
|
...
|
|
modparam("uac","rr_store_param","my_param")
|
|
...
|
|
|
|
3.2. from_restore_mode (string)
|
|
|
|
There are 3 mode of restoring the original FROM 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.
|
|
|
|
This parameter is optional, it's default value being “auto”.
|
|
|
|
Example 1.2. Set from_restore_mode parameter
|
|
...
|
|
modparam("uac","from_restore_mode","auto")
|
|
...
|
|
|
|
3.3. from_passwd (string)
|
|
|
|
String password to be used to encrypt the RR storing parameter. If
|
|
empty, no encryption will be used.
|
|
|
|
Default value of this parameter is empty.
|
|
|
|
Example 1.3. Set from_passwd parameter
|
|
...
|
|
modparam("uac","from_passwd","my_secret_passwd")
|
|
...
|
|
|
|
3.4. credential (string)
|
|
|
|
Contains a multiple definition of credentials used to perform
|
|
authentication.
|
|
|
|
This parameter is required if UAC authentication is used.
|
|
|
|
Example 1.4. Set credential parameter
|
|
...
|
|
modparam("uac","credential","username:domain:password")
|
|
...
|
|
|
|
3.5. auth_realm_avp (string)
|
|
|
|
The definition of an AVP that might contain the realm to be used to
|
|
perform authentication.
|
|
|
|
If you define it, you also need to define “auth_username_avp”
|
|
(Section 3.6, “auth_username_avp (string)”) and “auth_username_avp”
|
|
(Section 3.7, “auth_password_avp (string)”).
|
|
|
|
Example 1.5. Set auth_realm_avp parameter
|
|
...
|
|
modparam("uac","auth_realm_avp","$avp(i:10)")
|
|
...
|
|
|
|
3.6. 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.5, “auth_realm_avp (string)”) and “auth_username_avp”
|
|
(Section 3.7, “auth_password_avp (string)”).
|
|
|
|
Example 1.6. Set auth_username_avp parameter
|
|
...
|
|
modparam("uac","auth_username_avp","$avp(i:11)")
|
|
...
|
|
|
|
3.7. auth_password_avp (string)
|
|
|
|
The definition of an AVP that might contain the password to be used to
|
|
perform authentication.
|
|
|
|
If you define it, you also need to define “auth_password_avp”
|
|
(Section 3.7, “auth_password_avp (string)”) and “auth_username_avp”
|
|
(Section 3.7, “auth_password_avp (string)”).
|
|
|
|
Example 1.7. Set auth_password_avp parameter
|
|
...
|
|
modparam("uac","auth_password_avp","$avp(i:12)")
|
|
...
|
|
|
|
3.8. reg_db_url (string)
|
|
|
|
DB URL to fetch user profiles for registration.
|
|
|
|
Example 1.8. Set reg_db_url parameter
|
|
...
|
|
modparam("uac", "reg_db_url",
|
|
"mysql://openser:openserrw@localhost/openser")
|
|
...
|
|
|
|
3.9. 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:'.
|
|
|
|
Example 1.9. Set reg_contact_addr parameter
|
|
...
|
|
modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
|
|
...
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. uac_replace_from(display,uri)
|
|
4.2. uac_replace_from(uri)
|
|
4.3. uac_restore_from()
|
|
4.4. uac_auth()
|
|
4.5. uac_req_send()
|
|
4.6. uac_reg_lookup(uuid, dst)
|
|
|
|
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.
|
|
|
|
Example 1.10. 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","");
|
|
# 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.11. 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.12. uac_restore_from usage
|
|
...
|
|
uac_restore_from();
|
|
...
|
|
|
|
4.4. 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.13. uac_auth usage
|
|
...
|
|
uac_auth();
|
|
...
|
|
|
|
4.5. 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.14. 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_send();
|
|
...
|
|
|
|
4.6. uac_reg_lookup(uuid, dst)
|
|
|
|
This function sets the PV dst to SIP URI that correspond to uuid in uac
|
|
registations table. uuid and dst must be pseudo-variables.
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
Example 1.15. uac_reg_lookup usage
|
|
...
|
|
|
|
if(uac_reg_lookup("$rU", "$ru"))
|
|
{
|
|
lookup("location");
|
|
}
|
|
...
|
|
|
|
5. Exported pseudo-variables
|
|
|
|
* $uac_req(key)
|
|
|
|
Exported pseudo-variables are documented at
|
|
http://www.kamailio.org/dokuwiki/.
|
|
|
|
6. 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
|
|
|
|
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.16. lookup remote registrations usage
|
|
...
|
|
if(uac_reg_lookup("$rU", "$ru")) {
|
|
xlog("request from a remote SIP provider [$ou => $ru]\n");
|
|
}
|
|
lookup("location");
|
|
...
|