AVPops Module

Ramona-Elena Modroiu

   voice-system.ro

Edited by

Ramona-Elena Modroiu

   Copyright  2004, 2005 voice-system.ro
     _________________________________________________________

   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. AVP naming format
        1.4. Exported Parameters

              1.4.1. avp_url (string)
              1.4.2. db_url (string)
              1.4.3. avp_table (string)
              1.4.4. avp_aliases (string)
              1.4.5. use_domain (integer)
              1.4.6. uuid_column (string)
              1.4.7. username_column (string)
              1.4.8. domain_column (string)
              1.4.9. attribute_column (string)
              1.4.10. value_column (string)
              1.4.11. type_column (string)
              1.4.12. db_scheme (string)

        1.5. Exported Functions

              1.5.1. avp_db_load(source,name) 
              1.5.2. avp_db_store(source,name)
              1.5.3. avp_db_delete(source,name)
              1.5.4. avp_db_query(query[,dest])
              1.5.5. avp_write(value,name)
              1.5.6. avp_delete(name) 
              1.5.7. avp_pushto(destination,name) 
              1.5.8. avp_check(name,op_value) 
              1.5.9. avp_copy(old_name,new_name) 
              1.5.10. avp_printf(dest, format) 
              1.5.11. avp_subst(avps, subst)
              1.5.12. avp_op(name,op_value) 
              1.5.13. is_avp_set(name) 
              1.5.14. avp_print() 

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. AVP naming examples
   1-2. Set avp_url parameter
   1-3. Set avp_table parameter
   1-4. Set avp_aliases parameter
   1-5. Set use_domain parameter
   1-6. Set uuid_column parameter
   1-7. Set username_column parameter
   1-8. Set domain_column parameter
   1-9. Set attribute_column parameter
   1-10. Set value_column parameter
   1-11. Set type_column parameter
   1-12. Set db_scheme parameter
   1-13. avp_db_load usage
   1-14. avp_db_store usage
   1-15. avp_db_delete usage
   1-16. avp_db_query usage
   1-17. avp_write usage
   1-18. avp_delete usage
   1-19. avp_pushto usage
   1-20. avp_check usage
   1-21. avp_copy usage
   1-22. avp_printf usage
   1-23. avp_subst usage
   1-24. avp_op usage
   1-25. is_avp_set usage
   1-26. 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) 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.

   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. AVP naming format

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

     * avp_flags = type_flags [script_flags]; type_flags = 'I' |
       'i' | 'S' | 's'; script_flags = 0..255
       'I' or 'i' means that the type of avp name is integer (ID)
       'S' or 's' means that the type of avp name is string
       The type flag is mandatory.
       script_flags must be an 8 bit unsigned number, therefore
       can be set up to 8 flags. If no script flag is provided,
       the name will match all AVPs, regardless they have or not
       a script flag set (preserves the compatibility with the
       old naming schema).
     * avp_name = string | integer
       string - might be any alphanumeric string, wich contain
       following characters: [a-z] [A-Z] [0-9] '_'
       integer - might be an unsigned integer, greater than zero,
       up to 2^16-1
     * avp_alias = string
       string - might be any alphanumeric string, wich contain
       following characters: [a-z] [A-Z] [0-9] '_'

   Example 1-1. AVP naming examples
...
$avp(i:11) - the AVP identified by integer 11
$avp(s:foo) - the AVP identified by the string 'foo'
$avp(bar) - the AVP identified by the AVP alias 'bar'
$avp(i3:123) - the AVP identified by the integer 123 which has script f
lags 1
    and 2 set
...
     _________________________________________________________

1.4. Exported Parameters

1.4.1. avp_url (string)

   DB URL for database connection.

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

   Example 1-2. Set avp_url parameter
...
modparam("avpops","avp_url","mysql://user:passwd@host/database")
...
     _________________________________________________________

1.4.2. db_url (string)

   This parameter has the same meaning as "avp_url" parameter.
     _________________________________________________________

1.4.3. 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.4. avp_aliases (string)

   Contains a multiple definition of aliases for AVP names.

   This parameter is optional. 

   Example 1-4. Set avp_aliases parameter
...
modparam("avpops","avp_aliases","uuid=I:660;email=s:email_addr;fwd=i:75
3")
...
     _________________________________________________________

1.4.5. 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-5. Set use_domain parameter 
...
modparam("avpops","use_domain",1)
...
     _________________________________________________________

1.4.6. uuid_column (string)

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

   Default value is "uuid". 

   Example 1-6. Set uuid_column parameter
...
modparam("avpops","uuid_column","uuid")
...
     _________________________________________________________

1.4.7. username_column (string)

   Name of column containing the username.

   Default value is "username". 

   Example 1-7. Set username_column parameter
...
modparam("avpops","username_column","username")
...
     _________________________________________________________

1.4.8. domain_column (string)

   Name of column containing the domain name.

   Default value is "domain". 

   Example 1-8. Set domain_column parameter
...
modparam("avpops","domain_column","domain")
...
     _________________________________________________________

1.4.9. attribute_column (string)

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

   Default value is "attribute". 

   Example 1-9. Set attribute_column parameter 
...
modparam("avpops","attribute_column","attribute")
...
     _________________________________________________________

1.4.10. value_column (string)

   Name of column containing the AVP value.

   Default value is "value". 

   Example 1-10. Set value_column parameter 
...
modparam("avpops","value_column","value")
...
     _________________________________________________________

1.4.11. type_column (string)

   Name of column containing the AVP type.

   Default value is "type". 

   Example 1-11. Set type_column parameter 
...
modparam("avpops","type_column","type")
...
     _________________________________________________________

1.4.12. db_scheme (string)

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

   Default value is "NULL". 

   Example 1-12. Set db_scheme parameter 
...
modparam("avpops","db_scheme",
"scheme1:table=subscriber;uuid_column=uuid;value_column=first_name")
...
     _________________________________________________________

1.5. Exported Functions

1.5.1. avp_db_load(source,name)

   Loads from DB into memory the AVPs corresponding to the given
   source. If given, it sets the script flags for loaded AVPs.

   Meaning of the parameters is as follows:

     * source - what info is used for identifying the AVPs.
       Parameter syntax:
          + source = (pvar|str_value)
            ['/'('username'|'domain'|'uri'|'uuid')]) 
          + pvar = any pseudo variable defined in OpenSER. 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 - 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.

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

   Example 1-13. avp_db_load usage
...
avp_db_load("$fu","$(i:678)");
avp_db_load("$ru/domain","i:/domain_preferences");
avp_db_load("$uuid","$avp(s:404fwd)/fwd_table");
avp_db_load("$ru","$avp(i1:123)/$some_scheme");
...
     _________________________________________________________

1.5.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-14. avp_db_store usage
...
avp_db_store("$tu","$avp(i:678)");
avp_db_store("$ru/username","$avp(email)");
...
     _________________________________________________________

1.5.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-15. avp_db_delete usage
...
avp_db_delete("$tu","$avp(i:678)");
avp_db_delete("$ru/username","$avp(email)");
avp_db_delete("$uuid","$avp(s:404fwd)/fwd_table");
...
     _________________________________________________________

1.5.4. avp_db_query(query[,dest])

   Make a database query and store the result in AVPs.

   The meaning and usage of the parameters:

     * query - must be a valid SQL query. The parameter can
       contain pseudo-variables.
     * dest - a list with AVP names where to store the result.
       The format is "$avp(name1);$avp(name2);...". If this
       parameter is ommited, the result is stored in
       "$avp(i:1);$avp(i:2);...". If the result gives many rows,
       then multiple AVPs with corresponding name will be added.

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

   Example 1-16. avp_db_query usage
...
avp_db_query("select password, ha1 from subscriber where username='$tu'
",
        "$avp(i:678);$avp(i:679)");
avp_db_query("delete from subscriber");
...
     _________________________________________________________

1.5.5. 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 = pvar ['/'('username'|'domain')]) 
          + pvar = any pseudo-variable defined in OpenSER 
          + 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-17. avp_write usage
...
avp_write("$tu","$avp(i:678)");
avp_write("$ru/username","$avp(email)");
avp_write("$si","$avp(s:ip)");
avp_write("$du","$avp(s:next_hop)");
avp_write("$hdr(call-id)","$avp(i:11)");
avp_write("i:333","$avp(i:6)");
...
     _________________________________________________________

1.5.6. 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 = (matching_flags|avp_name|avp_alias)['/'flag] 
          + matching_flags = please refer to avp_db_load()
            function 
          + flag = 'g'|'G' 

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

   Example 1-18. avp_delete usage
...
avp_delete("$avp(i:678)/g");
avp_delete("$avp(email)");
avp_delete("i");
avp_delete("a3");
...
     _________________________________________________________

1.5.7. 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 = '$ru' ['/'('username'|'domain')] |
            '$du' | '$br' 
          + $ru '['/'('username'|'domain')] - write the AVP in
            the request URI or in username/domain part of it 
          + $du - write the AVP in 'dst_uri' field 
          + $br - write the AVP directly as a new branch (does
            not affect RURI) 
     * 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-19. avp_pushto usage
...
avp_pushto("$ru","$avp(i:678)");
avp_pushto("$ru/domain","$avp(s:backup_domains)/g");
avp_pushto("$du","$avp(i:679)");
avp_pushto("$br","$avp(i:680)");
...
     _________________________________________________________

1.5.8. 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 = ( pseudo-variable ) 
     * 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 = pseudo-variable | fix_value 
          + fix_value = 'i:'integer | 's:'string | string 
          + flags = 'g' | 'G' | 'i' | 'I' 
       Operator meaning:
          + eq - equal
          + ne - not equal
          + lt - less than
          + le - less or equal
          + gt - greater than
          + ge - greater or equal
          + re - regexp (regular exression match)
          + fm - fast match (see: man fnmatch)
          + and - bitwise 'and'
          + or - bitwise 'or'
          + xor - bitwise 'xor'
       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-20. avp_check usage
...
avp_check("$avp(i:678)", "lt/i:345/g");
avp_check("$fd","eq/$td/I");
avp_check("$avp(s:foo)","gt/$avp($bar)/g");
avp_check("$avp(s:foo)","re/sip:.*@bar.net/g");
avp_check("$avp(s:foo)","fm/$avp(fm_avp)/g");
...
     _________________________________________________________

1.5.9. 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-21. avp_copy usage
...
avp_copy("$avp(i:678)", "$avp(s:345)/g");
avp_copy("$avp(old)","$avp(new)/gd");
...
     _________________________________________________________

1.5.10. 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-1.1.x.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-22. avp_printf usage
...
avp_printf("$avp(i:20)", "This is a $rm request with call-id $hdr(call-
id)");
...
     _________________________________________________________

1.5.11. 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-23. 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("$avp(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("$avp(i:678)/$avp(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.5.12. 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 = pseudo-variable | fix_value 
          + 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-24. avp_op usage
...
avp_op("$avp(i:678)", "add/i:345/g");
avp_op("$avp(number)","sub/$avp(number2)/d");
...
     _________________________________________________________

1.5.13. 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 = avp_name|avp_alias [ '/' flags ]) 
            flags = ('e'|'s'|'n') - e = empty value; s = value
            string; n = value number (int) 

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

   Example 1-25. is_avp_set usage
...
if(is_avp_set("$avp(i:678)"))
    log("AVP with integer id 678 exists\n");
...
     _________________________________________________________

1.5.14. 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-26. 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 <team@openser.org> or, if you want to keep
   the mail private, send it to <ramona@voice-system.ro>.

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

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   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
   <team@openser.org>.