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