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