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.4.1. avp_url (string)

DB URL for database connection.

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

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

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

1.4.4. avp_aliases (string) - removed

This is no longer a parameter of 'avpops' module. AVP aliases can be defined directly in configuration script, in global parameters section.

...
avp_aliases="uuid=I:660;email=s:email_addr;fwd=i:753"
...
				

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

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

1.4.6. uuid_column (string)

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

Default value is "uuid".

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

1.4.7. username_column (string)

Name of column containing the username.

Default value is "username".

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

1.4.8. domain_column (string)

Name of column containing the domain name.

Default value is "domain".

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

1.4.9. attribute_column (string)

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

Default value is "attribute".

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

1.4.10. value_column (string)

Name of column containing the AVP value.

Default value is "value".

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

1.4.11. type_column (string)

Name of column containing the AVP type.

Default value is "type".

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

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

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

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

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

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

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

  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.

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

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

The function has been removed from 'avpops' module. Same functionality can be achived directly in configuration script via assignement operator.

...
avp_write("$tu","$avp(i:678)");           => $avp(i:678) = $tu;
avp_write("$ru/username","$avp(email)");  => $avp(email) = $rU;
avp_write("$si","$avp(s:ip)");            => $avp(s:ip) = $si;
avp_write("$du","$avp(s:next_hop)");      => $avp(s:next_hop) = $du;
avp_write("$hdr(call-id)","$avp(i:11)");  => $avp(i:11) = $hdr(call-id);
avp_write("i:333","$avp(i:6)");           => $avp(i:6) = 333;
avp_write("s:abc","$avp(i:7)");           => $avp(i:7) = "abc";
...
				

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

...
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)/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 and ONREPLY_ROUTE.

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

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

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

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

1.5.10. avp_printf(dest, format)

NOTE: since OpenSER 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 OpenSER. The list with all pseudo-variables in OpenSER can be found at: http://openser.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 and ONREPLY_ROUTE.

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

...
# 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 and ONREPLY_ROUTE.

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

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

...
avp_print();
...