(1.0.D003) Design documentation

diff --git a/doc/design.xml b/doc/design.xml
new file mode 100644 (file)
index 0000000..f14ef8f
--- /dev/null
+++ b/doc/design.xml
@@ -0,0 +1,193 @@
+<?xml version="1.0"?>
+<!DOCTYPE doc SYSTEM "/usr/local/xslt/doc.dtd">
+<?xml-stylesheet type="text/xsl" href="/usr/local/xslt/html.xsl"?>
+<doc style="main.css">
+
+<!--
+      XML documentation system
+      Original author :  Arjen Baart - arjen@andromeda.nl
+      Version         : $Revision: 1.1 $
+
+      This document is prepared for XMLDoc. Transform to HTML,
+      LaTeX, Postscript or plain text with XMLDoc utilities and
+      XSLT sheets from http://www.andromeda.nl/projects/xmldoc/
+-->
+
+<book>
+<titlepage>
+   <title>Gnucomo - Computer Monitoring</title>
+   <author>Arjen Baart <code>&lt;arjen@andromeda.nl&gt;</code></author>
+   <author>Brenno de Winter<code>&lt;brenno@dewinter.com&gt;</code></author>
+   <date>July 12, 2002</date>
+   <docinfo>
+      <infoitem label="Version">0.1</infoitem>
+      <infoitem label="Organization">Andromeda Technology &amp; Automation</infoitem>
+      <infoitem label="Organization">De Winter Information Solutions</infoitem>
+   </docinfo>
+   <abstract>
+   </abstract>
+</titlepage>
+
+<toc/>
+
+<chapter>
+<heading>Introduction</heading>
+
+<para>
+<strong>Gnucomo</strong> is a system to monitor computer systems.
+This document describes the design of the <strong>Gnucomo</strong> applications
+and is based upon the development manifest.
+</para>
+
+</chapter>
+
+<chapter>
+<heading>Architecture</heading>
+
+<para>
+The architecture of <strong>gnucomo</strong> is shown in the
+dataflow diagram below:
+</para>
+
+<para>
+   <picture src='dataflow.png' eps='dataflow.eps'/>
+</para>
+
+<para>
+Architectural items to consider:
+<itemize>
+<item>Active and passive data aquisition</item>
+<item>Monitoring static and dynamic system parameters</item>
+<item>Upper and lower limits for system parameters</item>
+</itemize>
+</para>
+
+<para>
+Existing log analysis tools: logwatch, analog.
+</para>
+</chapter>
+
+<chapter>
+<heading>System design</heading>
+
+<para>
+<strong>Gnucomo</strong> is a collection of different application programs,
+rather than a single application.
+All these application programs revolve around the <strong>Gnucomo</strong>
+database as described in the manifest.
+</para>
+
+<section>
+<heading>Database design</heading>
+
+<para>
+Log entries are stored in a database with at least the following fields:
+<itemize>
+<item>hostname</item>
+<item>timestamp</item>
+<item>service (kernel, daemon, ...)</item>
+<item>Log message</item>
+</itemize>
+</para>
+</section>
+
+<section>
+<heading>Configuration</heading>
+
+<para>
+Configurational parameters are stored in a XML formatted configuration file.
+The config file contains a two-level hierarchy.
+The first level denotes the section for which the parameter is used
+and the second level is the parameter itself.
+Both sections and parameters are elements in XML terminology.
+The top-level (root) element is the configuration tree itself.
+The root element must have the same name as the application's name
+for which the configuration is intended.
+The level-1 elements are sections of the configuration tree.
+Within these section elements, the configuration has several parameter elements.
+Each parameter is an element by itself.
+The element's name is the name of the parameter, just as a section
+element's name is the name of the section.
+The content of the parameter element is the value of the parameter.
+Attributes in either section elements or parameter elements are not used.
+</para>
+<para>
+The configuration file is located in two places.
+The is a system wide configuration in
+<code>/usr/local/etc/gnucomo.conf</code> and each user may
+have his or her own configuration in <code>~/.gnucomo.conf</code>.
+The value of a user-specific configuration parameter overrides
+the system-wide value.
+</para>
+<para>
+At the moment, the gnucomo configuration has one section, holding
+four parameters which define how to access the gnucomo database:
+<itemize>
+<item>type</item>
+<item>name</item>
+<item>user</item>
+<item>password</item>
+</itemize>
+
+The <emph>type</emph> parameter must have the content <code>PostgreSQL</code>.
+Other database systems are not supported yet.
+</para>
+
+<subsection>
+<heading>gnucomo_config class</heading>
+
+<para>
+Each Gnucomo application should have exectly one object of the
+<strong>gnucomo_config</strong> to obtain its configurational
+parameters.
+The following methods are supported in this class:
+
+<itemize>
+
+<item>
+  read(String name)
+  <para>
+  Reads the XML formatted configuration files from
+  <code>/usr/local/etc/&lt;name&gt;.conf</code> and
+  <code>~/.&lt;name&gt;.conf</code>.
+  </para>
+</item>
+
+<item>
+  String find_parameter(String section, String param)
+  <para>
+  Return the value of the parameter <emph>param</emph> in
+  section <emph>section</emph>.
+  </para>
+</item>
+
+<item>
+  String Database()
+  <para>
+  Return the database access string to be used for the PgDatabase constructor.
+  </para>
+</item>
+
+</itemize>
+</para>
+
+</subsection>
+</section>
+
+<section>
+<heading>Design ideas</heading>
+
+<para>
+Use of a neural network to analyse system logs:
+<itemize>
+<item>Classify words</item>
+<item>Classify message based on word classification</item>
+</itemize>
+</para>
+
+</section>
+
+</chapter>
+
+</book>
+</doc>

diff --git a/test/t0003a.sh b/test/t0003a.sh
new file mode 100644 (file)
index 0000000..ef44ed0
--- /dev/null
+++ b/test/t0003a.sh
@@ -0,0 +1 @@
+xmllint --noout --valid doc/design.xml