doc/sonews.xml
author chris <chris@marvin>
Thu, 06 Aug 2009 18:34:10 +0200
changeset 5 ad210aa137a4
parent 4 cdddff328b78
permissions -rw-r--r--
Removing tags as they point to invalid changesets after history refactoring.
     1 <?xml version="1.0"?>
     2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
     3   <!ENTITY tex "TeX">
     4   <!ENTITY latex "LaTeX">
     5 ]>
     6 <book id="sonews.xml" lang="en">
     7   <title>sonews Usenet News Server</title>
     8   <para>
     9     <emphasis role="bold">sonews</emphasis> is NNTP server than can provide 
    10     access to both local and global Usenets newsgroups. It is written in 
    11     <ulink url="http://java.sun.com/">Java</ulink> and uses a relational
    12     database as backend.
    13   </para>
    14   <para>
    15     <emphasis role="bold">2009/07/28</emphasis>:
    16     <emphasis>sonews/1.0.0</emphasis>
    17     (<ulink url="files/sonews-1.0.0.tar.bz2">binary tarball</ulink>,
    18     <ulink url="files/sonews-1.0.0-src.tar.bz2">source tarball</ulink>) new major release.
    19     A lot of refactoring was done to make the code more robust and 
    20     maintainable. Of course, several bugs were fixed, too ;)
    21     The 0.5.x line moves from unstable to testing in the DEB repository although
    22     the 1.0.x seems no less stable. If in doubt choose 1.0.x.
    23   </para>
    24   <para>
    25     <emphasis role="bold">2009/07/01</emphasis>:
    26     <emphasis>sonews/0.5.1</emphasis>
    27     (<ulink url="files/sonews-0.5.1.tar.bz2">binary tarball</ulink>,
    28     <ulink url="files/sonews-0.5.1-src.tar.bz2">source tarball</ulink>) bugfix
    29     release.
    30     Broken Cancel-mechanism and broken buildscript fixed.
    31     See <ulink url="http://code.xerxys.info:8000/hgwebdir.cgi/sonews-0.5/log/287">
    32       changelog</ulink> for more details.
    33   </para>
    34   <para>
    35     <emphasis role="bold">2009/06/29</emphasis>: 
    36     <emphasis>sonews/0.5.0</emphasis> 
    37     (<ulink url="files/sonews-0.5.0.tar.bz2">binary tarball</ulink>,
    38     <ulink url="files/sonews-0.5.0-src.tar.bz2">source tarball</ulink>) final 
    39     released. 
    40     The setup is a little clumsy but the software is stable and works well.
    41   </para>
    42   
    43   <chapter>
    44     <title>Introduction</title>
    45     <para>sonews is a RCF3977 compliant NNTP Usenet server. 
    46     It is written in Java and uses a relation database management system
    47     (RDBMS) as backend (currently
    48     <ulink url="http://www.postgresql.com/">PostgreSQL</ulink> and
    49     <ulink url="http://www.mysql.com/">MySQL</ulink>).
    50     sonews is highly multithreaded and uses Java NIO asynchronous sockets
    51     to handle thousands of concurrent connections.</para>
    52     <para>sonews is Free and Open Source Software (FOSS) licensed under the 
    53     terms of the
    54     <ulink url="http://www.gnu.org/licenses/gpl.html">GNU General Public License</ulink>
    55     Version 3 (or later).</para>
    56 
    57     <sect1 label="1.1">
    58       <title>History</title>
    59       <para>Ancestor of sonews is probably the Neat NNTP Daemon (n3tpd) 
    60       although there is very little code in sonews that can be identified
    61       as direct derivation.
    62       sonews was developed as diploma thesis project of Christian Lins at
    63       <ulink url="http://de.sun.com/">StarOffice development</ulink>
    64       in Hamburg and is now a Free Software project.</para>
    65     </sect1>
    66 
    67     <sect1 label="1.2">
    68       <title>Roadmap</title>
    69         <para>
    70         For sonews/1.1.x a plugin API for storage backends and command handlers
    71         is planned. 
    72         See <ulink url="http://bugs.xerxys.info/">Bugtracker</ulink> for
    73         issues with target sonews/1.1.x.
    74         </para>
    75     </sect1>
    76   </chapter>
    77 
    78   <chapter label="2">
    79     <title>Installation and initial setup</title>
    80     <sect1 label="2.1">
    81       <title>Download &amp; Installation</title>
    82       <sect2 label="2.1.1">
    83         <title>Debian based systems</title>
    84         <para>You can install sonews with 
    85         <ulink url="http://www.debian.org/doc/manuals/apt-howto/">APT</ulink>
    86         easily.
    87         Add the following line to /etc/apt/sources.list:</para>
    88         <screen>deb http://packages.xerxys.info/debian/ testing main # for sonews/0.5.x</screen>
    89         <screen>deb http://packages.xerxys.info/debian/ unstable main # for sonews/1.0.x</screen>
    90         <para>And add the GPG-Key for package authentification, see 
    91         <ulink url="http://packages.xerxys.info/debian/">Xerxys Debian Repository</ulink>
    92         for more details.</para>
    93         <para>Then force an update of your local package list:</para>
    94         <screen># apt-get update</screen>
    95         <para>To install sonews and all prerequisites issue the following command:</para>
    96         <screen># apt-get install sonews</screen>
    97         <para>This method should work for all recent Debian-based distributions
    98 (<ulink url="http://www.debian.org/">Debian</ulink>, <ulink url="http://www.ubuntu.com/">Ubuntu</ulink>, etc.).</para>
    99       </sect2>
   100 
   101       <sect2 label="2.1.2">
   102         <title>Other *nix systems</title>
   103         <para>See <ulink url="files/">Files Section</ulink> for recent binary and source tarballs.</para>
   104         <para>Use the binary archive and extract it in a directory of your choice. Make sure your system
   105 provides the necessary prerequisites:</para>
   106         <itemizedlist>
   107           <listitem>
   108             <para>Java6 compatible runtime (JRE)</para>
   109           </listitem>
   110           <listitem>
   111             <para>Java Mail API implementation, e.g. <ulink url="http://java.sun.com/products/javamail/">Sun Java Mail</ulink>.
   112 GNU JavaMail has a broken POP3 Provider and does not work with sonews.</para>
   113           </listitem>
   114           <listitem>
   115             <para>JSP Servlet Container (e.g. 
   116             <ulink url="http://kitten.sonews.org/">Kitten</ulink>) [optional]</para>
   117           </listitem>
   118         </itemizedlist>
   119       </sect2>
   120     </sect1>
   121 
   122     <sect1 label="2.2">
   123       <title>Initial database setup</title>
   124       <para>Before you start sonews, you must prepare the database. Currently sonews is known
   125 to work with PostgreSQL and MySQL.</para>
   126       <para>It is highly recommended to create an own database for every sonews instance, e.g.
   127 called 'sonews'. Additionally, it is recommended to create a unique database user
   128 for sonews, e.g. 'sonewsuser'. Please do not use the root user for sonews!
   129 The sonews user needs rights for SELECT, INSERT and UPDATE statements.
   130 Refer to the database's manual for instructions.</para>
   131       <para>You will find the SQL Schema definitions in the helpers subdirectory of
   132 the source and binary distributions. You can create the tables manually using
   133 this templates or you can use the setup helper:</para>
   134       <screen>user@debian$ sonews setup</screen>
   135       <para>or on other *nix systems:</para>
   136       <screen>user@nix$ java -jar sonews.jar org.sonews.util.DatabaseSetup</screen>
   137       <para>The tool will ask for some information about your database environment,
   138 connect to the database, create the tables and creates a default bootstrap
   139 config file called sonews.conf.</para>
   140     </sect1>
   141   </chapter>
   142 
   143   <chapter label="3">
   144     <title>Running sonews</title>
   145     <sect1 label="3.1">
   146       <title>Configuration</title>
   147       <para>There is a bootstrap configuration in /etc/sonews/sonews.conf and a regular configuration
   148 in the database table config.</para>
   149       <para>There are various configuration values that can be adapted:</para>
   150       <variablelist>
   151         <varlistentry>
   152           <term>&lsquo;<literal>sonews.article.maxsize</literal>&rsquo;</term>
   153           <listitem>
   154             <para>Maximum allowed body size of a news message given in kilobytes. Please note that
   155 for MySQL the &lsquo;<literal>max_allowed_packet</literal>&rsquo; configuration variable must
   156 be set to a value higher than &lsquo;<literal>sonews.article.maxsize</literal>&rsquo; otherwise posting
   157 of large mails will fail.</para>
   158           </listitem>
   159         </varlistentry>
   160           <varlistentry>
   161           <term>&lsquo;<literal>sonews.debug</literal>&rsquo;</term>
   162           <listitem>
   163             <para>
   164             If set to true every(!) data going through sonews' socket
   165             is written to sonews.log. After a high traffic night the logfile can be
   166             several gigabytes large, so be careful with this setting.
   167             </para>
   168           </listitem>
   169         </varlistentry>
   170         <varlistentry>
   171           <term>&lsquo;<literal>sonews.hostname</literal>&rsquo;</term>
   172           <listitem>
   173             <para>
   174               Canonical name of the server instance. This variable is part of
   175               the server's hello message to the client and used to generate
   176               Message-Ids.
   177               It is highly recommended to set sonews.hostname to the full
   178               qualified domain name (FQDN) of the host machine.
   179             </para>
   180           </listitem>
   181         </varlistentry>
   182         <varlistentry>
   183           <term>&lsquo;<literal>sonews.timeout</literal>&rsquo;</term>
   184           <listitem>
   185             <para>
   186               Socket timeout for client connections in seconds. Default as
   187               recommended in RFC3977 is 180 seconds.
   188             </para>
   189           </listitem>
   190         </varlistentry>
   191         <varlistentry>
   192           <term>&lsquo;<literal>sonews.port</literal>&rsquo;</term>
   193           <listitem>
   194             <para>
   195               Listening port of sonews daemon. This value can be overridden
   196               with the -p command line argument.
   197             </para>
   198           </listitem>
   199         </varlistentry>
   200         <varlistentry>
   201           <term>&lsquo;<literal>sonews.xdaemon.host</literal>&rsquo;</term>
   202           <listitem>
   203             <para>
   204               Hostname or IP address of the client machine that is allowed to
   205               use the XDAEMON command. Default: localhost
   206             </para>
   207           </listitem>
   208         </varlistentry>
   209       </variablelist>
   210     </sect1>
   211 
   212     <sect1 label="3.2">
   213       <title>Command line arguments</title>
   214       <para>If you like to start sonews directly, you can use one of the following
   215 arguments:</para>
   216       <screen>java -jar sonews.jar [arguments]
   217         where arguments:
   218     -c|-config         &lt;path to config file&gt; if custom config file preferred
   219     -dumpjdbcdriver    Prints out a list of available JDBC drivers
   220     -feed              Enables feed daemon for pulling news from peer servers
   221     -h|-help           This output
   222     -mlgw              Enables the Mailinglist Gateway poller
   223     -p portnumber      Port on which sonews is listening for incoming connections.
   224                        Overrides port settings in config file and database.</screen>
   225     </sect1>
   226 
   227     <sect1 label="3.3">
   228       <title>Webinterface</title>
   229       <para>The package sonews-web provides an optional webinterface that can be used to
   230 review statistical information and configuration values of sonews.</para>
   231       <screen>sonews-web start|stop</screen>
   232       <para>The webinterface uses the the lightweight Servlet Container Kitten and is
   233 per default listening on HTTP-Port 8080 (go to http://localhost:8080/sonews).</para>
   234     </sect1>
   235 
   236     <sect1 label="3.4">
   237       <title>Newsgroup configuration</title>
   238       <para>
   239         Currently some manual work is necessary to create a newsgroup hosted
   240         by a sonews instance.
   241       </para>
   242       <para>
   243         One possibility is to talk via Telnet to the sonews instance and
   244         use the non-standard command XDAEMON.
   245       <screen>telnet localhost 119</screen>
   246       <screen>XDAEMON GROUPADD local.test 0</screen>
   247       Please note that the XDAEMON command has restricted access and is only
   248       available via local connections (default, can be changed with config
   249       value sonews.xdaemon.host).
   250       </para>
   251       <para>
   252         You can also use the web interface to create newsgroups.
   253       </para>
   254     </sect1>
   255   </chapter>
   256 
   257   <chapter label="4">
   258     <title>Development</title>
   259     <para>You're welcome to create patches with bugfixes or additional features. The
   260 Mercurial DSCM makes this step an easy task.</para>
   261     <para>Just clone the public <ulink url="http://www.selenic.com/mercurial/">Mercurial</ulink> repository:</para>
   262     <screen>hg clone http://code.xerxys.info:8000/hg/sonews/ sonews-trunk</screen>
   263     <para>Then make your changes, create a bundle of changesets and send this to me via email.
   264 Or ask for push access to the public repository.</para>
   265     <para>
   266         There is a nightly generated <ulink url="apidoc/">Javadoc API documentation</ulink> that will help
   267         you to get in touch with the sonews source.
   268     </para>
   269     <para>Some debugging hints: if the server blocks and does not longer respond you
   270 probably found a deadlock. Do not kill the process with "kill -9 &lt;pid&gt;"
   271 but send a SIGQUIT signal with "kill -3 &lt;pid&gt;" and the Java VM will output
   272 a stracktrace of all threads. This output is the most valuable information to
   273 fix the deadlock.</para>
   274 
   275     <sect1 label="4.1">
   276       <title>Contributors</title>
   277       <para>Maintainer and project lead:
   278 Christian Lins (contact christian.lins (at) fh-osnabrueck.de)</para>
   279     </sect1>
   280 
   281     <sect1 label="4.2">
   282       <title>Sponsors</title>
   283       <para>The author thanks <ulink url="http://www.sun.com/">Sun Microsystems</ulink> for fully
   284 financing the first version of sonews. A really free software supporting company!</para>
   285       <para>If you like to support sonews with a donation of any kind (hardware, books, money, donuts,...),
   286  feel free to contact the project leader.
   287 A friendly email or a bug report is most welcome, too :-)</para>
   288     </sect1>
   289   </chapter>
   290 
   291   <chapter label="5">
   292     <title>Links and further information</title>
   293     <itemizedlist>
   294       <listitem>
   295         <para><ulink url="http://bugs.xerxys.info/">Bugtracker</ulink>, register necessary, see project 'sonews'.</para>
   296       </listitem>
   297       <listitem>
   298         <para><ulink url="http://www.sun.com/">Sun Microsystems</ulink>, friendly sponsor.</para>
   299       </listitem>
   300       <listitem>
   301         <para><ulink url="http://www.fh-osnabrueck">University of Applied Sciences Osnabrueck</ulink></para>
   302       </listitem>
   303     </itemizedlist>
   304   </chapter>
   305 </book>