%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%                       Legal Notice                            %
%                                                               %
% This document is copyright (C) Olaf Kirch, okir@monad.swb.de  %
%                                                               %
% For copying conditions, please refer to the file COPYING.	%
%                                                               %
% The author is not liable for any damages, direct or indirect, %
% resulting from the use of information provided in this        %
% document.                                                     %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% When viewing this document with vi on an 80-columns screen,   %
% do a ':se nonumber' first.                                    %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Newsreader Configuration}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{newsreaders}
\index{news!reader|see {newsreader}}
\index{newsreader!configuring}
\index{configuring!newsreader}

Newsreaders are intended to offer the user functionality that allows her
to access the functions of the news system easily, like posting
articles, or skimming the contents of a newsgroup in a comfortable way.
The quality of this interface is subject of endless flame wars.


There are a couple of newsreaders available which have been ported to
\linux{}. Below I will describe the basic setup for the three most
popular ones, namely \prog{tin}, \prog{trn}, and \prog{nn}.


One of the most effective newsreaders is

\begin{tscreen}
\begin{verbatim}
$ find /var/spool/news -name '[0-9]*' -exec cat {} \; | more
\end{verbatim}
\end{tscreen}

This is the way \unix{} die-hards read their news.


The majority of newsreaders, however, are much more sophisticated.
They usually offer a full-screen interface with separate levels for
displaying all groups the user has subscribed to, for displaying an
overview of all articles in one group. and for individual articles.


At the newsgroup level, most newsreaders display a list of articles,
showing their subject line, and the author. In big groups, it is impossible
for the user to keep track of articles relating to each other, although
it is possible to identify responses to earlier articles.


\index{newsreader!threading}
\index{news!follow-up}
A response usually repeats the original article's subject, prepending it
with ``\term{Re: }''. Additionally, the message id of the article it is
a direct follow-up to may be given in the \mhdr{References:} header
line. Sorting articles by these two criteria generates small clusters
(in fact, trees) of articles, which are called \emph{threads}. One of the
tasks in writing a newsreader is devising an efficient scheme of
threading, because the time required for this is proportional to the
square of the number of articles.


Here, we will not dig any further into how the user interfaces are
built. All newsreaders currently available for \linux{} have a good help
function, so you ought to get along.


In the following, we will only deal with administrative tasks. Most of
these relate to the creation of threads databases and accounting.


\section{\prog{tin} Configuration}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{newsreaders.tin}
\index{newsreader!tass@\prog{tass}}
\index{newsreader!tin@\prog{tin}}
\index{tass@\prog{tass}}
\index{tin@\prog{tin}}

The most versatile newsreader with respect to threading is \prog{tin}.
It was written by Iain Lea and is loosely modeled on an older newsreader
named \prog{tass}.\footnote{
 Written by Rich Skrenta.
} It does its threading when the user enters the newsgroup, and it is
pretty fast at this unless you're doing this via NNTP.


\index{newsreader!threading}
\index{INN}
On an 486DX50, it takes roughly 30 seconds to thread 1000 articles when
reading directly from disk.  Over NNTP to a loaded news server, this
would be somewhere above 5 minutes.\footnote{
 Things improve drastically if the NNTP
 server does the threading itself, and lets the client retrieve the
 threads databases; INN-1.4 does this, for instance.
} You may improve this by regularly updating your index file with the
\option{-u} option, or by invoking \prog{tin} with the \option{-U}
option.


Usually, \prog{tin} dumps its threading databases in the user's
home directory below \file{.tin/index}. This may however be costly
in terms of resources, so that you should want to keep a single copy
of them in a central location. This may be achieved by making \prog{tin}
setuid to \user{news}, for example, or some entirely unprivileged
account.\footnote{
 However, do \emph{not} use \user{nobody} for this. As a rule, no files
 or commands whatsoever should be associated with this user.
} \prog{tin} will then keep all thread databases below
\file{/var/spool/news/.index}.
For any file access or shell escape, it will reset its effective uid to
the real uid of the user who invoked it.\footnote{
 This is the reason why you will get ugly error messages when invoking
 it as super user. But then, you shouldn't work as \user{root}, anyway.
}


\index{newsreader!creating thread databases}
A better solution is to install the \prog{tind} indexing daemon that
runs as a daemon and regularly updates the index files.  This daemon is
however not included in any release of \linux, so you would have to
compile it yourself. If you are running a LAN with a central news
server, you may even run \prog{tind} on the server and have all clients
retrieve the index files via NNTP. This, of course, requires an
extension to NNTP. Patches for \prog{nntpd} that implement this
extension are included in the \prog{tin} source.


The version of \prog{tin} included in some \linux{} distributions has no
NNTP support compiled in, but most do have it now.  When invoked as
\prog{rtin} or with the \option{-r} option, \prog{tin} tries to connect
to the NNTP server specified in the file \file{/etc/nntpserver} or in
the \shellvar{NNTPSERVER} environment variable.  The \file{nntpserver}
file simply contains the server's name on a single line.


\section{\prog{trn} Configuration}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{newsreaders.trn}
\index{newsreader!trn@\prog{trn}}
\index{trn@\prog{trn}}

\prog{trn} is the successor to an older newsreader, too, namely
\prog{rn} (which means \emph{read news}). The ``t'' in its name stands
for ``threaded''.  It was written by Wayne Davidson.


\index{newsreader!creating thread databases}
Unlike \prog{tin}, \prog{trn} has no provision for generating its
threading database at run-time. Instead, it uses those prepared by a
program called \prog{mthreads} that has to be invoked regularly from
\prog{cron} to update the index files.


\index{mthreads@\prog{mthreads}}
Not running \prog{mthreads}, however, doesn't mean you cannot access new
articles, it only means you will have all those ``Novell buys out
Linix!!'' articles scattered across your article selection menu,
instead of a single thread you may easily skip.


To turn on threading for particular newsgroups, \prog{mthreads} is
invoked with the list of newsgroups on the command line.  The list is
made up in exactly the same fashion as the one in the \file{sys} file:


\begin{tscreen}
\begin{verbatim}
mthreads comp,rec,!rec.games.go
\end{verbatim}
\end{tscreen}


\noindent
will enable threading for all of \ngrp{comp} and \ngrp{rec}, except for
\ngrp{rec.games.go} (people who play Go don't need fancy threads). After
that, you simply invoke it without any option at all to make it thread
any newly arrived articles.  Threading of all groups found in your
\file{active} file can be turned on by invoking \prog{mthreads} with a
group list of \ngrp{all}.


If you're receiving news during the night, you will customarily run
\prog{mthreads} once in the morning, but you can also to do so more
frequently if needed.  Sites that have very heavy traffic may want to
run \prog{mthreads} in daemon mode.  When it is started at boot time using
the \option{-d} option, it puts itself in the background, and wakes up
every 10~minutes to check if there are any newly-arrived articles, and
threads them. To run \prog{mthreads} in daemon mode, put the following
line in your \file{rc.news} script:


\begin{tscreen}
\begin{verbatim}
/usr/local/bin/rn/mthreads -deav
\end{verbatim}
\end{tscreen}


The \option{-a} option makes \prog{mthread} automatically turn on threading
for new groups as they are created; \option{-v} enables verbose log
messages to \prog{mthreads}' log file, \file{mt.log} in the directory
where you have \prog{trn} installed.


\index{C News!update low water mark}
\index{news!expiring}
Old articles no longer available must be removed from the index files
regularly.  By default, only articles whose number is below the low
water mark will be removed.\footnote{
 Note that C~news doesn't update this low water mark automatically;
 you have to run \prog{updatemin} to do so. Please refer to
 chapter~\ref{cnews}.
} Articles above this number who have been expired nevertheless (because
the oldest article has been assigned an long expiry date by an
\mhdr{Expires:} header field) may be removed by giving \prog{mthreads}
the \option{-e} option to force an ``enhanced'' expiry run. When
\prog{mthreads} is running in daemon mode, the \option{-e} option makes
it put in such an enhanced expiry run once a day, shortly after
midnight.


\section{\prog{nn} Configuration}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{newsreaders.nn}
\index{newsreader!nn@\prog{nn}}
\index{nn@\prog{nn}}
\index{Storm, Kim F.}

\prog{nn}, written by Kim~F. Storm, claims to be a newsreader whose
ultimate goal is not to read news. It's name stands for ``No News'', and
its motto is ``No news is good news. \prog{nn} is better.''


To achieve this ambitious goal, \prog{nn} comes along with a large
assortment of maintenance tools that not only allow generation of
threads, but also extensive checks on the consistency of these
databases, accounting, gathering of usage statistics, and access
restrictions. There is also an administration program called
\prog{nnadmin}, which allows you to perform these tasks interactively.
It is very intuitive, hence we will not dwell on these aspects, and only
deal with the generation of the index files.


\index{newsreader!creating thread databases}
The \prog{nn} threads database manager is called \prog{nnmaster}.  It is
usually run as a daemon, started from the \file{rc.news} or
\file{rc.inet2} script.  It is invoked as


\begin{tscreen}
\begin{verbatim}
/usr/local/lib/nn/nnmaster -l -r -C
\end{verbatim}
\end{tscreen}


This enables threading for all newsgroups present in your \file{active}
file.


Equivalently, you may invoke \prog{nnmaster} periodically from
\prog{cron}, giving it a list of groups to act upon. This list is very
similar to the subscription list in the \file{sys} file, except that it
uses blanks instead of commas. Instead of the fake group name
\ngrp{all}, an empty argument of \term{\dqt\dqt} should be used to
denote all groups.  A sample invocation is


\begin{tscreen}
\begin{verbatim}
# /usr/local/lib/nn/nnmaster !rec.games.go rec comp
\end{verbatim}
\end{tscreen}


Note that the order is significant here: The leftmost group
specification that matches always wins. Thus, if we had put
\keyword{!rec.games.go} after \keyword{rec}, all articles from this
group had been threaded nevertheless.


\index{news!expiring}
\prog{nn} offers several methods to remove expired articles from its
databases.  The first is to update the database by scanning the news
group directories and discarding the entries whose corresponding article
is no longer available.  This is the default operation obtained by
invoking \prog{nnmaster} with the \option{-E} option. It is reasonably
fast unless you're doing this via NNTP.  


Method~2 behaves exactly like a default expiry run of \prog{mthreads},
in that it only removes those entries that refer to articles whose
number is below the low water mark in the \file{active} file. It may be
enabled using the \option{-e} option.


Finally, a third strategy is to discard the entire database and
recollect all articles. This may be done by giving \option{-E3} to
\prog{nnmaster}.


The list of groups to be expired is given by the \option{-F} option in
the same fashion as above.  However, if you have \prog{nnmaster} running
as daemon, you must kill it (using \option{-k}) before expiry can take
place, and to re-start it with the original options afterwards.  Thus
the proper command to run expire on all groups using method~1 is:


\begin{tscreen}
\begin{verbatim}
# nnmaster -kF ""
# nnmaster -lrC
\end{verbatim}
\end{tscreen}


There are many more flags that may be used to fine-tune the behavior of
\prog{nn}. If you are concerned about removing bad articles or
digestifying article digests, read the \prog{nnmaster} manual page.


\prog{nnmaster} relies on a file named \file{GROUPS}, which is located
in \file{/usr/local/lib/nn}. If it does not exist initially, it is
created.  For each newsgroup, it contains a line that begins with the
group's name, optionally followed by a time stamp, and flags. You may
edit these flags to enable certain behavior for the group in question,
but you may not change the order in which the groups appear.\footnote{
 This is because their order has to agree with that of the entries in the
 (binary) \file{MASTER} file.
} The flags allowed and their effects are detailed in the
\prog{nnmaster} manual page, too.

