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