1.1 --- a/doc/config.xsl Thu Aug 06 18:34:10 2009 +0200
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,17 +0,0 @@
1.4 -<?xml version="1.0"?>
1.5 -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
1.6 - xmlns:fo="http://www.w3.org/1999/XSL/Format"
1.7 - version="1.0">
1.8 - <xsl:param name="use.id.as.filename" select="1"/>
1.9 - <xsl:param name="admon.graphics" select="1"/>
1.10 - <xsl:param name="admon.graphics.path"></xsl:param>
1.11 - <xsl:param name="chunk.section.depth" select="0"></xsl:param>
1.12 - <xsl:param name="html.stylesheet" select="'sonews.css'"/>
1.13 -<xsl:template name="user.footer.navigation">
1.14 - <p class="copyright">
1.15 - <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-sa/3.0/80x15.png" /></a> This work by <span xmlns:cc="http://creativecommons.org/ns#" property="cc:attributionName">Christian Lins</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-Share Alike 3.0 License</a>.
1.16 - </p>
1.17 -</xsl:template>
1.18 -
1.19 -</xsl:stylesheet>
1.20 -
2.1 --- a/doc/makedoc Thu Aug 06 18:34:10 2009 +0200
2.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
2.3 @@ -1,1 +0,0 @@
2.4 -xmlto --skip-validation html -m config.xsl sonews.xml
3.1 --- a/doc/sonews.css Thu Aug 06 18:34:10 2009 +0200
3.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
3.3 @@ -1,35 +0,0 @@
3.4 -body
3.5 -{
3.6 - font-family: Liberation Sans,Verdana,sans-serif;
3.7 - font-size: 11pt;
3.8 -}
3.9 -
3.10 -.screen {
3.11 - font-family: monospace;
3.12 - font-size: 1em;
3.13 - display: block;
3.14 - padding: 10px;
3.15 - border: 1px solid #bbb;
3.16 - background-color: #eee;
3.17 - color: #000;
3.18 - overflow: auto;
3.19 - border-radius: 2.5px;
3.20 - -moz-border-radius: 2.5px;
3.21 - margin: 0.5em 2em;
3.22 -
3.23 -}
3.24 -
3.25 -.programlisting {
3.26 - font-family: monospace;
3.27 - font-size: 1em;
3.28 - display: block;
3.29 - padding: 10px;
3.30 - border: 1px solid #bbb;
3.31 - background-color: #ddd;
3.32 - color: #000;
3.33 - overflow: auto;
3.34 - border-radius: 2.5px;
3.35 - -moz-border-radius: 2.5px;
3.36 - margin: 0.5em 2em;
3.37 -}
3.38 -
4.1 --- a/doc/sonews.xml Thu Aug 06 18:34:10 2009 +0200
4.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
4.3 @@ -1,305 +0,0 @@
4.4 -<?xml version="1.0"?>
4.5 -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4.6 - <!ENTITY tex "TeX">
4.7 - <!ENTITY latex "LaTeX">
4.8 -]>
4.9 -<book id="sonews.xml" lang="en">
4.10 - <title>sonews Usenet News Server</title>
4.11 - <para>
4.12 - <emphasis role="bold">sonews</emphasis> is NNTP server than can provide
4.13 - access to both local and global Usenets newsgroups. It is written in
4.14 - <ulink url="http://java.sun.com/">Java</ulink> and uses a relational
4.15 - database as backend.
4.16 - </para>
4.17 - <para>
4.18 - <emphasis role="bold">2009/07/28</emphasis>:
4.19 - <emphasis>sonews/1.0.0</emphasis>
4.20 - (<ulink url="files/sonews-1.0.0.tar.bz2">binary tarball</ulink>,
4.21 - <ulink url="files/sonews-1.0.0-src.tar.bz2">source tarball</ulink>) new major release.
4.22 - A lot of refactoring was done to make the code more robust and
4.23 - maintainable. Of course, several bugs were fixed, too ;)
4.24 - The 0.5.x line moves from unstable to testing in the DEB repository although
4.25 - the 1.0.x seems no less stable. If in doubt choose 1.0.x.
4.26 - </para>
4.27 - <para>
4.28 - <emphasis role="bold">2009/07/01</emphasis>:
4.29 - <emphasis>sonews/0.5.1</emphasis>
4.30 - (<ulink url="files/sonews-0.5.1.tar.bz2">binary tarball</ulink>,
4.31 - <ulink url="files/sonews-0.5.1-src.tar.bz2">source tarball</ulink>) bugfix
4.32 - release.
4.33 - Broken Cancel-mechanism and broken buildscript fixed.
4.34 - See <ulink url="http://code.xerxys.info:8000/hgwebdir.cgi/sonews-0.5/log/287">
4.35 - changelog</ulink> for more details.
4.36 - </para>
4.37 - <para>
4.38 - <emphasis role="bold">2009/06/29</emphasis>:
4.39 - <emphasis>sonews/0.5.0</emphasis>
4.40 - (<ulink url="files/sonews-0.5.0.tar.bz2">binary tarball</ulink>,
4.41 - <ulink url="files/sonews-0.5.0-src.tar.bz2">source tarball</ulink>) final
4.42 - released.
4.43 - The setup is a little clumsy but the software is stable and works well.
4.44 - </para>
4.45 -
4.46 - <chapter>
4.47 - <title>Introduction</title>
4.48 - <para>sonews is a RCF3977 compliant NNTP Usenet server.
4.49 - It is written in Java and uses a relation database management system
4.50 - (RDBMS) as backend (currently
4.51 - <ulink url="http://www.postgresql.com/">PostgreSQL</ulink> and
4.52 - <ulink url="http://www.mysql.com/">MySQL</ulink>).
4.53 - sonews is highly multithreaded and uses Java NIO asynchronous sockets
4.54 - to handle thousands of concurrent connections.</para>
4.55 - <para>sonews is Free and Open Source Software (FOSS) licensed under the
4.56 - terms of the
4.57 - <ulink url="http://www.gnu.org/licenses/gpl.html">GNU General Public License</ulink>
4.58 - Version 3 (or later).</para>
4.59 -
4.60 - <sect1 label="1.1">
4.61 - <title>History</title>
4.62 - <para>Ancestor of sonews is probably the Neat NNTP Daemon (n3tpd)
4.63 - although there is very little code in sonews that can be identified
4.64 - as direct derivation.
4.65 - sonews was developed as diploma thesis project of Christian Lins at
4.66 - <ulink url="http://de.sun.com/">StarOffice development</ulink>
4.67 - in Hamburg and is now a Free Software project.</para>
4.68 - </sect1>
4.69 -
4.70 - <sect1 label="1.2">
4.71 - <title>Roadmap</title>
4.72 - <para>
4.73 - For sonews/1.1.x a plugin API for storage backends and command handlers
4.74 - is planned.
4.75 - See <ulink url="http://bugs.xerxys.info/">Bugtracker</ulink> for
4.76 - issues with target sonews/1.1.x.
4.77 - </para>
4.78 - </sect1>
4.79 - </chapter>
4.80 -
4.81 - <chapter label="2">
4.82 - <title>Installation and initial setup</title>
4.83 - <sect1 label="2.1">
4.84 - <title>Download & Installation</title>
4.85 - <sect2 label="2.1.1">
4.86 - <title>Debian based systems</title>
4.87 - <para>You can install sonews with
4.88 - <ulink url="http://www.debian.org/doc/manuals/apt-howto/">APT</ulink>
4.89 - easily.
4.90 - Add the following line to /etc/apt/sources.list:</para>
4.91 - <screen>deb http://packages.xerxys.info/debian/ testing main # for sonews/0.5.x</screen>
4.92 - <screen>deb http://packages.xerxys.info/debian/ unstable main # for sonews/1.0.x</screen>
4.93 - <para>And add the GPG-Key for package authentification, see
4.94 - <ulink url="http://packages.xerxys.info/debian/">Xerxys Debian Repository</ulink>
4.95 - for more details.</para>
4.96 - <para>Then force an update of your local package list:</para>
4.97 - <screen># apt-get update</screen>
4.98 - <para>To install sonews and all prerequisites issue the following command:</para>
4.99 - <screen># apt-get install sonews</screen>
4.100 - <para>This method should work for all recent Debian-based distributions
4.101 -(<ulink url="http://www.debian.org/">Debian</ulink>, <ulink url="http://www.ubuntu.com/">Ubuntu</ulink>, etc.).</para>
4.102 - </sect2>
4.103 -
4.104 - <sect2 label="2.1.2">
4.105 - <title>Other *nix systems</title>
4.106 - <para>See <ulink url="files/">Files Section</ulink> for recent binary and source tarballs.</para>
4.107 - <para>Use the binary archive and extract it in a directory of your choice. Make sure your system
4.108 -provides the necessary prerequisites:</para>
4.109 - <itemizedlist>
4.110 - <listitem>
4.111 - <para>Java6 compatible runtime (JRE)</para>
4.112 - </listitem>
4.113 - <listitem>
4.114 - <para>Java Mail API implementation, e.g. <ulink url="http://java.sun.com/products/javamail/">Sun Java Mail</ulink>.
4.115 -GNU JavaMail has a broken POP3 Provider and does not work with sonews.</para>
4.116 - </listitem>
4.117 - <listitem>
4.118 - <para>JSP Servlet Container (e.g.
4.119 - <ulink url="http://kitten.sonews.org/">Kitten</ulink>) [optional]</para>
4.120 - </listitem>
4.121 - </itemizedlist>
4.122 - </sect2>
4.123 - </sect1>
4.124 -
4.125 - <sect1 label="2.2">
4.126 - <title>Initial database setup</title>
4.127 - <para>Before you start sonews, you must prepare the database. Currently sonews is known
4.128 -to work with PostgreSQL and MySQL.</para>
4.129 - <para>It is highly recommended to create an own database for every sonews instance, e.g.
4.130 -called 'sonews'. Additionally, it is recommended to create a unique database user
4.131 -for sonews, e.g. 'sonewsuser'. Please do not use the root user for sonews!
4.132 -The sonews user needs rights for SELECT, INSERT and UPDATE statements.
4.133 -Refer to the database's manual for instructions.</para>
4.134 - <para>You will find the SQL Schema definitions in the helpers subdirectory of
4.135 -the source and binary distributions. You can create the tables manually using
4.136 -this templates or you can use the setup helper:</para>
4.137 - <screen>user@debian$ sonews setup</screen>
4.138 - <para>or on other *nix systems:</para>
4.139 - <screen>user@nix$ java -jar sonews.jar org.sonews.util.DatabaseSetup</screen>
4.140 - <para>The tool will ask for some information about your database environment,
4.141 -connect to the database, create the tables and creates a default bootstrap
4.142 -config file called sonews.conf.</para>
4.143 - </sect1>
4.144 - </chapter>
4.145 -
4.146 - <chapter label="3">
4.147 - <title>Running sonews</title>
4.148 - <sect1 label="3.1">
4.149 - <title>Configuration</title>
4.150 - <para>There is a bootstrap configuration in /etc/sonews/sonews.conf and a regular configuration
4.151 -in the database table config.</para>
4.152 - <para>There are various configuration values that can be adapted:</para>
4.153 - <variablelist>
4.154 - <varlistentry>
4.155 - <term>‘<literal>sonews.article.maxsize</literal>’</term>
4.156 - <listitem>
4.157 - <para>Maximum allowed body size of a news message given in kilobytes. Please note that
4.158 -for MySQL the ‘<literal>max_allowed_packet</literal>’ configuration variable must
4.159 -be set to a value higher than ‘<literal>sonews.article.maxsize</literal>’ otherwise posting
4.160 -of large mails will fail.</para>
4.161 - </listitem>
4.162 - </varlistentry>
4.163 - <varlistentry>
4.164 - <term>‘<literal>sonews.debug</literal>’</term>
4.165 - <listitem>
4.166 - <para>
4.167 - If set to true every(!) data going through sonews' socket
4.168 - is written to sonews.log. After a high traffic night the logfile can be
4.169 - several gigabytes large, so be careful with this setting.
4.170 - </para>
4.171 - </listitem>
4.172 - </varlistentry>
4.173 - <varlistentry>
4.174 - <term>‘<literal>sonews.hostname</literal>’</term>
4.175 - <listitem>
4.176 - <para>
4.177 - Canonical name of the server instance. This variable is part of
4.178 - the server's hello message to the client and used to generate
4.179 - Message-Ids.
4.180 - It is highly recommended to set sonews.hostname to the full
4.181 - qualified domain name (FQDN) of the host machine.
4.182 - </para>
4.183 - </listitem>
4.184 - </varlistentry>
4.185 - <varlistentry>
4.186 - <term>‘<literal>sonews.timeout</literal>’</term>
4.187 - <listitem>
4.188 - <para>
4.189 - Socket timeout for client connections in seconds. Default as
4.190 - recommended in RFC3977 is 180 seconds.
4.191 - </para>
4.192 - </listitem>
4.193 - </varlistentry>
4.194 - <varlistentry>
4.195 - <term>‘<literal>sonews.port</literal>’</term>
4.196 - <listitem>
4.197 - <para>
4.198 - Listening port of sonews daemon. This value can be overridden
4.199 - with the -p command line argument.
4.200 - </para>
4.201 - </listitem>
4.202 - </varlistentry>
4.203 - <varlistentry>
4.204 - <term>‘<literal>sonews.xdaemon.host</literal>’</term>
4.205 - <listitem>
4.206 - <para>
4.207 - Hostname or IP address of the client machine that is allowed to
4.208 - use the XDAEMON command. Default: localhost
4.209 - </para>
4.210 - </listitem>
4.211 - </varlistentry>
4.212 - </variablelist>
4.213 - </sect1>
4.214 -
4.215 - <sect1 label="3.2">
4.216 - <title>Command line arguments</title>
4.217 - <para>If you like to start sonews directly, you can use one of the following
4.218 -arguments:</para>
4.219 - <screen>java -jar sonews.jar [arguments]
4.220 - where arguments:
4.221 - -c|-config <path to config file> if custom config file preferred
4.222 - -dumpjdbcdriver Prints out a list of available JDBC drivers
4.223 - -feed Enables feed daemon for pulling news from peer servers
4.224 - -h|-help This output
4.225 - -mlgw Enables the Mailinglist Gateway poller
4.226 - -p portnumber Port on which sonews is listening for incoming connections.
4.227 - Overrides port settings in config file and database.</screen>
4.228 - </sect1>
4.229 -
4.230 - <sect1 label="3.3">
4.231 - <title>Webinterface</title>
4.232 - <para>The package sonews-web provides an optional webinterface that can be used to
4.233 -review statistical information and configuration values of sonews.</para>
4.234 - <screen>sonews-web start|stop</screen>
4.235 - <para>The webinterface uses the the lightweight Servlet Container Kitten and is
4.236 -per default listening on HTTP-Port 8080 (go to http://localhost:8080/sonews).</para>
4.237 - </sect1>
4.238 -
4.239 - <sect1 label="3.4">
4.240 - <title>Newsgroup configuration</title>
4.241 - <para>
4.242 - Currently some manual work is necessary to create a newsgroup hosted
4.243 - by a sonews instance.
4.244 - </para>
4.245 - <para>
4.246 - One possibility is to talk via Telnet to the sonews instance and
4.247 - use the non-standard command XDAEMON.
4.248 - <screen>telnet localhost 119</screen>
4.249 - <screen>XDAEMON GROUPADD local.test 0</screen>
4.250 - Please note that the XDAEMON command has restricted access and is only
4.251 - available via local connections (default, can be changed with config
4.252 - value sonews.xdaemon.host).
4.253 - </para>
4.254 - <para>
4.255 - You can also use the web interface to create newsgroups.
4.256 - </para>
4.257 - </sect1>
4.258 - </chapter>
4.259 -
4.260 - <chapter label="4">
4.261 - <title>Development</title>
4.262 - <para>You're welcome to create patches with bugfixes or additional features. The
4.263 -Mercurial DSCM makes this step an easy task.</para>
4.264 - <para>Just clone the public <ulink url="http://www.selenic.com/mercurial/">Mercurial</ulink> repository:</para>
4.265 - <screen>hg clone http://code.xerxys.info:8000/hg/sonews/ sonews-trunk</screen>
4.266 - <para>Then make your changes, create a bundle of changesets and send this to me via email.
4.267 -Or ask for push access to the public repository.</para>
4.268 - <para>
4.269 - There is a nightly generated <ulink url="apidoc/">Javadoc API documentation</ulink> that will help
4.270 - you to get in touch with the sonews source.
4.271 - </para>
4.272 - <para>Some debugging hints: if the server blocks and does not longer respond you
4.273 -probably found a deadlock. Do not kill the process with "kill -9 <pid>"
4.274 -but send a SIGQUIT signal with "kill -3 <pid>" and the Java VM will output
4.275 -a stracktrace of all threads. This output is the most valuable information to
4.276 -fix the deadlock.</para>
4.277 -
4.278 - <sect1 label="4.1">
4.279 - <title>Contributors</title>
4.280 - <para>Maintainer and project lead:
4.281 -Christian Lins (contact christian.lins (at) fh-osnabrueck.de)</para>
4.282 - </sect1>
4.283 -
4.284 - <sect1 label="4.2">
4.285 - <title>Sponsors</title>
4.286 - <para>The author thanks <ulink url="http://www.sun.com/">Sun Microsystems</ulink> for fully
4.287 -financing the first version of sonews. A really free software supporting company!</para>
4.288 - <para>If you like to support sonews with a donation of any kind (hardware, books, money, donuts,...),
4.289 - feel free to contact the project leader.
4.290 -A friendly email or a bug report is most welcome, too :-)</para>
4.291 - </sect1>
4.292 - </chapter>
4.293 -
4.294 - <chapter label="5">
4.295 - <title>Links and further information</title>
4.296 - <itemizedlist>
4.297 - <listitem>
4.298 - <para><ulink url="http://bugs.xerxys.info/">Bugtracker</ulink>, register necessary, see project 'sonews'.</para>
4.299 - </listitem>
4.300 - <listitem>
4.301 - <para><ulink url="http://www.sun.com/">Sun Microsystems</ulink>, friendly sponsor.</para>
4.302 - </listitem>
4.303 - <listitem>
4.304 - <para><ulink url="http://www.fh-osnabrueck">University of Applied Sciences Osnabrueck</ulink></para>
4.305 - </listitem>
4.306 - </itemizedlist>
4.307 - </chapter>
4.308 -</book>