<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		Flatstore is one of so-called &osips; 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.
	</para>
	<para>
		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.
	</para>
	<para>
		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.
	</para>
	<para>
		The acc module can be configured to use flatstore module as
		database backend using the db_url_parameter:
	</para>
	<programlisting>
modparam("acc", "db_url", "flatstore:/var/log/acc")
</programlisting>
	<para>
		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 &osips;
		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;prefix&gt;&lt;table_name&gt;[_&lt;process_name&gt;]&lt;suffix&gt;
</programlisting>
	<para>
		For example, without setting any module parameter, the
		entries writen by &osips; 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 &osips; 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 &osips; 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.
	</para>

	<section id="rotating">
		<title>Rotating Log Files</title>
		<para>
		There is a new &osips; MI (management interface) command called 
		flat_rotate.
		When &osips; 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:
		</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 &osips; will still be writing all
			data into the renamed files.
			</para>
		</listitem>
		<listitem>
			<para>
			Send &osips; the MI command to close and reopen the
			renamed files. For example, using FIFO:
			<screen>
opensips-cli -x mi flat_rotate
			</screen>
			This will force &osips; 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 &osips; 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.
			</para>
			<para>
			Note that 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.
			</para>
		</listitem>
		<listitem>
			<para>
			Move the renamed files somewhere else and process them.
			</para>
		</listitem>
		</itemizedlist>
	</section>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following  modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &osips; modules</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_flush" xreflabel="flush">
		<title><varname>flush</varname> (integer)</title>
		<para>
		Enable or disable flushing after each write.
		</para>
		<para>
		<emphasis>
			Default value is 1.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>flush</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_flatstore", "flush", 0)
...
</programlisting>
		</example>
	</section>
	<section id="param_delimiter" xreflabel="delimiter">
		<title><varname>delimiter</varname> (char)</title>
		<para>
		Delimiter used to separate the values.
		</para>
		<para>
		<emphasis>
			Default value is '|'.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>delimiter</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_flatstore", "delimiter", ";")
...
</programlisting>
		</example>
	</section>
	<section id="param_suffix" xreflabel="suffix">
		<title><varname>suffix</varname> (string)</title>
		<para>
		The suffix appended to the table name. Can be a pseudo
		variable.
		</para>
		<para>
		<emphasis>
			Default value is ".log".
		</emphasis>
		</para>
		<example>
		<title>Set <quote>suffix</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_flatstore", "suffix", "$time(%H)")
...
</programlisting>
		</example>
	</section>
	<section id="param_prefix" xreflabel="prefix">
		<title><varname>prefix</varname> (string)</title>
		<para>
		The table name prefix. Can be a pseudo variable.
		</para>
		<para>
		<emphasis>
			Defaul value is none.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>prefix</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_flatstore", "prefix", "$time(%H)")
...
</programlisting>
		</example>
	</section>
	<section id="param_single_file" xreflabel="single_file">
		<title><varname>single_file</varname> (integer)</title>
		<para>
		Specifies if all the processes should dump the data
		into a single file.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <quote>single_file</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("db_flatstore", "single_file", 1)
...
</programlisting>
		</example>
	</section>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<para>
	There are no function exported to routing script.
	</para>
	</section>
	
	<section id="exported_mi_functions" xreflabel="Exported MI Functions">
	<title>Exported MI Functions</title>
	<section id="mi_flat_rotate" xreflabel="flat_rotate">
		<title>
		<function moreinfo="none">flat_rotate</function>
		</title>
		<para>
		It changes the name of the files where it is written.
		</para>
		<para>
		Name: <emphasis>flat_rotate</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		opensips-cli -x mi flat_rotate
		</programlisting>
	</section>	
    </section>
</chapter>

