README

domain Module
     __________________________________________________________

   Table of Contents

   1. Admin 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.3.5. attrs_col (string)

        1.4. Exported Functions

              1.4.1. is_from_local([attrs_var])
              1.4.2. is_uri_host_local([attrs_var])
              1.4.3. is_domain_local(domain, [attrs_var])

        1.5. Exported MI Functions

              1.5.1. domain_reload
              1.5.2. domain_dump

        1.6. Known Limitations

   2. Developer Guide

        2.1. Available Functions

              2.1.1. is_domain_local(domain)

   3. Contributors

        3.1. By Commit Statistics
        3.2. By Commit Activity

   4. Documentation

        4.1. Contributors

   List of Tables

   3.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   3.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Setting db_url parameter
   1.2. db_mode example
   1.3. Setting domain_table parameter
   1.4. Setting domain_col parameter
   1.5. Setting attrs_col parameter
   1.6. is_from_local usage
   1.7. is_uri_host_local usage
   1.8. is_domain_local usage

Chapter 1. Admin 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://opensipsro:opensipsro@localhost/opensips”

   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. db_mode 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.3.5. attrs_col (string)

   Name of column containing attributes in domain table.

   Default value is “attrs”.

   Example 1.5. Setting attrs_col parameter
modparam("domain", "attrs_col", "attributes")

1.4. Exported Functions

1.4.1. is_from_local([attrs_var])

   Checks based on domain table if host part of From header uri is
   one of the local domains that the proxy is responsible for. The
   argument is optional and if present it should contain a
   writable variable that will be populated with the attributes
   from the database.

   This function can be used from REQUEST_ROUTE.

   Example 1.6. is_from_local usage
...
if (is_from_local()) {
        ...
};
...
if (is_from_local($var(attrs))) {
        xlog("Domain attributes are $var(attrs)\n");
        ...
};
...

1.4.2. is_uri_host_local([attrs_var])

   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. The argument is optional
   and if present it should contain a writable variable that will
   be populated with the attributes from the database.

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

   Example 1.7. is_uri_host_local usage
...
if (is_uri_host_local()) {
        ...
};
...
if (is_uri_host_local($var(attrs))) {
        xlog("Domain attributes are $var(attrs)\n");
        ...
};

1.4.3. is_domain_local(domain, [attrs_var])

   This function checks if the domain contained in the first
   parameter 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()

   Parameters:
     * domain (string)
     * attrs_var (var, optional) - a writable variable that will
       be populated with the attributes from the database.

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

   Example 1.8. 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(850))) {
        ...
};
if (is_domain_local($avp(some_avp))) {
        ...
};
if (is_domain_local($avp(some_avp), $avp(attrs))) {
        xlog("Domain attributes are $avp(attrs)\n");
        ...
};
...

1.5. Exported MI Functions

1.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:
                opensips-cli -x mi domain_reload

1.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:
                opensips-cli -x mi domain_dump

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 Guide

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

2.1. Available Functions

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

Chapter 3. Contributors

3.1. By Commit Statistics

   Table 3.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Bogdan-Andrei Iancu (@bogdan-iancu) 55 41 425 559
   2. Jan Janak (@janakj) 32 21 999 113
   3. Juha Heinanen (@juha-h) 30 20 700 233
   4. Razvan Crainea (@razvancrainea) 20 13 287 221
   5. Daniel-Constantin Mierla (@miconda) 19 16 92 79
   6. Liviu Chircu (@liviuchircu) 11 8 45 109
   7. Vlad Patrascu (@rvlad-patrascu) 9 5 96 123
   8. Dan Pascu (@danpascu) 8 4 232 101
   9. Andrei Pelinescu-Onciul 8 4 186 121
   10. Henning Westerholt (@henningw) 7 5 44 48

   All remaining contributors: Edson Gellert Schubert,
   Elena-Ramona Modroiu, Jiri Kuthan (@jiriatipteldotorg), @coxx,
   Konstantin Bokarius, Klaus Darilion, Anca Vamanu, Norman
   Brandinger (@NormB), Peter Lemenkov (@lemenkov), UnixDev,
   Andreas Granig, John Burke.

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

3.2. By Commit Activity

   Table 3.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  John Burke                          Jan 2022 - Jan 2022
   2.  Bogdan-Andrei Iancu (@bogdan-iancu) Oct 2005 - Mar 2020
   3.  Razvan Crainea (@razvancrainea)     Jun 2011 - Sep 2019
   4.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   5.  Liviu Chircu (@liviuchircu)         Mar 2014 - Nov 2018
   6.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   7.  @coxx                               Mar 2010 - Mar 2010
   8.  Anca Vamanu                         Sep 2009 - Sep 2009
   9.  UnixDev                             Feb 2009 - Feb 2009
   10. Juha Heinanen (@juha-h)             Jan 2003 - May 2008

   All remaining contributors: Henning Westerholt (@henningw),
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert, Elena-Ramona Modroiu, Dan Pascu (@danpascu),
   Norman Brandinger (@NormB), Andreas Granig, Klaus Darilion, Jan
   Janak (@janakj), Andrei Pelinescu-Onciul, Jiri Kuthan
   (@jiriatipteldotorg).

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Vlad Patrascu (@rvlad-patrascu), Razvan Crainea
   (@razvancrainea), Peter Lemenkov (@lemenkov), Liviu Chircu
   (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu),
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert, Juha Heinanen (@juha-h), Elena-Ramona
   Modroiu, Dan Pascu (@danpascu), Klaus Darilion, Jan Janak
   (@janakj).

   Documentation Copyrights:

   Copyright © 2002-2008 Juha Heinanen