src/modules/pdt/README
31ccf6a2
 pdt Module
 
 Elena-Ramona Modroiu
 
bd5ba9e7
    asipto.com
    <ramona@asipto.com>
31ccf6a2
 
 Edited by
 
 Elena-Ramona Modroiu
 
bd5ba9e7
    <ramona@asipto.com>
d34518a2
 
9cb2a163
    Copyright © 2003 FhG FOKUS
31ccf6a2
 
9cb2a163
    Copyright © 2004 Voice Sistem SRL
ee036e63
 
9cb2a163
    Copyright © 2008 Elena-Ramona Modroiu
d9bb387b
      __________________________________________________________________
31ccf6a2
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
31ccf6a2
 
d9bb387b
         1. Overview
         2. Dependencies
31ccf6a2
 
d9bb387b
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
31ccf6a2
 
ba7961bb
         3. Parameters
31ccf6a2
 
d9bb387b
               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)
31ccf6a2
 
ba7961bb
         4. Functions
31ccf6a2
 
d9bb387b
               4.1. prefix2domain(rewrite_mode, multidomain_mode)
               4.2. prefix2domain(rewrite_mode)
               4.3. prefix2domain()
fd494bce
               4.4. pd_translate(sdomain, rewrite_mode)
d77df08a
 
07f2b283
         5. RPC Commands
31ccf6a2
 
07f2b283
               5.1. pdt.list
               5.2. pdt.reload
31ccf6a2
 
d9bb387b
         6. Installation and Running
d77df08a
 
31ccf6a2
    List of Examples
d77df08a
 
    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
995469b5
    1.8. Set fetch_rows parameter
    1.9. Set char_list parameter
    1.10. Set check_domain parameter
    1.11. prefix2domain usage
fd494bce
    1.12. pd_translate usage
31ccf6a2
 
9fc784c6
 Chapter 1. Admin Guide
31ccf6a2
 
d9bb387b
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
ba7961bb
    3. Parameters
d9bb387b
 
         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)
 
ba7961bb
    4. Functions
d9bb387b
 
         4.1. prefix2domain(rewrite_mode, multidomain_mode)
         4.2. prefix2domain(rewrite_mode)
         4.3. prefix2domain()
fd494bce
         4.4. pd_translate(sdomain, rewrite_mode)
d9bb387b
 
07f2b283
    5. RPC Commands
31ccf6a2
 
07f2b283
         5.1. pdt.list
         5.2. pdt.reload
31ccf6a2
 
d9bb387b
    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.
31ccf6a2
 
    <prefix><userid><:password>@<mydomain.com> ...
 
    and the result will be:
 
    <userid><:password>@<domain[:port]>...
 
d77df08a
    Example 1.1. prefix-domain translation
040e9ae3
 prefix=123, domain(FROM)=siphub.org
31ccf6a2
 
040e9ae3
 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"
31ccf6a2
 sip:12391001@mydomain.com  => sip:91001@alpha.org
 
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.
bd5ba9e7
      * A sample config file is located in './doc/'.
d9bb387b
      * 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
a32f9480
        in './doc/' (pdt_fifo_list.sh).
31ccf6a2
 
d9bb387b
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
31ccf6a2
 
d9bb387b
 2.1. Kamailio Modules
31ccf6a2
 
    The following modules must be loaded before this module:
37e4f522
      * A Kamailio database module (e.g., mysql, dbtext).
31ccf6a2
 
d9bb387b
 2.2. External Libraries or Applications
31ccf6a2
 
d9bb387b
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
31ccf6a2
      * None.
 
ba7961bb
 3. Parameters
31ccf6a2
 
d9bb387b
    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)
31ccf6a2
 
1797d621
    URL of the database table to be used.
31ccf6a2
 
9cb2a163
    Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
31ccf6a2
 
d77df08a
    Example 1.2. Set db_url parameter
31ccf6a2
 ...
1797d621
 modparam("pdt", "db_url", "dbdriver://username:password@dbhost/dbname")
31ccf6a2
 ...
 
d9bb387b
 3.2. db_table (string)
31ccf6a2
 
    Table name.
 
9cb2a163
    Default value is “pdt”.
31ccf6a2
 
d77df08a
    Example 1.3. Set db_table parameter
31ccf6a2
 ...
 modparam("pdt", "db_table", "pdt")
 ...
 
d9bb387b
 3.3. sdomain_column (string)
040e9ae3
 
    Name of 'sdomain' column.
 
9cb2a163
    Default value is “sdomain”.
040e9ae3
 
d77df08a
    Example 1.4. Set sdomain_column parameter
040e9ae3
 ...
 modparam("pdt", "domain_column", "source_domain")
 ...
 
d9bb387b
 3.4. prefix_column (string)
31ccf6a2
 
    Name of 'prefix' column.
 
9cb2a163
    Default value is “prefix”.
31ccf6a2
 
d77df08a
    Example 1.5. Set prefix_column parameter
31ccf6a2
 ...
040e9ae3
 modparam("pdt", "prefix_column", "prefix")
31ccf6a2
 ...
 
d9bb387b
 3.5. domain_column (string)
31ccf6a2
 
    Name of 'domain' column.
 
9cb2a163
    Default value is “domain”.
31ccf6a2
 
d77df08a
    Example 1.6. Set domain_column parameter
31ccf6a2
 ...
 modparam("pdt", "domain_column", "hostname")
 ...
 
d9bb387b
 3.6. prefix (string)
31ccf6a2
 
d9bb387b
    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.
31ccf6a2
 
989206bd
    Default value is NULL.
31ccf6a2
 
d77df08a
    Example 1.7. Set prefix parameter
31ccf6a2
 ...
 modparam("pdt", "prefix", "00")
 ...
 
d9bb387b
 3.7. fetch_rows (integer)
ee036e63
 
    Number of rows to be loaded in one step from database.
 
989206bd
    Default value is 1000.
ee036e63
 
995469b5
    Example 1.8. Set fetch_rows parameter
ee036e63
 ...
 modparam("pdt", "fetch_rows", 4000)
 ...
 
d9bb387b
 3.8. char_list (string)
31ccf6a2
 
d95d071b
    The list with characters allowed in prefix.
31ccf6a2
 
9cb2a163
    Default value is “0123456789”.
31ccf6a2
 
995469b5
    Example 1.9. Set char_list parameter
31ccf6a2
 ...
d95d071b
 modparam("pdt", "char_list", "0123456789*+")
31ccf6a2
 ...
 
d9bb387b
 3.9. check_domain (integer)
ad0f637d
 
d9bb387b
    Module will check if destination domain is duplicated for same source
    domain (1 - check; 0 - don't check).
ad0f637d
 
989206bd
    Default value is 1.
ad0f637d
 
995469b5
    Example 1.10. Set check_domain parameter
ad0f637d
 ...
 modparam("pdt", "check_domain", 0)
 ...
 
ba7961bb
 4. Functions
d9bb387b
 
    4.1. prefix2domain(rewrite_mode, multidomain_mode)
    4.2. prefix2domain(rewrite_mode)
    4.3. prefix2domain()
fd494bce
    4.4. pd_translate(sdomain, rewrite_mode)
31ccf6a2
 
9cb2a163
 4.1.  prefix2domain(rewrite_mode, multidomain_mode)
31ccf6a2
 
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.
31ccf6a2
 
d9bb387b
    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).
040e9ae3
 
d9bb387b
    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 "*".
617e6c49
 
9cb2a163
    The “rewrite_mode” parameter specifies whether to strip or not the
d9bb387b
    prefix from user part. The possible values are:
522ece1d
      * 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.
31ccf6a2
 
9cb2a163
    The “multidomain_mode” parameter specifies the kind of multidomain
d9bb387b
    support to use. The possible values are:
617e6c49
      * 0 : Translation of URI regardless of source domain.
989206bd
      * 1 : Translation of URI using as source domain the domain in
        From-URI.
      * 2 : Translation of URI using as source domain the domain in
d9bb387b
        From-URI. In case there is no entry for the required sdomain, it
        tries the translation using "*" as sdomain.
522ece1d
      * $PV : any PV holding one of the above values.
617e6c49
 
7b56ffd7
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
995469b5
    Example 1.11. prefix2domain usage
31ccf6a2
 ...
617e6c49
 prefix2domain("2", "2");
 ...
522ece1d
 $var(a) = 1;
 prefix2domain("$var(a)", "2");
 ...
617e6c49
 
9cb2a163
 4.2.  prefix2domain(rewrite_mode)
617e6c49
 
    The same as prefix2domain(rewrite_mode, "0"), that is without
d9bb387b
    multidomain support, translation of URI being done regardless of the
    source domain.
31ccf6a2
 ...
 prefix2domain("2");
 ...
 
9cb2a163
 4.3.  prefix2domain()
617e6c49
 
    The same as prefix2domain("0", "0").
 ...
 prefix2domain();
 ...
 
9cb2a163
 4.4.  pd_translate(sdomain, rewrite_mode)
fd494bce
 
    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.
 
9cb2a163
    The “sdomain” parameter specifies the source domain to be used to match
fd494bce
    the longest prefix. Can be a static string or dynamic parameter with
    variables inside.
 
9cb2a163
    The “rewrite_mode” parameter specifies whether to strip or not the
fd494bce
    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)");
 ...
 
07f2b283
 5. RPC Commands
31ccf6a2
 
07f2b283
    5.1. pdt.list
    5.2. pdt.reload
31ccf6a2
 
d9bb387b
    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
07f2b283
    prefix-domain pair at runtime you have to use RPC commands. All changes
    made via these commands are applied to database and the cache is
    updated correspondingly.
d9bb387b
 
07f2b283
 5.1.  pdt.list
1061d103
 
    Produces a listing of the entries prefixes/domains/sdomains.
 
07f2b283
    Name: pdt.list
1061d103
 
    Parameters:
      * _sdomain_ : a source domain value.
      * _prefix_ : a prefix value
      * _domain_: a domain value
 
    "." (dot) means NULL value
 
d9bb387b
    The comparison operation is 'START WITH' -- if domain is 'a' then all
    domains starting with 'a' are listed.
1061d103
 
07f2b283
    RPC Command Example:
 ...
2064efea
 kamcmd pdt.list kamailio.org 123
07f2b283
 ...
617e6c49
 
    Examples:
07f2b283
      * “pdt.list siph 2 .” : Lists the entries where sdomain is starting
d9bb387b
        with 'siph', prefix is starting with '2' and domain is anything
07f2b283
      * “pdt.list siph 2” : Lists the entries where sdomain is starting
d9bb387b
        with 'siph', prefix is starting with '2' and domain is anything
07f2b283
      * “pdt.list . 2 open” : Lists the entries where sdomain is anything,
d9bb387b
        prefix starts with '2' and domain starts with 'open'.
 
07f2b283
 5.2.  pdt.reload
d95d071b
 
    Reload all sdomain-prefix-domain records from database.
 
07f2b283
    Name: pdt.reload
d95d071b
 
    Parameters:
      * none
 
07f2b283
    RPC Command Example:
 ...
 kamcmd pdt.reload
 ...
1061d103
 
d9bb387b
 6. Installation and Running
1061d103
 
d9bb387b
    Example shell scripts for MI FIFO commands are placed in './doc/'
    (pdt_fifo_add.sh, pdt_fifo_delete.sh, pdt_fifo_list.sh).