$Revision: 1533 $
$Date: 2007-01-23 12:01:01 +0200 (Tue, 23 Jan 2007) $
User's Guide
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]>...
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).
Dependencies
&ser; Modules
The following modules must be loaded before this module:
A &ser; database module (e.g., mysql,
dbtext).
External Libraries or Applications
The following libraries or applications must be installed before running
&ser; with this module loaded:
None.
Exported Parameters
<varname>db_url</varname> (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
.
Set <varname>db_url</varname> parameter
...
modparam("pdt", "db_url", "mysql://user:xxx@127.0.0.1/ser")
...
<varname>db_table</varname> (string)
Table name.
Default value is pdt
.
Set <varname>db_table</varname> parameter
...
modparam("pdt", "db_table", "pdt")
...
<varname>sdomain_column</varname> (string)
Name of 'sdomain' column.
Default value is sdomain
.
Set <varname>sdomain_column</varname> parameter
...
modparam("pdt", "domain_column", "source_domain")
...
<varname>prefix_column</varname> (string)
Name of 'prefix' column.
Default value is prefix
.
Set <varname>prefix_column</varname> parameter
...
modparam("pdt", "prefix_column", "prefix")
...
<varname>domain_column</varname> (string)
Name of 'domain' column.
Default value is domain
.
Set <varname>domain_column</varname> parameter
...
modparam("pdt", "domain_column", "hostname")
...
<varname>prefix</varname> (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.
Set <varname>prefix</varname> parameter
...
modparam("pdt", "prefix", "00")
...
<varname>hsize_2pow</varname> (integer)
Number of the hash entries = 2^hash_size.
Default value is 4.
Set <varname>hsize_2pow</varname> parameter
...
modparam("pdt", "hsize_2pow", 4)
...
<varname>sync_time</varname> (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.
Set <varname>sync_time</varname> parameter
...
modparam("pdt", "sync_time", 300)
...
<varname>clean_time</varname> (integer)
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.
Default value is 900.
Set <varname>clean_time</varname> parameter
...
modparam("pdt", "clean_time", 600)
...
Exported Functions
<function moreinfo="none">prefix2domain(rewrite_mode, multidomain_mode)</function>
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.
<function>prefix2domain</function> usage
...
prefix2domain("2", "2");
...
<function moreinfo="none">prefix2domain(rewrite_mode)</function>
The same as prefix2domain(rewrite_mode, "0"), that is without
multidomain support, translation of &uri; being done regardless of
the source domain.
...
prefix2domain("2");
...
<function moreinfo="none">prefix2domain()</function>
The same as prefix2domain("0", "0").
...
prefix2domain();
...
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 &ser; start up time.
<function moreinfo="none">pdt_add</function>
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_
<function moreinfo="none">pdt_delete</function>
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_
<function moreinfo="none">pdt_list</function>
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'.
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).