diff -r 000000000000 -r 6fceb66e1ad7 doc/sonews.xml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/sonews.xml	Fri Jun 26 16:48:50 2009 +0200
@@ -0,0 +1,254 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+  <!ENTITY tex "TeX">
+  <!ENTITY latex "LaTeX">
+]>
+<book id="sonews.xml" lang="en">
+  <title>sonews Usenet News Server</title>
+  <para>
+    <emphasis role="bold">sonews</emphasis> is NNTP server than can provide 
+    access to both local and global Usenets newsgroups. It is written in 
+    <ulink url="http://java.sun.com/">Java</ulink> and uses a relational
+    database as backend.
+  </para>
+  <para>
+    <emphasis role="bold">2009/06/29</emphasis>: 
+    <emphasis>sonews/0.5.0</emphasis> 
+    (<ulink url="files/sonews-0.5.0.tar.bz2">binary tarball</ulink>,
+    <ulink url="files/sonews-0.5.0-src.tar.bz2">source tarball</ulink>) final 
+    released. 
+    The setup is a little clumsy but the software is stable and works well.
+  </para>
+  
+  <chapter>
+    <title>Introduction</title>
+    <para>sonews is a RCF3977 compliant NNTP Usenet server. 
+    It is written in Java and uses a relation database management system
+    (RDBMS) as backend (currently
+    <ulink url="http://www.postgresql.com/">PostgreSQL</ulink> and
+    <ulink url="http://www.mysql.com/">MySQL</ulink>).
+    sonews is highly multithreaded and uses Java NIO asynchronous sockets
+    to handle thousands of concurrent connections.</para>
+    <para>sonews is Free and Open Source Software (FOSS) licensed under the 
+    terms of the
+    <ulink url="http://www.gnu.org/licenses/gpl.html">GNU General Public License</ulink>
+    Version 3 (or later).</para>
+
+    <sect1 label="1.1">
+      <title>History</title>
+      <para>Ancestor of sonews is probably the Neat NNTP Daemon (n3tpd) 
+      although there is very little code in sonews that can be identified
+      as direct derivation.
+      sonews was developed as diploma thesis project of Christian Lins at
+      <ulink url="http://de.sun.com/">StarOffice development</ulink>
+      in Hamburg and is now a Free Software project.</para>
+    </sect1>
+
+    <sect1 label="1.2">
+      <title>Roadmap</title>
+      <sect2 label="1.2.1">
+        <title>sonews/0.6</title>
+        <para>Planned to implement the XPAT command for searching, correctly 
+        hashed Message-Ids and a news purging command.
+        See <ulink url="http://bugs.xerxys.info/">Bugtracker</ulink> for
+        issues with target sonews/0.6.x.</para>
+      </sect2>
+    </sect1>
+  </chapter>
+
+  <chapter label="2">
+    <title>Installation and initial setup</title>
+    <sect1 label="2.1">
+      <title>Download &amp; Installation</title>
+      <sect2 label="2.1.1">
+        <title>Debian based systems</title>
+        <para>You can install sonews with 
+        <ulink url="http://www.debian.org/doc/manuals/apt-howto/">APT</ulink>
+        easily.
+        Add the following line to /etc/apt/sources.list:</para>
+        <screen>deb http://packages.xerxys.info/debian/ unstable main
+        </screen>
+        <para>And add the GPG-Key for package authentification, see 
+        <ulink url="http://packages.xerxys.info/debian/">Xerxys Debian Repository</ulink>
+        for more details.</para>
+        <para>Then force an update of your local package list:</para>
+        <screen># apt-get update
+</screen>
+        <para>To install sonews and all prerequisites issue the following command:</para>
+        <screen># apt-get install sonews
+        </screen>
+        <para>This method should work for all recent Debian-based distributions
+(<ulink url="http://www.debian.org/">Debian</ulink>, <ulink url="http://www.ubuntu.com/">Ubuntu</ulink>, etc.).</para>
+      </sect2>
+
+      <sect2 label="2.1.2">
+        <title>Other *nix systems</title>
+        <para>See <ulink url="files/">Files Section</ulink> for recent binary and source tarballs.</para>
+        <para>Use the binary archive and extract it in a directory of your choice. Make sure your system
+provides the necessary prerequisites:</para>
+        <itemizedlist>
+          <listitem>
+            <para>Java6 compatible runtime (JRE)</para>
+          </listitem>
+          <listitem>
+            <para>Java Mail API implementation, e.g. <ulink url="http://java.sun.com/products/javamail/">Sun Java Mail</ulink>.
+GNU JavaMail has a broken POP3 Provider and does not work with sonews.</para>
+          </listitem>
+          <listitem>
+            <para>JSP Servlet Container (e.g. 
+            <ulink url="http://kitten.sonews.org/">Kitten</ulink>) [optional]</para>
+          </listitem>
+        </itemizedlist>
+      </sect2>
+    </sect1>
+
+    <sect1 label="2.2">
+      <title>Initial database setup</title>
+      <para>Before you start sonews, you must prepare the database. Currently sonews is known
+to work with PostgreSQL and MySQL.</para>
+      <para>It is highly recommended to create an own database for every sonews instance, e.g.
+called 'sonews'. Additionally, it is recommended to create a unique database user
+for sonews, e.g. 'sonewsuser'. Please do not use the root user for sonews!
+The sonews user needs rights for SELECT, INSERT and UPDATE statements.
+Refer to the database's manual for instructions.</para>
+      <para>You will find the SQL Schema definitions in the helpers subdirectory of
+the source and binary distributions. You can create the tables manually using
+this templates or you can use the setup helper:</para>
+      <screen>user@debian$ sonews setup
+</screen>
+      <para>or on other *nix systems:</para>
+      <screen>user@nix$ java -jar sonews.jar org.sonews.util.DatabaseSetup
+</screen>
+      <para>The tool will ask for some information about your database environment,
+connect to the database, create the tables and creates a default bootstrap
+config file called sonews.conf.</para>
+    </sect1>
+  </chapter>
+
+  <chapter label="3">
+    <title>Running sonews</title>
+    <sect1 label="3.1">
+      <title>Configuration</title>
+      <para>There is a bootstrap configuration in /etc/sonews/sonews.conf and a regular configuration
+in the database table config.</para>
+      <para>There are various configuration values that can be adapted:</para>
+      <variablelist>
+        <varlistentry>
+          <term>&lsquo;<literal>sonews.article.maxsize</literal>&rsquo;</term>
+          <listitem>
+            <para>Maximum allowed body size of a news message given in kilobytes. Please note that
+for MySQL the &lsquo;<literal>max_allowed_packet</literal>&rsquo; configuration variable must
+be set to a value higher than &lsquo;<literal>sonews.article.maxsize</literal>&rsquo; otherwise posting
+of large mails will fail.</para>
+          </listitem>
+        </varlistentry>
+          <varlistentry>
+          <term>&lsquo;<literal>sonews.debug</literal>&rsquo;</term>
+          <listitem>
+            <para>
+            If set to true every(!) data going through sonews' socket
+            is written to sonews.log. After a night the logfile can be
+            several gigabytes large, so be careful with this setting.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>&lsquo;<literal>sonews.hostname</literal>&rsquo;</term>
+          <listitem>
+            <para>Canonical name of the server instance. This variable is part of the server's
+hello message to the client and used to generate Message-Ids.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>&lsquo;<literal>sonews.timeout</literal>&rsquo;</term>
+          <listitem>
+            <para>Socket timeout for client connections in seconds.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>&lsquo;<literal>sonews.port</literal>&rsquo;</term>
+          <listitem>
+            <para>Listening port of sonews daemon.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect1>
+
+    <sect1 label="3.2">
+      <title>Command line arguments</title>
+      <para>If you like to start sonews directly, you can use one of the following
+arguments:</para>
+      <screen>java -jar sonews.jar [arguments]
+        where arguments:
+    -c|-config         &lt;path to config file&gt; if custom config file preferred
+    -dumpjdbcdriver    Prints out a list of available JDBC drivers
+    -feed              Enables feed daemon for pulling news from peer servers
+    -h|-help           This output
+    -mlgw              Enables the Mailinglist Gateway poller
+    -p portnumber      Port on which sonews is listening for incoming connections.
+                       Overrides port settings in config file and database.
+
+</screen>
+    </sect1>
+
+    <sect1 label="3.3">
+      <title>Webinterface</title>
+      <para>The package sonews-web provides an optional webinterface that can be used to
+review statistical information and configuration values of sonews.</para>
+      <screen>sonews-web start|stop
+</screen>
+      <para>The webinterface uses the the lightweight Servlet Container Kitten and is
+per default listening on HTTP-Port 8080 (go to http://localhost:8080/sonews).</para>
+    </sect1>
+  </chapter>
+
+  <chapter label="4">
+    <title>Development</title>
+    <para>You're welcome to create patches with bugfixes or additional features. The
+Mercurial DSCM makes this step an easy task.</para>
+    <para>Just clone the public <ulink url="http://www.selenic.com/mercurial/">Mercurial</ulink> repository:</para>
+    <screen>hg clone http://code.xerxys.info:8000/hg/sonews/trunk sonews-trunk
+</screen>
+    <para>Then make your changes, create a bundle of changesets and send this to me via email.
+Or ask for push access to the public repository.</para>
+    <para>
+        There is a nightly generated <ulink url="apidoc/">Javadoc API documentation</ulink> that will help
+        you to get in touch with the sonews source.
+    </para>
+    <para>Some debugging hints: if the server blocks and does not longer respond you
+probably found a deadlock. Do not kill the process with "kill -9 &lt;pid&gt;"
+but send a SIGQUIT signal with "kill -3 &lt;pid&gt;" and the Java VM will output
+a stracktrace of all threads. This output is the most valuable information to
+fix the deadlock.</para>
+
+    <sect1 label="4.1">
+      <title>Contributors</title>
+      <para>Maintainer and project lead:
+Christian Lins (contact christian.lins (at) fh-osnabrueck.de)</para>
+    </sect1>
+
+    <sect1 label="4.2">
+      <title>Sponsors</title>
+      <para>The author thanks <ulink url="http://www.sun.com/">Sun Microsystems</ulink> for fully
+financing the first version of sonews. A really free software supporting company!</para>
+      <para>If you like to support sonews with a donation of any kind (hardware, books, money, donuts,...),
+ feel free to contact the project leader.
+A friendly email or a bug report is most welcome, too :-)</para>
+    </sect1>
+  </chapter>
+
+  <chapter label="5">
+    <title>Links and further information</title>
+    <itemizedlist>
+      <listitem>
+        <para><ulink url="http://bugs.xerxys.info/">Bugtracker</ulink>, register necessary, see project 'sonews'.</para>
+      </listitem>
+      <listitem>
+        <para><ulink url="http://www.sun.com/">Sun Microsystems</ulink>, friendly sponsor.</para>
+      </listitem>
+      <listitem>
+        <para><ulink url="http://www.fh-osnabrueck">University of Applied Sciences Osnabrueck</ulink></para>
+      </listitem>
+    </itemizedlist>
+  </chapter>
+</book>