
pdt Module

Elena-Ramona Modroiu

   voice-system.ro

Edited by

Elena-Ramona Modroiu

   Copyright  2003 FhG FOKUS

   Copyright  2004 voice-system.ro
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSER Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. db_url (string)
              1.3.2. db_table (string)
              1.3.3. sdomain_column (string)
              1.3.4. prefix_column (string)
              1.3.5. domain_column (string)
              1.3.6. prefix (string)
              1.3.7. hsize_2pow (integer)
              1.3.8. sync_time (integer)
              1.3.9. clean_time (integer)

        1.4. Exported Functions

              1.4.1. prefix2domain(rewrite_mode,
                      multidomain_mode)

              1.4.2. prefix2domain(rewrite_mode)
              1.4.3. prefix2domain()

        1.5. Exported MI Functions

              1.5.1. pdt_add
              1.5.2. pdt_delete
              1.5.3. pdt_list

        1.6. Installation & Running

   2. Developer's Guide
   3. Frequently Asked Questions

   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 hsize_2pow parameter
   1-9. Set sync_time parameter
   1-10. Set clean_time parameter
   1-11. prefix2domain usage
     _________________________________________________________

Chapter 1. User's Guide

1.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 and the MySQL script to create the
       database needed by PDT are located in './doc/'.
     * Sample shell scripts to manage prefix-domain pairs are
       also located in './doc/' (pdt_fifo_add.sh,
       pdt_fifo_delete.sh, pdt_fifo_list.sh).
     _________________________________________________________

1.2. Dependencies

1.2.1. OpenSER Modules

   The following modules must be loaded before this module:

     * A OpenSER database module (e.g., mysql, dbtext).
     _________________________________________________________

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSER with this module loaded:

     * None.
     _________________________________________________________

1.3. Exported Parameters

1.3.1. db_url (string)

   SQL URL of database--username, password, host, port and
   database (ex: mysql://username:password@hostname.com/database)

   Default value is "mysql://root@127.0.0.1/pdt". 

   Example 1-2. Set db_url parameter
...
modparam("pdt", "db_url", "mysql://user:xxx@127.0.0.1/ser")
...
     _________________________________________________________

1.3.2. db_table (string)

   Table name.

   Default value is "pdt". 

   Example 1-3. Set db_table parameter
...
modparam("pdt", "db_table", "pdt")
...
     _________________________________________________________

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

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

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

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

1.3.7. hsize_2pow (integer)

   Number of the hash entries = 2^hash_size.

   Default value is 4. 

   Example 1-8. Set hsize_2pow parameter
...
modparam("pdt", "hsize_2pow", 4)
...
     _________________________________________________________

1.3.8. sync_time (integer)

   Time in seconds to synchronize the cache of each process with
   the changes made through FIFO. Any prefix-domain change made
   through FIFO is guaranteed to have efect after this period of
   time past.

   Default value is 600. 

   Example 1-9. Set sync_time parameter
...
modparam("pdt", "sync_time", 300)
...
     _________________________________________________________

1.3.9. clean_time (integer)

   Time in seconds to clean the changes inserted via FIFO. The
   changes will be removed from FIFO diff list only when all
   OpenSER processes applied these changes.

   Default value is 900. 

   Example 1-10. Set clean_time parameter
...
modparam("pdt", "clean_time", 600)
...
     _________________________________________________________

1.4. Exported Functions

1.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. If the parameter is missing or it
   has the value "0", then the prefix is removed along with the
   leading prefix. If the value is "1", only the leading prefix
   is removed. If the values is "2" the user part of the URI is
   not changed.

   The "multidomain_mode" parameter specifies the kind of
   multidomain support to use. There are three possible values:

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

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

   Example 1-11. prefix2domain usage
...
prefix2domain("2", "2");
...
     _________________________________________________________

1.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");
...
     _________________________________________________________

1.4.3. prefix2domain()

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

1.5. Exported MI Functions

   The modules uses only the cache to look up domains. If you
   want to add or delete a new prefix-domain pair you have to use
   MI FIFO commands. All changes made via these commands are
   applied to database, while the database is loaded only at
   OpenSER start up time.
     _________________________________________________________

1.5.1. pdt_add

   Adds a new sdomain-prefix-domain entry.

   Name: pdt_add

   Parameters:

     * _sdomain_ : source domain
     * _prefix_: prefix
     * _domain_: domain corresponding to a pair of source domain
       and prefix

   MI FIFO Command Format:
                :pdt_add:_reply_fifo_file_
                _sdomain_
                _prefix_
                _domain_
                _empty_line_
     _________________________________________________________

1.5.2. pdt_delete

   Removes a sdomain-prefix-domain entry.

   Name: pdt_delete

   Parameters:

     * _sdomain_ : a source domain
     * _domain_: a domain associated via a prefix with the source
       domain

   MI FIFO Command Format:
                :pdt_delete:_reply_fifo_file_
                _sdomain_
                _domain_
                _empty_line_
     _________________________________________________________

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

1.6. Installation & Running

   Make sure you have created the table needed by this module.

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

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.
