
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. 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:75
3")
...
     _________________________________________________________

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 <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>.
