Domain Module

Juha Heinanen

Edited by

Juha Heinanen

   Copyright  2002, 2003 Juha Heinanen
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies
        1.3. Exported Parameters

              1.3.1. db_url (string)
              1.3.2. db_mode (integer)
              1.3.3. domain_table (string)
              1.3.4. domain_col (string)

        1.4. Exported Functions

              1.4.1. is_from_local()
              1.4.2. is_uri_host_local()
              1.4.3. is_domain_local(variable)

        1.5. FIFO Commands

              1.5.1. domain_reload
              1.5.2. domain_dump

        1.6. Known Limitations

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Setting db_url parameter
   1-2. nonce_expire example
   1-3. Setting domain_table parameter
   1-4. Setting domain_col parameter
   1-5. is_from_local usage
   1-6. is_uri_host_local usage
   1-7. is_domain_local usage
     _________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   Domain module implements checks that based on domain table
   determine if a host part of an URI is "local" or not. A
   "local" domain is one that the proxy is responsible for.

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

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

1.3. Exported Parameters

1.3.1. db_url (string)

   This is URL of the database to be used.

   Default value is
   "mysql://openserro:openserro@localhost/openser"

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

1.3.2. db_mode (integer)

   Database mode: 0 means non-caching, 1 means caching.

   Default value is 0 (non-caching).

   Example 1-2. nonce_expire example
modparam("domain", "db_mode", 1)   # Use caching
     _________________________________________________________

1.3.3. domain_table (string)

   Name of table containing names of local domains that the proxy
   is responsible for. Local users must have in their sip uri a
   host part that is equal to one of these domains.

   Default value is "domain".

   Example 1-3. Setting domain_table parameter
modparam("domain", "domain_table", "new_name")
     _________________________________________________________

1.3.4. domain_col (string)

   Name of column containing domains in domain table.

   Default value is "domain".

   Example 1-4. Setting domain_col parameter
modparam("domain", "domain_col", "domain_name")
     _________________________________________________________

1.4. Exported Functions

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

   Example 1-5. is_from_local usage
...
if (is_from_local()) {
        ...
};
...
     _________________________________________________________

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

   Example 1-6. is_uri_host_local usage
...
if (is_uri_host_local()) {
        ...
};
...
     _________________________________________________________

1.4.3. is_domain_local(variable)

   This function checks if the domain contained in the variable
   is local. The variable can be an avp_name, an avp_alias or a
   special keyword pointing to certain SIP headers from where the
   domain should be taken.

   The input variable can be one of the following:

     * $ruri - take the domain part of the request URI
     * $from - take the domain part of the From header
     * avp - the domain is given by the value of the avp which is
       either an avp_name or an avp_alias

   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 an avp. The following equivalences exist:

     * is_domain_local("$ruri") is same as is_uri_host_local()
     * is_domain_local("$from") is same as is_from_local()

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

   Example 1-7. is_domain_local usage
...
if (is_domain_local("$ruri")) {
        ...
};
if (is_domain_local("$from")) {
        ...
};
if (is_domain_local("$some_avp_alias")) {
        ...
};
if (is_domain_local("i:850")) {
        ...
};
if (is_domain_local("s:some_avp")) {
        ...
};
...
     _________________________________________________________

1.5. FIFO Commands

1.5.1. domain_reload

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

1.5.2. domain_dump

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

1.6. Known Limitations

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

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about OpenSER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on
   one of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.