v3.1   README4: A LINUX-TO-DEMON-INTERNET CONFIGURATION GUIDE   10/05/96  

     CNEWS: CONFIGURING SLACKWARE LINUX FOR USENET NEWS WITH C NEWS
     ==============================================================

     Copyright 1994-6 John A. Phillips.      john@linux.demon.co.uk


This README is has been tested on Slackware 3.0, 2.3, 2.2 and 2.1.  It
describes a usenet news set-up using slurp to bring in batches of news
articles from your news server(s), C News to store and process it, and
e-mail to send out articles posted at your site.  It also describes how
to set up the newsreader nn.

Some of the files you need to install or modify are contained in the
package, for you to copy directly into place.  See the list at the end
of this README.  Configuration should be done as user news in sections
4C to 4G and in section 4L, and as user root elsewhere.


4A Requirements and installation notes
--------------------------------------
Please see the "Requirements and installation notes" section of the
README in the BASIC package for the basic networking set-up.  I assume
you have successfully completed this set-up first.

For running usenet news using C News, the relevant optional packages of
disk set N are:

    cnews     Required for this package (see the NOTEs below about INN)
    inn       Do *not* install (see the NOTEs below if you want to use INN)
    tin       Recommended as an alternative newsreader to nn and trn
    trn-nntp  Do *not* install - this is an on-line news reader
    trn       Recommended as an alternative newsreader to nn and tin
    nn-nntp   Do *not* install - this is an on-line news reader
    nn-spool  Required as the newsreader assumed in this package (NOTE 4)

NOTE 1:  The news transport agents INN and C News cannot operate
together. Simply installing INN prevents C News from operating
correctly.  The only sound advice is do not install INN if you want to
use C News.

NOTE 2:  If you have installed INN, but want to run C News, the way to
remove INN is:  (i) run pkgtool and ask it to remove INN; (ii) ask
pkgtool to remove C News, if this is also installed; then (iii) remove
/usr/lib/news and all sub-directories; and (iv) ask pkgtool to install C
News from the appropriate N-series disk.  The C News de-install, then
re-install process is necessary as the two packages partially overlap.

NOTE 3:  If you want to use INN, please see Ivan Beveridge's notes on
using INN instead of C News.  These may be found in the INN package
within this guide.  In this case, do not install C News.

NOTE 4:  Most of this guide is about C-news and slurp, and only a small
part is about the newsreader nn.  If you want to use another news reader
(e.g. tin) then that's OK.  Ignore the instructions for nn and install
whatever news reader you feel happy with.  There is a note about tin. 

* Before you start, please correct the home directory for user news,
given in /etc/passwd, from /usr/lib/news to /var/lib/news.


4B Install slurp
----------------
* Install the slurp binary and manpage from the package.  For Slackware
2.* copy slurp-aout into place as /usr/local/sbin/slurp.  Slackware 3.0
needs slurp-elf instead.  You should end up with these files installed:

    /usr/local/sbin/slurp
    /usr/local/man/man1/slurp.1

To make sure slurp is owned by user news, execute: 

    chown news.news /usr/local/sbin/slurp

NOTE: Slackware's C News is compiled to use the C library dbm database
format for its history file (rather than using dbz).  Because of this,
the slurp in this package has also been compiled with dbm.


4C Configure slurp for your news servers and groups
---------------------------------------------------
You need to configure slurp as user news in the C News configuration
directory (/var/lib/news).  Starting as user root, execute "su news".

* /var/lib/news/slurp.sys is the list of newsgroups you want slurp to
get from each news server you may wish to use.  List your required news
groups in the file after the name of the news server from which you want
to get them.  The file (which is in the package and can be copied
directly into place) should look something like:

    # Feed from news.demon.co.uk
    # ==========================
    news.demon.co.uk:\
    comp.os.linux.announce,comp.os.linux.networking,demon.announce,\
    demon.ip.support,demon.ip.support.unix,demon.tech.unix,demon.test,\
    misc.test.moderated,news.announce.newusers
    #
    # Feed from pubnews.demon.co.uk
    # =============================
    pubnews.demon.co.uk:\
    comp.os.linux.announce,comp.os.linux.networking,demon.announce,\
    demon.ip.support,demon.ip.support.unix,demon.tech.unix,demon.test,\
    misc.test.moderated,news.announce.newusers
    #
    # END OF FILE

There must be NO WHITE SPACE in these lists.  Hence the "\" at the end
of each line in the example above where the line is broken, after which
there must be no spaces, tabs or other characters.  You may have as many
news group names on each line as you wish, or just one.

Having multiple feed specifications in slurp.sys allows you to easily
swap between servers (see section 4N).  The lists of news groups need
not be identical, but until you are sure about how this works, I
recommend you do keep identical lists for each server.

* /var/lib/news/slurp.<NEWS_SERVER> (e.g. slurp.news.demon.co.uk) must
be created for each server in the slurp.sys file.  It must contain the
date and time (in GMT) from which you want new news to be suppiled.  The
format is YYMMDD HHMMSS.  For example 24th April 1996 at 14:20:26 GMT is
designated like this (see the files in the package which you can copy
into place):

    960424 142026

The files will automatically be updated in future.  Please remember to
set them to a just couple of hours into the past (in GMT) or you may get
a deluge of news when you first log in.  In use, slurp may sometimes use
these files to also contain a list of specific message IDs to download.


4D General C News set up
------------------------
The configuration in this section needs to be performed as user news.

* /var/lib/news/whoami is used to construct the Path: header in your
news posts.  It should contain your fully-qualified domain name (FQDN):

    <YOUR_HOST_NAME>.demon.co.uk

Use your (single-word) hostname in place of <YOUR_HOST_NAME> here and
throughout this package.

* /var/lib/news/organization is used in the Organization: header of your
news posts.  It may contain any suitable string, for example:

    A Private Internet Host

* /var/lib/news/mailname is used for e-mail replies to your news posts.
It should read:

    <YOUR_HOST_NAME>.demon.co.uk


4E Configure C News sending and receiving
-----------------------------------------
The configuration in this section needs to be performed as user news.

* /var/lib/news/sys controls how you send and receive news.  It must be
edited as follows (or copy the example file in the package into place):

    # Line indicating what we are willing to receive.
    ME:all/all

    # Route all outgoing news postings via the C News batching mechanism.
    # Exclude newsgroup general and all groups with local distribution.  
    demon/news.demon.co.uk:all,!general/all,!local:fL

This file specifies that you accept all incoming news, and pass all of
your locally-generated news to the C News batching process, except for
posts to news group general and all posts marked "Distribution: local".

This set-up makes news group general a newsgroup that is completely
local to your site and does not propagate anywhere else (whatever
distribution you specify).  Making the distribution "local" for any
other news group has the same effect.  You may find this useful for
testing or other purposes.

* /var/lib/news/batchparms tells C News how to batch up and send out the
news created at your site.  It should be installed as follows (or copied
into place from the file in the package):

    # site    size    queue    builder    muncher    sender
    # ----    ----    -----    -------    -------    ------
    demon     300000  20       nocomp     nocomp     viamail2news

* /var/lib/news/mailpaths controls how C News will deal with outgoing
news posted to moderated news groups.  In order to pass these posts to a
mail to news gateway that knows all about moderators, it should read:

    all      %s@moderators.uu.net

* Check that these essential incoming and outgoing news spool
directories are in place, owned by user news and with group news:

    /var/spool/news/in.coming
    /var/spool/news/in.coming/bad
    /var/spool/news/out.going
    /var/spool/news/out.master

* Make a temporary spool directory for incoming news with:

    mkdir /var/spool/news/in.coming/tmp

* Make a batch spool directory for the outgoing demon feed with:

    mkdir /var/spool/news/out.going/demon

* Copy the viamail2news script from the package into the out.going/demon
directory, and make sure it is executable by user news.


4F Configure active C News newsgroups
-------------------------------------
The configuration in this section needs to be performed as user news.

* /var/lib/news/active is the list of newsgroups you store locally, with
the article numbers available in your local news database.  It should
already contain entries for general, news.announce.newusers, control and
junk.

You need the group junk to catch any news articles that arrive but can't
be otherwise filed under /var/spool/news.  You need the control group,
even if you don't want to receive news control messages, in order to be
able to issue cancel messages for news you have sent out but wish to
cancel.

* You need to create the news database directories in /var/spool/news
for the groups which are already in the active file.  To do this, run
the command:

    /usr/lib/newsbin/maint/adddirs

* Now add the remaining news groups from your slurp.sys file to the
active file with the following commands (the addgroup commands also make
the database directories in /var/spool/news):

    /usr/lib/newsbin/maint/addgroup comp.os.linux.announce m
    /usr/lib/newsbin/maint/addgroup comp.os.linux.networking y
    /usr/lib/newsbin/maint/addgroup demon.announce m
    /usr/lib/newsbin/maint/addgroup demon.ip.support y
    /usr/lib/newsbin/maint/addgroup demon.ip.support.unix y
    /usr/lib/newsbin/maint/addgroup demon.tech.unix y
    /usr/lib/newsbin/maint/addgroup demon.test y
    /usr/lib/newsbin/maint/addgroup misc.test.moderated m

NOTE:  "y" = posting allowed; "n" = posting not allowed; "m" = moderated
group; and "=another.group.name" redirects posts to another.group.name.
It is up to you to designate correctly which groups are moderated.  See
section 4N on how to check which groups are moderated.


4G News expiry and maintenance of C News
----------------------------------------
The configuration in this section needs to be performed as user news.

* /var/lib/news/explist controls your news database expiry strategy.
Leave it for now and in most cases you'll get a seven-day expire.
Decide on a strategy later and edit this file to set it up.  See the
Linux Network Administrators' Guide for details, or the C News
documentation ("man expire" etc.).

* You can update the crontab for user news to automatically expire old
news and maintain C News, by adding the following lines (from the file
./news/crontab.cnews in the package):

    # [c news] Expire C News
    59 0 * * * /usr/lib/newsbin/expire/doexpire
    30 3 * * * /usr/lib/newsbin/expire/upact
    
    # [c news] Manage C News files and report if needed
    10 8 * * * /usr/lib/newsbin/maint/newsdaily
    00 5,13,21 * * * /usr/lib/newsbin/maint/newswatch

Use "crontab -e" to directly edit the current news crontab.  Or use
"crontab -l > file" to save the current news crontab, then add the above
lines to the file and finally use "crontab file" to install it.  If
you're setting up nn, you might want to install nn's crontab entries at
the same time (see 4L)

For the first few of days you may get e-mail about errlog.o, errlog.oo
or errlog.ooo etc. not existing.  This is normal and will go away as
these files are created.  Alternatively, just execute "su news" (if
you're logged in as root), "cd /var/lib/news" and "touch errlog.o" etc.
to stop the error messages.

The set-up for cron/crontab assumes you are going to be running your
machine 24 hours per day as is usual with Unix machines.  Some of the
commands are executed in the early hours of the morning (e.g. doexpire
at 00:59 and upact at 03:30).  If you wish to shut down your machine
whilst it is not in use, the doexpire and upact commands above should be
run by hand, in that order, when you need to expire old news.  Run them
as user news.

If your machine gets regularly shut down, it is still worthwhile to
sometimes (say once a week) run newsdaily and newswatch (in the
background - newsdaily waits around for long periods) to tidy up or
check things.

NOTE 1:  With this set-up, some news servers regularly cause newsdaily
to e-mail the news administrator about stale/future/misdated news, or
bad headers.  I do not know the cause, but it appears to be harmless.

NOTE 2:  If newsdaily ever complains about bad news batches, look in
/var/spool/news/in.coming/bad and move the files there up to in.coming.
In most cases the news will be sent correctly on its way the next time
news is downloaded.

NOTE 3:  Please avoid using times in crontab between 01:00 and 02:59.
On two days of the year, tasks scheduled at or between these local times
may execute either twice or not at all.


4H Final C News configuration matters
-------------------------------------
The configuration in this section needs to be performed as user root.
If you previously used su to become news, type "exit" to go back to
being root.

* For Slackware 2.2 only, fix a bug in /var/lib/news/bin/config, where
the following line:

    NEWSPATH=${NEWSPATH-/bin:/usr/bin:/sbin:/usr/sbin}

must be corrected to:

    NEWSPATH=${NEWSPATH-/bin:/usr/bin:/usr/sbin:/sbin}

* Install a missing file, /var/lib/news/setnewsids.  For Slackware 2.1,
copy setnewsids.21 from the package into place as setnewsids.  For
Slackware 2.2, 2.3 or 3.0, copy setnewsids.22 instead.  Check that
setnewsids is owned by root ("chown root.root setnewsids" if needed),
and has the right permissions ("chmod 4755 setnewsids" if needed).

* In Slackware 2.1, 2.2 and 2.3, a bug in /usr/lib/newsbin/spacefor must
be corrected.  The line:

    . ${NEWSCONFIG-/usr/lib/news/bin/config}

must be corrected to:

    . ${NEWSCONFIG-/var/lib/news/bin/config}

* To allow news articles posted at your site to be inserted immediately
into your local news database, insert a missing option in a call to
newsspool towards the end of /usr/lib/newsbin/inject/injnews.  About 12
lines from the end you will find:

    newsspool -g 0 <$censart                # TODO: pass relayopts

Insert "$relayopts" to change the line to:

    newsspool $relayopts -g 0 <$censart     # TODO: pass relayopts

* Edit /usr/lib/newsbin/input/newsrun to change "sleep 45" to "sleep 5"
(near the end).  This speeds up processing in a simple installation such
as this.

* If you want to force C News to add the optional "Lines:" header, see
the comments near the end of /usr/lib/newsbin/inject/pnews for how to do
this.

* In /etc/rc.d/rc.local, add these lines to clean up news at boot time:

    echo "Cleaning up c news ..."
    /bin/su news -c /usr/lib/newsbin/maint/newsboot


4I Signature
------------
The text (up to the first four lines) in the file .signature in your
home directory will be added to the end of news posts as a signature.


4J A note on C News file ownership
----------------------------------
The canonical way to run C News is to make sure that news is the owner
and group of all news spool and configuration files and directories.
That is:

FILE(S) OR DIRECTORY(IES)           OWNER   GROUP   OTHER REQUIREMENTS
-------------------------           -----   -----   ------------------
/var/spool/news                     news    news    -
/var/spool/news/...                 news    news    -
/var/lib/news                       news    news    -
/var/lib/news/...                   news    news    -

The news executables in /usr/lib/newsbin may have owner.group set to any
reasonable values, such as root.root, root.bin or news.news, as long as
all users can read and execute them.  This also applies to the
executable file inews in the configuration directory /var/lib/news which
does not actually have to be news.news as stated in the above table.

HOWEVER the following exceptions are VERY important:

FILE(S) OR DIRECTORY(IES)           OWNER   GROUP   OTHER REQUIREMENTS
-------------------------           -----   -----   ------------------
/var/lib/news/setnewsids            root    (any)   setuid
/usr/lib/newsbin/relay/relaynews    news    news    setuid + setgid
/usr/lib/newsbin/input/newsspool    news    news    setuid + setgid

(any) = root, bin or news (normally).

User news and group news should be present in /etc/passwd and /etc/group
and should not be used for anything other than news processing.

In the end, ownership of the news files seems to cause most of the main
problems with C News.  Change ownership with chown and chgrp; change
permissions (including setuid and setgid) with chmod.


4K Set up nn
------------
News readers trn and tin (see the note below) are alternatives, but this
section assumes you are setting up nn.  You must do this as user root.

* Fix the ownership of /usr/lib/nn with: 

    chown news.news /usr/lib/nn

* For Slackware 2.2 only, fix the permissions of /var/tmp with: 

    chmod 1777 /var/tmp

* For Slackware 3.0 only, fix a link to the wrong inews with:

    cd /usr/bin
    rm inews
    ln -s ../lib/newsbin/inject/inews inews

* Initialize a new central nn threading database in /var/spool/nn with: 

    /usr/lib/nn/nnmaster -I

NOTE: the option is -I, not -l. When asked to confirm with "OK", do so.

* Now synchronize nn's central threading database with the C News
database in /var/spool/news (even though this may be empty) with:

    /usr/lib/nn/nnmaster

If you are installing nn with a large C News database already in place,
the process may take a long time.  For me it takes about 15 minutes, but
for a brand new installation it takes almost no time at all.

* The nn subject database (/var/spool/nn/subjects) is then updated with:

    su news -c /usr/lib/nn/nnspew

When you first run nn to read news, it will set up your ~/.newsrc file
to list all of the news groups in the active file.  This file contains
the groups you want to read and the records of which articles you have
already read.  You should edit it to suit your requirements.  A !
instead of a : after a group name unsubscribes you from that group.  New
groups you add later to C News (see 4N) are added automatically to your
~/.newsrc.

A NOTE on tin:  I don't use tin myself, but you should be able to use
tin straight out of the box.  Simply ignore the instructions above
(except for the fix to /var/tmp); skip section 4L below; and delete all
commands except newsrun from inside the braces at the end of "procnews"
(see section 4M).  Used this way, tin maintains its threading database
under directory .tin in each user's home directory.  If you have more
than a couple of users, it is probably better to get tin to maintain a
single copy of this database centrally, like nn.  The tin manpage will
explain this and will clarify other matters on tin use and maintenance.


4L nn maintenance
-----------------
* Update the crontab for news (use "su news" and "crontab -e"), to
maintain nn by adding the following lines (from ./news/crontab.nn in the
package):

    # [nn] Stash a copy of the active file for nngoback (keep the last 7)
    0 3 * * * /usr/lib/nn/back_act 7

    # [nn] Expire nn several hours after the news database
    0 4 * * * /usr/lib/nn/nnmaster -Fk ""

    # [nn] Keep up to date the nn subject database
    0 5 * * * /usr/lib/nn/nnspew
 
If you're running a news reader other than nn, you must substitute those
entries for nn with any required for maintaining your own news reader.

If your machine doesn't expire news automatically because it gets
regularly turned off, run the above commands in order after you manually
expire news.


4M Automate news processing
---------------------------
* As user root, link news processing with the BASE package (network)
set-up by installing this file from the package:

    /usr/local/sbin/procnews

* Edit /usr/local/sbin/start.dip to uncomment and enable the procnews
call.

The procnews script calls sendbatches to send out news from this site,
then slurp to bring in a batch of news.  It then puts the news into the
C News database (with newsrun) before finally updating nn's threading
database (with nnmaster and nnspew).  If you are not running nn, remove
the nnmaster and nnspew commands from inside the braces at the end of
procnews.


4N Summary and notes
--------------------
C News and nn should now be working.  Read news with "nn"; post news
with "nnpost".  See "man nn" for details.

To send and receive news, procnews gets called from start.dip when you
log on, but root can run "procnews", "procnews news", "procnews
news.demon.co.uk", "procnews pubnews" etc. manually whilst on-line, as
long as no other copy of procnews is running, and the news server is set
up as shown in section 4C.

To change news server either (i) edit procnews to change the default
news server there from news.demon.co.uk to another (pubnews.demon.co.uk,
for example), or (ii) edit start.dip to call "procnews pubnews" or
similar instead of just running "procnews".  Again, if you haven't done
so already, you must also set up the new news server as described in
section 4C.

To add a new news group, become user news with "su news", add the group
to the slurp.sys file (for all relevant news servers) and then run an
addgroup as in section 4F.  Back as root with "exit", run
/usr/lib/nn/nnmaster to tell nn about the new group (or wait until
nnmaster runs after the next news download).  You will be unable to use
nn with the new group until nnmaster runs and tells nn about it.

To delete a group, become news and remove the name from slurp.sys, so
you don't download it.  You will, however, still see cross-posted
articles.  To stop this, use "/usr/lib/newsbin/maint/delgroup
news.group.name" as well.

Locally posted news will not be seen by nn until /usr/lib/nn/nnmaster
runs to update the nn threading database.  This runs after a download,
but it does not mean you downloaded your own articles.  You could run
nnmaster manually or from a crontab entry to periodically inform nn of
new local posts or new groups.  Tin will see local posts immediately.

Local posts or incoming news batches may occasionally appear in
/var/spool/news/in.coming/bad.  The news maintenance commands in the
news crontab will notify you.  Usually, just moving the file(s) up to
/var/spool/news/in.coming and running "/usr/lib/newsbin/input/newsrun"
(both as user news) will send these batches correctly on their way.

If you wish to get a current list of the newsgroups the news server
knows, when on-line you can run:

    telnet news.demon.co.uk nntp | tee <FILENAME>

and then issue the command "LIST".  The server will send a list of all
groups it knows and these will be captured in <FILENAME>.  This may take
a couple of minutes or more depending on how busy things are at Demon.
Type "QUIT" after the list is complete (when a line with a single dot
appears).  Alternatively, a list is maintained daily on ftp.demon.co.uk
in /pub/news/active*, which you can get by ftp,

This list, however you get it, will also tell you which groups the
server thinks are moderated and which are not.

Finally, if you find you are having problems with C News, look for clues
in log files like /var/lib/news/log, batchlog, errlog, errlog.o etc.


4P Files in this package
------------------------

File name (Slackware)                    Location in this package
=====================                    ========================
/usr/local/man/man1/slurp.1              cnews/slurp.1
/var/lib/news/batchparms                 cnews/batchparms
/var/spool/cron/crontabs/news            cnews/crontab.cnews
/var/spool/cron/crontabs/news            cnews/crontab.nn
/var/lib/news/setnewsids                 cnews/setnewsids.21 (*)
/var/lib/news/setnewsids                 cnews/setnewsids.22 (**)
/var/lib/news/slurp.news.demon.co.uk     cnews/slurp.news.demon.co.uk
/var/lib/news/slurp.pubnews.demon.co.uk  cnews/slurp.pubnews.demon.co.uk
/var/lib/news/slurp.sys                  cnews/slurp.sys
/var/lib/news/sys                        cnews/sys
/var/spool/news/out.going/demon/viamail2news  cnews/viamail2news
/usr/local/sbin/procnews                 cnews/procnews
/usr/local/sbin/slurp                    cnews/slurp-aout (+)
/usr/local/sbin/slurp                    cnews/slurp-elf  (++)

*  For Slackware 2.1 only.          ** For Slackware 2.2, 2.3 or 3.0.
+  For Slackware 2.1, 2.2 or 2.3.   ++ For Slackware 3.0 only.

END OF README4