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