uri Module

Jan Janak

FhG FOKUS

Edited by

Jan Janak

Edited by

Bogdan-Andrei Iancu

Edited by

Irina-Maria Stanescu

Revision History
Revision $Revision: 6019 $$Date: 2009-08-25 12:26:51 +0200 (Tue, 25 Aug 2009) $

Table of Contents

1. Admin Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. aaa_url (string)
1.3.2. service_type (integer)
1.3.3. use_sip_uri_host (integer)
1.3.4. db_url (string)
1.3.5. db_table (string)
1.3.6. user_column (string)
1.3.7. domain_column (string)
1.3.8. uriuser_column (string)
1.3.9. use_uri_table (integer)
1.3.10. use_domain (integer)
1.4. Exported Functions
1.4.1. db_check_to()
1.4.2. db_check_from()
1.4.3. db_does_uri_exist()
1.4.4. db_get_auth_id(string, var, var)
1.4.5. aaa_does_uri_exist([pvar])
1.4.6. aaa_does_uri_user_exist([pvar])
1.4.7. is_user(username)
1.4.8. has_totag()
1.4.9. uri_param(param)
1.4.10. uri_param(param,value)
1.4.11. add_uri_param(param)
1.4.12. tel2sip()
1.4.13. is_uri_user_e164(pseudo-variable)

List of Examples

1.1. Set aaa_url parameter
1.2. Set service_type parameter
1.3. Set use_sip_uri_host parameter
1.4. Set db_url parameter
1.5. Set uri_table parameter
1.6. Set user_column parameter
1.7. Set domain_column parameter
1.8. Set uriuser_column parameter
1.9. Set use_uri_table parameter
1.10. Set use_domain parameter
1.11. db_check_to usage
1.12. db_check_from usage
1.13. db_does_uri_exist usage
1.14. db_get_auth_id usage
1.15. aaa_does_uri_exist usage
1.16. aaa_does_uri_user_exist usage
1.17. is_user usage
1.18. has_totag usage
1.19. uri_param usage
1.20. uri_param usage
1.21. add_uri_param usage
1.22. tel2sip usage
1.23. is_uri_user_e164 usage

Chapter 1. Admin Guide

1.1. Overview

Various checks related to SIP URI.

This module implements some URI related AAA or DB based tests.

1.2. Dependencies

1.2.1. OpenSIPS Modules

At least one of the following modules must be loaded before this module:

  • a OpenSIPS database module .

  • an aaa protocol module .

1.2.2. External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

  • None.

1.3. Exported Parameters

1.3.1. aaa_url (string)

This is the url representing the AAA protocol used and the location of the configuration file of this protocol.

Example 1.1. Set aaa_url parameter

...
modparam("uri", "aaa_url", "radius:/etc/radiusclient-ng/radiusclient.conf")
...

1.3.2. service_type (integer)

AAA service type used in aaa_does_uri_exist and aaa_does_uri_user_exist checks.

Default value is 10 (Call-Check).

Example 1.2. Set service_type parameter

...
modparam("uri", "service_type", 11)
...

1.3.3. use_sip_uri_host (integer)

If zero, aaa_does_uri_exist sends to AAA server Request URI user@host in UserName attribute. If non-zero, aaa_does_uri_exist sends to AAA server Request URI user in UserName attribute and host in SIP-URI-Host attribute.

Default value is 0.

Example 1.3. Set use_sip_uri_host parameter

...
modparam("uri", "use_sip_uri_host", 1)
...

1.3.4. db_url (string)

URL of the database to be used.

If the db_url string is not set, you will not be able to use the DB related functions.

Default value is “>NULL”.

Example 1.4. Set db_url parameter

...
modparam("uri", "db_url", "mysql://username:password@localhost/opensips")
...

1.3.5. db_table (string)

The DB table that should be used. Its possible to use the “subscriber” and “uri” table. If the “uri” table should be used, an additional parameter (Section 1.3.9, “use_uri_table (integer)”) must be set.

Default value is “subscriber”.

Example 1.5. Set uri_table parameter

...
modparam("uri", "db_table", "uri")
...

1.3.6. user_column (string)

Column holding usernames in the table.

Default value is “username”.

Example 1.6. Set user_column parameter

...
modparam("uri", "user_column", "username")
...

1.3.7. domain_column (string)

Column holding domain in the table.

Default value is “domain”.

Example 1.7. Set domain_column parameter

...
modparam("uri", "domain_column", "domain")
...

1.3.8. uriuser_column (string)

Column holding URI username in the table.

Default value is “uri_user”.

Example 1.8. Set uriuser_column parameter

...
modparam("uri", "uriuser_column", "uri_user")
...

1.3.9. use_uri_table (integer)

Specify if the “uri” table should be used for checkings instead of “subscriber” table. A non-zero value means true.

Default value is “0 (false)”.

Example 1.9. Set use_uri_table parameter

...
modparam("uri", "use_uri_table", 1)
...

1.3.10. use_domain (integer)

Specify if the domain part of the URI should be used to identify the users (along with username). This is useful in multi domain setups, a non-zero value means true.

This parameter is only evaluated for calls to “does_uri_exist”, all other functions checks the digest username and realm against the given username, if the “uri” table is used.

Default value is “0 (false)”.

Example 1.10. Set use_domain parameter

...
modparam("uri", "use_domain", 1)
...

1.4. Exported Functions

1.4.1.  db_check_to()

Check To username against URI table (if use_uri_table is set) or digest credentials (no DB backend required).

This function can be used from REQUEST_ROUTE.

Example 1.11. db_check_to usage

...
if (db_check_to()) {
	...
};
...

1.4.2.  db_check_from()

Check From username against URI table (if use_uri_table is set) or digest credentials (no DB backend required).

This function can be used from REQUEST_ROUTE.

Example 1.12. db_check_from usage

...
if (db_check_from()) {
	...
};
...

1.4.3.  db_does_uri_exist()

Check if username in the request URI belongs to an existing user.

As the checking is done against URI table (if use_uri_table is set) or subscriber table.

This function can be used from REQUEST_ROUTE.

Example 1.13. db_does_uri_exist usage

...
if (db_does_uri_exist()) {
	...
};
...

1.4.4.  db_get_auth_id(string, var, var)

Checks given uri-string username against URI table (if use_uri_table is set) or subscriber table (database backend required). Returns true if the user exists in the database, and sets the given variables to the authentication id and realm corresponding to the given uri.

This function can be used from REQUEST_ROUTE.

Example 1.14. db_get_auth_id usage

...
if (db_get_auth_id("$ru", "$avp(s:auth_id)", "$avp(s:auth_realm)")) {
	...
};
...

1.4.5.  aaa_does_uri_exist([pvar])

Checks from Radius if user@host in Request-URI or in URI stored in pseudo variable argument belongs to a local user. Can be used to decide if 404 or 480 should be returned after lookup has failed. If yes, loads AVP based on SIP-AVP reply items returned from Radius. Each SIP-AVP reply item must have a string value of form:

  • value = SIP_AVP_NAME SIP_AVP_VALUE

  • SIP_AVP_NAME = STRING_NAME | '#'ID_NUMBER

  • SIP_AVP_VALUE = ':'STRING_VALUE | '#'NUMBER_VALUE

Returns 1 if Radius returns Access-Accept, -1 if Radius returns Access-Reject, and -2 in case of internal error.

This function can be used from REQUEST_ROUTE.

Example 1.15. aaa_does_uri_exist usage

...
if (aaa_does_uri_exist()) {
	...
};
...

1.4.6.  aaa_does_uri_user_exist([pvar])

Similar to aaa_does_uri_exist, but check is done based only on Request-URI user part or user stored in pseudo variable argument. User should thus be unique among all users, such as an E.164 number.

This function can be used from REQUEST_ROUTE.

Example 1.16. aaa_does_uri_user_exist usage

...
if (aaa_does_uri_user_exist()) {
	...
};
...

1.4.7.  is_user(username)

Check if the username in credentials matches the given username.

Meaning of the parameters is as follows:

  • username - Username string.

This function can be used from REQUEST_ROUTE.

Example 1.17. is_user usage

...
if (is_user("john")) {
	...
};
...

1.4.8.  has_totag()

Check if To header field uri contains tag parameter.

This function can be used from REQUEST_ROUTE.

Example 1.18. has_totag usage

...
if (has_totag()) {
	...
};
...

1.4.9.  uri_param(param)

Find if Request URI has a given parameter with no value

Meaning of the parameters is as follows:

  • param - parameter name to look for.

This function can be used from REQUEST_ROUTE.

Example 1.19. uri_param usage

...
if (uri_param("param1")) {
	...
};
...

1.4.10.  uri_param(param,value)

Find if Request URI has a given parameter with matching value

Meaning of the parameters is as follows:

  • param - parameter name to look for.

  • value - parameter value to match.

This function can be used from REQUEST_ROUTE.

Example 1.20. uri_param usage

...
if (uri_param("param1","value1")) {
	...
};
...

1.4.11.  add_uri_param(param)

Add to RURI a parameter (name=value);

Meaning of the parameters is as follows:

  • param - parameter to be appended in “name=value” format.

This function can be used from REQUEST_ROUTE.

Example 1.21. add_uri_param usage

...
add_uri_param("nat=yes");
...

1.4.12.  tel2sip()

Converts RURI, if it is tel URI, to SIP URI. Returns true, only if conversion succeeded or if no conversion was needed (like RURI was not tel URI.

This function can be used from REQUEST_ROUTE.

Example 1.22. tel2sip usage

...
tel2sip();
...

1.4.13.  is_uri_user_e164(pseudo-variable)

Checks if userpart of URI stored in pseudo variable is E164 number.

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

Example 1.23. is_uri_user_e164 usage

...
if (is_uri_user_e164("$fu")) {  # Check From header URI user part
   ...
}
if (is_uri_user_e164("$avp(i:705)") {
   # Check user part of URI stored in avp i:705
   ...
};
...