Juha Heinanen jh@tutpro.com 2002-2010 Juha Heinanen

Domain modules, as the name suggests, implements support for multiple independent virtual domains hosted on one SIP server. This is often useful if you have multiple domain names and you want to make them all work and appear as one. Alternatively you might find the module useful if you want to run a shared SIP service for multiple independent customers. The module stores all supported domains and associated configuration in a database table. Most of the information can be cached in memory for performance reasons.

The domain module adds support for so-called virtual domains. A virtual domain is just a collection of domain names and associated configuration information identified by a unique identifier. We refer to the domain identifier as DID elsewhere in the documentation. DID stands for "Domain IDentifier". In traditional POST world the term DID has a different meaning though. Please be aware that this is just pure coincidence. All domain names that belong to one virtual domain are interchangeable. From SIP server's perspective there is no difference between them. They can be used in SIP URIs interchangeably and the behavior of the SIP server will not be affected. This is called "domain name normalization" and it is one of the steps performed early during SIP message processing. The DID identifier can be anything. To the SIP server DIDs are just opaque strings and what format you choose depends on your requirements and the type of the setup. You can use numbers in smaller setups if the size of the data is a concern. You can set the DID to the canonical domain name of the domain. You can use RFC 4122 style UUIDs if your setup is large and distributed. You can use anything as long as it can be represented as string. The only requirement is that the identifier of each virtual domain must be unique. The following example illustrates how one virtual domain can be represented. The iptel.org domain runs a public SIP service. The users of the service can use SIP URIs of form sip:username@iptel.org. The SIP service is distributed, there is a number of SIP servers. The SIP servers are also available through a number of other domain names, such as sip.iptel.org, proxy.iptel.org and so on. We created one virtual domain in the domain module and added all such domain names to the virtual domain: iptel | +---iptel.org +---sip.iptel.org +---proxy.iptel.org +---213.192.59.75 In the example above, we chose "iptel" as the unique identifier for the virtual domain. This identifier is permanent. It never changes. Over time we may change domain names assigned to this virtual domain, but this identifier never changes. The main reason why virtual domain identifiers must never change is that because they are referenced from other tables, for example the accounting table. The data in the accounting table is long-lived, usually archived, and this ensures that the data will still reference correct virtual domain, no matter what domain names are assigned to it. The virtual domain described above will be stored in the domain table in the database: +-------+-----------------+-------+ | did | domain | flags | +-------+-----------------+-------+ | iptel | iptel.org | 33 | | iptel | sip.iptel.org | 33 | | iptel | proxy.iptel.org | 33 | | iptel | 213.192.59.75 | 33 | +-------+-----------------+-------+ Because all domain names that belong to one particular virtual domain are equal, it does not matter which domain name is used in the host part of the SIP URI. Thus an imaginary user joe with SIP URI sip:joe@iptel.org will also be reachable as sip:joe@sip.iptel.org, sip:joe@proxy.iptel.org, and sip:joe@213.192.59.75. If we add a new domain name to this virtual domain then joe will also be able to use the new domain name in his SIP URI, without the need to change anything.

In addition to a number of domain names, each virtual domain can also have extra configuration information associated with it. The possibility to configure the SIP server sightly differently in each virtual domain is, in fact, the main reason why we introduced the concept of virtual domains. We wanted to have one SIP server which will provide SIP service to multiple different customers and each of the customers may have slightly different configuration requirements. That's how domain-level configuration attributes were born. Because the administrator of the SIP server seldom knows configuration requirements in advance, we decided to implement a generic solution and store all configuration options in named attributes. Named attributes are just like variables, they have a name and they have a value. Attributes are accessible from the configuration script of the SIP server. Domain-level attributes are attributes that are associated with a particular virtual domain. They can be used to store additional configuration for the entire virtual domain, that is all users that belong (or have SIP URI) in that particular virtual domain. Domain-level attributes can be overridden be user-level attributes with the same name configured for a particular user. In other words a domain level attribute will only be effective if no user-level attribute with the same name exists. Domain-level attributes are stored in a separate table. The name of the table is domain_attrs and it is defined as follows: +-------+------------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------+------------------+------+-----+---------+-------+ | did | varchar(64) | YES | MUL | NULL | | | name | varchar(32) | NO | | NULL | | | type | int(11) | NO | | 0 | | | value | varchar(255) | YES | | NULL | | | flags | int(10) unsigned | NO | | 0 | | +-------+------------------+------+-----+---------+-------+ Each attribute has name, type and value. A single attribute can have multiple values and in that case it will occupy more rows in the table. Each attribute is associated with a particular virtual domain using the DID identifier. Domain-level attributes can contain just about anything. It is a generic configuration mechanism and it is up to you to define a list of attribute that are meaningful in your setup and use those attributes in the routing part of the configuration file. Attributes for a particular virtual-domain are made available to script function by the lookup_domain function. This is the function that is used to map domain names to DIDs. One of the side-effects of the function is that it makes domain-level attributes available to script function if a matching virtual domain is found. When caching is enabled, all attributes from domain_attrs table are cached in memory, just like virtual domain themselves. If you disable caching then the domain module will attempt to load attributes from the database each time you call lookup_domain. Attributes cached in memory can be realoaded with the domain.reload management function.

Domain module operates in caching or non-caching mode depending on value of module parameter db_mode. In caching mode domain module reads the contents of domain table into cache memory when the module is loaded. After that domain table is re-read only when module is given domain_reload fifo command. Any changes in domain table must thus be followed by domain_reload command in order to reflect them in module behavior. In non-caching mode domain module always queries domain table in the database. Caching is implemented using a hash table. The size of the hash table is given by HASH_SIZE constant defined in domain_mod.h. Its "factory default" value is 128. Caching mode is highly recommended if you want to use domain-level attributes.

The module depends on the following modules (in the other words the listed modules must be loaded before this module): database - Any database module

There is an unlikely race condition on domain list update. If a process uses a table, which is reloaded at the same time twice through FIFO, the second reload will delete the original table still in use by the process.