AVPops Module

Ramona-Elena Modroiu

Edited by

Ramona-Elena Modroiu


Table of Contents
1. User's Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSER Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. avp_url (string)
1.3.2. avp_table (string)
1.3.3. avp_aliases (string)
1.3.4. use_domain (integer)
1.3.5. uuid_column (string)
1.3.6. username_column (string)
1.3.7. domain_column (string)
1.3.8. attribute_column (string)
1.3.9. value_column (string)
1.3.10. type_column (string)
1.3.11. db_scheme (string)
1.4. Exported Functions
1.4.1. avp_db_load(source,name)
1.4.2. avp_db_store(source,name)
1.4.3. avp_db_delete(source,name)
1.4.4. avp_write(value,name)
1.4.5. avp_delete(name)
1.4.6. avp_pushto(destination,name)
1.4.7. avp_check(name,op_value)
1.4.8. avp_copy(old_name,new_name)
1.4.9. avp_printf(dest, format)
1.4.10. avp_subst(avps, subst)
1.4.11. avp_op(name,op_value)
1.4.12. is_avp_set(name)
1.4.13. avp_print()
2. Developer's Guide
3. Frequently Asked Questions
List of Examples
1-1. Set avp_url parameter
1-2. Set avp_table parameter
1-3. Set avp_aliases 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_write usage
1-16. avp_delete usage
1-17. avp_pushto usage
1-18. avp_check usage
1-19. avp_copy usage
1-20. avp_printf usage
1-21. avp_subst usage
1-22. avp_op usage
1-23. is_avp_set usage
1-24. avp_print usage

Chapter 1. User's Guide

1.1. Overview

AVPops (AVP-operations) modules implements a set of script functions which allow access and manipulation of user AVPs (preferences). 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.

An up-to-date tutorial providing more information (detailed explanations and commented examples) can be found on Voice Sistem documentation web page at http://voice-system.ro/docs/avpops .


1.2. Dependencies

1.2.1. OpenSER 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 OpenSER with this module loaded:

  • None


1.3. Exported Parameters

1.3.1. avp_url (string)

DB URL for database connection.

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

Example 1-1. Set avp_url parameter

...
modparam("avpops","avp_url","mysql://user:passwd@host/database")
...
				

1.3.2. avp_table (string)

DB table to be used.

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

Example 1-2. Set avp_table parameter

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

1.3.3. avp_aliases (string)

Contains a multiple definition of aliases for AVP names.

This parameter is optional.

Example 1-3. Set avp_aliases parameter

...
modparam("avpops","avp_aliases","uuid=I:660;email=s:email_addr;fwd=i:753")
...
				

1.3.4. 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.3.5. 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.3.6. 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.3.7. 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.3.8. 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.3.9. 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.3.10. 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.3.11. db_scheme (string)

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

Default value is "NULL".

Example 1-11. Set db_scheme parameter

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

1.4. Exported Functions

1.4.1. avp_db_load(source,name)

Loads from DB into memory the AVPs corresponding to the given source.

Meaning of the parameters is as follows:

  • source - what info is used for identifying the AVPs. Parameter syntax:

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

    • sip_uri = '$from' | '$to' | '$ruri'

  • name - which AVPs will be loaded from DB into memory. Parameter syntax is:

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

    • avp_spec = ''|'s:'|'i:'|avp_name|avp_alias

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-12. avp_db_load usage

...
avp_db_load("$from","i:678");
avp_db_load("$ruri/domain","i:/domain_preferences");
avp_db_load("$uuid","s:404fwd/fwd_table");
avp_db_load("$ruri","i:123/$some_scheme");
...
				

1.4.2. avp_db_store(source,name)

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.

Example 1-13. avp_db_store usage

...
avp_db_store("$to","i:678");
avp_db_store("$ruri/username","$email");
...
				

1.4.3. avp_db_delete(source,name)

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.

Example 1-14. avp_db_delete usage

...
avp_db_delete("$to","i:678");
avp_db_delete("$ruri/username","$email");
avp_db_delete("$uuid","s:404fwd/fwd_table");
...
				

1.4.4. avp_write(value,name)

The function writes some value (given) or some information from the SIP message into a new AVP.

Meaning of the parameters is as follows:

  • value - the value to be written into the AVP. Parameter syntax:

    • value = (variable) | (fix_value)

    • variable = '$src_ip' | '$dst_ip' | '$hdr(name)' | '$duri' | (sip_uri)['/'('username'|'domain')])

    • sip_uri = '$from' | '$to' | '$ruri'

    • fix_value = 'i:'integer | 's:'string | string

    Integer values can be given in hexadecimal using notation 'i:0xhex_number' (e.g.,: 'i:0xabcd');

  • name - the name of the new written AVP. Parameter syntax is:

    • name = avp_name | avp_alias

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-15. avp_write usage

...
avp_write("$to","i:678");
avp_write("$ruri/username","$email");
avp_write("$src_ip","s:ip");
avp_write("$duri","s:next_hop");
avp_write("$hdr[call-id]","i:11");
avp_write("i:333","i:6");
...
				

1.4.5. avp_delete(name)

Deletes from memory the AVPs with name or, if empty, all AVPs.

Meaning of the parameters is as follows:

  • name - which AVPs will be deleted from memory. Parameter syntax is:

    • name = (''|'s:'|'i:'|avp_name|avp_alias)['/'flag]

    • flag = 'g'|'G'

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-16. avp_delete usage

...
avp_delete("i:678/g");
avp_delete("$email");
avp_delete("i:");
avp_delete("");
...
				

1.4.6. avp_pushto(destination,name)

Pushes the value of AVP(s) into the SIP message.

Meaning of the parameters is as follows:

  • destination - as what will be the AVP value pushed into SIP message. Parameter syntax:

    • destination = ruri_dst | hdr_dst | '$duri'

    • ruri_dst = '$ruri'['/'('username'|'domain')]

    • hdr_dst = '$hdr_name'['/'('request'|'reply')]

  • name - which AVP(s) should be pushed into the SIP message. Parameter syntax is:

    • name = ( avp_name | avp_alias )['/'flags]

    • flags = 'g'

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-17. avp_pushto usage

...
avp_pushto("$ruri","i:678");
avp_pushto("$ruri/domain","s:backup_domains/g");
avp_pushto("$duri","i:679");
avp_pushto("$Email/reply","s:email");
avp_pushto("$Foo","$bar/g");
...
				

1.4.7. avp_check(name,op_value)

Checks the value of the AVP(s) against an operator and value.

Meaning of the parameters is as follows:

  • name - which AVP(s) should be checked. Parameter syntax is:

    • name = ( avp_name | avp_alias )

  • op_value - define the operator, the value and flags for checking. Parameter syntax is:

    • op_value = operator '/' value ['/'flags]

    • operator = 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge' | 're' | 'fm' | 'and' | 'or' | 'xor'

    • value = variable | fix_value

    • variable = '$from'|'$ruri'|'$from'|'$src_ip'|'$dst_ip'|avp_alias

    • fix_value = 'i:'integer | 's:'string | string

    • flags = 'g' | 'G' | 'i' | 'I'

    Integer values can be given in hexadecimal using notation: 'i:0xhex_number' (e.g.,: 'i:0xabcd');

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-18. avp_check usage

...
avp_check("i:678", "lt/i:345/g");
avp_check("s:person","eq/$from/I");
avp_check("s:foo","gt/$bar/g");
avp_check("s:foo","re/sip:.*@bar.net/g");
avp_check("s:foo","fm/$fm_avp/g");
...
				

1.4.8. avp_copy(old_name,new_name)

Copy / move an avp under a new name.

Meaning of the parameters is as follows:

  • name1 - which AVP(s) should be copied/moved. Parameter syntax is:

    • name = ( avp_name | avp_alias )

  • name2 - the new name of the copied/moved AVP(s). Parameter syntax is:

    • name = ( avp_name | avp_alias ) ['/'flags]

    • flags = 'g' | 'G' | 'd' | 'D' | 'n' | 'N' | 's' | 'S'

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-19. avp_copy usage

...
avp_copy("i:678", "s:345/g");
avp_copy("$old","$new/gd");
...
				

1.4.9. avp_printf(dest, format)

Prints the formatted string 'format' in the AVP 'dest'. The 'format' parameter can include any pseudo-variable defined in OpenSER. The list with all pseudo-variables in OpenSER can be found at: http://openser.org/docs/pseudo-variables.html.

Meaning of the parameters is as follows:

  • dest - in which AVP should be stored the result. Parameter syntax is:

    • name = ( avp_name | avp_alias )

  • format - the formatted string to be printed in 'dest' AVP.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-20. avp_printf usage

...
avp_printf("i:20", "This is a $rm request with the call-id $hdr(call-id)");
...
				

1.4.10. avp_subst(avps, subst)

Perl/sed-like subst applied to AVPs having string value.

Meaning of the parameters is as follows:

  • avps - source AVP, destination AVP and flags. Parameter syntax is:

    • avps = src_avp [ '/' dst_avp [ '/' flags ] ]

    • src_avp = ( avp_name | avp_alias )

    • dst_avp = ( avp_name | avp_alias ) - if dst_avp is missing then the value of src_avp will be replaced

    • flags = ( d | D | g | G ) -- (d, D - delete source avp; g, G - apply to all avps matching src_avp name)

  • subst - perl/sed-like reqular expression. Parameter syntax is:

    • subst = "/regexp/replacement/flags"

    • regexp - regular expression

    • replacement - replacement string, can include pseudo-variables and \1, ..., \9 for matching tokens, \0 for whole matching text

    • flags = 'g' | 'G' | 'i' | 'i' (g, G - replace all matching tokens; i, I - match ignore case)

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-21. avp_subst usage

...
# if avp i:678 has a string value in e-mail format, replace the
# domain part with the value of domain part from R-URI
avp_subst("i:678", "/(.*)@(.*)/\1@$rd/");

# if any avp i:678 has a string value in e-mail format, replace the
# domain part with the value of domain part from R-URI
# and place the result in avp i:679
avp_subst("i:678/i:679/g", "/(.*)@(.*)/\1@$rd/");
...
				

IMPORTANT NOTE: if the replacement string includes src_avp or dst_avp you will get something that you may not expect. In case you have many src_avp and you make the substitution to be applied to all of them, after the first src_avp is processed, it will be added in avp list and next processing will use it.


1.4.11. avp_op(name,op_value)

Different integer operations with avps.

Meaning of the parameters is as follows:

  • name - 'source_avp/destination_avp' - which AVP(s) should be processed and where to store the result. If 'destination_avp' is missing, same name as 'source_avp' is used to store the result.

    Parameter syntax is:

    • name = ( source_avp[/destination_avp] )

      source_avp = ( avp_name | avp_alias )

      destination_avp = ( avp_name | avp_alias )

  • op_value - define the operation, the value and flags. Parameter syntax is:

    • op_value = operator '/' value ['/'flags]

    • operator = 'add' | 'sub' | 'mul' | 'div' | 'mod' | 'and' | 'or' | 'xor' | 'not'

    • value = variable | fix_value

    • variable = avp_alias

    • fix_value = 'i:'integer

    • flags = 'g' | 'G' | 'd' | 'D'

    Integer values can be given in hexadecimal using notation 'i:0xhex_number' (e.g.,: 'i:0xabcd');

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-22. avp_op usage

...
avp_op("i:678", "add/i:345/g");
avp_op("$number","sub/$number2/d");
...
				

1.4.12. is_avp_set(name)

Check if any AVP with name is set.

Meaning of the parameters is as follows:

  • name - name of AVP to look for. Parameter syntax is:

    • name = ('s:'|'i:'|avp_name|avp_alias [ '/' flags ])

      flags = ('s'|'n') - s = value string; n = value number (int)

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-23. is_avp_set usage

...
if(is_avp_set("i:678"))
    log("AVP with integer id 678 exists\n");
...
				

1.4.13. avp_print()

Prints the list with all the AVPs from memory. This is only a helper/debug function.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-24. avp_print usage

...
avp_print();
...
				

Chapter 2. Developer's Guide

The module does not provide any API to use in other OpenSER modules.


Chapter 3. Frequently Asked Questions

3.1. Where can I find more documentation about this module?
3.2. Where can I post a question about this module?
3.3. How can I report a bug?

3.1. Where can I find more documentation about this module?

An up-to-date tutorial providing more information (detailed explanations and commneted examples) can be found on Voice Sistem documentation web page at http://voice-system.ro/docs/avpops .

3.2. Where can I post a question about this module?

Sent an email to or, if you want to keep the mail private, send it to .

Remember: first at all, check if your question was already answered on one of OpenSER mailing lists:

3.3. How can I report a bug?

Accumulate as much as possible information (OpenSER version, openser -V output, your OS (uname -a), OpenSER logs, network dumps, core dump files, configuration file) and send a mail to .