FLATSTORE module

Admin Guide

Overview

Flatstore is one of so-called OpenSIPS 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 default by the | 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 OpenSIPS processes must have permissions to create files in that directory.

Name of files in that directory will follow the following pattern:

<prefix><table_name>[_<process_name>]<suffix>

For example, without setting any module parameter, the entries writen by OpenSIPS 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 OpenSIPS 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 OpenSIPS 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. Alternatively, you can use the single_file parameter, and all processes will dump the data into the same file. Note that this will induce some latency.

Rotating Log Files

There is a new OpenSIPS MI (management interface) command called flat_rotate. When OpenSIPS 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

At this point OpenSIPS will still be writing all data into the renamed files.

• Send OpenSIPS the MI command to close and reopen the renamed files. For example, using FIFO:

opensips-cli -x mi flat_rotate

This will force OpenSIPS 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 OpenSIPS 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.

Note

The suffix and prefix parameters are re-evaluated each time the flat_rotate command is issued. Therefore, after a rotate command, it is possible to open a different file than previous one.

• Move the renamed files somewhere else and process them.

Dependencies

OpenSIPS Modules

The following modules must be loaded before this module:

• No dependencies on other OpenSIPS modules.

External Libraries or Applications

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

• None.

Exported Parameters

flush (integer)

Enable or disable flushing after each write.

Default value is 1.

Set 'flush' parameter

...
modparam("db_flatstore", "flush", 0)
...

delimiter (char)

Delimiter used to separate the values.

Default value is ’|‘.

Set 'delimiter' parameter

...
modparam("db_flatstore", "delimiter", ";")
...

suffix (string)

The suffix appended to the table name. Can be a pseudo variable.

Default value is “.log”.

Set 'suffix' parameter

...
modparam("db_flatstore", "suffix", "$time(%H)")
...

prefix (string)

The table name prefix. Can be a pseudo variable.

Defaul value is none.

Set 'prefix' parameter

...
modparam("db_flatstore", "prefix", "$time(%H)")
...

single_file (integer)

Specifies if all the processes should dump the data into a single file.

Default value is 0.

Set 'single_file' parameter

...
modparam("db_flatstore", "single_file", 1)
...

Exported Functions

There are no function exported to routing script.

Exported MI Functions

flat_rotate

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

Name: flat_rotate

Parameters: none

MI FIFO Command Format:

opensips-cli -x mi flat_rotate

Developer Guide

The module implements the DB API.

Contributors

By Commit Statistics

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

#	Name	DevScore	Commits	Lines++	Lines—
1.	Henning Westerholt (@henningw)	45	6	1541	1552
2.	Bogdan-Andrei Iancu (@bogdan-iancu)	35	26	565	238
3.	Razvan Crainea (@razvancrainea)	18	11	493	111
4.	Liviu Chircu (@liviuchircu)	16	11	134	144
5.	Jan Janak (@janakj)	16	4	1237	25
6.	Daniel-Constantin Mierla (@miconda)	12	10	60	40
7.	Stefan Darius (@dariusstefan)	10	5	329	67
8.	Vlad Patrascu (@rvlad-patrascu)	6	4	34	41
9.	Elena-Ramona Modroiu	4	2	24	2
10.	Andrei Pelinescu-Onciul	3	1	29	3

All remaining contributors: Konstantin Bokarius, Razvan Pistolea, Peter Lemenkov (@lemenkov), Edson Gellert Schubert, Maksym Sobolyev (@sobomax).

(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)	Sep 2011 - Jun 2026
3.	Liviu Chircu (@liviuchircu)	Mar 2014 - May 2024
4.	Bogdan-Andrei Iancu (@bogdan-iancu)	Oct 2005 - Apr 2019
5.	Vlad Patrascu (@rvlad-patrascu)	May 2017 - Apr 2019
6.	Peter Lemenkov (@lemenkov)	Jun 2018 - Jun 2018
7.	Maksym Sobolyev (@sobomax)	Feb 2017 - Feb 2017
8.	Razvan Pistolea	Jul 2009 - Jul 2009
9.	Daniel-Constantin Mierla (@miconda)	Nov 2006 - Mar 2008
10.	Konstantin Bokarius	Mar 2008 - Mar 2008

All remaining contributors: Edson Gellert Schubert, Henning Westerholt (@henningw), Elena-Ramona Modroiu, Andrei Pelinescu-Onciul, Jan Janak (@janakj).

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

Documentation

Contributors

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

License

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