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

      <sect2 label="1.2.1">

        <title>sonews/1.0</title>

        <para>

        Various minor fixes and code cleanup (Storage and Command interface for

        the upcoming Plugin API).

        </para>

        <para>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/1.0.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 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>