"Fossies" - the Fresh Open Source Software Archive

Member "opensips-3.0.1/modules/db_text/README" (1 Oct 2019, 15724 Bytes) of package /linux/misc/opensips-3.0.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 3.0.0_vs_3.0.1.

    1 db_text Module
    2      __________________________________________________________
    3 
    4    Table of Contents
    5 
    6    1. Admin Guide
    7 
    8         1.1. Overview
    9 
   10               1.1.1. Design of db_text engine
   11               1.1.2. Internal format of a db_text table
   12               1.1.3. Existing limitations
   13 
   14         1.2. Dependencies
   15 
   16               1.2.1. OpenSIPS modules
   17               1.2.2. External libraries or applications
   18 
   19         1.3. Exported Parameters
   20 
   21               1.3.1. db_mode (integer)
   22 
   23         1.4. Exported Functions
   24         1.5. Exported MI Functions
   25 
   26               1.5.1. dbt_dump
   27               1.5.2. dbt_reload
   28 
   29         1.6. Installation and Running
   30 
   31               1.6.1. Using db_text with basic OpenSIPS
   32                       configuration
   33 
   34    2. Developer Guide
   35    3. Contributors
   36 
   37         3.1. By Commit Statistics
   38         3.2. By Commit Activity
   39 
   40    4. Documentation
   41 
   42         4.1. Contributors
   43 
   44    List of Tables
   45 
   46    3.1. Top contributors by DevScore^(1), authored commits^(2) and
   47           lines added/removed^(3)
   48 
   49    3.2. Most recently active contributors^(1) to this module
   50 
   51    List of Examples
   52 
   53    1.1. Sample of a db_text table
   54    1.2. Minimal OpenSIPS location db_text table definition
   55    1.3. Minimal OpenSIPS subscriber db_text table example
   56    1.4. Set db_mode parameter
   57    1.5. Load the db_text module
   58    1.6. Definition of 'subscriber' table (one line)
   59    1.7. Definition of 'location' and 'aliases' tables (one line)
   60    1.8. Definition of 'version' table and sample records
   61    1.9. Configuration file
   62 
   63 Chapter 1. Admin Guide
   64 
   65 1.1. Overview
   66 
   67    The module implements a simplified database engine based on
   68    text files. It can be used by OpenSIPS DB interface instead of
   69    other database module (like MySQL).
   70 
   71    The module is meant for use in demos or small devices that do
   72    not support other DB modules. It keeps everything in memory and
   73    if you deal with large amount of data you may run quickly out
   74    of memory. Also, it has not implemented all standard database
   75    facilities (like order by), it includes minimal functionality
   76    to work properly with OpenSIPS
   77 
   78    NOTE: the timestamp is printed in an integer value from time_t
   79    structure. If you use it in a system that cannot do this
   80    conversion, it will fail (support for such situation is in
   81    to-do list).
   82 
   83    NOTE: even when is in non-caching mode, the module does not
   84    write back to hard drive after changes. In this mode, the
   85    module checks if the corresponding file on disk has changed,
   86    and reloads it. The write on disk happens at OpenSIPS shut
   87    down.
   88 
   89 1.1.1. Design of db_text engine
   90 
   91    The db_text database system architecture:
   92      * a database is represented by a directory in the local file
   93        system. NOTE: when you use db_text in OpenSIPS, the
   94        database URL for modules must be the path to the directory
   95        where the table-files are located, prefixed by “text://”,
   96        e.g., “text:///var/dbtext/opensips”. If there is no “/”
   97        after “text://” then “CFG_DIR/” is inserted at the
   98        beginning of the database path. So, either you provide an
   99        absolute path to database directory or a relative one to
  100        “CFG_DIR” directory.
  101      * a table is represented by a text file inside database
  102        directory.
  103 
  104 1.1.2. Internal format of a db_text table
  105 
  106    First line is the definition of the columns. Each column must
  107    be declared as follows:
  108      * the name of column must not include white spaces.
  109      * the format of a column definition is: name(type,attr).
  110      * between two column definitions must be a white space, e.g.,
  111        “first_name(str) last_name(str)”.
  112      * the type of a column can be:
  113           + int - integer numbers.
  114           + double - real numbers with two decimals.
  115           + str - strings with maximum size of 4KB.
  116      * a column can have one of the attributes:
  117           + auto - only for 'int' columns, the maximum value in
  118             that column is incremented and stored in this field if
  119             it is not provided in queries.
  120           + null - accept null values in column fields.
  121           + if no attribute is set, the fields of the column
  122             cannot have null value.
  123      * each other line is a row with data. The line ends with
  124        “\n”.
  125      * the fields are separated by “:”.
  126      * no value between two ':' (or between ':' and start/end of a
  127        row) means “null” value.
  128      * next characters must be escaped in strings: “\n”, “\r”,
  129        “\t”, “:”.
  130      * 0 -- the zero value must be escaped too.
  131 
  132    Example 1.1. Sample of a db_text table
  133 ...
  134 id(int,auto) name(str) flag(double) desc(str,null)
  135 1:nick:0.34:a\tgood\: friend
  136 2:cole:-3.75:colleague
  137 3:bob:2.50:
  138 ...
  139 
  140    Example 1.2. Minimal OpenSIPS location db_text table definition
  141 ...
  142 username(str) contact(str) expires(int) q(double) callid(str) cseq(int)
  143 ...
  144 
  145    Example 1.3. Minimal OpenSIPS subscriber db_text table example
  146 ...
  147 username(str) password(str) ha1(str) domain(str) ha1b(str)
  148 suser:supasswd:xxx:alpha.org:xxx
  149 ...
  150 
  151 1.1.3. Existing limitations
  152 
  153    This database interface don't support the data insertion with
  154    default values. All such values specified in the database
  155    template are ignored. So its advisable to specify all data for
  156    a column at insertion operations.
  157 
  158 1.2. Dependencies
  159 
  160 1.2.1. OpenSIPS modules
  161 
  162    The next modules must be loaded before this module:
  163      * none.
  164 
  165 1.2.2. External libraries or applications
  166 
  167    The next libraries or applications must be installed before
  168    running OpenSIPS with this module:
  169      * none.
  170 
  171 1.3. Exported Parameters
  172 
  173    None.
  174 
  175 1.3.1. db_mode (integer)
  176 
  177    Set caching mode (0) or non-caching mode (1). In caching mode,
  178    data is loaded at startup. In non-caching mode, the module
  179    check every time a table is requested whether the corresponding
  180    file on disk has changed, and if yes, will re-load table from
  181    file.
  182 
  183    Default value is “0”.
  184 
  185    Example 1.4. Set db_mode parameter
  186 ...
  187 modparam("db_text", "db_mode", 1)
  188 ...
  189 
  190 1.4. Exported Functions
  191 
  192    None.
  193 
  194 1.5. Exported MI Functions
  195 
  196 1.5.1. dbt_dump
  197 
  198    Write back to hard drive modified tables.
  199 
  200    Name: dbt_dump.
  201 
  202    Parameters: none
  203 
  204    MI FIFO Command Format:
  205 opensips-cli -x mi dbt_dump
  206 
  207 1.5.2. dbt_reload
  208 
  209    Causes db_text module to reload cached tables from disk.
  210    Depending on parameters it could be a whole cache or a
  211    specified database or a single table. If any table cannot be
  212    reloaded from disk - the old version preserved and error
  213    reported.
  214 
  215    Name: dbt_reload.
  216 
  217    Parameters:
  218      * db_name (optional) - database name to reload.
  219      * table_name (optional, but cannot be present without the
  220        db_name parameter) - specific table to reload.
  221 
  222    MI FIFO Command Format:
  223 opensips-cli -x mi dbt_reload
  224 
  225 opensips-cli -x mi dbt_reload /path/to/dbtext/database
  226 
  227 opensips-cli -x mi dbt_reload /path/to/dbtext/database table_name
  228 
  229 1.6. Installation and Running
  230 
  231    Compile the module and load it instead of mysql or other DB
  232    modules.
  233 
  234    REMINDER: when you use db_text in OpenSIPS, the database URL
  235    for modules must be the path to the directory where the
  236    table-files are located, prefixed by “text://”, e.g.,
  237    “text:///var/dbtext/opensips”. If there is no “/” after
  238    “text://” then “CFG_DIR/” is inserted at the beginning of the
  239    database path. So, either you provide an absolute path to
  240    database directory or a relative one to “CFG_DIR” directory.
  241 
  242    Example 1.5. Load the db_text module
  243 ...
  244 loadmodule "/path/to/opensips/modules/db_text.so"
  245 ...
  246 modparam("module_name", "database_URL", "text:///path/to/dbtext/database
  247 ")
  248 ...
  249 
  250 1.6.1. Using db_text with basic OpenSIPS configuration
  251 
  252    Here are the definitions for most important table as well as a
  253    basic configuration file to use db_text with OpenSIPS. The
  254    table structures may change in time and you will have to adjust
  255    next examples.
  256 
  257    You have to populate the table 'subscriber' by hand with user
  258    profiles in order to have authentication. To use with the given
  259    configuration file, the table files must be placed in the
  260    '/tmp/opensipsdb' directory.
  261 
  262    Example 1.6. Definition of 'subscriber' table (one line)
  263 ...
  264 username(str) domain(str) password(str) first_name(str) last_name(str) p
  265 hone(str) email_address(str) datetime_created(int) datetime_modified(int
  266 ) confirmation(str) flag(str) sendnotification(str) greeting(str) ha1(st
  267 r) ha1b(str) perms(str) allow_find(str) timezone(str,null) rpid(str,null
  268 )
  269 ...
  270 
  271    Example 1.7. Definition of 'location' and 'aliases' tables (one
  272    line)
  273 ...
  274 username(str) domain(str,null) contact(str,null) received(str) expires(i
  275 nt,null) q(double,null) callid(str,null) cseq(int,null) last_modified(st
  276 r) flags(int) user_agent(str) socket(str)
  277 ...
  278 
  279    Example 1.8. Definition of 'version' table and sample records
  280 ...
  281 table_name(str) table_version(int)
  282 subscriber:3
  283 location:6
  284 aliases:6
  285 ...
  286 
  287    Example 1.9. Configuration file
  288 ...
  289 #
  290 # simple quick-start config script with dbtext
  291 #
  292 
  293 # ----------- global configuration parameters ------------------------
  294 
  295 #debug_mode=yes
  296 children=4
  297 
  298 check_via=no    # (cmd. line: -v)
  299 dns=no          # (cmd. line: -r)
  300 rev_dns=no      # (cmd. line: -R)
  301 
  302 listen=udp:10.100.100.1:5060
  303 
  304 # ------------------ module loading ----------------------------------
  305 
  306 # use dbtext database
  307 loadmodule "modules/dbtext/dbtext.so"
  308 
  309 loadmodule "modules/sl/sl.so"
  310 loadmodule "modules/tm/tm.so"
  311 loadmodule "modules/rr/rr.so"
  312 loadmodule "modules/maxfwd/maxfwd.so"
  313 loadmodule "modules/usrloc/usrloc.so"
  314 loadmodule "modules/registrar/registrar.so"
  315 loadmodule "modules/textops/textops.so"
  316 loadmodule "modules/textops/mi_fifo.so"
  317 
  318 # modules for digest authentication
  319 loadmodule "modules/auth/auth.so"
  320 loadmodule "modules/auth_db/auth_db.so"
  321 
  322 # ----------------- setting module-specific parameters ---------------
  323 
  324 # -- mi_fifo params --
  325 
  326 modparam("mi_fifo", "fifo_name", "/tmp/opensips_fifo")
  327 
  328 # -- usrloc params --
  329 
  330 # use dbtext database for persistent storage
  331 modparam("usrloc", "db_mode", 2)
  332 modparam("usrloc|auth_db", "db_url", "text:///tmp/opensipsdb")
  333 
  334 # -- auth params --
  335 #
  336 modparam("auth_db", "calculate_ha1", 1)
  337 modparam("auth_db", "password_column", "password")
  338 modparam("auth_db", "user_column", "username")
  339 modparam("auth_db", "domain_column", "domain")
  340 
  341 # -------------------------  request routing logic -------------------
  342 
  343 # main routing logic
  344 
  345 route{
  346     # initial sanity checks -- messages with
  347     # max_forwards==0, or excessively long requests
  348     if (!mf_process_maxfwd_header("10")) {
  349         sl_send_reply("483","Too Many Hops");
  350         exit;
  351     };
  352     if ($ml >=  65535 ) {
  353         sl_send_reply("513", "Message too big");
  354         exit;
  355     };
  356 
  357     # we record-route all messages -- to make sure that
  358     # subsequent messages will go through our proxy; that's
  359     # particularly good if upstream and downstream entities
  360     # use different transport protocol
  361     if (!$rm=="REGISTER") record_route();
  362 
  363     # subsequent messages withing a dialog should take the
  364     # path determined by record-routing
  365     if (loose_route()) {
  366         # mark routing logic in request
  367         append_hf("P-hint: rr-enforced\r\n");
  368         route(1);
  369         exit;
  370     };
  371 
  372     if (!is_myself("$rd")) {
  373         # mark routing logic in request
  374         append_hf("P-hint: outbound\r\n");
  375         route(1);
  376         exit;
  377     };
  378 
  379     # if the request is for other domain use UsrLoc
  380     # (in case, it does not work, use the following command
  381     # with proper names and addresses in it)
  382     if (is_myself("$rd")) {
  383         if ($rm=="REGISTER") {
  384             # digest authentication
  385             if (!www_authorize("", "subscriber")) {
  386                 www_challenge("", "0");
  387                 exit;
  388             };
  389 
  390             save("location");
  391             exit;
  392         };
  393 
  394         lookup("aliases");
  395         if (!is_myself("$rd")) {
  396             append_hf("P-hint: outbound alias\r\n");
  397             route(1);
  398             exit;
  399         };
  400 
  401         # native SIP destinations are handled using our USRLOC DB
  402         if (!lookup("location")) {
  403             sl_send_reply("404", "Not Found");
  404             exit;
  405         };
  406     };
  407     append_hf("P-hint: usrloc applied\r\n");
  408     route(1);
  409 }
  410 
  411 route[1]
  412 {
  413     # send it out now; use stateful forwarding as it works reliably
  414     # even for UDP2TCP
  415     if (!t_relay()) {
  416         sl_reply_error();
  417     };
  418 }
  419 
  420 
  421 ...
  422 
  423 Chapter 2. Developer Guide
  424 
  425    Once you have the module loaded, you can use the API specified
  426    by OpenSIPS DB interface.
  427 
  428 Chapter 3. Contributors
  429 
  430 3.1. By Commit Statistics
  431 
  432    Table 3.1. Top contributors by DevScore^(1), authored
  433    commits^(2) and lines added/removed^(3)
  434      Name DevScore Commits Lines ++ Lines --
  435    1. Daniel-Constantin Mierla (@miconda) 134 59 6126 1441
  436    2. Bogdan-Andrei Iancu (@bogdan-iancu) 39 30 308 307
  437    3. Henning Westerholt (@henningw) 25 15 252 410
  438    4. Liviu Chircu (@liviuchircu) 16 13 39 90
  439    5. Razvan Crainea (@razvancrainea) 14 12 106 38
  440    6. Jan Janak (@janakj) 10 7 124 106
  441    7. Vlad Patrascu (@rvlad-patrascu) 7 5 76 49
  442    8. Ovidiu Sas (@ovidiusas) 7 5 61 8
  443    9. Sergey Khripchenko 5 2 185 2
  444    10. Jiri Kuthan (@jiriatipteldotorg) 4 2 8 6
  445 
  446    All remaining contributors: Ionut Ionita (@ionutrazvanionita),
  447    Konstantin Bokarius, Razvan Pistolea, Chris Heiser, Norman
  448    Brandinger (@NormB), Peter Lemenkov (@lemenkov), Edson Gellert
  449    Schubert, Dusan Klinec, Andrei Pelinescu-Onciul.
  450 
  451    (1) DevScore = author_commits + author_lines_added /
  452    (project_lines_added / project_commits) + author_lines_deleted
  453    / (project_lines_deleted / project_commits)
  454 
  455    (2) including any documentation-related commits, excluding
  456    merge commits. Regarding imported patches/code, we do our best
  457    to count the work on behalf of the proper owner, as per the
  458    "fix_authors" and "mod_renames" arrays in
  459    opensips/doc/build-contrib.sh. If you identify any
  460    patches/commits which do not get properly attributed to you,
  461    please submit a pull request which extends "fix_authors" and/or
  462    "mod_renames".
  463 
  464    (3) ignoring whitespace edits, renamed files and auto-generated
  465    files
  466 
  467 3.2. By Commit Activity
  468 
  469    Table 3.2. Most recently active contributors^(1) to this module
  470                       Name                   Commit Activity
  471    1.  Razvan Crainea (@razvancrainea)     Oct 2011 - Sep 2019
  472    2.  Liviu Chircu (@liviuchircu)         Mar 2014 - May 2019
  473    3.  Ovidiu Sas (@ovidiusas)             Dec 2012 - May 2019
  474    4.  Bogdan-Andrei Iancu (@bogdan-iancu) Nov 2003 - Apr 2019
  475    5.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
  476    6.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
  477    7.  Dusan Klinec                        Dec 2015 - Dec 2015
  478    8.  Sergey Khripchenko                  Aug 2015 - Aug 2015
  479    9.  Ionut Ionita (@ionutrazvanionita)   Jan 2015 - Feb 2015
  480    10. Razvan Pistolea                     Jul 2009 - Jul 2009
  481 
  482    All remaining contributors: Henning Westerholt (@henningw),
  483    Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Chris
  484    Heiser, Edson Gellert Schubert, Norman Brandinger (@NormB), Jan
  485    Janak (@janakj), Jiri Kuthan (@jiriatipteldotorg), Andrei
  486    Pelinescu-Onciul.
  487 
  488    (1) including any documentation-related commits, excluding
  489    merge commits
  490 
  491 Chapter 4. Documentation
  492 
  493 4.1. Contributors
  494 
  495    Last edited by: Razvan Crainea (@razvancrainea), Peter Lemenkov
  496    (@lemenkov), Liviu Chircu (@liviuchircu), Vlad Patrascu
  497    (@rvlad-patrascu), Bogdan-Andrei Iancu (@bogdan-iancu), Sergey
  498    Khripchenko, Ovidiu Sas (@ovidiusas), Daniel-Constantin Mierla
  499    (@miconda), Konstantin Bokarius, Edson Gellert Schubert,
  500    Henning Westerholt (@henningw).
  501 
  502    Documentation Copyrights:
  503 
  504    Copyright © 2003-2004 FhG FOKUS