Installation instructions for INN 1.4 on Linux
==============================================

by:
	Arjan de Vet <devet@adv.win.tue.nl>

with comments and additions from:

	Vince Skahan <vince@victrola.wa.com>


My situation
------------

I'll first describe my situation.

My Linux machine is called adv.win.tue.nl. I use a Sun machine called
svin09.info.win.tue.nl at Eindhoven University of Technology as my
UUCP/News host. The MX (mail exchange) record for host adv.win.tue.nl
points to svin09.info.win.tue.nl. svin09 is also the news machine at the
university and it sends me news batches via UUCP.


Necessary for running INN on Linux
----------------------------------

- A kernel with TCP/IP installed.
- A syslogd daemon running.
- A good /bin/sh shell (see below).
- Some patience...


Installing INN
--------------

IMPORTANT:

- DO ALL WORK AS USER news (except starting INN)!!!

  You only need to be root to create new or chown existing directories or
  to start innd.

- BACKUP YOUR OLD NEWS SYSTEM FIRST!!

  If you are running Cnews (or another news system) now, backup everything
  under /usr/lib/news except /usr/spool/news/*. The best thing to do when
  moving from Cnews to INN is to disable any command that could feed you
  new articles before continuing with the installation.

- PRINT OUT ALL INN DOCS AND THE INN FAQ AND READ THEM!

  Do it!


Installation steps:

1. untar inn1.4.tar.Z in a directory inn-1.4

2. cd inn-1.4
   patch -p0 < inn-1.4-ctlinnd-patch

   This fixes a problem with multiple ctlinnd processes when not using
   Unix Domain Sockets, most visible when receiving a lot of newgroup
   messages simultaneously (e.g., the comp.os.linux reorganization).

3. copy config.data to inn-1.4/config/config.data

   Edit the paths in this file. I store almost everything under
   /usr/lib/news.

4. Run the inn-1.4/BUILD script:

   - I used the C version of subst.
   - Ignore the messages about lint, just continue.
   - Do not edit the data files right know, install the default ones for
     now.

   This will make the binaries and it will setup sample config files in
   inn-1.4/site. It installs these binaries and config files under
   /usr/lib/news.  It will (re)create the history file and the DBZ files
   for you; this can take some time.

5. Now you have to adapt the config files in inn-1.4/site for your
   situation.

   IMPORTANT: Never edit the config files under /usr/lib/news directly.
   Always edit the files in inn-1.4/site (so keep sources online!) and run
   `make install' in the inn-1.4/site directory to update the files under
   /usr/lib/news.

   The site directory of this inn-1.4-linux distribution contains all
   config files I had to (or wanted to) change:

   control.ctl	Determines how control messages are handled. In my
		control.ctl newgroups are always honored; rmgroups are
		mailed to the news administrator.

   expire.ctl	Determines expiration. Read the manual page.

   hosts.nntp	IMPORTANT: The host where innd will be running *must* be
		listed here if you are not using Unix Domain Sockets
		(which is the case on Linux).

		In my case I had to add adv.win.tue.nl.

   innd.conf	I set domain (win.tue.nl), organization and server
		(adv.win.tue.nl, where innd will be running) here.
		Fromhost and pathost default to `adv.win.tue.nl' which
		will be used in From: lines and in the Path: line.

   newsfeeds	This file determines outgoing feeds. Please read the
		manual page!

		In the ME entry I use !* as the default feed, which means
		that feeds get no groups by default.  Individual entries
		for other sites override this default.

		The entry for svin09 says that all groups (except junk)
		and all distributions (except local) should be fed to
		svin09.

		A special feed @overview is for the overchan program,
		which updates the News Overview (NOV) database used by
		modern newsreaders. Uncomment this if you don't want NOV.

   nnrp.access	I added my local host adv.win.tue.nl which has read and
		post access for all groups. Post access is the most
		important because I do reading from /usr/spool/news.

   overview.fmt	This determines the format of the .overview (NOV) files. I
		uncommented the Xref:full line because it makes trn 3.*
		faster.

   send-uucp	I added the -z flag to UUXFLAGS so that my newshost does
		not send reports by email about each rnews execution.

   You can use these files by copying them to the inn-1.4/site directory.

   After editing these files (and maybe other files too) for your local
   situation you should run a `make install' in the inn-1.4/site directory.
   This installs the changed files under /usr/lib/news. If you want to
   change any other files later, edit them in inn-1.4/site and do a `make
   install' afterwards. In some cases you will need to shutdown or pause
   innd. Read the docs and the FAQ for more information.

   INN has now been installed.

   I have rnews installed in /usr/lib/news/rnews so I had to make a
   symlink from /bin/rnews to /usr/lib/news/inews.

   Outgoing news is stored in /usr/spool/news/out.going/site where site is
   a file and not a directory (like Cnews). Delete any old directories
   before running INN.  If you're running uucp, make sure you have
   `HAVE_UUSTAT DO' in config.data or outgoing batching will die.

   When you have no active file, BUILD will make one. Otherwise it uses
   the existing one in /usr/lib/news (possibly the one from Cnews).

   Make a mail aliases for `news' if you want another user (e.g., root or
   yourself) to receive the daily reports.

   Be sure *NOT* to have a line for nntp in your inetd config file
   (/etc/inetd.conf). The startup scripts rc.news opens the NNTP port and
   gives it to innd.


Running INN
-----------

When experimenting with INN it is always useful to have a `tail -f
/var/log/syslog' running.

To start INN you have to execute the /usr/lib/news/etc/rc.news script as
root(!). You can add this to your /etc/rc.local.

To create an initial NOV database you have to run `expireover -a' (as
news) when innd is running.

You should now be able to post news in a test group (groups can be created
by the ctlinnd command, see manual page) when your Pnews (or whatever)
script uses INN's /usr/lib/news/inews program. If the old inews was also
in /usr/lib/news than everything should work fine. Check /usr/lib/news/log
whether the posting arrived (this can take a minute). You can also take a
look at /usr/spool/news/group/name/ to check whether the posting has been
stored on disk. When you have outgoing feeds, you can check
/usr/spool/news/out.going/* for the article you just posted.

If everything seems to work locally, call your UUCP host or enable NNTP
newsfeeding and watch the log files and syslog files.


Crontab
-------

You will need a crontab for the user `news' which does the daily expire
and other maintanance.

Here's mine:

-----------------------------------------------------------------------------
# news crontab
#
# min hour day month dayofweek (1=Mo,7=Su) command
SHELL=/bin/sh
PATH=/bin:/usr/bin:/usr/local/bin

# both bash-1.12 and ash need a '< /dev/null'
# bash-1.13cwru does not need it
10 23 * * * /usr/lib/news/rnews -U < /dev/null
15 23 * * * /usr/lib/news/bin/news.daily expireover delayrm < /dev/null
-----------------------------------------------------------------------------

rnews -U processes any news batches which could not be unbatched because
innd was not running. The `expireover' keyword must be present if you are
using NOV.

I run (as user `news') the news batching command

	/usr/lib/news/send-uucp svin09

in a script uupoll which makes batches and starts uucico for my newshost
svin09. You can add a similar command to the news crontab if you want
batching at regular times and not only when polling with the UUCP host.


NNTP news reading
-----------------

After putting the local host adv.win.tue.nl in hosts.nntp, no NNTP news
reading is possible anymore from host adv.win.tue.nl unless the news
reader knows the `mode reader' command (the NNTP version of trn 3.2 works
OK). See the INN FAQ for more information.


Bourne shell
------------

INN depends on a good Bourne shell compatible shell. When first installing
INN I was using bash 1.12 as /bin/sh (like most people do). I found a lot
of errors (not only with INN) when using this bash 1.12 as /bin/sh. After
reporting these to Chet Ramey (one of the authors of Bash) he gave me
access to a beta version of bash 1.13. This new bash is not for general
distribution (yet), but it is *very* good at emulating the Bourne shell
(the best emulation I know). I do not know when it will be released
officially.

For the time being, you have to use NetBSD's ash for Linux or bash 1.12
with some patches described below.

* NetBSD ash (Linux port 0.1, available at ftp.win.tue.nl) works OK for
  news.daily in the crontab when adding a </dev/null at the end (otherwise
  it hangs on some `uniq' command). It handles newgroup and other control
  messages without any problems.

* Bash 1.12 does not work OK for news.daily. You have to apply the
  bash-1.12-fd3.diff patch (after the bash-1.12-linux.diff by Rick
  Sladkey) to get a new bash 1.12. This bash also needs a </dev/null at
  the end of the news.daily line in the crontab (like ash, see above).

  Remaining problem with this bash 1.12 is that it does not handle
  newgroup and other control messages correctly. You have to change all
  occurences of:

  ##  Some shells don't pass in $* unless we explicitly pass it in here.
  ##  =()<. @<_PATH_PARSECTL>@ "$@">()=
  . /usr/lib/news/parsecontrol "$@"

  to

  ##  Some shells don't pass in $* unless we explicitly pass it in here.
  ##  =()<. @<_PATH_PARSECTL>@>()=
  . /usr/lib/news/parsecontrol

  in all control message handling scripts (newgroup, rmgroup, sendsys
  etc.) in inn-1.4/site followed by a `make install' in the same directory.

If you want to be safe, I would suggest using a patched bash 1.12 with
changed newgroup, rmgroup etc. scripts.

	Arjan de Vet
	Department of Mathematics and Computing Science
	Eindoven University of Technology
	The Netherlands
	devet@adv.win.tue.nl
