mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
307 lines
8.0 KiB
307 lines
8.0 KiB
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<section id="dbtext" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<sectioninfo>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Daniel-Constantin</firstname>
|
|
<surname>Mierla</surname>
|
|
<affiliation><orgname>FhG FOKUS</orgname></affiliation>
|
|
<address>
|
|
<email>mierla@fokus.fraunhofer.de</email>
|
|
</address>
|
|
</author>
|
|
</authorgroup>
|
|
<copyright>
|
|
<year>2003</year>
|
|
<year>2004</year>
|
|
<holder>FhG FOKUS</holder>
|
|
</copyright>
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>$Revision$</revnumber>
|
|
<date>$Date$</date>
|
|
</revision>
|
|
</revhistory>
|
|
</sectioninfo>
|
|
|
|
<title>Dbtext Module</title>
|
|
|
|
|
|
<section id="dbtext.overview">
|
|
<title>Overview</title>
|
|
<para>
|
|
The module implements a simplified database engine based on text
|
|
files. It can be used by SER DB interface instead of other database
|
|
module (like MySQL).
|
|
</para>
|
|
<para>
|
|
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 SER.
|
|
</para>
|
|
|
|
<section id="design">
|
|
<title>Design of Dbtext Engine</title>
|
|
<para>
|
|
The dbtext database system architecture:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
A database is represented by a directory on the
|
|
local file system.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
When you use "dbtext" in SER, 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.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
A table is represented by a text file inside
|
|
database directory.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="internal_format">
|
|
<title>Internal Format of a Dbtext Table</title>
|
|
<para>
|
|
First line is the definition of the columns. Each column must
|
|
be declared as follows:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
the name of column must not include white spaces.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
the format of a column definition is:
|
|
<emphasis>name(type,attr)</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
between two column definitions must be a white
|
|
space, e.g.,
|
|
"first_name(str) last_name(str)".
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
the type of a column can be:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>int</emphasis> - integer
|
|
numbers.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>double</emphasis> - real numbers with two
|
|
decimals.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>str</emphasis> - strings with maximum size of 4KB.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
a column can have one of the attributes:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>auto</emphasis> - only for 'int'
|
|
columns, the maximum value in that column is
|
|
incremented and stored in this field if it is not
|
|
provided in queries.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>null</emphasis> - accept null
|
|
values in column fields.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
if no attribute is set, the fields of
|
|
the column cannot have null value.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
each other line is a row with data. The
|
|
line ends with "\n".
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
the fields are separated by ":".
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
no value between two ':' (or between ':' and
|
|
start/end of a row) means "null" value.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
next characters must be escaped in strings: "\n",
|
|
"\r", "\t", ":".
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>0</emphasis> - The zero value must be
|
|
escaped too.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<example>
|
|
<title>Sample of a dbtext table</title>
|
|
<programlisting>
|
|
...
|
|
id(int,auto) name(str) flag(double) desc(str,null)
|
|
1:nick:0.34:a\tgood\:friend
|
|
2:cole:-3.75:colleague3:bob:2.50:
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Minimal SER location dbtext table definition</title>
|
|
<programlisting>
|
|
...
|
|
username(str) contact(str) expires(int) q(double) callid(str) cseq(int)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Minimal SER subscriber dbtext table example</title>
|
|
<programlisting>
|
|
...
|
|
username(str) password(str) ha1(str) domain(str) ha1b(str)
|
|
suser:supasswd:xxx:iptel.org:xxx
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="install_run">
|
|
<title>Installation And Running</title>
|
|
<para>
|
|
Compile the module and load it instead of mysql or other DB
|
|
modules.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
When you use <emphasis>dbtext</emphasis> in SER, 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.
|
|
</para>
|
|
</note>
|
|
<example>
|
|
<title>Load the dbtext module</title>
|
|
<programlisting>
|
|
...
|
|
loadmodule "/path/to/ser/modules/dbtext.so"
|
|
...
|
|
modparam("module_name", "db_url", "dbtext:///path/to/dbtext/database")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
|
|
<section id="using">
|
|
<title>Using Dbtext With Basic SER Configuration</title>
|
|
<para>
|
|
Here are the definitions for most important table as well as a
|
|
basic configuration file to use dbtext with SER. The table
|
|
structures may change in time and you will have to adjust
|
|
next examples.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<example>
|
|
<title>Definition of 'subscriber' table (one line)</title>
|
|
<programlisting>
|
|
...
|
|
username(str) domn(str) password(str) first_name(str) last_name(str)
|
|
phone(str) email_address(str) datetime_created(int)
|
|
datetime_modified(int) confirmation(str) flag(str)
|
|
sendnotification(str) greeting(str) ha1(str) ha1b(str)
|
|
perms(str) allow_find(str) timezone(str,null) rpid(str,null)
|
|
uuid(str,null)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Definition of 'location' and 'aliases' tables (one line)</title>
|
|
<programlisting>
|
|
...
|
|
username(str) domain(str,null) contact(str,null) expires(int,null)
|
|
q(double,null) callid(str,null) cseq(int,null)
|
|
last_modified(str) replicate(int,null) state(int,null)
|
|
flags(int) user_agent(str) received(str)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Definition of 'version' table and sample records</title>
|
|
<programlisting>
|
|
...
|
|
table_name(str) table_version(int) subscriber:3 location:6 aliases:6
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Configuration file</title>
|
|
<programlisting>
|
|
<xi:include href="dbtext-ser.cfg" parse="text"/>
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
</section>
|