modules_k/db_flatstore/README
ac1ffec9
 Flatstore Module
 
 Jan Janak
 
    FhG FOKUS
 
 Edited by
 
 Jan Janak
 
    Copyright � 2004, 2005 FhG FOKUS
d77df08a
    Revision History
37e4f522
    Revision $Revision$ $Date: 2008-03-19 20:31:30 +0100
                               (Mi, 19 Mär 2008) $
719e7b81
      __________________________________________________________
ac1ffec9
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
ac1ffec9
 
         1.1. Overview
 
               1.1.1. Rotating Log Files
 
         1.2. Dependencies
 
37e4f522
               1.2.1. Kamailio Modules
ac1ffec9
               1.2.2. External Libraries or Applications
 
         1.3. Exported Parameters
 
               1.3.1. flush (integer)
 
         1.4. Exported Functions
e5495f50
         1.5. Exported MI Functions
 
231d507f
               1.5.1. flat_rotate
ac1ffec9
 
9fc784c6
    2. Developer Guide
ac1ffec9
 
    List of Examples
d77df08a
 
    1.1. Set "flush" parameter
ac1ffec9
 
9fc784c6
 Chapter 1. Admin Guide
ac1ffec9
 
 1.1. Overview
 
37e4f522
    Flatstore is one of so-called Kamailio database modules. It
    does not export any functions executable from the configuration
719e7b81
    scripts, but it exports a subset of functions from the database
    API and thus other module can use it instead of, for example,
    mysql module.
ac1ffec9
 
    The module does not export all functions of the database API,
    it supports only one function, insert. The module is limited
719e7b81
    but very fast. It is especially suitable for storing accounting
    information on sites with extremely high traffic. If MySQL is
    too slow or if you get a huge amount of accounting data then
    you can consider using this module. Note that the acc module is
    the only module that was tested with flastore.
ac1ffec9
 
    The format of the files produced by this module is plain text.
719e7b81
    Each line consists of several fields, fields are separated by |
    character. New information is always appended at the end of the
    file, searching, deleting and updating of existing data is not
    supported by the module.
ac1ffec9
 
    The acc module can be configured to use flatstore module as
    database backend using the db_url_parameter:
 modparam("acc", "db_url", "flatstore:/var/log/acc")
 
    This configuration options tells acc module that it should use
719e7b81
    the flatstore module and the flatstore module should create all
    files in /var/log/acc directory. The directory must exist and
37e4f522
    Kamailio processes must have permissions to create files in
    that directory.
ac1ffec9
 
    Name of files in that directory will follow the following
    pattern:
 <table_name>_<process_name>.log
 
37e4f522
    For example, entries writen by Kamailio process 8 into acc
    table would be written in file acc_8.log. For each table there
    will be several files, one file for every Kamailio process that
    wrote some data into that table. The main reason why there are
ac1ffec9
    several files for each table is that it is much faster to have
    one file per process, because it does not require any locking
37e4f522
    and thus Kamailio processes will not block each other. To get
ac1ffec9
    the complete data for a table you can simply concatenate the
    contents of files with the same table name but different
    process id.
 
 1.1.1. Rotating Log Files
 
37e4f522
    There is a new Kamailio MI (management interface) command
    called flat_rotate. When Kamailio receives the command then it
    will close and reopen all files used by flatstore module. The
ac1ffec9
    rotation itself has to be done by another application (such as
    logrotate). Follow these steps to rotate files generated by
    flatstore module:
      * Rename the files that you want to rotate:
 cd /var/log/acc
 mv acc_1.log acc_1.log.20050605
 mv acc_2.log acc_2.log.20050605
 mv acc_4.log acc_3.log.20050605
 ...
719e7b81
 
37e4f522
        Note that at this point Kamailio will still be writing all
719e7b81
        data into the renamed files.
37e4f522
      * Send Kamailio the MI command to close and reopen the
        renamed files. For example, using FIFO:
bb30e4a8
 kamctl fifo flat_rotate
719e7b81
 
37e4f522
        This will force Kamailio to close the renamed files and
        open new ones with original names, such as acc_1.log. New
        files will be open at the point when Kamailio has some data
        to write. It is normal that the files will be not created
719e7b81
        immediately if there is no traffic on the proxy server.
ac1ffec9
      * Move the renamed files somewhere else and process them.
 
 1.2. Dependencies
 
37e4f522
 1.2.1. Kamailio Modules
ac1ffec9
 
    The following modules must be loaded before this module:
37e4f522
      * No dependencies on other Kamailio modules.
ac1ffec9
 
 1.2.2. External Libraries or Applications
 
    The following libraries or applications must be installed
37e4f522
    before running Kamailio with this module loaded:
ac1ffec9
      * None.
 
 1.3. Exported Parameters
 
 1.3.1. flush (integer)
 
    Enable or disable flushing after each write.
 
719e7b81
    Default value is 1.
ac1ffec9
 
d77df08a
    Example 1.1. Set "flush" parameter
ac1ffec9
 ...
3d2dc1df
 modparam("db_flatstore", "flush", 0)
ac1ffec9
 ...
 
 1.4. Exported Functions
 
    There are no function exported to routing script.
 
e5495f50
 1.5. Exported MI Functions
 
d77df08a
 1.5.1.  flat_rotate
e5495f50
 
    It changes the name of the files where it is written.
231d507f
 
    Name: flat_rotate
 
    Parameters: none
 
    MI FIFO Command Format:
                 :flat_rotate:_reply_fifo_file_
                 _empty_line_
e5495f50
 
9fc784c6
 Chapter 2. Developer Guide
ac1ffec9
 
    The module implements the DB API.