<?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/07/28</emphasis>:

     <emphasis>sonews/1.0.0</emphasis>

     (<ulink url="files/sonews-1.0.0.tar.bz2">binary tarball</ulink>,

     <ulink url="files/sonews-1.0.0-src.tar.bz2">source tarball</ulink>) new major release.

     A lot of refactoring was done to make the code more robust and 

     maintainable. Of course, several bugs were fixed, too ;)

     The 0.5.x line moves from unstable to testing in the DEB repository although

     the 1.0.x seems no less stable. If in doubt choose 1.0.x.

   </para>

   <para>

     <emphasis role="bold">2009/07/01</emphasis>:

     <emphasis>sonews/0.5.1</emphasis>

     (<ulink url="files/sonews-0.5.1.tar.bz2">binary tarball</ulink>,

     <ulink url="files/sonews-0.5.1-src.tar.bz2">source tarball</ulink>) bugfix

     release.

     Broken Cancel-mechanism and broken buildscript fixed.

     See <ulink url="http://code.xerxys.info:8000/hgwebdir.cgi/sonews-0.5/log/287">

       changelog</ulink> for more details.

   </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>

         <para>

         For sonews/1.1.x a plugin API for storage backends and command handlers

         is planned. 

         See <ulink url="http://bugs.xerxys.info/">Bugtracker</ulink> for

         issues with target sonews/1.1.x.

         </para>

     </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/ testing main # for sonews/0.5.x</screen>

         <screen>deb http://packages.xerxys.info/debian/ unstable main # for sonews/1.0.x</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 high traffic 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.

               It is highly recommended to set sonews.hostname to the full

               qualified domain name (FQDN) of the host machine.

             </para>

           </listitem>

         </varlistentry>

         <varlistentry>

           <term>&lsquo;<literal>sonews.timeout</literal>&rsquo;</term>

           <listitem>

             <para>

               Socket timeout for client connections in seconds. Default as

               recommended in RFC3977 is 180 seconds.

             </para>

           </listitem>

         </varlistentry>

         <varlistentry>

           <term>&lsquo;<literal>sonews.port</literal>&rsquo;</term>

           <listitem>

             <para>

               Listening port of sonews daemon. This value can be overridden

               with the -p command line argument.

             </para>

           </listitem>

         </varlistentry>

         <varlistentry>

           <term>&lsquo;<literal>sonews.xdaemon.host</literal>&rsquo;</term>

           <listitem>

             <para>

               Hostname or IP address of the client machine that is allowed to

               use the XDAEMON command. Default: localhost

             </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         <path to config file> 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>

     <sect1 label="3.4">

       <title>Newsgroup configuration</title>

       <para>

         Currently some manual work is necessary to create a newsgroup hosted

         by a sonews instance.

       </para>

       <para>

         One possibility is to talk via Telnet to the sonews instance and

         use the non-standard command XDAEMON.

       <screen>telnet localhost 119</screen>

       <screen>XDAEMON GROUPADD local.test 0</screen>

       Please note that the XDAEMON command has restricted access and is only

       available via local connections (default, can be changed with config

       value sonews.xdaemon.host).

       </para>

       <para>

         You can also use the web interface to create newsgroups.

       </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/ 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 <pid>"

 but send a SIGQUIT signal with "kill -3 <pid>" 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>