uri Module

Jan Janak

   FhG FOKUS

Edited by

Jan Janak

Edited by

Bogdan-Andrei Iancu

Edited by

Irina-Maria Stanescu

   Copyright © 2003 FhG FOKUS

   Copyright © 2005, 2009 Voice Sistem SRL
   Revision History
   Revision $Revision: 8740 $ $Date$
     __________________________________________________________

   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. del_uri_param(param)
              1.4.13. tel2sip()
              1.4.14. 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. add_uri_param usage
   1.23. tel2sip usage
   1.24. 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.con
f")
...

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.

   Matching is done against the URI table (if use_uri_table is
   set) or the 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(auth_id)", "$avp(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.  del_uri_param(param)

   Delete a parameter from the RURI being given the
   key(key=value);

   Meaning of the parameters is as follows:
     * param - key of the parameter to be removed/

   This function can be used from REQUEST_ROUTE.

   Example 1.22. add_uri_param usage
...
del_uri_param("name");
...

1.4.13.  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.23. tel2sip usage
...
tel2sip();
...

1.4.14.  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.24. is_uri_user_e164 usage
...
if (is_uri_user_e164("$fu")) {  # Check From header URI user part
   ...
}
if (is_uri_user_e164("$avp(uri)") {
   # Check user part of URI stored in avp uri
   ...
};
...
