# &adminguide;

## Overview

Domain module implements checks that based on domain table determine if a domain is local. A local domain is one that the proxy is responsible for. SIP URIs of local users must have hostpart that is equal to one of these domains.

Domain module reads the contents of domain and domain_attrs tables into cache memory when the module is loaded. Any changes in domain or domain_attrs tables must thus be followed by domain.reload rpc command in order to reflect them in module behavior.

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.

## Dependencies

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

- database -- Any database module

## Parameters

### `db_url` (string)

This is URL of the database to be used.

Default value is &defaultrodb;

#### Setting db_url parameter

    modparam("domain", "db_url", "mysql://ser:pass@db_host/ser")

### `domain_table` (string)

Name of table containing names of local domains that the proxy is responsible for.

Default value is domain.

#### Setting domain_table parameter

    modparam("domain", "domain_table", "new_name")

### `domain_attrs_table` (string)

Name of table containing attributes of local domains.

Default value is domain_attrs.

#### Setting domain_attrs_table parameter

    modparam("domain", "domain_attrs_table", "local_domain_attributes")

### `did_col` (string)

Name of column containing domain id (did) of domain in domain and domain_attrs tables. In domain table, a did column value may be NULL, which means that it has same value as domain column.

Default value is did.

#### Setting did_col parameter

    modparam("domain", "did_col", "domain_did")

### `domain_col` (string)

Name of column containing domain name in domain table.

Default value is domain.

#### Setting domain_col parameter

    modparam("domain", "domain_col", "domain_name")

### `name_col` (string)

Name of column containing attribute name in domain_attrs table.

Default value is name.

#### Setting name_col parameter

    modparam("domain", "name_col", "attr_name")

### `type_col` (string)

Name of column containing attribute type in domain_attrs table. Type value 0 is integer and type value 2 is string.

Default value is type.

#### Setting name_col parameter

    modparam("domain", "type_col", "attr_type")

### `value_col` (string)

Name of column containing attribute value in domain_attrs table.

Default value is value.

#### Setting value_col parameter

    modparam("domain", "value_col", "attr_value")

### `register_myself` (integer)

Register the list of domains to match 'myself' check: 0 means no myself registration, 1 means enable myself registration.

Default value is 0 (disable).

#### register_myself example

    modparam("domain", "register_myself", 1)

## Functions

### `is_from_local()`

Checks based on domain table if host part of From header uri is one of the local domains that the proxy is responsible for

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

#### is_from_local usage

    ...
    if (is_from_local()) {
    	...
    };
    ...

### `is_uri_host_local()`

If called from route or failure route block, checks based on domain table if host part of Request-URI is one of the local domains that the proxy is responsible for. If called from branch route, the test is made on host part of URI of first branch, which thus must have been appended to the transaction before is_uri_host_local() is called.

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

#### is_uri_host_local usage

    ...
    if (is_uri_host_local()) {
    	...
    };
    ...

### `is_domain_local(domain)`

This function checks if the domain contained in the parameter is local. The parameter can be a static string or contain pseudo-variables.

This function is a generalized form of the is_from_local() and is_uri_host_local() functions, being able to completely replace them and also extends them by allowing the domain to be taken from any of the above mentioned sources. The following equivalences exist:

- is_domain_local("$rd") is same as is_uri_host_local()

- is_domain_local("$fd") is same as is_from_local()

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

#### is_domain_local usage

    ...
    if (is_domain_local("$rd")) {
    	...
    }
    if (is_domain_local("my.domain.com")) {
    	...
    }
    if (is_domain_local("$fd")) {
    	...
    }
    if (is_domain_local("$avp(some_avp_alias)")) {
    	...
    }
    if (is_domain_local("$avp(i:850)")) {
    	...
    }
    if (is_domain_local("$avp(s:some_avp)")) {
    	...
    }
    ...

### `lookup_domain(domain [, prefix])`

This function checks if domain given in domain argument is local and, if so, adds attributes associated with domain's id (did) to AVPs. If prefix argument (string) is given, names of attributes are prefixes by it. In addition to attributes given in domain_attrs table, AVP named did containing the did of domain is added.

Both parameters can contain pseudo-variables.

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

#### lookup_domain

    ...
    if (lookup_domain("$fd", "from_")) {
        xlog("L_INFO", "did of domain $fd is $avp(from_did)\n");
    }
    ...

## RPC Commands

### `domain.reload`

Causes domain module to re-read the contents of domain table into cache memory.

Name: domain.reload

Parameters: none

Example:

    		&sercmd; domain.reload

### `domain.dump`

Causes domain module to dump domain names in its cache memory.

Name: domain.dump

Parameters: none

Example:

    		&sercmd; domain.dump

## Known Limitations

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