kamailio/modules/db_flatstore/doc/db_flatstore.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;

]>

<section id="flatstore" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
	<authorgroup>
	    <author>
		<firstname>Jan</firstname>
		<surname>Janak</surname>
		<affiliation><orgname>FhG FOKUS</orgname></affiliation>
		<email>jan@iptel.org</email>
	    </author>
	</authorgroup>
	<copyright>
	    <year>2004</year>
	    <year>2005</year>
	    <holder>FhG FOKUS</holder>
	</copyright>
    </sectioninfo>

    <title>Db_flatstore Module</title>

    <section id="flatstore.overview">
	<title>Overview</title>
	<para>
	    Db_flatstore is one of so-called &siprouter; 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 modules can use it as a database driver, instead of, for
	    example, the Mysql module.
	</para>
	<para>
	    The module does not implement all functions of the database API, it
	    supports only one function, insert. This means that 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. Please note that the acc module is the only module that
	    was tested with the flastore module.
	</para>
	<para>
	    The format of the files produced by this module is plain text. Each
	    line consists of several fields, fields are separated by the "|"
	    character (vertical bar). New information is always appended at the end 
	    of the file. <emphasis>Searching, deleting and updating of existing data is not
	    supported by the module</emphasis>.
	</para>
	<para>
	    The acc module can be configured to use db_flatstore module as
	    database backend using the db_url_parameter:
	</para>
	<programlisting>
modparam("acc", "db_url", "flatstore:/var/log/acc")
	</programlisting>
	<para>
	    This configuration option tells the acc module that it should use the
	    db_flatstore module and the db_flatstore module should create all files
	    in the /var/log/acc directory. The directory must exist and &siprouter;
	    processes must have permissions to create files in that directory.
	</para>
	<para>
	    Name of files in that directory will follow the following pattern:
	</para>
	<programlisting>
&lt;table_name&gt;_&lt;process_name&gt;.log
	</programlisting>
	<para>
	    For example, entries writen by the &siprouter; process 8 into the acc
	    table would be written in file acc_8.log. For each table there will be 
	    several files, one file for every &siprouter; 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 &siprouter; 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.
	</para>
	<section id="rotating">
	    <title>Rotating Log Files</title>
	    <para>
		The module implements a &siprouter; management interface command called
	        flatstore.rotate. When &siprouter; receives the command it will
		close and reopen all files used by the db_flatstore module. 
		The rotation itself has to be done by another application 
		(such as logrotate). Follow these steps to rotate files generated by 
		the db_flatstore module:
	    </para>
	    <itemizedlist>
		<listitem>
		    <para>
			Rename the files that you want to rotate:
			<screen>
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
...
			</screen>
			Note that at this point &siprouter; will still be writing all
			data into the renamed files.
		    </para>
		</listitem>
		<listitem>
		    <para>
			Send &siprouter; the management command to close and reopen the
			renamed files:
			<screen>
&sercmd; flatstore.rotate
			</screen>
			This will force &siprouter; to close the renamed files and open
			new ones with original names, such as
			<filename>acc_1.log</filename>. New files will be open
			at the point when &siprouter; has some data to write. It is
			normal that the files will be not created immediately
			if there is no traffic on the SIP server.
		    </para>
		</listitem>
		<listitem>
		    <para>
			Move the renamed files somewhere else and process them.
		    </para>
		</listitem>
	    </itemizedlist>
	</section>
    </section>

    <xi:include href="params.xml"/>

</section>