1.1 --- a/doc/sonews.xml Thu Aug 06 18:34:10 2009 +0200
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,305 +0,0 @@
1.4 -<?xml version="1.0"?>
1.5 -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
1.6 - <!ENTITY tex "TeX">
1.7 - <!ENTITY latex "LaTeX">
1.8 -]>
1.9 -<book id="sonews.xml" lang="en">
1.10 - <title>sonews Usenet News Server</title>
1.11 - <para>
1.12 - <emphasis role="bold">sonews</emphasis> is NNTP server than can provide
1.13 - access to both local and global Usenets newsgroups. It is written in
1.14 - <ulink url="http://java.sun.com/">Java</ulink> and uses a relational
1.15 - database as backend.
1.16 - </para>
1.17 - <para>
1.18 - <emphasis role="bold">2009/07/28</emphasis>:
1.19 - <emphasis>sonews/1.0.0</emphasis>
1.20 - (<ulink url="files/sonews-1.0.0.tar.bz2">binary tarball</ulink>,
1.21 - <ulink url="files/sonews-1.0.0-src.tar.bz2">source tarball</ulink>) new major release.
1.22 - A lot of refactoring was done to make the code more robust and
1.23 - maintainable. Of course, several bugs were fixed, too ;)
1.24 - The 0.5.x line moves from unstable to testing in the DEB repository although
1.25 - the 1.0.x seems no less stable. If in doubt choose 1.0.x.
1.26 - </para>
1.27 - <para>
1.28 - <emphasis role="bold">2009/07/01</emphasis>:
1.29 - <emphasis>sonews/0.5.1</emphasis>
1.30 - (<ulink url="files/sonews-0.5.1.tar.bz2">binary tarball</ulink>,
1.31 - <ulink url="files/sonews-0.5.1-src.tar.bz2">source tarball</ulink>) bugfix
1.32 - release.
1.33 - Broken Cancel-mechanism and broken buildscript fixed.
1.34 - See <ulink url="http://code.xerxys.info:8000/hgwebdir.cgi/sonews-0.5/log/287">
1.35 - changelog</ulink> for more details.
1.36 - </para>
1.37 - <para>
1.38 - <emphasis role="bold">2009/06/29</emphasis>:
1.39 - <emphasis>sonews/0.5.0</emphasis>
1.40 - (<ulink url="files/sonews-0.5.0.tar.bz2">binary tarball</ulink>,
1.41 - <ulink url="files/sonews-0.5.0-src.tar.bz2">source tarball</ulink>) final
1.42 - released.
1.43 - The setup is a little clumsy but the software is stable and works well.
1.44 - </para>
1.45 -
1.46 - <chapter>
1.47 - <title>Introduction</title>
1.48 - <para>sonews is a RCF3977 compliant NNTP Usenet server.
1.49 - It is written in Java and uses a relation database management system
1.50 - (RDBMS) as backend (currently
1.51 - <ulink url="http://www.postgresql.com/">PostgreSQL</ulink> and
1.52 - <ulink url="http://www.mysql.com/">MySQL</ulink>).
1.53 - sonews is highly multithreaded and uses Java NIO asynchronous sockets
1.54 - to handle thousands of concurrent connections.</para>
1.55 - <para>sonews is Free and Open Source Software (FOSS) licensed under the
1.56 - terms of the
1.57 - <ulink url="http://www.gnu.org/licenses/gpl.html">GNU General Public License</ulink>
1.58 - Version 3 (or later).</para>
1.59 -
1.60 - <sect1 label="1.1">
1.61 - <title>History</title>
1.62 - <para>Ancestor of sonews is probably the Neat NNTP Daemon (n3tpd)
1.63 - although there is very little code in sonews that can be identified
1.64 - as direct derivation.
1.65 - sonews was developed as diploma thesis project of Christian Lins at
1.66 - <ulink url="http://de.sun.com/">StarOffice development</ulink>
1.67 - in Hamburg and is now a Free Software project.</para>
1.68 - </sect1>
1.69 -
1.70 - <sect1 label="1.2">
1.71 - <title>Roadmap</title>
1.72 - <para>
1.73 - For sonews/1.1.x a plugin API for storage backends and command handlers
1.74 - is planned.
1.75 - See <ulink url="http://bugs.xerxys.info/">Bugtracker</ulink> for
1.76 - issues with target sonews/1.1.x.
1.77 - </para>
1.78 - </sect1>
1.79 - </chapter>
1.80 -
1.81 - <chapter label="2">
1.82 - <title>Installation and initial setup</title>
1.83 - <sect1 label="2.1">
1.84 - <title>Download & Installation</title>
1.85 - <sect2 label="2.1.1">
1.86 - <title>Debian based systems</title>
1.87 - <para>You can install sonews with
1.88 - <ulink url="http://www.debian.org/doc/manuals/apt-howto/">APT</ulink>
1.89 - easily.
1.90 - Add the following line to /etc/apt/sources.list:</para>
1.91 - <screen>deb http://packages.xerxys.info/debian/ testing main # for sonews/0.5.x</screen>
1.92 - <screen>deb http://packages.xerxys.info/debian/ unstable main # for sonews/1.0.x</screen>
1.93 - <para>And add the GPG-Key for package authentification, see
1.94 - <ulink url="http://packages.xerxys.info/debian/">Xerxys Debian Repository</ulink>
1.95 - for more details.</para>
1.96 - <para>Then force an update of your local package list:</para>
1.97 - <screen># apt-get update</screen>
1.98 - <para>To install sonews and all prerequisites issue the following command:</para>
1.99 - <screen># apt-get install sonews</screen>
1.100 - <para>This method should work for all recent Debian-based distributions
1.101 -(<ulink url="http://www.debian.org/">Debian</ulink>, <ulink url="http://www.ubuntu.com/">Ubuntu</ulink>, etc.).</para>
1.102 - </sect2>
1.103 -
1.104 - <sect2 label="2.1.2">
1.105 - <title>Other *nix systems</title>
1.106 - <para>See <ulink url="files/">Files Section</ulink> for recent binary and source tarballs.</para>
1.107 - <para>Use the binary archive and extract it in a directory of your choice. Make sure your system
1.108 -provides the necessary prerequisites:</para>
1.109 - <itemizedlist>
1.110 - <listitem>
1.111 - <para>Java6 compatible runtime (JRE)</para>
1.112 - </listitem>
1.113 - <listitem>
1.114 - <para>Java Mail API implementation, e.g. <ulink url="http://java.sun.com/products/javamail/">Sun Java Mail</ulink>.
1.115 -GNU JavaMail has a broken POP3 Provider and does not work with sonews.</para>
1.116 - </listitem>
1.117 - <listitem>
1.118 - <para>JSP Servlet Container (e.g.
1.119 - <ulink url="http://kitten.sonews.org/">Kitten</ulink>) [optional]</para>
1.120 - </listitem>
1.121 - </itemizedlist>
1.122 - </sect2>
1.123 - </sect1>
1.124 -
1.125 - <sect1 label="2.2">
1.126 - <title>Initial database setup</title>
1.127 - <para>Before you start sonews, you must prepare the database. Currently sonews is known
1.128 -to work with PostgreSQL and MySQL.</para>
1.129 - <para>It is highly recommended to create an own database for every sonews instance, e.g.
1.130 -called 'sonews'. Additionally, it is recommended to create a unique database user
1.131 -for sonews, e.g. 'sonewsuser'. Please do not use the root user for sonews!
1.132 -The sonews user needs rights for SELECT, INSERT and UPDATE statements.
1.133 -Refer to the database's manual for instructions.</para>
1.134 - <para>You will find the SQL Schema definitions in the helpers subdirectory of
1.135 -the source and binary distributions. You can create the tables manually using
1.136 -this templates or you can use the setup helper:</para>
1.137 - <screen>user@debian$ sonews setup</screen>
1.138 - <para>or on other *nix systems:</para>
1.139 - <screen>user@nix$ java -jar sonews.jar org.sonews.util.DatabaseSetup</screen>
1.140 - <para>The tool will ask for some information about your database environment,
1.141 -connect to the database, create the tables and creates a default bootstrap
1.142 -config file called sonews.conf.</para>
1.143 - </sect1>
1.144 - </chapter>
1.145 -
1.146 - <chapter label="3">
1.147 - <title>Running sonews</title>
1.148 - <sect1 label="3.1">
1.149 - <title>Configuration</title>
1.150 - <para>There is a bootstrap configuration in /etc/sonews/sonews.conf and a regular configuration
1.151 -in the database table config.</para>
1.152 - <para>There are various configuration values that can be adapted:</para>
1.153 - <variablelist>
1.154 - <varlistentry>
1.155 - <term>‘<literal>sonews.article.maxsize</literal>’</term>
1.156 - <listitem>
1.157 - <para>Maximum allowed body size of a news message given in kilobytes. Please note that
1.158 -for MySQL the ‘<literal>max_allowed_packet</literal>’ configuration variable must
1.159 -be set to a value higher than ‘<literal>sonews.article.maxsize</literal>’ otherwise posting
1.160 -of large mails will fail.</para>
1.161 - </listitem>
1.162 - </varlistentry>
1.163 - <varlistentry>
1.164 - <term>‘<literal>sonews.debug</literal>’</term>
1.165 - <listitem>
1.166 - <para>
1.167 - If set to true every(!) data going through sonews' socket
1.168 - is written to sonews.log. After a high traffic night the logfile can be
1.169 - several gigabytes large, so be careful with this setting.
1.170 - </para>
1.171 - </listitem>
1.172 - </varlistentry>
1.173 - <varlistentry>
1.174 - <term>‘<literal>sonews.hostname</literal>’</term>
1.175 - <listitem>
1.176 - <para>
1.177 - Canonical name of the server instance. This variable is part of
1.178 - the server's hello message to the client and used to generate
1.179 - Message-Ids.
1.180 - It is highly recommended to set sonews.hostname to the full
1.181 - qualified domain name (FQDN) of the host machine.
1.182 - </para>
1.183 - </listitem>
1.184 - </varlistentry>
1.185 - <varlistentry>
1.186 - <term>‘<literal>sonews.timeout</literal>’</term>
1.187 - <listitem>
1.188 - <para>
1.189 - Socket timeout for client connections in seconds. Default as
1.190 - recommended in RFC3977 is 180 seconds.
1.191 - </para>
1.192 - </listitem>
1.193 - </varlistentry>
1.194 - <varlistentry>
1.195 - <term>‘<literal>sonews.port</literal>’</term>
1.196 - <listitem>
1.197 - <para>
1.198 - Listening port of sonews daemon. This value can be overridden
1.199 - with the -p command line argument.
1.200 - </para>
1.201 - </listitem>
1.202 - </varlistentry>
1.203 - <varlistentry>
1.204 - <term>‘<literal>sonews.xdaemon.host</literal>’</term>
1.205 - <listitem>
1.206 - <para>
1.207 - Hostname or IP address of the client machine that is allowed to
1.208 - use the XDAEMON command. Default: localhost
1.209 - </para>
1.210 - </listitem>
1.211 - </varlistentry>
1.212 - </variablelist>
1.213 - </sect1>
1.214 -
1.215 - <sect1 label="3.2">
1.216 - <title>Command line arguments</title>
1.217 - <para>If you like to start sonews directly, you can use one of the following
1.218 -arguments:</para>
1.219 - <screen>java -jar sonews.jar [arguments]
1.220 - where arguments:
1.221 - -c|-config <path to config file> if custom config file preferred
1.222 - -dumpjdbcdriver Prints out a list of available JDBC drivers
1.223 - -feed Enables feed daemon for pulling news from peer servers
1.224 - -h|-help This output
1.225 - -mlgw Enables the Mailinglist Gateway poller
1.226 - -p portnumber Port on which sonews is listening for incoming connections.
1.227 - Overrides port settings in config file and database.</screen>
1.228 - </sect1>
1.229 -
1.230 - <sect1 label="3.3">
1.231 - <title>Webinterface</title>
1.232 - <para>The package sonews-web provides an optional webinterface that can be used to
1.233 -review statistical information and configuration values of sonews.</para>
1.234 - <screen>sonews-web start|stop</screen>
1.235 - <para>The webinterface uses the the lightweight Servlet Container Kitten and is
1.236 -per default listening on HTTP-Port 8080 (go to http://localhost:8080/sonews).</para>
1.237 - </sect1>
1.238 -
1.239 - <sect1 label="3.4">
1.240 - <title>Newsgroup configuration</title>
1.241 - <para>
1.242 - Currently some manual work is necessary to create a newsgroup hosted
1.243 - by a sonews instance.
1.244 - </para>
1.245 - <para>
1.246 - One possibility is to talk via Telnet to the sonews instance and
1.247 - use the non-standard command XDAEMON.
1.248 - <screen>telnet localhost 119</screen>
1.249 - <screen>XDAEMON GROUPADD local.test 0</screen>
1.250 - Please note that the XDAEMON command has restricted access and is only
1.251 - available via local connections (default, can be changed with config
1.252 - value sonews.xdaemon.host).
1.253 - </para>
1.254 - <para>
1.255 - You can also use the web interface to create newsgroups.
1.256 - </para>
1.257 - </sect1>
1.258 - </chapter>
1.259 -
1.260 - <chapter label="4">
1.261 - <title>Development</title>
1.262 - <para>You're welcome to create patches with bugfixes or additional features. The
1.263 -Mercurial DSCM makes this step an easy task.</para>
1.264 - <para>Just clone the public <ulink url="http://www.selenic.com/mercurial/">Mercurial</ulink> repository:</para>
1.265 - <screen>hg clone http://code.xerxys.info:8000/hg/sonews/ sonews-trunk</screen>
1.266 - <para>Then make your changes, create a bundle of changesets and send this to me via email.
1.267 -Or ask for push access to the public repository.</para>
1.268 - <para>
1.269 - There is a nightly generated <ulink url="apidoc/">Javadoc API documentation</ulink> that will help
1.270 - you to get in touch with the sonews source.
1.271 - </para>
1.272 - <para>Some debugging hints: if the server blocks and does not longer respond you
1.273 -probably found a deadlock. Do not kill the process with "kill -9 <pid>"
1.274 -but send a SIGQUIT signal with "kill -3 <pid>" and the Java VM will output
1.275 -a stracktrace of all threads. This output is the most valuable information to
1.276 -fix the deadlock.</para>
1.277 -
1.278 - <sect1 label="4.1">
1.279 - <title>Contributors</title>
1.280 - <para>Maintainer and project lead:
1.281 -Christian Lins (contact christian.lins (at) fh-osnabrueck.de)</para>
1.282 - </sect1>
1.283 -
1.284 - <sect1 label="4.2">
1.285 - <title>Sponsors</title>
1.286 - <para>The author thanks <ulink url="http://www.sun.com/">Sun Microsystems</ulink> for fully
1.287 -financing the first version of sonews. A really free software supporting company!</para>
1.288 - <para>If you like to support sonews with a donation of any kind (hardware, books, money, donuts,...),
1.289 - feel free to contact the project leader.
1.290 -A friendly email or a bug report is most welcome, too :-)</para>
1.291 - </sect1>
1.292 - </chapter>
1.293 -
1.294 - <chapter label="5">
1.295 - <title>Links and further information</title>
1.296 - <itemizedlist>
1.297 - <listitem>
1.298 - <para><ulink url="http://bugs.xerxys.info/">Bugtracker</ulink>, register necessary, see project 'sonews'.</para>
1.299 - </listitem>
1.300 - <listitem>
1.301 - <para><ulink url="http://www.sun.com/">Sun Microsystems</ulink>, friendly sponsor.</para>
1.302 - </listitem>
1.303 - <listitem>
1.304 - <para><ulink url="http://www.fh-osnabrueck">University of Applied Sciences Osnabrueck</ulink></para>
1.305 - </listitem>
1.306 - </itemizedlist>
1.307 - </chapter>
1.308 -</book>