pdt Module

Elena-Ramona Modroiu

   asipto.com
   <ramona@asipto.com>

Edited by

Elena-Ramona Modroiu

   <ramona@asipto.com>

   Copyright  2003 FhG FOKUS

   Copyright  2004 Voice Sistem SRL

   Copyright  2008 Elena-Ramona Modroiu
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. db_url (string)
              3.2. db_table (string)
              3.3. sdomain_column (string)
              3.4. prefix_column (string)
              3.5. domain_column (string)
              3.6. prefix (string)
              3.7. fetch_rows (integer)
              3.8. char_list (string)
              3.9. check_domain (integer)

        4. Functions

              4.1. prefix2domain(rewrite_mode, multidomain_mode)
              4.2. prefix2domain(rewrite_mode)
              4.3. prefix2domain()
              4.4. pd_translate(sdomain, rewrite_mode)

        5. MI Commands

              5.1. pdt_list
              5.2. pdt_reload

        6. Installation and Running

   List of Examples

   1.1. prefix-domain translation
   1.2. Set db_url parameter
   1.3. Set db_table parameter
   1.4. Set sdomain_column parameter
   1.5. Set prefix_column parameter
   1.6. Set domain_column parameter
   1.7. Set prefix parameter
   1.8. Set fetch_rows parameter
   1.9. Set char_list parameter
   1.10. Set check_domain parameter
   1.11. prefix2domain usage
   1.12. pd_translate usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. db_url (string)
        3.2. db_table (string)
        3.3. sdomain_column (string)
        3.4. prefix_column (string)
        3.5. domain_column (string)
        3.6. prefix (string)
        3.7. fetch_rows (integer)
        3.8. char_list (string)
        3.9. check_domain (integer)

   4. Functions

        4.1. prefix2domain(rewrite_mode, multidomain_mode)
        4.2. prefix2domain(rewrite_mode)
        4.3. prefix2domain()
        4.4. pd_translate(sdomain, rewrite_mode)

   5. MI Commands

        5.1. pdt_list
        5.2. pdt_reload

   6. Installation and Running

1. Overview

   This module translates a numerical prefix into a domain and updates
   accordingly the request URI.

   The module looks up at the R-URI part of a message and if the user part
   begins with an established prefix it will update the URI. Updating the
   uri consists of: remove the prefix from the user part of the uri and
   keep the rest as the user part of the new uri. The host and port are
   changed with the domain matched for the leading prefix and the domain
   in From URI.

   <prefix><userid><:password>@<mydomain.com> ...

   and the result will be:

   <userid><:password>@<domain[:port]>...

   Example 1.1. prefix-domain translation
prefix=123, domain(FROM)=siphub.org

entry in database:
 sdomain=siphub.org
    domain[123]=alpha.org
    domain[124]=beta.org
    domain[125]=gamma.org

The RURI will be updated in the following way"
sip:12391001@mydomain.com  => sip:91001@alpha.org

   The prefix could be prefixed by other digits. These digits will not be
   used to look up the domain (the classic example, 00 used for
   international calls, then follows the country prefix). For more
   information on this, see 'prefix' parameter.
     * A sample config file is located in './doc/'.
     * MySQL script to create the database needed by PDT is located in
       '../../scripts/mysql/pdt-create.sql'
       The database is loaded by Kamailio only at start up time and only
       cache is used to lookup domains. Check the MI Functions for
       adding/deleting prefix-domain pairs or reloading from database at
       runtime.
     * Sample shell scripts to manage prefix-domain pairs are also located
       in './doc/' (pdt_fifo_list.sh).

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * A Kamailio database module (e.g., mysql, dbtext).

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None.

3. Parameters

   3.1. db_url (string)
   3.2. db_table (string)
   3.3. sdomain_column (string)
   3.4. prefix_column (string)
   3.5. domain_column (string)
   3.6. prefix (string)
   3.7. fetch_rows (integer)
   3.8. char_list (string)
   3.9. check_domain (integer)

3.1. db_url (string)

   URL of the database table to be used.

   Default value is "mysql://openser:openserrw@localhost/openser".

   Example 1.2. Set db_url parameter
...
modparam("pdt", "db_url", "dbdriver://username:password@dbhost/dbname")
...

3.2. db_table (string)

   Table name.

   Default value is "pdt".

   Example 1.3. Set db_table parameter
...
modparam("pdt", "db_table", "pdt")
...

3.3. sdomain_column (string)

   Name of 'sdomain' column.

   Default value is "sdomain".

   Example 1.4. Set sdomain_column parameter
...
modparam("pdt", "domain_column", "source_domain")
...

3.4. prefix_column (string)

   Name of 'prefix' column.

   Default value is "prefix".

   Example 1.5. Set prefix_column parameter
...
modparam("pdt", "prefix_column", "prefix")
...

3.5. domain_column (string)

   Name of 'domain' column.

   Default value is "domain".

   Example 1.6. Set domain_column parameter
...
modparam("pdt", "domain_column", "hostname")
...

3.6. prefix (string)

   Default leading prefix who denotes what URI needs to be translated - if
   it is NULL the module will not check the R-URI against it and the PDT
   prefix is considered starting from the first digit. Otherwise, the
   module will check first if the R-URI starts with it and will skip it to
   look up the domain.

   Default value is NULL.

   Example 1.7. Set prefix parameter
...
modparam("pdt", "prefix", "00")
...

3.7. fetch_rows (integer)

   Number of rows to be loaded in one step from database.

   Default value is 1000.

   Example 1.8. Set fetch_rows parameter
...
modparam("pdt", "fetch_rows", 4000)
...

3.8. char_list (string)

   The list with characters allowed in prefix.

   Default value is "0123456789".

   Example 1.9. Set char_list parameter
...
modparam("pdt", "char_list", "0123456789*+")
...

3.9. check_domain (integer)

   Module will check if destination domain is duplicated for same source
   domain (1 - check; 0 - don't check).

   Default value is 1.

   Example 1.10. Set check_domain parameter
...
modparam("pdt", "check_domain", 0)
...

4. Functions

   4.1. prefix2domain(rewrite_mode, multidomain_mode)
   4.2. prefix2domain(rewrite_mode)
   4.3. prefix2domain()
   4.4. pd_translate(sdomain, rewrite_mode)

4.1. prefix2domain(rewrite_mode, multidomain_mode)

   Build a new URI if it is necessary. Returns 1 when the translation was
   made or there was nothing to translate (user part of the URI is empty,
   it does not match the prefix parameter or there is no domain associated
   with a possible prefix from user part). Returns -1 in error cases.

   The translation is done based on lookup up for a entry in the database
   where the sdomain equals the domain in FROM uri, and the prefix matches
   the beginning of the user part of the RURI. If such an entry is found,
   then the domain in RURI is updated with the domain of this entry
   (sdomain, prefix, domain).

   There is also the possibility to have the translation of URI regardless
   of source domain. This can be achieved inserting in the database
   entries where sdomain has the value "*".

   The "rewrite_mode" parameter specifies whether to strip or not the
   prefix from user part. The possible values are:
     * 0: the prefix is removed along with the leading prefix.
     * 1: only the leading prefix is removed.
     * 2: the user part of the URI is not changed.
     * $PV : any PV holding one of the above values.

   The "multidomain_mode" parameter specifies the kind of multidomain
   support to use. The possible values are:
     * 0 : Translation of URI regardless of source domain.
     * 1 : Translation of URI using as source domain the domain in
       From-URI.
     * 2 : Translation of URI using as source domain the domain in
       From-URI. In case there is no entry for the required sdomain, it
       tries the translation using "*" as sdomain.
     * $PV : any PV holding one of the above values.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

   Example 1.11. prefix2domain usage
...
prefix2domain("2", "2");
...
$var(a) = 1;
prefix2domain("$var(a)", "2");
...

4.2. prefix2domain(rewrite_mode)

   The same as prefix2domain(rewrite_mode, "0"), that is without
   multidomain support, translation of URI being done regardless of the
   source domain.
...
prefix2domain("2");
...

4.3. prefix2domain()

   The same as prefix2domain("0", "0").
...
prefix2domain();
...

4.4. pd_translate(sdomain, rewrite_mode)

   Translate R-URI based on source domain and longest prefix matching.
   Returns 1 when the translation was made or there was nothing to
   translate. Returns -1 in error cases.

   The translation is done based on lookup up for an entry in the database
   where the sdomain parameter equals the sdomain in database table.

   The "sdomain" parameter specifies the source domain to be used to match
   the longest prefix. Can be a static string or dynamic parameter with
   variables inside.

   The "rewrite_mode" parameter specifies whether to strip or not the
   prefix from user part. The possible values are:
     * 0: the prefix is removed along with the leading prefix.
     * 1: only the leading prefix is removed.
     * 2: the user part of the URI is not changed.
     * $PV : any PV holding one of the above values.

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

   Example 1.12. pd_translate usage
...
pd_translate("$fd", "2");
...
pd_translate("*", "$var(a)");
...

5. MI Commands

   5.1. pdt_list
   5.2. pdt_reload

   The database is loaded by Kamailio at start up time. The module uses
   only the cache to look up domains. If you want to add or delete a new
   prefix-domain pair at runtime you have to use MI FIFO commands. All
   changes made via these commands are applied to database and the cache
   is updated correspondingly.

5.1. pdt_list

   Produces a listing of the entries prefixes/domains/sdomains.

   Name: pdt_list

   Parameters:
     * _sdomain_ : a source domain value.
     * _prefix_ : a prefix value
     * _domain_: a domain value

   "." (dot) means NULL value

   The comparison operation is 'START WITH' -- if domain is 'a' then all
   domains starting with 'a' are listed.

   MI FIFO Command Format:
                :pdt_list:_reply_fifo_file_
                _sdomain_
                _prefix_
                _domain_
                _empty_line_

   Examples:
     * "pdt_list siph 2 ." : Lists the entries where sdomain is starting
       with 'siph', prefix is starting with '2' and domain is anything
     * "pdt_list siph 2" : Lists the entries where sdomain is starting
       with 'siph', prefix is starting with '2' and domain is anything
     * "pdt_list . 2 open" : Lists the entries where sdomain is anything,
       prefix starts with '2' and domain starts with 'open'.

5.2. pdt_reload

   Reload all sdomain-prefix-domain records from database.

   Name: pdt_reload

   Parameters:
     * none

   MI FIFO Command Format:
                :pdt_reload:_reply_fifo_file_
                _empty_line_

6. Installation and Running

   Example shell scripts for MI FIFO commands are placed in './doc/'
   (pdt_fifo_add.sh, pdt_fifo_delete.sh, pdt_fifo_list.sh).