kamailio/modules/avpops

AVPops Module

Ramona-Elena Modroiu

   <ramona@rosdev.ro>

Edited by

Ramona-Elena Modroiu

   <ramona@rosdev.ro>

   Copyright © 2004, 2005 Voice Sistem SRL
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. AVP naming format
        4. Parameters

              4.1. db_url (string)
              4.2. avp_table (string)
              4.3. use_domain (integer)
              4.4. uuid_column (string)
              4.5. username_column (string)
              4.6. domain_column (string)
              4.7. attribute_column (string)
              4.8. value_column (string)
              4.9. type_column (string)
              4.10. db_scheme (string)

        5. Functions

              5.1. avp_db_load(source,name)
              5.2. avp_db_store(source,name)
              5.3. avp_db_delete(source,name)
              5.4. avp_db_query(query[,dest])
              5.5. avp_delete(name)
              5.6. avp_pushto(destination,name)
              5.7. avp_check(name,op_value)
              5.8. avp_copy(old_name,new_name)
              5.9. avp_printf(dest, format)
              5.10. avp_subst(avps, subst)
              5.11. avp_op(name,op_value)
              5.12. is_avp_set(name)
              5.13. avp_print()

   List of Examples

   1.1. AVP naming examples
   1.2. Set db_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. 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. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. AVP naming format
   4. Parameters

        4.1. db_url (string)
        4.2. avp_table (string)
        4.3. use_domain (integer)
        4.4. uuid_column (string)
        4.5. username_column (string)
        4.6. domain_column (string)
        4.7. attribute_column (string)
        4.8. value_column (string)
        4.9. type_column (string)
        4.10. db_scheme (string)

   5. Functions

        5.1. avp_db_load(source,name)
        5.2. avp_db_store(source,name)
        5.3. avp_db_delete(source,name)
        5.4. avp_db_query(query[,dest])
        5.5. avp_delete(name)
        5.6. avp_pushto(destination,name)
        5.7. avp_check(name,op_value)
        5.8. avp_copy(old_name,new_name)
        5.9. avp_printf(dest, format)
        5.10. avp_subst(avps, subst)
        5.11. avp_op(name,op_value)
        5.12. is_avp_set(name)
        5.13. avp_print()

1. Overview

   The AVPops (AVP-operations) module implements a set of script functions
   which allow access and manipulation of user attribute-value pairs
   (AVPs, preferences) and pseudo-variables. AVPs are a powerful tool for
   implementing services/preferences per user/domain. With this module,
   they are usable directly from configuration script.

   The module implement functions for interfacing DB resources
   (loading/storing/removing), functions for swapping information between
   AVPs and SIP messages and a function for testing/checking the value of
   an AVP.

   If you just need a way to execute SQL statements in a Kamailio
   configuration script, please consider use the sqlops module instead.

   AVPs are persistent per SIP transaction, being available in "route",
   "branch_route" and "failure_route". A tutorial providing more
   information (detailed explanations and commented examples) can be found
   on the SIP-router web site.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * Optionally a database module

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None

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 an integer (ID)
       'S' or 's' means that the type of avp name is string
       The type flag is mandatory. Please note that the type flag only
       indicates type of name, not type of variable. An avp with name type
       "i" may very well contain text strings.
       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 flags 1
    and 2 set
...

4. Parameters

   4.1. db_url (string)
   4.2. avp_table (string)
   4.3. use_domain (integer)
   4.4. uuid_column (string)
   4.5. username_column (string)
   4.6. domain_column (string)
   4.7. attribute_column (string)
   4.8. value_column (string)
   4.9. type_column (string)
   4.10. db_scheme (string)

4.1. db_url (string)

   DB URL for database connection.

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

   Example 1.2. Set db_url parameter
...
modparam("avpops","db_url","mysql://user:passwd@host/database")
...

4.2. avp_table (string)

   DB table to be used.

   This parameter is optional, it's default value being NULL. But if you
   specify a db_url, you need also setup this parameter.

   Example 1.3. Set avp_table parameter
...
modparam("avpops","avp_table","avptable")
...

4.3. use_domain (integer)

   If the domain part of the 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)
...

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

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

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

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

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

4.9. type_column (string)

   Name of integer column containing the AVP type.

   Default value is “type”.

   Possible column values are
     * 0 - AVP with string name and string value
     * 1 - AVP with string name and integer value
     * 2 - AVP with integer name and string value
     * 3 - AVP with integer name and integer value

   Example 1.10. Set type_column parameter
...
modparam("avpops","type_column","type")
...

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

5. Functions

   5.1. avp_db_load(source,name)
   5.2. avp_db_store(source,name)
   5.3. avp_db_delete(source,name)
   5.4. avp_db_query(query[,dest])
   5.5. avp_delete(name)
   5.6. avp_pushto(destination,name)
   5.7. avp_check(name,op_value)
   5.8. avp_copy(old_name,new_name)
   5.9. avp_printf(dest, format)
   5.10. avp_subst(avps, subst)
   5.11. avp_op(name,op_value)
   5.12. is_avp_set(name)
   5.13. avp_print()

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. It returns true if
   it loaded some values in AVPs, false otherwise (db error, no avp loaded
   ...).

   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 Kamailio. 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')
            (NOTE: matching_flags cannot be used with $db_scheme because
            the name of AVP to save in cannot be specified), the rest have
            the meaning descriped in 'AVP naming format' chapter.

   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","$(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");
...

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, LOCAL_ROUTE and ONREPLY_ROUTE.

   Example 1.13. avp_db_store usage
...
avp_db_store("$tu","$avp(i:678)");
avp_db_store("$ru/username","$avp(email)");
...

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, LOCAL_ROUTE and ONREPLY_ROUTE.

   Example 1.14. 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");
...

5.4.  avp_db_query(query[,dest])

   Make a database query and store the result in AVPs. This command is
   deprecated, please use the more flexible and advanced sqlops module
   instead.

   The meaning and usage of the parameters:
     * query - 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.
     * 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. The value type of the AVP (string or integer) will be
       derived from the type of the columns. Please note that only this
       two datatypes are supported, so its not possible for example to
       return floating point or big integer values this way.

   The function delivers the following return-codes:
     * -1 - An error occured while querying the database (e.g. wrong SQL
       or database error)
     * 1 - Query was successful
     * -2 - Query was successful, but no rows where returned.

   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(i:678);$avp(i:679)");
avp_db_query("delete from subscriber");
...

5.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 = (matching_flags|avp_name|avp_alias)['/'flag]
          + matching_flags = please refer to avp_db_load() function
          + flag = 'g'|'G' = deletes not only the last value but the
            complete AVP.

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

   Example 1.16. avp_delete usage
...
avp_delete("$avp(i:678)/g");
avp_delete("$avp(email)");
avp_delete("i");
avp_delete("a3");
...

5.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 = '$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)/pseudo-variable should be pushed into the SIP
       message. Parameter syntax is:
          + name = ( avp_name | avp_alias | pvar_name )['/'flags]
          + flags = 'g' - effective only with AVPs

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

   Example 1.17. avp_pushto usage
...
avp_pushto("$ru/domain","$fd");
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)");
...

5.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 = ( 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, LOCAL_ROUTE and ONREPLY_ROUTE.

   Example 1.18. 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($var(bar))/g");
avp_check("$avp(s:foo)","re/sip:.*@bar.net/g");
avp_check("$avp(s:foo)","fm/$avp(fm_avp)/g");
...

   NOTE: you can use a xavp variable ($xavp(key1[indx1]=>key2[indx2])) as
   first or second parameter. If you want to check all the values of the
   key2 you should use [*] at indx2. The [*] index is not allowed at
   indx1.
...
avp_check("$xavp(op[0]=>lt[0])", "lt/i:345/g");
avp_check("$xavp(op=>fd","eq/$td/I");
avp_check("$xavp(op[1]=>foo[*])","gt/$avp($var(bar))/g");
avp_check("$avp(s:foo)","re/$xavp(op[0]=>re[*]/g");
$var(id)=2;
avp_check("$xavp(op=>foo[*])","fm/$xavp(op=>fm[$var(id)])/g");
...

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

   NOTE: if a list of AVPs is copied/moved (flag g|G), then the order of
   the values is reversed. Copy/move twice in order to get the same order
   as in original list.

   This function can be used from ANY_ROUTE.

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

5.9.  avp_printf(dest, format)

   NOTE: since Kamailio 1.3.0 the function has been moved to core and it
   is an alias to pv_printf().

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

   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, LOCAL_ROUTE and ONREPLY_ROUTE.

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

5.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, LOCAL_ROUTE and ONREPLY_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("$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.

5.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 = 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, LOCAL_ROUTE and ONREPLY_ROUTE.

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

5.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 = 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, LOCAL_ROUTE and ONREPLY_ROUTE.

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

5.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, LOCAL_ROUTE and ONREPLY_ROUTE.

   Example 1.24. avp_print usage
...
avp_print();
...