newsstats/doc/INSTALL

NewsStats (c) 2010-2013, 2025 Thomas Hochstein <thh@thh.name>

NewsStats is a software package that can be used to collect
statistical information from a live Usenet feed and then analyze it
to create statistical reports.

This  package is free software; you can redistribute it and/or modify
it under the terms of the GNU Public License as published by the Free
Software Foundation.

---------------------------------------------------------------------

INSTALLATION INSTRUCTIONS

1) Install the scripts

   * Download the current version of NewsStats from
     <https://th-h.de/net/software/newsstats/>.

   * Untar it into a directory of your choice, i.e. /srv/newsstats:

     $ cd /srv
     $ tar -xzf newsstats-n.n.n.tar.gz

     Scripts in this path - at least feedlog.pl - should be executable by the
     news user.

2) Configuration

   * Copy the sample configuration file newsstats.conf.sample to
     newsstats.conf and modify it for your purposes:

     $ cp etc/newsstats.conf.sample etc/newsstats.conf
     $ vim etc/newsstats.conf

   a) Mandatory configuration options

   * DBDriver = mysql
     Database driver used; currently only mysql is supported.

   * DBHost = localhost
     The host your mysql server is running on.

   * DBUser =
     The username to connect to the database server.

   * DBPw =
     Matching password for your username.

   * DBDatabase = newsstats
     Database name.

   NewsStats will use those credentials to connect to your mysql
   installation.

   * DBTableRaw = raw_de
     Table holding raw statistical data.

   * DBTableGrps = groups_de
     Table holding data on postings per group.

   * DBTableHosts = hosts_de
     Table holding data on postings per server.

   * DBTableClnts = clients_de
     Table holding data on postings per client.

   b) Optional configuration options

   * TLH = de.alt,news.admin
     Limit examination to that top-level hierarchy/hierarchies.
     Comma-separated list.

3) Database (mysql) setup

   * Setup your database server with an username, a password and
     (optionally) a database matching the NewsStats configuration
     (see 2 a).

   * Start the database creation script:

     $ bin/dbcreate.pl

     It will create the database (if not already present), create the
     necessary database tables and display some information on the
     next steps.

4) Feed (INN) setup

   You have to set up an INN feed to feedlog.pl.

   * Edit your 'newsfeeds' file and insert something like

     ## gather statistics for NewsStats
     newsstats!\
             :!*,de.*\
             :Tc,WmtfbsPNH,Ac:/path/to/feedlog.pl

   * You should only feed that hierarchy (those hierarchies ...) to
     feedlog.pl that you want to cover with your statistical analysis.
     It may be a good idea to setup different feeds (to different
     databases ...) for different hierarchies.

   * Please double check that your path to feedlog.pl is correct and
     feedlog.pl can be executed by the news user

   * Check your 'newsfeeds' syntax:

     $ ctlinnd checkfile

   * Reload 'newsfeeds':

     $ ctlinnd reload newsfeeds 'Adding newsstats! feed'

   * Watch your 'news.notice' and 'errlog' files:

     $ tail -f /var/log/news/news.notice
     ...
     $ tail -f /var/log/news/errlog

   Everything should be going smoothly now.

   * If INN is spewing error messages to 'errlog' or reporting
     continous respawns of feedlog.pl to 'news.notice', stop your feed:

     $ ctlinnd drop 'newsstats!'

     and investigate. 'errlog' may be helpful here.

   * You can restart the feed with

     $ ctlinnd begin 'newsstats!'

     later.

You should be done now.

Just have a look at your raw data (DBTableRaw). It should now start to
fill up.