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 during authentication - the response may be rejected.
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.

2. Dependencies

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)

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.

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 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.10, “auth_username_avp (string)”) and “auth_username_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_username_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_password_avp” (Section 3.11, “auth_password_avp (string)”) and “auth_username_avp” (Section 3.11, “auth_password_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.

Example 1.12. Set reg_db_url parameter

...
modparam("uac", "reg_db_url",
    "mysql://kamailio:kamailiorw@localhost/kamailio")
...

3.13. `reg_timer_interval` (string)

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

The default value is 90 seconds.

Example 1.13. Set reg_timer_inteval parameter

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

3.14. `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.14. Set reg_contact_addr parameter

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

4. Functions

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.

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.15. 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.16. 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.17. 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.

Example 1.18. 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","");
# 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.

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.19. 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.20. 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.21. uac_auth usage

...
uac_auth();
...

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.22. 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.9. `uac_reg_lookup(uuid, dst)`

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

This function can be used from ANY_ROUTE.

Example 1.23. uac_reg_lookup usage

...

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

4.10. `uac_reg_request_to(user, mode)`

This function can be used to send an authenticated request to a remote user in the uac registrations table. It sets the request-uri, dst-uri 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.24. 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()
	}
}
...

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.25. lookup remote registrations usage

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

UAC Module

Ramona-Elena Modroiu

Daniel-Constantin Mierla

Edited by

Ramona-Elena Modroiu

Chapter 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 (string)

3.14. reg_contact_addr (string)

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_request_to(user, mode)

5. Exported pseudo-variables

6. Remote Registration

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` (string)

3.14. `reg_contact_addr` (string)

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_request_to(user, mode)`