DBTEXT Module
Daniel-Constantin Mierla
<miconda@gmail.com>
Edited by
Daniel-Constantin Mierla
<miconda@gmail.com>
Copyright © 2003, 2004 FhG FOKUS
Revision History
Revision $Revision: 5906 $ $Date: 2009-07-21 10:45:05 +0300
(Tue, 21 Jul 2009) $
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.1.1. Design of dbtext engine
1.1.2. Internal format of a dbtext table
1.1.3. Existing limitations
1.2. Dependencies
1.2.1. OpenSIPS modules
1.2.2. External libraries or applications
1.3. Exported Parameters
1.3.1. db_mode (integer)
1.4. Exported Functions
1.5. Installation and Running
1.5.1. Using dbtext with basic OpenSIPS
configuration
2. Developer Guide
List of Examples
1.1. Sample of a dbtext table
1.2. Minimal OpenSIPS location dbtext table definition
1.3. Minimal OpenSIPS subscriber dbtext table example
1.4. Set db_mode parameter
1.5. Load the dbtext module
1.6. Definition of 'subscriber' table (one line)
1.7. Definition of 'location' and 'aliases' tables (one line)
1.8. Definition of 'version' table and sample records
1.9. Configuration file
Chapter 1. Admin Guide
1.1. Overview
The module implements a simplified database engine based on
text files. It can be used by OpenSIPS DB interface instead of
other database module (like MySQL).
The module is meant for use in demos or small devices that do
not support other DB modules. It keeps everything in memory and
if you deal with large amount of data you may run quickly out
of memory. Also, it has not implemented all standard database
facilities (like order by), it includes minimal functionality
to work properly (who knows ?!?) with OpenSIPS.
NOTE: the timestamp is printed in an integer value from time_t
structure. If you use it in a system that cannot do this
conversion, it will fail (support for such situation is in
to-do list).
NOTE: even when is in non-caching mode, the module does not
write back to hard drive after changes. In this mode, the
module checks if the corresponding file on disk has changed,
and reloads it. The write on disk happens at OpenSIPS shut
down.
1.1.1. Design of dbtext engine
The dbtext database system architecture:
* a database is represented by a directory in the local file
system. NOTE: when you use dbtext in OpenSIPS, the database
URL for modules must be the path to the directory where the
table-files are located, prefixed by "dbtext://", e.g.,
"dbtext:///var/dbtext/ser". If there is no "/" after
"dbtext://" then "CFG_DIR/" is inserted at the beginning of
the database path. So, either you provide an absolute path
to database directory or a relative one to "CFG_DIR"
directory.
* a table is represented by a text file inside database
directory.
1.1.2. Internal format of a dbtext table
First line is the definition of the columns. Each column must
be declared as follows:
* the name of column must not include white spaces.
* the format of a column definition is: name(type,attr).
* between two column definitions must be a white space, e.g.,
"first_name(str) last_name(str)".
* the type of a column can be:
+ int - integer numbers.
+ double - real numbers with two decimals.
+ str - strings with maximum size of 4KB.
* a column can have one of the attributes:
+ auto - only for 'int' columns, the maximum value in
that column is incremented and stored in this field if
it is not provided in queries.
+ null - accept null values in column fields.
+ if no attribute is set, the fields of the column
cannot have null value.
* each other line is a row with data. The line ends with
"\n".
* the fields are separated by ":".
* no value between two ':' (or between ':' and start/end of a
row) means "null" value.
* next characters must be escaped in strings: "\n", "\r",
"\t", ":".
* 0 -- the zero value must be escaped too.
Example 1.1. Sample of a dbtext table
...
id(int,auto) name(str) flag(double) desc(str,null)
1:nick:0.34:a\tgood\: friend
2:cole:-3.75:colleague
3:bob:2.50:
...
Example 1.2. Minimal OpenSIPS location dbtext table definition
...
username(str) contact(str) expires(int) q(double) callid(str) cseq(int)
...
Example 1.3. Minimal OpenSIPS subscriber dbtext table example
...
username(str) password(str) ha1(str) domain(str) ha1b(str)
suser:supasswd:xxx:alpha.org:xxx
...
1.1.3. Existing limitations
This database interface don't support the data insertion with
default values. All such values specified in the database
template are ignored. So its advisable to specify all data for
a column at insertion operations.
1.2. Dependencies
1.2.1. OpenSIPS modules
The next modules must be loaded before this module:
* none.
1.2.2. External libraries or applications
The next libraries or applications must be installed before
running OpenSIPS with this module:
* none.
1.3. Exported Parameters
None.
1.3.1. db_mode (integer)
Set caching mode (0) or non-caching mode (1). In caching mode,
data is loaded at startup. In non-caching mode, the module
check every time a table is requested whether the corresponding
file on disk has changed, and if yes, will re-load table from
file.
Default value is "0".
Example 1.4. Set db_mode parameter
...
modparam("db_text", "db_mode", 1)
...
1.4. Exported Functions
None.
1.5. Installation and Running
Compile the module and load it instead of mysql or other DB
modules.
REMINDER: when you use dbtext in OpenSIPS, the database URL for
modules must be the path to the directory where the table-files
are located, prefixed by "dbtext://", e.g.,
"dbtext:///var/dbtext/ser". If there is no "/" after
"dbtext://" then "CFG_DIR/" is inserted at the beginning of the
database path. So, either you provide an absolute path to
database directory or a relative one to "CFG_DIR" directory.
Example 1.5. Load the dbtext module
...
loadmodule "/path/to/opensips/modules/db_text.so"
...
modparam("module_name", "database_URL", "text:///path/to/dbtext/database
")
...
1.5.1. Using dbtext with basic OpenSIPS configuration
Here are the definitions for most important table as well as a
basic configuration file to use dbtext with OpenSIPS. The table
structures may change in time and you will have to adjust next
examples. These are know to work with upcoming OpenSIPS v0.9.x
You have to populate the table 'subscriber' by hand with user
profiles in order to have authentication. To use with the given
configuration file, the table files must be placed in the
'/tmp/serdb' directory.
Example 1.6. Definition of 'subscriber' table (one line)
...
username(str) domain(str) password(str) first_name(str) last_name(str) p
hone(str) email_address(str) datetime_created(int) datetime_modified(int
) confirmation(str) flag(str) sendnotification(str) greeting(str) ha1(st
r) ha1b(str) perms(str) allow_find(str) timezone(str,null) rpid(str,null
)
...
Example 1.7. Definition of 'location' and 'aliases' tables (one
line)
...
username(str) domain(str,null) contact(str,null) received(str) expires(i
nt,null) q(double,null) callid(str,null) cseq(int,null) last_modified(st
r) flags(int) user_agent(str) socket(str)
...
Example 1.8. Definition of 'version' table and sample records
...
table_name(str) table_version(int)
subscriber:3
location:6
aliases:6
...
Example 1.9. Configuration file
...
#
# $Id: README 5906 2009-07-21 09:05:29Z bogdan_iancu $
#
# simple quick-start config script with dbtext
#
# ----------- global configuration parameters ------------------------
#debug=9 # debug level (cmd line: -dddddddddd)
#fork=yes
#log_stderror=no # (cmd line: -E)
check_via=no # (cmd. line: -v)
dns=no # (cmd. line: -r)
rev_dns=no # (cmd. line: -R)
children=4
listen=10.100.100.1
port=5060
# ------------------ module loading ----------------------------------
# use dbtext database
loadmodule "modules/dbtext/dbtext.so"
loadmodule "modules/sl/sl.so"
loadmodule "modules/tm/tm.so"
loadmodule "modules/rr/rr.so"
loadmodule "modules/maxfwd/maxfwd.so"
loadmodule "modules/usrloc/usrloc.so"
loadmodule "modules/registrar/registrar.so"
loadmodule "modules/textops/textops.so"
loadmodule "modules/textops/mi_fifo.so"
# modules for digest authentication
loadmodule "modules/auth/auth.so"
loadmodule "modules/auth_db/auth_db.so"
# ----------------- setting module-specific parameters ---------------
# -- mi_fifo params --
modparam("mi_fifo", "fifo_name", "/tmp/opensips_fifo")
# -- usrloc params --
# use dbtext database for persistent storage
modparam("usrloc", "db_mode", 2)
modparam("usrloc|auth_db", "db_url", "dbtext:///tmp/opensipsdb")
# -- auth params --
#
modparam("auth_db", "calculate_ha1", 1)
modparam("auth_db", "password_column", "password")
modparam("auth_db", "user_column", "username")
modparam("auth_db", "domain_column", "domain")
# -- rr params --
# add value to ;lr param to make some broken UAs happy
modparam("rr", "enable_full_lr", 1)
# ------------------------- request routing logic -------------------
# main routing logic
route{
# initial sanity checks -- messages with
# max_forwards==0, or excessively long requests
if (!mf_process_maxfwd_header("10")) {
sl_send_reply("483","Too Many Hops");
exit;
};
if (msg:len >= max_len ) {
sl_send_reply("513", "Message too big");
exit;
};
# we record-route all messages -- to make sure that
# subsequent messages will go through our proxy; that's
# particularly good if upstream and downstream entities
# use different transport protocol
if (!method=="REGISTER") record_route();
# subsequent messages withing a dialog should take the
# path determined by record-routing
if (loose_route()) {
# mark routing logic in request
append_hf("P-hint: rr-enforced\r\n");
route(1);
exit;
};
if (!uri==myself) {
# mark routing logic in request
append_hf("P-hint: outbound\r\n");
route(1);
exit;
};
# if the request is for other domain use UsrLoc
# (in case, it does not work, use the following command
# with proper names and addresses in it)
if (uri==myself) {
if (method=="REGISTER") {
# digest authentication
if (!www_authorize("", "subscriber")) {
www_challenge("", "0");
exit;
};
save("location");
exit;
};
lookup("aliases");
if (!uri==myself) {
append_hf("P-hint: outbound alias\r\n");
route(1);
exit;
};
# native SIP destinations are handled using our USRLOC DB
if (!lookup("location")) {
sl_send_reply("404", "Not Found");
exit;
};
};
append_hf("P-hint: usrloc applied\r\n");
route(1);
}
route[1]
{
# send it out now; use stateful forwarding as it works reliably
# even for UDP2TCP
if (!t_relay()) {
sl_reply_error();
};
}
...
Chapter 2. Developer Guide
Once you have the module loaded, you can use the API specified
by OpenSIPS DB interface.
