db_text Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview

              1.1.1. Design of db_text engine
              1.1.2. Internal format of a db_text 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.3.2. buffer_size (integer)

        1.4. Exported Functions
        1.5. Exported MI Functions

              1.5.1. dbt_dump
              1.5.2. dbt_reload

        1.6. Installation and Running

              1.6.1. Using db_text with basic OpenSIPS
                      configuration

   2. Developer Guide
   3. Contributors

        3.1. By Commit Statistics
        3.2. By Commit Activity

   4. Documentation

        4.1. Contributors

   List of Tables

   3.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   3.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Sample of a db_text table
   1.2. Minimal OpenSIPS location db_text table definition
   1.3. Minimal OpenSIPS subscriber db_text table example
   1.4. Set db_mode parameter
   1.5. Set buffer_size parameter
   1.6. Load the db_text module
   1.7. Definition of 'subscriber' table (one line)
   1.8. Definition of 'location' and 'aliases' tables (one line)
   1.9. Definition of 'version' table and sample records
   1.10. 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 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 db_text engine

   The db_text 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.

1.1.2. Internal format of a db_text 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 db_text 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 db_text table definition
...
username(str) contact(str) expires(int) q(double) callid(str) cseq(int)
...

   Example 1.3. Minimal OpenSIPS subscriber db_text 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

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.3.2. buffer_size (integer)

   Size of the buffer used to read the text file.

   Default value is “4096”.

   Example 1.5. Set buffer_size parameter
...
modparam("db_text", "buffer_size", 8192)
...

1.4. Exported Functions

   None.

1.5. Exported MI Functions

1.5.1. dbt_dump

   Write back to hard drive modified tables.

   Name: dbt_dump.

   Parameters: none

   MI FIFO Command Format:
opensips-cli -x mi dbt_dump

1.5.2. dbt_reload

   Causes db_text module to reload cached tables from disk.
   Depending on parameters it could be a whole cache or a
   specified database or a single table. If any table cannot be
   reloaded from disk - the old version preserved and error
   reported.

   Name: dbt_reload.

   Parameters:
     * db_name (optional) - database name to reload.
     * table_name (optional, but cannot be present without the
       db_name parameter) - specific table to reload.

   MI FIFO Command Format:
opensips-cli -x mi dbt_reload

opensips-cli -x mi dbt_reload /path/to/dbtext/database

opensips-cli -x mi dbt_reload /path/to/dbtext/database table_name

1.6. Installation and Running

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

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

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

1.6.1. Using db_text with basic OpenSIPS configuration

   Here are the definitions for most important table as well as a
   basic configuration file to use db_text with OpenSIPS. The
   table structures may change in time and you will have to adjust
   next examples.

   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/opensipsdb' directory.

   Example 1.7. 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.8. 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.9. Definition of 'version' table and sample records
...
table_name(str) table_version(int)
subscriber:3
location:6
aliases:6
...

   Example 1.10. Configuration file
...
#
# simple quick-start config script with dbtext
#

# ----------- global configuration parameters ------------------------

#debug_mode=yes
udp_workers=4

check_via=no    # (cmd. line: -v)
dns=no          # (cmd. line: -r)
rev_dns=no      # (cmd. line: -R)

socket=udp:10.100.100.1: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", "text:///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 ($ml >=  65535 ) {
        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 (!$rm=="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 (!is_myself("$rd")) {
        # 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 (is_myself("$rd")) {
        if ($rm=="REGISTER") {
            # digest authentication
            if (!www_authorize("", "subscriber")) {
                www_challenge("", "0");
                exit;
            };

            save("location");
            exit;
        };

        lookup("aliases");
        if (!is_myself("$rd")) {
            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.

Chapter 3. Contributors

3.1. By Commit Statistics

   Table 3.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Daniel-Constantin Mierla (@miconda) 135 59 6126 1441
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 41 32 310 309
   3. Henning Westerholt (@henningw) 25 15 252 410
   4. Liviu Chircu (@liviuchircu) 21 18 71 110
   5. Razvan Crainea (@razvancrainea) 21 17 121 95
   6. Jan Janak (@janakj) 11 7 124 106
   7. Ovidiu Sas (@ovidiusas) 8 6 105 20
   8. Vlad Patrascu (@rvlad-patrascu) 8 6 94 49
   9. Sergey Khripchenko (@shripchenko) 5 2 185 2
   10. Jiri Kuthan (@jiriatipteldotorg) 4 2 8 6

   All remaining contributors: Ionut Ionita (@ionutrazvanionita),
   Maksym Sobolyev (@sobomax), Konstantin Bokarius, Razvan
   Pistolea, Chris Heiser, Norman Brandinger (@NormB), Peter
   Lemenkov (@lemenkov), Edson Gellert Schubert, Dusan Klinec
   (@ph4r05), 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. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

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

3.2. By Commit Activity

   Table 3.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Liviu Chircu (@liviuchircu)         Mar 2014 - May 2024
   2.  Ovidiu Sas (@ovidiusas)             Dec 2012 - Mar 2024
   3.  Maksym Sobolyev (@sobomax)          Feb 2023 - Feb 2023
   4.  Razvan Crainea (@razvancrainea)     Oct 2011 - Jan 2022
   5.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Dec 2021
   6.  Bogdan-Andrei Iancu (@bogdan-iancu) Nov 2003 - Apr 2020
   7.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   8.  Dusan Klinec (@ph4r05)              Dec 2015 - Dec 2015
   9.  Sergey Khripchenko (@shripchenko)   Aug 2015 - Aug 2015
   10. Ionut Ionita (@ionutrazvanionita)   Jan 2015 - Feb 2015

   All remaining contributors: Razvan Pistolea, Henning Westerholt
   (@henningw), Daniel-Constantin Mierla (@miconda), Konstantin
   Bokarius, Chris Heiser, Edson Gellert Schubert, Norman
   Brandinger (@NormB), Jan Janak (@janakj), Jiri Kuthan
   (@jiriatipteldotorg), Andrei Pelinescu-Onciul.

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

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Ovidiu Sas (@ovidiusas), Liviu Chircu
   (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Razvan
   Crainea (@razvancrainea), Peter Lemenkov (@lemenkov), Vlad
   Patrascu (@rvlad-patrascu), Sergey Khripchenko (@shripchenko),
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert, Henning Westerholt (@henningw).

   Documentation Copyrights:

   Copyright © 2003-2004 FhG FOKUS
