obsolete/pdt/README
d9bb387b
 1. PDT module
5a2940fd
 
03d2aa4e
 Elena-Ramona Modroiu
5a2940fd
 
d9bb387b
    Asipto
03d2aa4e
 
d9bb387b
    Copyright © 2003 FhG FOKUS
      __________________________________________________________________
03d2aa4e
 
d9bb387b
    1.1. Overview
    1.2. Dependencies
03d2aa4e
 
d9bb387b
         1.2.1. SER Modules
03d2aa4e
 
d9bb387b
    1.3. Parameters
03d2aa4e
 
d9bb387b
         1.3.1. db_url (string)
         1.3.2. db_table (string)
         1.3.3. prefix_column (string)
         1.3.4. domain_column (string)
         1.3.5. prefix (string)
         1.3.6. hsize_2pow (integer)
         1.3.7. sync_time (integer)
         1.3.8. clean_time (integer)
03d2aa4e
 
d9bb387b
    1.4. Functions
03d2aa4e
 
d9bb387b
         1.4.1. prefix2domain(mode)
5ac87c47
 
d9bb387b
    1.5. FIFO Interface
03d2aa4e
 
 1.1. Overview
 
d9bb387b
    This module translates a numerical prefix into a domain and updates
    accordingly the request URI.
03d2aa4e
 
d9bb387b
    The module looks up at the Request-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.
03d2aa4e
 
5ac87c47
    <prefix><userid><:password>@<mydomain.com> ...
03d2aa4e
 
    and the result will be:
 
    <userid><:password>@<domain[:port]>...
 
d9bb387b
    Example 1. prefix-domain translation
5ac87c47
 prefix=123
 domain[123]=alpha.org
03d2aa4e
 
5ac87c47
 sip:12391001@mydomain.com  => sip:91001@alpha.org
03d2aa4e
 
d9bb387b
    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).
03d2aa4e
 
 1.2. Dependencies
 
 1.2.1. SER Modules
 
    The following modules must be loaded before this module:
5ac87c47
      * A SER database module (e.g., mysql, dbtext).
03d2aa4e
 
d9bb387b
 1.3. Parameters
03d2aa4e
 
 1.3.1. db_url (string)
 
d9bb387b
    SQL URL of database--username, password, host, port and database (ex:
    mysql://username:password@hostname.com/database)
03d2aa4e
 
d9bb387b
    Default value is 'mysql://root@127.0.0.1/pdt'.
03d2aa4e
 
d9bb387b
    Example 2. Set db_url parameter
03d2aa4e
 ...
5ac87c47
 modparam("pdt", "db_url", "mysql://user:xxx@127.0.0.1/ser")
03d2aa4e
 ...
 
 1.3.2. db_table (string)
 
    Table name.
 
d9bb387b
    Default value is "prefix_domain".
03d2aa4e
 
d9bb387b
    Example 3. Set db_table parameter
03d2aa4e
 ...
5ac87c47
 modparam("pdt", "db_table", "pdt")
03d2aa4e
 ...
 
5ac87c47
 1.3.3. prefix_column (string)
03d2aa4e
 
5ac87c47
    Name of 'prefix' column.
03d2aa4e
 
d9bb387b
    Default value is "prefix".
03d2aa4e
 
d9bb387b
    Example 4. Set prefix_column parameter
03d2aa4e
 ...
5ac87c47
 modparam("pdt", "prefix_column", "code")
03d2aa4e
 ...
 
5ac87c47
 1.3.4. domain_column (string)
03d2aa4e
 
5ac87c47
    Name of 'domain' column.
03d2aa4e
 
d9bb387b
    Default value is "domain".
03d2aa4e
 
d9bb387b
    Example 5. Set domain_column parameter
03d2aa4e
 ...
5ac87c47
 modparam("pdt", "domain_column", "hostname")
03d2aa4e
 ...
 
 1.3.5. prefix (string)
 
d9bb387b
    Default leading prefix who denotes what URI needs to be translated - if
    it is NULL the module will not check the Request-URI; against it and
    the PDT prefix is considered starting from the first digit. Otherwise,
    the module will check first if the Request-URI starts with it and will
    skip it to look up the domain.
03d2aa4e
 
d9bb387b
    Default value is NULL.
03d2aa4e
 
d9bb387b
    Example 6. Set prefix parameter
03d2aa4e
 ...
5ac87c47
 modparam("pdt", "prefix", "00")
03d2aa4e
 ...
 
 1.3.6. hsize_2pow (integer)
 
    Number of the hash entries = 2^hash_size.
 
d9bb387b
    Default value is 4.
03d2aa4e
 
d9bb387b
    Example 7. Set hsize_2pow parameter
03d2aa4e
 ...
 modparam("pdt", "hsize_2pow", 4)
 ...
 
5ac87c47
 1.3.7. sync_time (integer)
 
d9bb387b
    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.
5ac87c47
 
d9bb387b
    Default value is 600.
5ac87c47
 
d9bb387b
    Example 8. Set sync_time parameter
5ac87c47
 ...
 modparam("pdt", "sync_time", 300)
 ...
 
 1.3.8. clean_time (integer)
 
d9bb387b
    Time in seconds to clean the changes inserted via FIFO. The changes
    will be removed from FIFO diff list only when all SER processes applied
    these changes.
5ac87c47
 
d9bb387b
    Default value is 900.
5ac87c47
 
d9bb387b
    Example 9. Set clean_time parameter
5ac87c47
 ...
 modparam("pdt", "clean_time", 600)
 ...
 
d9bb387b
 1.4. Functions
03d2aa4e
 
d9bb387b
 1.4.1.  prefix2domain(mode)
03d2aa4e
 
d9bb387b
    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.
03d2aa4e
 
d9bb387b
    The "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.
2ee939b2
 
d9bb387b
    Example 10. prefix2domain usage
03d2aa4e
 ...
 prefix2domain();
 ...
2ee939b2
 prefix2domain("2");
 ...
03d2aa4e
 
d9bb387b
 1.5. FIFO Interface
03d2aa4e
 
d9bb387b
    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 FIFO commands. All
    changes made via FIFO are applied to database. The database is loaded
    only at SER start up time.
5ac87c47
 
    There are three FIFO commands to use with PDT.
      * pdt_add - add a new prefix-domain pair
      * pdt_delete - remove a prefix-domain pair
      * pdt_list - list the prefixes and the domains
 
d9bb387b
    Example shell scripts for these commands are placed in './doc/'
    (pdt_fifo_add.sh, pdt_fifo_delete.sh, pdt_fifo_list.sh). More about, in
    the comments before the implementation of the functions, inside the
    'pdt.c' file.