AVPs in SER

AVPs are divided in lists (also referred as tracks). The lists allow loading at the same time AVPs with the same name for both the caller and the callee. There are 3 AVPs lists: "from" (the AVPs loaded based on the caller), "to" (the AVPs loaded based on the callee) and "global" (the list of global AVPs, loaded independent of any message attribute). If the AVP list is not specified, the "from" list will be used by default.

Each AVP lists, except the global one, is further divided into levels (also referred as classes). Each level has its own namespace (several levels can contain AVPs with the same name in the same time). There are 3 AVP levels: "URI", "user" and "domain". The levels allow further grouping of the AVPs based on characteristics such as uri, user or domain and choosing the most specific defined AVP if the level is not explicitly specified (e.g. an user level AVP will override a domain level AVP with the same name). The levels can also reduce the number of attributes stored in the database, by having the attributes common for the entire domain (a kind of default "settings") in one table and only a low number of specific overrides per user or per uri. If the level is no specified, SER will search for the given AVP in order, through the 3 levels.

(based on Jan's message from the mailing list http://lists.sip-router.org/pipermail/sr-dev/2008-December/000227.html )

A long time ago we started using AVPs to store all kinds of configuration information. We needed some sort of general configuration mechanism because real-world scripts were getting too complex and at that time the AVPs were readily available.

We started by loading attribute names and value from a database table into AVPs. This mechanism was/is same as in k. We would always load a set of attributes this way for a particular user (identified by username and domain from his/her SIP URI). With this mechanism in place, we were able to load a generic set of configuration options for a particular user of the server, I guess you have the same.

To make the AVPs easily accessible from the configuration script, we added support for AVP identifiers in the config script, so that you can access AVP with name foo as $foo.

As we migrated more and more configuration options to AVPs, it became clear that having just one set of AVPs was not enough. Although we could load all the config options for the caller (From URI) from the database into a set of AVPs, we could not do the same for the callee (Request-URI) at the same time. We could not do it because they would conflict with the AVPs of the caller as both users could have AVPs with same names but different values.

To get around this issue we added another list of AVPs. The new AVP list works the same way, it can contain AVPs with same names as AVPs in the original list and they do not conflict. All functions that work with lists of AVPs now take the list to work on as parameter.

To make both AVP lists available in the configuration script, we extended the syntax of AVPs identifiers so the script write can choose the AVP list to work with. SO instead of just $foo you can write either

  $f.foo or $t.foo

$f refers to the original AVP list which is commonly associated with the caller. The address/uid of the caller is taken from From header, hence the 'f' in the identifier. $t refers to the AVP list which contains configuration settings of the callee. The address/uid of the calle can be taken either from the Request-URI or To headers, hence the 't' in the identifier.

The original syntax without any list identifier is still available, in other words you can still write $foo, this is defined as a shorthand for $f.foo. If you do not specify the AVP list to be used then you are referring to the list containing AVPs of the caller (From).

It also turned out that in some cases we would be having too many attributes in the database table storing AVPs. This can happen in bigger setups, having tens or hundreds of thousands users or serving multiple domains. This can slow the database down and makes SER load too much data. Based on my observations it is common that a large number of users have AVPs with same values. If ten thousands of users have attribute named 'foo' with value 'bar' then the attribute will be stored in the database ten thousand times.

As a remedy for this problem, we introduced the concept of AVP levels. The AVPs described so far and stored in user_attrs table are called user-level attributes and they store configuration specific to particular users. Then we added another two AVP lists to store so called domain-level AVPs.

Domain-level AVPs are used to store configuration information that is shared by a group of users. Domain-level AVPs are stored in a separate database table, the name of the table is domain_attrs and its contents is cached in memory by 'domain' SER module. This is an important difference, while user-level AVPs need to be loaded every time a SIP request is processed, domain-level AVPs are only loaded when the contents of domain_attrs table has changed.

The domain-level AVPs are called 'domain' because they are tied to a particular domain handled by the SIP server. That could be 'iptel.org', 'sip-router.org', and so on. This mainly useful for multi-domain setups. There are two domain-level AVP lists because it is common that SER works with two domains at the same time, the domain from From header (caller's domain) and the domain from Request-URI or To (callee's domain).

Again, we extended the syntax of AVP identifiers in the configuration file. So you can write:

  $fu.foo -- this way you are asking for the value of the user-level foo AVP.
  $fd.foo -- This will return the value of the domain-level foo AVP.

And similarly there is $tu and $td for callee's user-level and domain-level AVPs. If you specify 'u' in the AVP identifiers then SER searches only the list of user-level attributes. If you specify 'd' then SER searches only the list of domain-level attributes.

This behavior changes if you do NOT specify the level to be searched. In that case SER searches the user-level list first and if no match is found then the domain-level list will be searched. Thus if you write:

  $f.foo

then you are telling SER to search for the value of 'foo' AVP in the user-level list and continue with the domain-level list if no match is found. In other words, user-level AVPs have higher priority than domain-level AVPs. With this system you can efficiently set a configuration option for all users within a domain by creating a domain-level attribute and yet you can override that option with user-level attributes for particular users within that domain.

Then there are the global AVPs. Global AVPs can be used to store settings applicable to the whole SIP server and all domains on that server. Global AVPs are stored in global_attrs table and the contents of that table is cached in memory by gflags module. There is only one list of global AVPs. Global AVPs can be accessed with:

  $g.foo

(note that there is no 'f' or 't' in the identifier). The list of global AVPs is searched after the list of domain-level AVPs. So if you write:

  $f.foo

Then SER searches user-level AVPs first, then domain-level and then the global AVPs.

And finally there are also so called URI-level AVPs. They work just like user-level AVPs, but a single user can have multiple sets of uri-level AVPs. They are tied to SIP URIs of that user. Uri-level AVPs are denoted by 'r' in the AVP identifier, for example:

  $fr.foo

The list of URI-level AVPs is searched first, before the the list of the user-level AVPs, if the level is not explicitly specified. For example if you write:

 $f.foo

Then SER searches the URI-level AVPs first, then (if not found) the user-level AVPS, then domain-level and finally the global AVPs.

For AVPs with no list/track (f/from , t/to or g/global) and no level/class (r - URI, u - user, d - domain) specified, all the classes for URI ( r ), user (u) and domain (d) from the "from "(caller) list/track will be tried in order, followed by the global AVPs. For example for

 $foo

the following fully qualified AVPs will be tried (stopping at the first that exists): $fr.foo (URI-level AVP, from/caller track), $fu.foo (user-level AVP, from/caller track), $fd.foo (domain-level AVP, from/caller track) and $g.foo (global-level AVP).

For AVPs with a specified list/track ("from" or "to"), all the levels/classes will be tried in order, as above, but for the specified track. As above if nothing is found, the global AVPs will be tried. For example for

 $t.foo

the following fully qualified AVPs will be tried: $tr.foo, $tu.foo, $td.foo, $g.foo.

$f.foo

is equivalent with $foo ($foo is a shorthand for it).

If the track and class are specified, then only that fully qualified AVP will be tried. For example for

 $fd.foo

only the "domain" class from the "from" AVP list will be searched for the "foo" AVP.

Note that the global AVP list/track does not have any levels/classes. For example only $gu.foo is invalid, because it specifies a level/class for a global AVP.