Flatstore Module

Jan Janak

   FhG FOKUS

Edited by

Jan Janak

   Copyright  2004, 2005 FhG FOKUS
     __________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview

              1.1.1. Rotating Log Files

        1.2. Dependencies

              1.2.1. OpenSER Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. flush (integer)

        1.4. Exported Functions
        1.5. Exported MI Functions

              1.5.1. flat_rotate

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Set "flush" parameter
     __________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   Flatstore is one of so-called OpenSER database modules. It does
   not export any functions executable from the configuration
   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.

   The module does not export all functions of the database API,
   it supports only one function, insert. The module is limited
   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.

   The format of the files produced by this module is plain text.
   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.

   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
   the flatstore module and the flatstore module should create all
   files in /var/log/acc directory. The directory must exist and
   OpenSER processes must have permissions to create files in that
   directory.

   Name of files in that directory will follow the following
   pattern:
<table_name>_<process_name>.log

   For example, entries writen by OpenSER 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 OpenSER process that wrote
   some data into that table. The main reason why there are
   several files for each table is that it is much faster to have
   one file per process, because it does not require any locking
   and thus OpenSER processes will not block each other. To get
   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

   There is a new OpenSER MI (management interface) command called
   flat_rotate. When OpenSER receives the command then it will
   close and reopen all files used by flatstore module. The
   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
...

       Note that at this point OpenSER will still be writing all
       data into the renamed files.
     * Send OpenSER the MI command to close and reopen the renamed
       files. For example, using FIFO:
openserctl fifo flat_rotate

       This will force OpenSER 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 OpenSER has some data to
       write. It is normal that the files will be not created
       immediately if there is no traffic on the proxy server.
     * Move the renamed files somewhere else and process them.
     __________________________________________________________

1.2. Dependencies

1.2.1. OpenSER Modules

   The following modules must be loaded before this module:

     * No dependencies on other OpenSER modules.
     __________________________________________________________

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSER with this module loaded:

     * None.
     __________________________________________________________

1.3. Exported Parameters

1.3.1. flush (integer)

   Enable or disable flushing after each write.

   Default value is 1.

   Example 1-1. Set "flush" parameter
...
modparam("flatstore", "flush", 0)
...
     __________________________________________________________

1.4. Exported Functions

   There are no function exported to routing script.
     __________________________________________________________

1.5. Exported MI Functions

1.5.1. flat_rotate

   It changes the name of the files where it is written.

   Name: flat_rotate

   Parameters: none

   MI FIFO Command Format:
                :flat_rotate:_reply_fifo_file_
                _empty_line_
     __________________________________________________________

Chapter 2. Developer's Guide

   The module implements the DB API.
     __________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about OpenSER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on one
   of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.
