1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/doc/sonews.xml Fri Jun 26 16:48:50 2009 +0200
1.3 @@ -0,0 +1,254 @@
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/06/29</emphasis>:
1.19 + <emphasis>sonews/0.5.0</emphasis>
1.20 + (<ulink url="files/sonews-0.5.0.tar.bz2">binary tarball</ulink>,
1.21 + <ulink url="files/sonews-0.5.0-src.tar.bz2">source tarball</ulink>) final
1.22 + released.
1.23 + The setup is a little clumsy but the software is stable and works well.
1.24 + </para>
1.25 +
1.26 + <chapter>
1.27 + <title>Introduction</title>
1.28 + <para>sonews is a RCF3977 compliant NNTP Usenet server.
1.29 + It is written in Java and uses a relation database management system
1.30 + (RDBMS) as backend (currently
1.31 + <ulink url="http://www.postgresql.com/">PostgreSQL</ulink> and
1.32 + <ulink url="http://www.mysql.com/">MySQL</ulink>).
1.33 + sonews is highly multithreaded and uses Java NIO asynchronous sockets
1.34 + to handle thousands of concurrent connections.</para>
1.35 + <para>sonews is Free and Open Source Software (FOSS) licensed under the
1.36 + terms of the
1.37 + <ulink url="http://www.gnu.org/licenses/gpl.html">GNU General Public License</ulink>
1.38 + Version 3 (or later).</para>
1.39 +
1.40 + <sect1 label="1.1">
1.41 + <title>History</title>
1.42 + <para>Ancestor of sonews is probably the Neat NNTP Daemon (n3tpd)
1.43 + although there is very little code in sonews that can be identified
1.44 + as direct derivation.
1.45 + sonews was developed as diploma thesis project of Christian Lins at
1.46 + <ulink url="http://de.sun.com/">StarOffice development</ulink>
1.47 + in Hamburg and is now a Free Software project.</para>
1.48 + </sect1>
1.49 +
1.50 + <sect1 label="1.2">
1.51 + <title>Roadmap</title>
1.52 + <sect2 label="1.2.1">
1.53 + <title>sonews/0.6</title>
1.54 + <para>Planned to implement the XPAT command for searching, correctly
1.55 + hashed Message-Ids and a news purging command.
1.56 + See <ulink url="http://bugs.xerxys.info/">Bugtracker</ulink> for
1.57 + issues with target sonews/0.6.x.</para>
1.58 + </sect2>
1.59 + </sect1>
1.60 + </chapter>
1.61 +
1.62 + <chapter label="2">
1.63 + <title>Installation and initial setup</title>
1.64 + <sect1 label="2.1">
1.65 + <title>Download & Installation</title>
1.66 + <sect2 label="2.1.1">
1.67 + <title>Debian based systems</title>
1.68 + <para>You can install sonews with
1.69 + <ulink url="http://www.debian.org/doc/manuals/apt-howto/">APT</ulink>
1.70 + easily.
1.71 + Add the following line to /etc/apt/sources.list:</para>
1.72 + <screen>deb http://packages.xerxys.info/debian/ unstable main
1.73 + </screen>
1.74 + <para>And add the GPG-Key for package authentification, see
1.75 + <ulink url="http://packages.xerxys.info/debian/">Xerxys Debian Repository</ulink>
1.76 + for more details.</para>
1.77 + <para>Then force an update of your local package list:</para>
1.78 + <screen># apt-get update
1.79 +</screen>
1.80 + <para>To install sonews and all prerequisites issue the following command:</para>
1.81 + <screen># apt-get install sonews
1.82 + </screen>
1.83 + <para>This method should work for all recent Debian-based distributions
1.84 +(<ulink url="http://www.debian.org/">Debian</ulink>, <ulink url="http://www.ubuntu.com/">Ubuntu</ulink>, etc.).</para>
1.85 + </sect2>
1.86 +
1.87 + <sect2 label="2.1.2">
1.88 + <title>Other *nix systems</title>
1.89 + <para>See <ulink url="files/">Files Section</ulink> for recent binary and source tarballs.</para>
1.90 + <para>Use the binary archive and extract it in a directory of your choice. Make sure your system
1.91 +provides the necessary prerequisites:</para>
1.92 + <itemizedlist>
1.93 + <listitem>
1.94 + <para>Java6 compatible runtime (JRE)</para>
1.95 + </listitem>
1.96 + <listitem>
1.97 + <para>Java Mail API implementation, e.g. <ulink url="http://java.sun.com/products/javamail/">Sun Java Mail</ulink>.
1.98 +GNU JavaMail has a broken POP3 Provider and does not work with sonews.</para>
1.99 + </listitem>
1.100 + <listitem>
1.101 + <para>JSP Servlet Container (e.g.
1.102 + <ulink url="http://kitten.sonews.org/">Kitten</ulink>) [optional]</para>
1.103 + </listitem>
1.104 + </itemizedlist>
1.105 + </sect2>
1.106 + </sect1>
1.107 +
1.108 + <sect1 label="2.2">
1.109 + <title>Initial database setup</title>
1.110 + <para>Before you start sonews, you must prepare the database. Currently sonews is known
1.111 +to work with PostgreSQL and MySQL.</para>
1.112 + <para>It is highly recommended to create an own database for every sonews instance, e.g.
1.113 +called 'sonews'. Additionally, it is recommended to create a unique database user
1.114 +for sonews, e.g. 'sonewsuser'. Please do not use the root user for sonews!
1.115 +The sonews user needs rights for SELECT, INSERT and UPDATE statements.
1.116 +Refer to the database's manual for instructions.</para>
1.117 + <para>You will find the SQL Schema definitions in the helpers subdirectory of
1.118 +the source and binary distributions. You can create the tables manually using
1.119 +this templates or you can use the setup helper:</para>
1.120 + <screen>user@debian$ sonews setup
1.121 +</screen>
1.122 + <para>or on other *nix systems:</para>
1.123 + <screen>user@nix$ java -jar sonews.jar org.sonews.util.DatabaseSetup
1.124 +</screen>
1.125 + <para>The tool will ask for some information about your database environment,
1.126 +connect to the database, create the tables and creates a default bootstrap
1.127 +config file called sonews.conf.</para>
1.128 + </sect1>
1.129 + </chapter>
1.130 +
1.131 + <chapter label="3">
1.132 + <title>Running sonews</title>
1.133 + <sect1 label="3.1">
1.134 + <title>Configuration</title>
1.135 + <para>There is a bootstrap configuration in /etc/sonews/sonews.conf and a regular configuration
1.136 +in the database table config.</para>
1.137 + <para>There are various configuration values that can be adapted:</para>
1.138 + <variablelist>
1.139 + <varlistentry>
1.140 + <term>‘<literal>sonews.article.maxsize</literal>’</term>
1.141 + <listitem>
1.142 + <para>Maximum allowed body size of a news message given in kilobytes. Please note that
1.143 +for MySQL the ‘<literal>max_allowed_packet</literal>’ configuration variable must
1.144 +be set to a value higher than ‘<literal>sonews.article.maxsize</literal>’ otherwise posting
1.145 +of large mails will fail.</para>
1.146 + </listitem>
1.147 + </varlistentry>
1.148 + <varlistentry>
1.149 + <term>‘<literal>sonews.debug</literal>’</term>
1.150 + <listitem>
1.151 + <para>
1.152 + If set to true every(!) data going through sonews' socket
1.153 + is written to sonews.log. After a night the logfile can be
1.154 + several gigabytes large, so be careful with this setting.
1.155 + </para>
1.156 + </listitem>
1.157 + </varlistentry>
1.158 + <varlistentry>
1.159 + <term>‘<literal>sonews.hostname</literal>’</term>
1.160 + <listitem>
1.161 + <para>Canonical name of the server instance. This variable is part of the server's
1.162 +hello message to the client and used to generate Message-Ids.</para>
1.163 + </listitem>
1.164 + </varlistentry>
1.165 + <varlistentry>
1.166 + <term>‘<literal>sonews.timeout</literal>’</term>
1.167 + <listitem>
1.168 + <para>Socket timeout for client connections in seconds.</para>
1.169 + </listitem>
1.170 + </varlistentry>
1.171 + <varlistentry>
1.172 + <term>‘<literal>sonews.port</literal>’</term>
1.173 + <listitem>
1.174 + <para>Listening port of sonews daemon.</para>
1.175 + </listitem>
1.176 + </varlistentry>
1.177 + </variablelist>
1.178 + </sect1>
1.179 +
1.180 + <sect1 label="3.2">
1.181 + <title>Command line arguments</title>
1.182 + <para>If you like to start sonews directly, you can use one of the following
1.183 +arguments:</para>
1.184 + <screen>java -jar sonews.jar [arguments]
1.185 + where arguments:
1.186 + -c|-config <path to config file> if custom config file preferred
1.187 + -dumpjdbcdriver Prints out a list of available JDBC drivers
1.188 + -feed Enables feed daemon for pulling news from peer servers
1.189 + -h|-help This output
1.190 + -mlgw Enables the Mailinglist Gateway poller
1.191 + -p portnumber Port on which sonews is listening for incoming connections.
1.192 + Overrides port settings in config file and database.
1.193 +
1.194 +</screen>
1.195 + </sect1>
1.196 +
1.197 + <sect1 label="3.3">
1.198 + <title>Webinterface</title>
1.199 + <para>The package sonews-web provides an optional webinterface that can be used to
1.200 +review statistical information and configuration values of sonews.</para>
1.201 + <screen>sonews-web start|stop
1.202 +</screen>
1.203 + <para>The webinterface uses the the lightweight Servlet Container Kitten and is
1.204 +per default listening on HTTP-Port 8080 (go to http://localhost:8080/sonews).</para>
1.205 + </sect1>
1.206 + </chapter>
1.207 +
1.208 + <chapter label="4">
1.209 + <title>Development</title>
1.210 + <para>You're welcome to create patches with bugfixes or additional features. The
1.211 +Mercurial DSCM makes this step an easy task.</para>
1.212 + <para>Just clone the public <ulink url="http://www.selenic.com/mercurial/">Mercurial</ulink> repository:</para>
1.213 + <screen>hg clone http://code.xerxys.info:8000/hg/sonews/trunk sonews-trunk
1.214 +</screen>
1.215 + <para>Then make your changes, create a bundle of changesets and send this to me via email.
1.216 +Or ask for push access to the public repository.</para>
1.217 + <para>
1.218 + There is a nightly generated <ulink url="apidoc/">Javadoc API documentation</ulink> that will help
1.219 + you to get in touch with the sonews source.
1.220 + </para>
1.221 + <para>Some debugging hints: if the server blocks and does not longer respond you
1.222 +probably found a deadlock. Do not kill the process with "kill -9 <pid>"
1.223 +but send a SIGQUIT signal with "kill -3 <pid>" and the Java VM will output
1.224 +a stracktrace of all threads. This output is the most valuable information to
1.225 +fix the deadlock.</para>
1.226 +
1.227 + <sect1 label="4.1">
1.228 + <title>Contributors</title>
1.229 + <para>Maintainer and project lead:
1.230 +Christian Lins (contact christian.lins (at) fh-osnabrueck.de)</para>
1.231 + </sect1>
1.232 +
1.233 + <sect1 label="4.2">
1.234 + <title>Sponsors</title>
1.235 + <para>The author thanks <ulink url="http://www.sun.com/">Sun Microsystems</ulink> for fully
1.236 +financing the first version of sonews. A really free software supporting company!</para>
1.237 + <para>If you like to support sonews with a donation of any kind (hardware, books, money, donuts,...),
1.238 + feel free to contact the project leader.
1.239 +A friendly email or a bug report is most welcome, too :-)</para>
1.240 + </sect1>
1.241 + </chapter>
1.242 +
1.243 + <chapter label="5">
1.244 + <title>Links and further information</title>
1.245 + <itemizedlist>
1.246 + <listitem>
1.247 + <para><ulink url="http://bugs.xerxys.info/">Bugtracker</ulink>, register necessary, see project 'sonews'.</para>
1.248 + </listitem>
1.249 + <listitem>
1.250 + <para><ulink url="http://www.sun.com/">Sun Microsystems</ulink>, friendly sponsor.</para>
1.251 + </listitem>
1.252 + <listitem>
1.253 + <para><ulink url="http://www.fh-osnabrueck">University of Applied Sciences Osnabrueck</ulink></para>
1.254 + </listitem>
1.255 + </itemizedlist>
1.256 + </chapter>
1.257 +</book>