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