1.1 --- a/doc/sonews.xml Wed Jul 01 10:48:22 2009 +0200
1.2 +++ b/doc/sonews.xml Wed Jul 22 14:04:05 2009 +0200
1.3 @@ -57,11 +57,15 @@
1.4 <sect1 label="1.2">
1.5 <title>Roadmap</title>
1.6 <sect2 label="1.2.1">
1.7 - <title>sonews/0.6</title>
1.8 - <para>Planned to implement the XPAT command for searching, correctly
1.9 + <title>sonews/1.0</title>
1.10 + <para>
1.11 + Various minor fixes and code cleanup (Storage and Command interface for
1.12 + the upcoming Plugin API).
1.13 + </para>
1.14 + <para>XPAT command for searching, correctly
1.15 hashed Message-Ids and a news purging command.
1.16 See <ulink url="http://bugs.xerxys.info/">Bugtracker</ulink> for
1.17 - issues with target sonews/0.6.x.</para>
1.18 + issues with target sonews/1.0.x.</para>
1.19 </sect2>
1.20 </sect1>
1.21 </chapter>
1.22 @@ -76,17 +80,14 @@
1.23 <ulink url="http://www.debian.org/doc/manuals/apt-howto/">APT</ulink>
1.24 easily.
1.25 Add the following line to /etc/apt/sources.list:</para>
1.26 - <screen>deb http://packages.xerxys.info/debian/ unstable main
1.27 - </screen>
1.28 + <screen>deb http://packages.xerxys.info/debian/ unstable main</screen>
1.29 <para>And add the GPG-Key for package authentification, see
1.30 <ulink url="http://packages.xerxys.info/debian/">Xerxys Debian Repository</ulink>
1.31 for more details.</para>
1.32 <para>Then force an update of your local package list:</para>
1.33 - <screen># apt-get update
1.34 -</screen>
1.35 + <screen># apt-get update</screen>
1.36 <para>To install sonews and all prerequisites issue the following command:</para>
1.37 - <screen># apt-get install sonews
1.38 - </screen>
1.39 + <screen># apt-get install sonews</screen>
1.40 <para>This method should work for all recent Debian-based distributions
1.41 (<ulink url="http://www.debian.org/">Debian</ulink>, <ulink url="http://www.ubuntu.com/">Ubuntu</ulink>, etc.).</para>
1.42 </sect2>
1.43 @@ -124,11 +125,9 @@
1.44 <para>You will find the SQL Schema definitions in the helpers subdirectory of
1.45 the source and binary distributions. You can create the tables manually using
1.46 this templates or you can use the setup helper:</para>
1.47 - <screen>user@debian$ sonews setup
1.48 -</screen>
1.49 + <screen>user@debian$ sonews setup</screen>
1.50 <para>or on other *nix systems:</para>
1.51 - <screen>user@nix$ java -jar sonews.jar org.sonews.util.DatabaseSetup
1.52 -</screen>
1.53 + <screen>user@nix$ java -jar sonews.jar org.sonews.util.DatabaseSetup</screen>
1.54 <para>The tool will ask for some information about your database environment,
1.55 connect to the database, create the tables and creates a default bootstrap
1.56 config file called sonews.conf.</para>
1.57 @@ -157,7 +156,7 @@
1.58 <listitem>
1.59 <para>
1.60 If set to true every(!) data going through sonews' socket
1.61 - is written to sonews.log. After a night the logfile can be
1.62 + is written to sonews.log. After a high traffic night the logfile can be
1.63 several gigabytes large, so be careful with this setting.
1.64 </para>
1.65 </listitem>
1.66 @@ -165,20 +164,40 @@
1.67 <varlistentry>
1.68 <term>‘<literal>sonews.hostname</literal>’</term>
1.69 <listitem>
1.70 - <para>Canonical name of the server instance. This variable is part of the server's
1.71 -hello message to the client and used to generate Message-Ids.</para>
1.72 + <para>
1.73 + Canonical name of the server instance. This variable is part of
1.74 + the server's hello message to the client and used to generate
1.75 + Message-Ids.
1.76 + It is highly recommended to set sonews.hostname to the full
1.77 + qualified domain name (FQDN) of the host machine.
1.78 + </para>
1.79 </listitem>
1.80 </varlistentry>
1.81 <varlistentry>
1.82 <term>‘<literal>sonews.timeout</literal>’</term>
1.83 <listitem>
1.84 - <para>Socket timeout for client connections in seconds.</para>
1.85 + <para>
1.86 + Socket timeout for client connections in seconds. Default as
1.87 + recommended in RFC3977 is 180 seconds.
1.88 + </para>
1.89 </listitem>
1.90 </varlistentry>
1.91 <varlistentry>
1.92 <term>‘<literal>sonews.port</literal>’</term>
1.93 <listitem>
1.94 - <para>Listening port of sonews daemon.</para>
1.95 + <para>
1.96 + Listening port of sonews daemon. This value can be overridden
1.97 + with the -p command line argument.
1.98 + </para>
1.99 + </listitem>
1.100 + </varlistentry>
1.101 + <varlistentry>
1.102 + <term>‘<literal>sonews.xdaemon.host</literal>’</term>
1.103 + <listitem>
1.104 + <para>
1.105 + Hostname or IP address of the client machine that is allowed to
1.106 + use the XDAEMON command. Default: localhost
1.107 + </para>
1.108 </listitem>
1.109 </varlistentry>
1.110 </variablelist>
1.111 @@ -196,20 +215,37 @@
1.112 -h|-help This output
1.113 -mlgw Enables the Mailinglist Gateway poller
1.114 -p portnumber Port on which sonews is listening for incoming connections.
1.115 - Overrides port settings in config file and database.
1.116 -
1.117 -</screen>
1.118 + Overrides port settings in config file and database.</screen>
1.119 </sect1>
1.120
1.121 <sect1 label="3.3">
1.122 <title>Webinterface</title>
1.123 <para>The package sonews-web provides an optional webinterface that can be used to
1.124 review statistical information and configuration values of sonews.</para>
1.125 - <screen>sonews-web start|stop
1.126 -</screen>
1.127 + <screen>sonews-web start|stop</screen>
1.128 <para>The webinterface uses the the lightweight Servlet Container Kitten and is
1.129 per default listening on HTTP-Port 8080 (go to http://localhost:8080/sonews).</para>
1.130 </sect1>
1.131 +
1.132 + <sect1 label="3.4">
1.133 + <title>Newsgroup configuration</title>
1.134 + <para>
1.135 + Currently some manual work is necessary to create a newsgroup hosted
1.136 + by a sonews instance.
1.137 + </para>
1.138 + <para>
1.139 + One possibility is to talk via Telnet to the sonews instance and
1.140 + use the non-standard command XDAEMON.
1.141 + <screen>telnet localhost 119</screen>
1.142 + <screen>XDAEMON GROUPADD local.test 0</screen>
1.143 + Please note that the XDAEMON command has restricted access and is only
1.144 + available via local connections (default, can be changed with config
1.145 + value sonews.xdaemon.host).
1.146 + </para>
1.147 + <para>
1.148 + You can also use the web interface to create newsgroups.
1.149 + </para>
1.150 + </sect1>
1.151 </chapter>
1.152
1.153 <chapter label="4">
1.154 @@ -217,8 +253,7 @@
1.155 <para>You're welcome to create patches with bugfixes or additional features. The
1.156 Mercurial DSCM makes this step an easy task.</para>
1.157 <para>Just clone the public <ulink url="http://www.selenic.com/mercurial/">Mercurial</ulink> repository:</para>
1.158 - <screen>hg clone http://code.xerxys.info:8000/hg/sonews/trunk sonews-trunk
1.159 -</screen>
1.160 + <screen>hg clone http://code.xerxys.info:8000/hg/sonews/ sonews-trunk</screen>
1.161 <para>Then make your changes, create a bundle of changesets and send this to me via email.
1.162 Or ask for push access to the public repository.</para>
1.163 <para>