DBTEXT module

Admin Guide

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.

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 db_text in OpenSIPS, the database URL for modules must be the path to the directory where the table-files are located, prefixed by “text://”, e.g., “text:///var/dbtext/opensips”. If there is no ”/” after “text://” 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.

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.

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:
...

Minimal OpenSIPS location dbtext table definition

...
username(str) contact(str) expires(int) q(double) callid(str) cseq(int)
...

Minimal OpenSIPS subscriber dbtext table example

...
username(str) password(str) ha1(str) domain(str) ha1b(str)
suser:supasswd:xxx:alpha.org:xxx
...

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.

Dependencies

OpenSIPS modules

The next modules must be loaded before this module:

• none.

External libraries or applications

The next libraries or applications must be installed before running OpenSIPS with this module:

• none.

Exported Parameters

None.

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”.

Set db_mode parameter

...
modparam("db_text", "db_mode", 1)
...

Exported Functions

None.

Installation and Running

Compile the module and load it instead of mysql or other DB modules.

Danger

When you use db_text in OpenSIPS, the database URL for modules must be the path to the directory where the table-files are located, prefixed by “text://”, e.g., “text:///var/dbtext/opensips”. If there is no ”/” after “text://” 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.

Load the dbtext module

...
loadmodule "/path/to/opensips/modules/db_text.so"
...
modparam("module_name", "database_URL", "text:///path/to/dbtext/database")
...

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.

Definition of 'subscriber' table (one line)

...
username(str) domain(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)
...

Definition of 'location' and 'aliases' tables (one line)

...
username(str) domain(str,null) contact(str,null) received(str) expires(int,null) q(double,null) callid(str,null) cseq(int,null) last_modified(str) flags(int) user_agent(str) socket(str)
...

Definition of 'version' table and sample records

...
table_name(str) table_version(int)
subscriber:3
location:6
aliases:6
...

Samples

OpenSIPS Config Script - DB_TEXT Usage

#
# $Id$
#
# 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")

# -------------------------  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();
    };
}

Developer Guide

Once you have the module loaded, you can use the API specified by OpenSIPS DB interface.

Contributors

By Commit Statistics

Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

#	Name	DevScore	Commits	Lines++	Lines—
1.	Daniel-Constantin Mierla (@miconda)	138	59	6195	1510
2.	Henning Westerholt (@henningw)	133	17	4516	4674
3.	Bogdan-Andrei Iancu (@bogdan-iancu)	30	21	320	323
4.	Jan Janak (@janakj)	11	7	128	110
5.	Stefan Darius (@dariusstefan)	11	4	521	120
6.	Jiri Kuthan (@jiriatipteldotorg)	4	2	8	6
7.	Konstantin Bokarius	3	1	3	5
8.	Razvan Crainea (@razvancrainea)	3	1	2	2
9.	Razvan Pistolea	3	1	2	2
10.	Norman Brandinger (@NormB)	3	1	1	1

All remaining contributors: Chris Heiser, Edson Gellert Schubert, Andrei Pelinescu-Onciul.

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits

(3) ignoring whitespace edits, renamed files and auto-generated files

By Commit Activity

#	Name	Commit Activity
1.	Stefan Darius (@dariusstefan)	Jun 2026 - Jul 2026
2.	Razvan Crainea (@razvancrainea)	Jun 2026 - Jun 2026
3.	Bogdan-Andrei Iancu (@bogdan-iancu)	Nov 2003 - Jul 2011
4.	Razvan Pistolea	Jul 2009 - Jul 2009
5.	Henning Westerholt (@henningw)	Aug 2007 - Mar 2009
6.	Daniel-Constantin Mierla (@miconda)	Feb 2003 - May 2008
7.	Konstantin Bokarius	Mar 2008 - Mar 2008
8.	Chris Heiser	Mar 2008 - Mar 2008
9.	Edson Gellert Schubert	Feb 2008 - Feb 2008
10.	Norman Brandinger (@NormB)	Aug 2006 - Aug 2006

All remaining contributors: Jan Janak (@janakj), Jiri Kuthan (@jiriatipteldotorg), Andrei Pelinescu-Onciul.

(1) including any documentation-related commits, excluding merge commits

Documentation

Contributors

Last edited by: Razvan Crainea (@razvancrainea), Bogdan-Andrei Iancu (@bogdan-iancu), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt (@henningw).

License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0