- improved documentation system

- documentation makefiles
- proper documentation dependency tracking in makefiles
- XML-based dialect of docbook used with xi:include inclusions

modules/db_flatstore/doc/Makefile

@@ -0,0 +1,29 @@
+#
+# The list of documents to build (without extensions)
+#
+DOCUMENTS = flatstore
+
+#
+# The root directory containing Makefile.doc
+#
+ROOT_DIR=../../..
+
+#
+# Validate docbook documents before generating output
+# (may be slow)
+#
+#VALIDATE=1
+
+#
+# You can override the stylesheet used to generate
+# xhtml documents here
+#
+#XHTML_XSL=$(ROOT_DIR)/doc/stylesheets/xhtml.xsl
+
+#
+# You can override the stylesheet used to generate
+# plain text documents here
+#
+#TXT_XSL=$(XHTML_XSL)
+
+include $(ROOT_DIR)/Makefile.doc

modules/db_flatstore/doc/flatstore.xml

@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<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>[email protected]</email>
+	    </author>
+	</authorgroup>
+	<copyright>
+	    <year>2004</year>
+	    <year>2005</year>
+	    <holder>FhG FOKUS</holder>
+	</copyright>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <title>Flatstore Module</title>
+
+    <section id="overview">
+	<title>Overview</title>
+	<para>
+	    Flatstore is one of so-called SER 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 |
+	    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 SER
+	    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 SER 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 SER 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 SER 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>
+		There is a new SER FIFO interface command called flat_rotate.
+		When SER 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 SER will still be writing all
+			data into the renamed files.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			Send SER the fifo command to close and reopen the
+			renamed files:
+			<screen>
+serctl fifo flat_rotate
+			</screen>
+			This will force SER 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 SER 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>
+		</listitem>
+		<listitem>
+		    <para>
+			Move the renamed files somewhere else and process them.
+		    </para>
+		</listitem>
+	    </itemizedlist>
+	</section>
+    </section>
+
+    <xi:include href="params.xml"/>
+
+</section>

modules/db_flatstore/doc/functions.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="flatstore.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <title>Functions</title>
+
+</section>

modules/db_flatstore/doc/params.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="flatstore.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <title>Parameters</title>
+
+    <section id="flush">
+	<title><varname>flush</varname> (integer)</title>
+	<para>
+	    Enable or disable flushing after each write.
+	</para>
+	<para>
+	    Default value is 1.
+	</para>
+    </section>
+</section>