kamailio/modules/domain/README

Domain Module

Juha Heinanen

   <jh@tutpro.com>

Edited by

Juha Heinanen

   <jh@tutpro.com>

   Copyright © 2002-2012 Juha Heinanen
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies
        3. Parameters

              3.1. db_url (string)
              3.2. domain_table (string)
              3.3. domain_attrs_table (string)
              3.4. did_col (string)
              3.5. domain_col (string)
              3.6. name_col (string)
              3.7. type_col (string)
              3.8. value_col (string)
              3.9. register_myself (integer)

        4. Functions

              4.1. is_from_local()
              4.2. is_uri_host_local()
              4.3. is_domain_local(pseudo_variable)
              4.4. lookup_domain(domain[, prefix])

        5. MI Commands

              5.1. domain_reload
              5.2. domain_dump

        6. Exported RPC Commands

              6.1. domain.reload
              6.2. domain.dump

        7. Known Limitations

   2. Developer Guide

        1. Available Functions

              1.1. is_domain_local(domain)

   List of Examples

   1.1. Setting db_url parameter
   1.2. Setting domain_table parameter
   1.3. Setting domain_attrs_table parameter
   1.4. Setting did_col parameter
   1.5. Setting domain_col parameter
   1.6. Setting name_col parameter
   1.7. Setting name_col parameter
   1.8. Setting value_col parameter
   1.9. register_myself example
   1.10. is_from_local usage
   1.11. is_uri_host_local usage
   1.12. is_domain_local usage
   1.13. lookup_domain

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies
   3. Parameters

        3.1. db_url (string)
        3.2. domain_table (string)
        3.3. domain_attrs_table (string)
        3.4. did_col (string)
        3.5. domain_col (string)
        3.6. name_col (string)
        3.7. type_col (string)
        3.8. value_col (string)
        3.9. register_myself (integer)

   4. Functions

        4.1. is_from_local()
        4.2. is_uri_host_local()
        4.3. is_domain_local(pseudo_variable)
        4.4. lookup_domain(domain[, prefix])

   5. MI Commands

        5.1. domain_reload
        5.2. domain_dump

   6. Exported RPC Commands

        6.1. domain.reload
        6.2. domain.dump

   7. Known Limitations

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

2. Dependencies

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

3. Parameters

   3.1. db_url (string)
   3.2. domain_table (string)
   3.3. domain_attrs_table (string)
   3.4. did_col (string)
   3.5. domain_col (string)
   3.6. name_col (string)
   3.7. type_col (string)
   3.8. value_col (string)
   3.9. register_myself (integer)

3.1. db_url (string)

   This is URL of the database to be used.

   Default value is “mysql://kamailioro:kamailioro@localhost/kamailio”

   Example 1.1. Setting db_url parameter
modparam("domain", "db_url", "mysql://ser:pass@db_host/ser")

3.2. domain_table (string)

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

   Default value is “domain”.

   Example 1.2. Setting domain_table parameter
modparam("domain", "domain_table", "new_name")

3.3. domain_attrs_table (string)

   Name of table containing attributes of local domains.

   Default value is “domain_attrs”.

   Example 1.3. Setting domain_attrs_table parameter
modparam("domain", "domain_attrs_table", "local_domain_attributes")

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

   Example 1.4. Setting did_col parameter
modparam("domain", "did_col", "domain_did")

3.5. domain_col (string)

   Name of column containing domain name in domain table.

   Default value is “domain”.

   Example 1.5. Setting domain_col parameter
modparam("domain", "domain_col", "domain_name")

3.6. name_col (string)

   Name of column containing attribute name in domain_attrs table.

   Default value is “name”.

   Example 1.6. Setting name_col parameter
modparam("domain", "name_col", "attr_name")

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

   Example 1.7. Setting name_col parameter
modparam("domain", "type_col", "attr_type")

3.8. value_col (string)

   Name of column containing attribute value in domain_attrs table.

   Default value is “value”.

   Example 1.8. Setting value_col parameter
modparam("domain", "value_col", "attr_value")

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

   Example 1.9. register_myself example
modparam("domain", "register_myself", 1)

4. Functions

   4.1. is_from_local()
   4.2. is_uri_host_local()
   4.3. is_domain_local(pseudo_variable)
   4.4. lookup_domain(domain[, prefix])

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

   Example 1.10. is_from_local usage
...
if (is_from_local()) {
        ...
};
...

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

   Example 1.11. is_uri_host_local usage
...
if (is_uri_host_local()) {
        ...
};
...

4.3. is_domain_local(pseudo_variable)

   This function checks if the domain contained in the pseudo_variable is
   local.

   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.

   Example 1.12. is_domain_local usage
...
if (is_domain_local("$rd")) {
        ...
};
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)")) {
        ...
};
...

4.4. lookup_domain(domain[, prefix])

   This function checks if domain given in domain argument (pseudo
   variable) 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 did containing did of domain is added.

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

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

5. MI Commands

   5.1. domain_reload
   5.2. domain_dump

5.1. domain_reload

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

   Name: domain_reload

   Parameters: none

   MI FIFO Command Format:
                :domain_reload:_reply_fifo_file_
                _empty_line_

5.2. domain_dump

   Causes domain module to dump hash indexes and domain names in its cache
   memory.

   Name: domain_dump

   Parameters: none

   MI FIFO Command Format:
                :domain_dump:_reply_fifo_file_
                _empty_line_

6. Exported RPC Commands

   6.1. domain.reload
   6.2. domain.dump

6.1. domain.reload

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

   Name: domain.reload

   Parameters: none

   Example:
                kamcmd domain.reload

6.2. domain.dump

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

   Name: domain.dump

   Parameters: none

   Example:
                kamcmd domain.dump

7. 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 FIFO or RPC,
   the second reload will delete the original table still in use by the
   process.

Chapter 2. Developer Guide

   Table of Contents

   1. Available Functions

        1.1. is_domain_local(domain)

   The module provides is_domain_local API function for use by other
   Kamailio modules.

1. Available Functions

   1.1. is_domain_local(domain)

1.1.  is_domain_local(domain)

   Checks if domain given in str* parameter is local.

   The function returns 1 if domain is local and -1 if domain is not local
   or if an error occurred.