AVPops Module


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. AVP naming format
1.4. Exported Parameters
1.4.1. db_url (string)
1.4.2. avp_table (string)
1.4.3. use_domain (integer)
1.4.4. uuid_column (string)
1.4.5. username_column (string)
1.4.6. domain_column (string)
1.4.7. attribute_column (string)
1.4.8. value_column (string)
1.4.9. type_column (string)
1.4.10. db_scheme (string)
1.5. Exported Functions
1.5.1. avp_db_load(source, name, [db_id], [prefix]])
1.5.2. avp_db_store(source, name, [db_id])
1.5.3. avp_db_delete(source, name, [db_id])
1.5.4. avp_db_query(query, [res_col_avps], [db_id])
1.6. Exported Asynchronous Functions
1.6.1. avp_db_query(query, [dest], [db_id])
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

List of Examples

1.1. AVP naming examples
1.2. Set avp_url parameter
1.3. Set avp_table parameter
1.4. Set use_domain parameter
1.5. Set uuid_column parameter
1.6. Set username_column parameter
1.7. Set domain_column parameter
1.8. Set attribute_column parameter
1.9. Set value_column parameter
1.10. Set type_column parameter
1.11. Set db_scheme parameter
1.12. avp_db_load usage
1.13. avp_db_store usage
1.14. avp_db_delete usage
1.15. avp_db_query usage
1.16. async avp_db_query usage

Chapter 1. Admin Guide

1.1. Overview

AVPops (AVP-operations) modules implements a set of script functions which allow access and manipulation of user AVPs (preferences) and pseudo-variables. AVPs are a powerful tool for implementing services/preferences per user/domain. Now they are usable directly from configuration script. Functions for interfacing DB resources (loading/storing/removing), functions for swapping information between AVPs and SIP messages, function for testing/checking the value of an AVP.

AVPs are persistent per SIP transaction, being available in "route", "branch_route" and "failure_route". To make them available in "onreply_route" armed via TM module, set "onreply_avp_mode" parameter of TM module (note that in the default "onreply_route", the AVPs of the transaction are not available).

1.2. Dependencies

1.2.1. OpenSIPS Modules

The following modules must be loaded before this module:

  • Optionally a database 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. AVP naming format

The format of the parameters specifying an AVP in functions exported by this module is: $avp(avp_name).

  • avp_name = string | integer

    string - might be any alphanumeric string, wich contain following characters: [a-z] [A-Z] [0-9] '_'

Example 1.1. AVP naming examples

...
$avp(11) - the AVP identified by name 11
$avp(foo) - the AVP identified by the string 'foo'
...
				

1.4. Exported Parameters

1.4.1. db_url (string)

DB URL for database connection. As the module allows the usage of multiple DBs (DB URLs), the actual DB URL may be preceded by an reference number. This reference number is to be passed to AVPOPS function that what to explicitly use this DB connection. If no reference number is given, 0 is assumed - this is the default DB URL.

This parameter is optional, it's default value being NULL.

Example 1.2. Set avp_url parameter

...
# default URL
modparam("avpops","db_url","mysql://user:passwd@host/database")
# an additional DB URL
modparam("avpops","db_url","1 postgres://user:passwd@host2/opensips")
...
				

1.4.2. avp_table (string)

DB table to be used.

This parameter is optional, it's default value being NULL.

Example 1.3. Set avp_table parameter

...
modparam("avpops","avp_table","avptable")
...
				

1.4.3. use_domain (integer)

If the domain part of the an URI should be used for identifying an AVP in DB operations.

Default value is 0 (no).

Example 1.4. Set use_domain parameter

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

1.4.4. uuid_column (string)

Name of column containing the uuid (unique user id).

Default value is uuid.

Example 1.5. Set uuid_column parameter

...
modparam("avpops","uuid_column","uuid")
...
				

1.4.5. username_column (string)

Name of column containing the username.

Default value is username.

Example 1.6. Set username_column parameter

...
modparam("avpops","username_column","username")
...
				

1.4.6. domain_column (string)

Name of column containing the domain name.

Default value is domain.

Example 1.7. Set domain_column parameter

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

1.4.7. attribute_column (string)

Name of column containing the attribute name (AVP name).

Default value is attribute.

Example 1.8. Set attribute_column parameter

...
modparam("avpops","attribute_column","attribute")
...
				

1.4.8. value_column (string)

Name of column containing the AVP value.

Default value is value.

Example 1.9. Set value_column parameter

...
modparam("avpops","value_column","value")
...
				

1.4.9. type_column (string)

Name of column containing the AVP type.

Default value is type.

Example 1.10. Set type_column parameter

...
modparam("avpops","type_column","type")
...
				

1.4.10. db_scheme (string)

Definition of a DB scheme to be used for non-standard access to Database information.

Definition of a DB scheme. Scheme syntax is:

  • db_scheme = name':'element[';'element]*

  • element =

    • 'uuid_col='string

    • 'username_col='string

    • 'domain_col='string

    • 'value_col='string

    • 'value_type='('integer'|'string')

    • 'table='string

Default value is NULL.

Example 1.11. Set db_scheme parameter

...
modparam("avpops","db_scheme",
"scheme1:table=subscriber;uuid_col=uuid;value_col=first_name")
...
				

1.5. Exported Functions

1.5.1.  avp_db_load(source, name, [db_id], [prefix]])

Loads from DB into memory the AVPs corresponding to the given source. If given, it sets the script flags for loaded AVPs. It returns true if it loaded some values in AVPs, false otherwise (db error, no avp loaded ...).

AVPs may be preceded by an optional prefix, in order to avoid some conflicts.

Meaning of the parameters is as follows:

  • source (string, no expand) - what info is used for identifying the AVPs. Parameter syntax:

    • source = (pvar|str_value) ['/'('username'|'domain'|'uri'|'uuid')])

    • pvar = any pseudo variable defined in OpenSIPS. If the pvar is $ru (request uri), $fu (from uri), $tu (to uri) or $ou (original uri), then the implicit flag is 'uri'. Otherwise, the implicit flag is 'uuid'.

  • name (string, no expand) - which AVPs will be loaded from DB into memory. Parameter syntax is:

    • name = avp_spec['/'(table_name|'$'db_scheme)]

    • avp_spec = matching_flags|$avp(avp_name)|$avp(avp_alias)

    • matching_flags = 'a' | 'A' | 'i' | 'I' | 's' | 'S' [script_flags]

      'a' or 'A' means matching any of AVP name types ('i' and 's'), the rest have the meaning descriped in 'AVP naming format' chapter.

  • db_id (int, optional) - reference to a defined DB URL (a numerical id) - see the db_url module parameter.

  • prefix (string, optional) - static string which will precede the names of the AVPs populated by this function.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.

Example 1.12. avp_db_load usage

...
avp_db_load("$fu", "$avp(678)");
avp_db_load("$ru/domain", "i/domain_preferences");
avp_db_load("$avp(uuid)", "$avp(404fwd)/fwd_table");
avp_db_load("$ru", "$avp(123)/$some_scheme");

# use DB URL id 3
avp_db_load("$ru", "$avp(1)", 3);

# precede all loaded AVPs by the "caller_" prefix
avp_db_load("$ru", "$avp(100)", , "caller_");
xlog("Loaded: $avp(caller_100)\n");

...
				

1.5.2.  avp_db_store(source, name, [db_id])

Stores to DB the AVPs corresponding to the given source.

The meaning and usage of the parameters are identical as for avp_db_load(source, name) function. Please refer to its description.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.

Example 1.13. avp_db_store usage

...
avp_db_store("$tu", "$avp(678)");
avp_db_store("$ru/username", "$avp(email)");
# use DB URL id 3
avp_db_store("$ru", "$avp(1)", 3);
...
				

1.5.3.  avp_db_delete(source, name, [db_id])

Deletes from DB the AVPs corresponding to the given source.

The meaning and usage of the parameters are identical as for avp_db_load(source, name) function. Please refer to its description.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.

Example 1.14. avp_db_delete usage

...
avp_db_delete("$tu", "$avp(678)");
avp_db_delete("$ru/username", "$avp(email)");
avp_db_delete("$avp(uuid)", "$avp(404fwd)/fwd_table");
# use DB URL id 3
avp_db_delete("$ru", "$avp(1)", 3);
...
				

1.5.4.  avp_db_query(query, [res_col_avps], [db_id])

Make a database query and store the result in AVPs.

The meaning and usage of the parameters:

  • query (string) - must be a valid SQL query. The parameter can contain pseudo-variables.

    You must escape any pseudo-variables manually to prevent SQL injection attacks. You can use the existing transformations escape.common and unescape.common to escape and unescape the content of any pseudo-variable. Failing to escape the variables used in the query makes you vulnerable to SQL injection, e.g. make it possible for an outside attacker to alter your database content. The function returns true if the query was successful, -2 in case the query returned an empty result set, and -1 for all other types of errors

  • res_col_avps (string, optional, no expand) - a list with AVP names where to store the result. The format is $avp(name1);$avp(name2);.... If this parameter is omitted, the result is stored in $avp(1);$avp(2);.... If the result consists of multiple rows, then multiple AVPs with corresponding names will be added. The value type of the AVP (string or integer) will be derived from the type of the columns. If the value in the database is NULL, the returned avp will be a string with the <null> value.

  • db_id (int, optional) - reference to a defined DB URL (a numerical id) - see the db_url module parameter. It can be either a constant, or a string/int variable.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.

Example 1.15. avp_db_query usage

...
avp_db_query("SELECT password, ha1 FROM subscriber WHERE username='$tu'",
	"$avp(pass);$avp(hash)");
avp_db_query("DELETE FROM subscriber");
avp_db_query("DELETE FROM subscriber", , 2);

$avp(id) = 2;
avp_db_query("DELETE FROM subscriber", , $avp(id));
...
				

1.6. Exported Asynchronous Functions

1.6.1.  avp_db_query(query, [dest], [db_id])

This function takes the same parameters and behaves identically to avp_db_query(), but asynchronously (after launching the query, the current SIP worker pauses the execution of the current SIP message until the result is available and attempts to process more SIP traffic).

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.

Example 1.16. async avp_db_query usage

...
{
...
/* Example of a slow MySQL query - it should take around 5 seconds */
async(
	avp_db_query(
		"SELECT table_name, table_version, SLEEP(0.1) from version",
		"$avp(tb_name); $avp(tb_ver); $avp(retcode)"),
	my_resume_route);
/* script execution is halted right after the async() call */
}

/* We will be called when data is ready - meanwhile, the worker is free */
route [my_resume_route]
{
	xlog("Results: \n$(avp(tb_name)[*])\n
-------------------\n$(avp(tb_ver)[*])\n
-------------------\n$(avp(retcode)[*])\n");
}
...
				

Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

 NameDevScoreCommitsLines ++Lines --
1. Bogdan-Andrei Iancu (@bogdan-iancu)124586903625
2. Daniel-Constantin Mierla (@miconda)1044429272158
3. Liviu Chircu (@liviuchircu)53271112944
4. Elena-Ramona Modroiu51114040390
5. Razvan Crainea (@razvancrainea)2114149246
6. Elena-Ramona Modroiu1851051192
7. Henning Westerholt (@henningw)128112133
8. Vlad Paiu (@vladpaiu)97392
9. Ionut Ionita (@ionutrazvanionita)8518012
10. Kobi Eshun (@ekobi)71300146

All remaining contributors: Andrei Pelinescu-Onciul, Anca Vamanu, Maksym Sobolyev (@sobomax), Norman Brandinger (@NormB), Vlad Patrascu (@rvlad-patrascu), Klaus Darilion, John Burke (@john08burke), Andrey Vorobiev, Olle E. Johansson, Kennard White, Julián Moreno Patiño, Konstantin Bokarius, Walter Doekes (@wdoekes), Andreas Granig, Peter Lemenkov (@lemenkov), Sergio Gutierrez, Edson Gellert Schubert, Ovidiu Sas (@ovidiusas).

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2. By Commit Activity

Table 2.2. Most recently active contributors(1) to this module

 NameCommit Activity
1. Bogdan-Andrei Iancu (@bogdan-iancu)Jun 2005 - Feb 2024
2. Vlad Paiu (@vladpaiu)Jun 2011 - Jul 2023
3. Razvan Crainea (@razvancrainea)Jun 2011 - Mar 2023
4. Maksym Sobolyev (@sobomax)Oct 2022 - Feb 2023
5. John Burke (@john08burke)Jun 2022 - Jun 2022
6. Liviu Chircu (@liviuchircu)Mar 2013 - Mar 2020
7. Vlad Patrascu (@rvlad-patrascu)May 2017 - Jul 2019
8. Peter Lemenkov (@lemenkov)Jun 2018 - Jun 2018
9. Andrey VorobievApr 2016 - Apr 2016
10. Julián Moreno PatiñoFeb 2016 - Feb 2016

All remaining contributors: Ionut Ionita (@ionutrazvanionita), Ovidiu Sas (@ovidiusas), Walter Doekes (@wdoekes), Anca Vamanu, Kennard White, Norman Brandinger (@NormB), Sergio Gutierrez, Kobi Eshun (@ekobi), Henning Westerholt (@henningw), Olle E. Johansson, Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Elena-Ramona Modroiu, Klaus Darilion, Andreas Granig, Andrei Pelinescu-Onciul, Elena-Ramona Modroiu.

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Razvan Crainea (@razvancrainea), John Burke (@john08burke), Liviu Chircu (@liviuchircu), Peter Lemenkov (@lemenkov), Ionut Ionita (@ionutrazvanionita), Vlad Paiu (@vladpaiu), Anca Vamanu, Norman Brandinger (@NormB), Kobi Eshun (@ekobi), Henning Westerholt (@henningw), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Elena-Ramona Modroiu, Klaus Darilion, Andrei Pelinescu-Onciul, Elena-Ramona Modroiu.

Documentation Copyrights:

Copyright © 2004-2008 Voice Sistem SRL