%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%                       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.                                    %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%               S T A R T   O F   C H A P T E R                 %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\def\newslib{\file{/usr/lib/news}}
\def\newsbin{\file{/usr/lib/news/bin}}
\def\newsspool{\file{/var/spool/news}}

\chapter{C~News}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% How C~News works                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews}
\index{C News|(}

One of the most popular software packages for Netnews is C~News. It was
designed for sites that carry news over UUCP links. This chapter
will discuss the central concepts of C~News, and the basic installation
and maintenance tasks.


\index{C News!spool directory}
C~News stores its configuration files in \newslib{}, and most of its
binaries in the \newsbin{} directory.  Articles are kept below
\newsspool. You should make sure virtually all files in these
directories are owned by user \user{news}, group \user{news}. Most
problems arise from files being inaccessible to C~News. Make it a rule
for you to become user \user{news} using \prog{su} before you touch
anything in there.  The only exceptions is \prog{setnewsids}, which is
used to set the real user id of some news programs. It must be owned by
\user{root} and must have the setuid bit set.


In the following, we describe all C~News configuration files in detail,
and show you what you have to do to keep your site running.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Delivering News}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.rnews}
\index{inews@\prog{inews}}
\index{rnews@\prog{rnews}}

\index{delivering!news}
Articles may be fed to C~News in several ways. When a local user posts an
article, the newsreader usually hands it to the \prog{inews} command,
which completes the header information. News from remote sites, be it a
single article or a whole batch, is given to the \prog{rnews} command,
which stores it in the \newsspool\file{in.coming} directory, from where
it will be picked up at a later time by \prog{newsrun}. With any of
these two techniques, however, the article will eventually be handed to
the \prog{relaynews} command.


\index{C News!relaynews@\prog{relaynews}}
\index{C News!history file@\file{history} file}
\index{C News!active file@\file{active} file}
\index{news!active file@\file{active} file}
\index{news!history}
\index{C News!receiving news|(}
\index{news!message id}
For each article, the \prog{relaynews} command first checks if the
article has already been seen at the local site by looking up the
message id in the \file{history} file. Duplicate articles will be
dropped. Then, \prog{relaynews} looks at the \mhdr{Newsgroups:} header
line to find out if the local site requests articles from any of these
groups.  If it does, and the newsgroup is listed in the \file{active}
file, \prog{relaynews} tries to store the article in the corresponding
directory in the news spool area. If this directory does not exist, it
is created.  The article's message id will then be logged to the
\file{history} file.  Otherwise, \prog{relaynews} drops the article.


\index{junk newsgroup@\ngrp{junk} newsgroup}
If \prog{relaynews} fails to store an incoming article because a group
it has been posted to is not listed in your \file{active} file, the
article will be moved to the \ngrp{junk} group.\footnote{
  There may be a difference between the groups that exist at your site,
  and those that your site is willing to receive. For example, the
  subscription list may specify \ngrp{comp.all}, which means all
  newsgroups below the \ngrp{comp} hierarchy, but at your site, only a
  number of \ngrp{comp} groups are listed in \file{active}. articles
  posted to those groups will be moved to \ngrp{junk}.
} \prog{relaynews} will also check for stale or misdated articles and
reject them. Incoming batches that fail for any other reason are moved
to \newsspool\file{/in.coming/bad}, and an error message is logged.


After this, the article will be relayed to all other sites that request
news from these groups, using the transport specified for each
particular site. To make sure it isn't sent to a site that already has
seen it, each destination site is checked against the article's
\mhdr{Path:} header field, which contains the list of sites the article
has traversed so far, written in bang path style.  Only if the
destination site's name does not appear in this list will the article be
sent to it.


\index{C News!UUCP}
\index{UUCP!news}
C~News is commonly used to relay news between UUCP sites, altough it is
also possible to use it in a NNTP environment. To deliver news to a remote
UUCP site~--- either single articles or whole batches~--- \prog{uux}
is used to execute the \prog{rnews} command on the remote site, and
feed the article or batch to it on standard input.


\index{C News!batching}
\index{news!batching}
When batching is enabled for a given site, C~News does not send any
incoming article immediately, but appends its path name to a file,
usually \file{out.going/\var{site}/togo}.  Periodically, a batcher
program is executed from a crontab entry,\footnote{
  Note that this should be the crontab of \user{news}, in order not
  to mangle file permissions.
} which puts the articles in one or more files, optionally compresses
them, and sends them to \prog{rnews} at the remote site.


Figure~\ref{cnews.fig.flow} shows the news flow through
\prog{relaynews}. Articles may be relayed to the local site (denoted by
\keyword{ME}), to some site named \host{ponderosa} via email, and a site
named \host{moria}, for which batching is enabled.


\begin{figure}[htbp]
\iftex
 \ifps
  \begin{center}
   \mbox{\epsffile{figures/flow.epsf}}
  \end{center}
 \else
  \begin{center}
   \input{flow.eepic}
  \end{center}
 \fi
\else
 \verbinclude{flow.ascii}
\fi
 \caption{
  \label{cnews.fig.flow}
  News flow through \prog{relaynews}.
 }
\end{figure}

\index{C News!receiving news|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Installation}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{configuring!C News|(}
\index{configuring!Usenet news|(}

To install C~News, untar the files into their proper places if you
haven't done so yet, and edit the configuration files listed below.
They are all located in \newslib.  Their formats will be described in
the following sections.

\begin{dispitems}
\ditem[\file{sys}]
        \index{C News!sys file@\file{sys} file}
        You probably have to modify the \keyword{ME} line that describes
        your system, although using \keyword{all/all} is always a safe
        bet. You also have to add a line for each site you feed news to.

        If you are a leaf site, you only need a line that sends all
        locally generated articles to your feed.  Assume your feed is
        \host{moria}, then your \file{sys} file should look like this:

        %% Can't use verbatim env here. Latex2e don't like linuxdoc.sty
        \begin{tscreen}
	  ME:all/all::\\
	  moria/moria.orcnet.org:all/all,!local:f:
        \end{tscreen}

\ditem[\file{organization}]
        Your organization's name. For example, ``\term{Virtual Brewery,
        Inc.}''.  On your home machine, enter ``private site'', or
        anything else you like.  Most people will not call your site
        properly configured if you haven't customized this file.

\ditem[\file{newsgroups}]

\ditem[\file{mailname}]
        Your site's mail name, e.g. \host{vbrew.com}.

\ditem[\file{whoami}]
        Your site's name for news purposes. Quite often, the UUCP site
        name is used, for example \host{vbrew}.

\ditem[\file{explist}]
	You should probably edit this file to reflect your preferred
	expiry times for some special newsgroups. Disk space may play an
	important role in it.

\end{dispitems}


\index{C News!create initial configuration}
\index{C News!active file@\file{active} file|(}
\index{C News}
To create an initial hierarchy of newsgroups, obtain an \file{active}
and a \file{newsgroups} file from the site that feeds you, and install
them in \newslib, making sure they are owned by news and have a mode of
644. Remove all \ngrp{to.*} groups from the active file, and add
\ngrp{to.}\var{mysite} and \ngrp{to.}\var{feedsite}, as well as
\ngrp{junk} and \ngrp{control}. The \ngrp{to.*} groups are normally used
for exchanging ihave/sendme messages, but you should create them
regardless of whether you plan to use ihave/sendme or not.  Next,
replace all article numbers in the second and third field of
\file{active} using the following command:


\begin{tscreen}
\begin{verbatim}
# cp active active.old
# sed 's/ [0-9]* [0-9]* / 0000000000 00001 /' active.old > active
# rm active.old
\end{verbatim}
\end{tscreen}


The second command is an invocation of \prog{sed(1)}, one of my
favorite \unix{} commands. This invocation replaces two strings of digits
with a string of zeroes and the string \term{000001}, respectively.


Finally, create the news spool directory and the subdirectories used for
incoming and outgoing news:


\begin{tscreen}
\begin{verbatim}
# cd /var/spool
# mkdir news news/in.coming news/out.going
# chown -R news.news news
# chmod -R 755 news
\end{verbatim}
\end{tscreen}


If you're using a later release of C~News, you may also have to create
the \file{out.master} directory in the news spool directory.


If you're using newsreaders from a different distribution than the C~News
you have running, you may find that some expect the news spool on
\file{/usr/spool/news} rather than in \file{/var/spool/news}. If your
newsreader doesn't seem to find any articles, create a symbolic
from \file{/usr/spool/news} to \file{/var/spool/news}.


Now, you are ready to receive news. Note that you don't have to create
any directories other than those shown above, because each time C~News
receives an article from a group for which there's no spool directory
yet, it will create it.


In particular, this happens to \emph{all} groups an article has
been crossposted to. So, after a while, you will find your news spool
cluttered with directories for newsgroups you have never subscribed
to, like \ngrp{alt.lang.teco}. You may prevent this by either removing
all unwanted groups from \file{active}, or by regularly running a
shell script which removes all empty directories below \newsspool{}
(except \file{out.going} and \file{in.coming}, of course).

\index{C News!active file@\file{active} file|)}


\index{C News!usenet@\user{usenet}}
\index{C News!newsmaster}
\index{news!newsmaster}
\index{newsmaster}
C~News needs a user to send error messages and status reports to.  By
default, this is \user{usenet}. If you use the default, you have to set
up an alias for it which forwards all of its mail to one or more
responsible persons.  (Chapters~\ref{smail} and~\ref{sendmail} explain
how to do so for \prog{smail} and \prog{sendmail}).  You may also
override this behavior by setting the environment variable
\keyword{NEWSMASTER} to the appropriate name.  You have to do so in
\user{news}' crontab file, as well as every time you invoke an
administrative tool manually, so installing an alias is probably easier.


\index{passwd@\file{passwd}!real user names}
\index{real user names}
\index{full user names}
While you're hacking \file{/etc/passwd}, make sure that every user has 
her real name in the \keyword{pw\_gecos} field of the password file (this
is the fourth field). It is a question of Usenet netiquette that the
sender's real name appears in the \mhdr{From:} field of the article.
Of course, you will want to do so anyway when you use mail.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The {\protect\tt sys} file}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.sys}
\index{C News!sys file@\file{sys} file|(}

The \file{sys} file, located in \newslib, controls which
hierarchies you receive and forward to other sites. Although there
are maintenance tools named \prog{addfeed} and \prog{delfeed}, I think
it's better to maintain this file by hand.


The \file{sys} file contains entries for each site you forward news to,
as well as a description of the groups you will accept.
An entry looks like


\begin{tscreen}
\var{site}[/\var{exclusions}]:\var{grouplist}[/\var{distlist}][:\var{flags}[:\var{cmds}]]
\end{tscreen}


Entries may be continued across newlines using a backslash (\keyword{\bs}).
A hash sign (\keyword{\#}) denotes a comment.


\begin{dispitems}
\ditem[\var{site}]
	This is the name of the site the entry applies to. One usually
	chooses the site's UUCP name for this.  There has to be an entry
	for your site in the \file{sys} file, too, else you will not
	receive any articles yourself.


	\index{C News!receiving news}
	\index{receiving news}
	\index{news!receiving}
	The special site name \keyword{ME} denotes your site. The
	\keyword{ME} entry defines all groups you are willing to store
	locally. Articles that aren't matched by the \keyword{ME} line
	will go to the \ngrp{junk} group.


	\index{C News!excluding sites}
	\index{C News!hostname aliases}
	\index{alias!and C News}
	Since C~News checks \var{site} against the site names in
	the \mhdr{Path:} header field, you have to make sure they really
	match. Some sites use their fully qualified domain name in this
	field, or an alias like \ngrp{news.}\var{site.domain}. To prevent
	any articles from being returned to these sites, you have to add
	these to the exclusion list, separated by commas.


	For the entry applying to site \host{moria}, for instance, the
	site field would contain \host{moria/}\host{moria.orcnet.org}.

\ditem[\var{grouplist}]
	\index{C News!exchanging news}
	\index{C News!limit a feed}
	This is a comma-separated subscription list of groups and
	hierarchies for that particular site. A hierarchy may be specified
	by giving the hierarchy's prefix (such as \ngrp{comp.os}
	for all groups whose name starts with this prefix), optionally
	followed by the keyword \ngrp{all} (e.g. \ngrp{comp.os.all}).


	A hierarchy or group is excluded from forwarding by preceding it
	with an exclamation mark. If a newsgroup is checked against the
	list, the longest match applies. For example, if \var{grouplist}
	contains

	\begin{tscreen}
	!comp,comp.os.linux,comp.folklore.computers
	\end{tscreen}

	\noindent
        no groups from the \ngrp{comp} hierarchy except
	\ngrp{comp.folklore.computers} and all groups below
	\ngrp{comp.os.linux} will be fed to that site.


	If the site requests to be forwarded all news
	you receive yourself, enter \keyword{all} as \var{grouplist}.


\ditem[\var{distlist}]
	\index{C News!limit a feed}
	\index{C News!limit a feed}
	\index{news!distributions}
	is offset from the \var{grouplist} by a slash, and contains a
	list of distributions to be forwarded.  Again, you may exclude
	certain distributions by preceding them with an exclamation
	mark. All distributions are denoted by \keyword{all}. Omitting
	\var{distlist} implies a list of \keyword{all}.


	For example, you may use a distribution list of
	\keyword{all,!local} to prevent news for local use only from
	being sent to remote sites.


	There are usually at least two distributions: \keyword{world},
	which is often the default distribution used when none is
	specified by the user, and \keyword{local}. There may be other
	distributions that apply to a certain region, state, country,
	etc. Finally, there are two distributions used by C~News only;
	these are \keyword{sendme} and \keyword{ihave}, and are used for
	the sendme/ihave protocol.


	The use of distributions is a subject of debate. For one, some
	newsreaders create bogus distributions by simply using the top
	level hierarchy, for example \ngrp{comp} when posting to
	\ngrp{comp.os.linux}.  Distributions that apply to regions are
	often questionable, too, because news may travel outside of your
	region when sent across the Internet.\footnote{
	  It is not uncommon for an article posted in, say Hamburg,
	  to go to Frankfurt via \host{reston.ans.net} in the 
	  Netherlands, or even via some site in the U.S.
	} Distributions applying to an organization, however, are very
	meaningful, for example to prevent confidential information from
	leaving the company network. This purpose, however, is generally
	served better by creating a separate newsgroup or hierarchy.


\ditem[\var{flags}]

	This describes certain parameters for the feed. It may be
	empty, or a combination of the following:

	\begin{dispitems}
	\ditem[\keyword{F}]
		\index{C News!batching}
		This flag enables batching.

	\ditem[\keyword{f}]
		\index{C News!batching}
		This is almost identical to the \keyword{F} flag, but allows 
		C~News to calculate the size of outgoing batches more
		precisely.

	\ditem[\keyword{I}]
		\index{C News!ihave/sendme}
		This flag makes C~News produce an article list suitable
		for use by ihave/sendme. Additional modifications to the
		\file{sys} and the \file{batchparms} file are required
		to enable ihave/sendme.

	\ditem[\keyword{n}]
		\index{C News!NNTP support}
		This creates batch files for active NNTP transfer
		clients like \prog{nntpxmit} (see chapter~\ref{nntp}).
		The batch files contain the article's filename along
		with its message id.

	\ditem[\keyword{L}]
		This tells C~News to transmit only articles posted at your
		site. This flag may be followed by a decimal number
		\var{n}, which makes C~News only transfer articles
		posted within \var{n} hops from your site. C~News
		determines the number of hops from the \mhdr{Path:} field.

	\ditem[\keyword{u}]
		This tells C~News to batch only articles from unmoderated
		groups. 

	\ditem[\keyword{m}]
		This tells C~News to batch only articles from moderated
		groups. 
	\end{dispitems}

	You may use at most one of \keyword{F}, \keyword{f},
	\keyword{I}, or \keyword{n}.

\ditem[\var{cmds}]
	\index{C News!rnews@\prog{rnews}}
	\index{C News!exchanging news}
	\index{C News!sending news}
	This field contains a command to be executed for each article,
	unless batching is enabled. The article will be fed to the
	command on standard input. This should only be used for very
	small feeds; otherwise the load on both systems will be too high.


	The default command is

	\begin{tscreen}
	 uux - -r -z \var{system}\/!rnews
	\end{tscreen}

	\noindent
	which invokes \prog{rnews} on the remote system, feeding it
	the article on standard input.


	The default search path for commands given in this field is
	\prog{/bin:/usr/bin:\newsbin/batch}. The latter directory
	contains a number of shell scripts whose name starts with
	\prog{via}; they are briefly described later in this chapter.


	\index{C News!batching}
	\index{C News!togo file@\file{togo} file}
	If batching is enabled using either of the \keyword{F} or
	\keyword{f}, \keyword{I} or \keyword{n} flags, C~News expects to
	find a file name in this field rather than a command. If the
	file name does not begin with a slash (\file{/}), it is assumed
	to be relative to \newsspool\file{/out.going}. If the field is
	empty, it defaults to \file{\var{system}\//togo}.


\end{dispitems}

When setting up C~News, you will most probably have to write your own
\file{sys} file. To help you with it, we give a sample file for
\host{vbrew.com} below, from which you might copy what you need.

\begin{tscreen}
\begin{verbatim}
# We take whatever they give us.
ME:all/all::

# We send everything we receive to moria, except for local and
# brewery-related articles. We use batching.
moria/moria.orcnet.org:all,!to,to.moria/all,!local,!brewery:f:

# We mail comp.risks to jack@ponderosa.uucp
ponderosa:comp.risks/all::rmail jack@ponderosa.uucp

# swim gets a minor feed
swim/swim.twobirds.com:comp.os.linux,rec.humor.oracle/all,!local:f:

# Log mail map articles for later processing
usenet-maps:comp.mail.maps/all:F:/var/spool/uumaps/work/batch
\end{verbatim}
\end{tscreen}

\index{C News!sys file@\file{sys} file|)}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The \prog{active} file}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.active}
\index{C News!active file@\file{active} file|(}
\index{C News!list of current groups}

The \file{active} file is located in \newslib{} and lists all groups
known at your site, and the articles currently online. You will rarely
have to touch it, but we explain it nevertheless for sake of
completeness.  Entries take the following form:

\begin{tscreen}
\var{newsgroup} \var{high} \var{low} \var{perm}
\end{tscreen}

\var{newsgroup} is, of course, the group's name.  \var{low} and
\var{high} are the lowest and highest numbers of articles currently
available.  If none are available at the moment, \var{low} is equal to
\var{high}+1.


\index{C~News!update low water mark}
At least, that's what the \var{low} field is meant to do.  However, for
efficiency reasons, C~News doesn't update this field.  This wouldn't be
such a big loss if there weren't some newsreaders that depend on it.
For instance, \prog{trn} checks this field to see if it can purge any
articles from its thread database.  To update the \var{low} field, you
therefore have to run the \prog{updatemin} command regularly (or, in
earlier version of C~News, the \prog{upact} script).


\var{perm} is a parameter detailing the access users are
granted to the group. It takes one of the following values:


\begin{dispitems}
\ditem[\keyword{y}]
        Users are allowed to post to this group.

\ditem[\keyword{n}]
        Users are not allowed to post to this group. However,
        the group may still be read.

\ditem[\keyword{x}]
        This group has been disabled locally. This happens
        sometimes when news admininistrators (or their superiors)
        take offense to articles posted to certain groups.

        Articles received for this group are not stored locally,
        although they are forwarded to the sites that request
        them.

\ditem[\keyword{m}]
        This denotes a moderated group. When a user tries to
        post to this group, an intelligent newsreader will notify
        her of this, and send the article to the moderator
        instead. The moderator's address is taken from 
        the \file{moderators} file in \newslib.

\ditem[\keyword{=\var{real-group}}]
        This marks \var{newsgroup} as being a local alias for
        another group, namely \var{real-group}. All articles
        posted to \var{newsgroup} will be redirected to it.
\end{dispitems}


In C~News, you will generally not have to access this file directly.
Groups may be added or deleted locally using \prog{addgroup} and
\prog{delgroup} (see below in section~\ref{cnews.maint}).
When groups are added or deleted for the whole of Usenet, this
is usually done by sending a \keyword{newgroup} or \keyword{rmgroup}
control message, respectively. \emph{Never send such a message yourself!}
For instructions on how to create a newsgroup, read the monthly
postings in \ngrp{news.announce.newusers}.


A file closely related to \file{active} is \file{active.times}. Whenever
a group is created, C~News logs a message to this file, containing
the name of the group created, the date of creation, whether it
was done by a \keyword{newgroup} control message or locally, and who did it.
This is for the convenience of newsreaders who may notify the user
of any recently created groups. It is also used by the
\keyword{NEWGROUPS} command of NNTP.


\index{C News!active file@\file{active} file|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Article Batching}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.batcher}
\index{C News!sending news|(}
\index{C News!batching|(}
\index{batching!news|(}
\index{news!batching}

Newsbatches follow a particular format which is the same for
Bnews, C~News, and INN. Each article is preceded by a line like this:

\begin{tscreen}
 \#! rnews \var{count}
\end{tscreen}

\noindent
where \var{count} is the number of bytes in the article. When batch
compression is used, the resulting file is compressed as a whole, and
preceded by another line, indicated by the message to be used for
unpacking. The standard compression tool is \ngrp{compress},
which is marked by

\begin{tscreen}
 \#! cunbatch
\end{tscreen}

Sometimes, when having to send batches via mail software that
removes the eighth bit from all data, a compressed batch may be
protected using what is called c7-encoding; these batches will be
marked by \prog{c7unbatch}.


When a batch is fed to \prog{rnews} on the remote site, it checks for
these markers and processes the batch appropriately.  Some sites also
use other compression tools, like \prog{gzip}, and precede their gzipped
files with \prog{zunbatch} instead.  C~News does not recognize
non-standard headers like these; you have to modify the source to
support them.


\index{sendbatches@\prog{sendbatches}}
\index{C News!sending news}
In C~News, article batching is performed by \newsbin\file{/batch/sendbatches},
which takes a list of articles from the \var{site}\file{/togo} file, and
puts them into several newsbatches.  It should be executed once per hour
or even more frequently, depending on the volume of traffic.


Its operation is controlled by the \file{batchparms} file in \newslib.
This file describes the maximum batch size allowed for each site, the
batching and optional compression program to be used, and the transport
for delivering it to the remote site. You may specify batching parameters
on a per-site basis, as well as a set of default parameters for
sites not explicitly mentioned.


To perform batching for a specific site, you invoke it as


\begin{tscreen}
 \# su news -c "\newsbin/batch/sendbatches \var{site}\/"
\end{tscreen}


\index{C News!batch parameters|(}
When invoked without arguments, \prog{sendbatches} handles all batch
queues. The interpretation of ``all'' depends on the presence of a
default entry in \file{batchparms}. If one is found, all directories in
\newsspool\file{/out.going} are checked, otherwise, it cycles through
all entries in \file{batchparms}.  Note that \prog{sendbatches}, when
scanning the \file{out.going} directory, takes only those directories
that contain no dot or at sign~(\keyword{@}) as site names.


When installing C~News, you will most likely find a \file{batchparms}
file in your distribution which contains a reasonable default entry,
so there's a good chance that you wouldn't have to touch the file.
Just in case, we describe its format nevertheless. Each line consists
of six fields, separated by spaces or tabs:

\begin{tscreen}
\var{site} \var{size} \var{max} \var{batcher} \var{muncher} \var{transport}
\end{tscreen}

\medskip
The meaning of these fields is as follows:

%\begin{dispitems}
%\ditem[\var{site}]
\var{site} is the name of the site the entry applies to. The \file{togo}
file for this site must reside in \file{out.going/togo} below the news
spool. A site name of \keyword{/default/} denotes the default entry.


%\ditem[\var{size}]
\var{size} is the maximum size of article batches created (before
compression). For single articles larger than this, C~News makes an
exception and puts them in a single batch by themselves.


%\ditem[\var{max}]
\var{max} is the maximum number of batches created and scheduled
for transfer before batching stalls for this particular site. This
is useful in case the remote site should be down for a long time,
because it prevents C~News from cluttering your UUCP spool directories 
with zillions of newsbatches.


C~News determines the number of queued batches using the \prog{queulen}
script in \newsbin. Vince Skahan's \file{newspak} release should contain
a script for BNU-compatible UUCPs. If you use a different flavor of spool
directories, for example, Taylor UUCP, you might have to write your
own.\footnote{
	If you don't care about the number of spool files (because
	you're the only person using your computer, and you don't
	write articles by the megabyte), you may replace the script's
	contents by a simple \prog{exit 0} statement.
}


%\ditem[\var{batcher}]
\index{C News!ihave/sendme}
The \var{batcher} field contains the command used for producing a
batch from the list of articles in the \file{togo} file. For regular feeds,
this is usually \prog{batcher}. For other purposes, alternative
batchers may be provided. For instance, the ihave/sendme protocol
requires the article list to be turned into ihave or sendme control
messages, which are posted to the newsgroup \ngrp{to.\var{site}}.
This is performed by \prog{batchih} and \prog{batchsm}.


%\ditem[\var{muncher}]
\index{C News!compressing batches}
The \var{muncher} field specifies the command used for compression.
Usually, this is \ngrp{compcun}, a script that produces a compressed
batch.\footnote{
  As shipped with C~News, \ngrp{compcun} uses \ngrp{compress} with the
  12~bit option, since this is the least common denominator for most
  sites. You may produce a copy of it, say \ngrp{compcun16},
  where you use 16~bit compression. The improvement is not too
  impressive, though.
} Alternatively, you might provide a muncher that uses \prog{gzip}, say
\prog{gzipcun} (to be clear: you have to write it yourself).  You have
to make sure that \prog{uncompress} on the remote site is patched to
recognize files compressed with \prog{gzip}.


If the remote site does not have an \prog{uncompress} command, you may
specify \prog{nocomp} which does not do any compression.


%\ditem[\var{transport}]
The last field, \var{transport}, describes the transport to be used.
A number of standard commands for different transports are available
whose names begin with \prog{via}. \prog{sendbatches} passes them
the destination site name on the command line.  If the \file{batchparms}
entry was not \keyword{/default/}, it derives the site name from the
\var{site} field by stripping of anything after and including the first
dot or slash.  If entry was \keyword{/default/}, the directory names in
\file{out.going} are used.


\index{rnews@\prog{rnews}}
\index{uux@\prog{uux}}
\index{C News!UUCP}
There are two commands that use \prog{uux} to execute \prog{rnews} on
the remote system; \prog{viauux} and \prog{viauuxz}. The latter sets the
\option{-z} flag for (older versions of) \prog{uux} to keep it from
returning success messages for each article delivered. Another command,
\prog{viamail}, sends article batches to the user \user{rnews} on the
remote system via mail. Of course, this requires that the remote system
somehow feeds all mail for \user{rnews} to their local news system.  For
a complete list of these transports, refer to the \file{newsbatch(8)}
manual page.

%\end{dispitems}


All commands from the last three fields must be located in either of
\file{out.going/}\var{site} or \newsbin\file{/batch}.  Most of them are
scripts, so that you may easily tailor new tools for your personal
needs. They are invoked as a pipe. The list of articles is fed to the
batcher on standard input, which produces the batch on standard output.
This is piped into the muncher, and so on.


A sample file is given below.

\begin{tscreen}
\begin{verbatim}
# batchparms file for the brewery
# site        | size   |max    |batcher  |muncher    |transport
#-------------+--------+-------+---------+-----------+-----------
/default/       100000  22      batcher   compcun     viauux
swim             10000  10      batcher   nocomp      viauux
\end{verbatim}
\end{tscreen}

\index{C News!batch parameters|)}
\index{C News!sending news|)}
\index{C News!batching|)}
\index{batching!news|)}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Expiring News}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.explist}
\index{C News!expiring|(}

In Bnews, expiring used to be performed by a program called \prog{expire},
which took a list of newsgroups as arguments, along with a time
specification after which articles had to be expired.  To have different
hierarchies expired at different times, you had to write a script that
invoked \prog{expire} for each of them separately.  C~News offers a more
convenient solution to this: in a file called \file{explist}, you may
specify newsgroups and expiration intervals.  A command called
\prog{doexpire} is usually run once a day from \prog{cron}, and
processes all groups according to this list.


\index{C News!archiving}
\index{news!archiving articles}
Occasionally, you may want to retain articles from certain groups even
after they have been expired; for example, you might want to keep
programs posted to \ngrp{comp.sources.unix}. This is called
\emph{archiving}. \file{explist} permits you to mark groups for
archiving.


An entry in \file{explist} looks like this:


\begin{tscreen}
\var{grouplist} \var{perm} \var{times} \var{archive}
\end{tscreen}


%\begin{dispitems}
%\ditem[\var{grouplist}]
\var{grouplist} is a comma-separated list of newsgroups to which
the entry applies. Hierarchies may be specified by giving the group
name prefix, optionally appended with \keyword{all}. For example, for
an entry applying to all groups below \ngrp{comp.os}, you might
either enter \ngrp{comp.os} or \ngrp{comp.os.all} in
\var{grouplist}.


When expiring news from a group, the name is checked against all
entries in \file{explist} in the order given. The first matching entry
applies. For example, to throw away the majority of \ngrp{comp} after
four days, except for \ngrp{comp.os.linux.announce} which you want
to keep for a week, you simply have an entry for the latter,
which specifies a seven-day expiration period, followed by that for
\ngrp{comp}, which specifies four days.


%\ditem[\var{perm}]
The \var{perm} field details if the entry applies to moderated,
unmoderated, or any groups. It may take the values \keyword{m},
\keyword{u}, or \keyword{x}, which denote moderated, unmoderated, or any
type.


%\ditem[\var{times}]
The third field, \var{times}, usually contains only a single number.
This is the number of days after which articles will be expired if they
haven't been assigned an artificial expiration date in an \mhdr{Expires:}
field in the article header. Note that this is the number of days counting
from its \emph{arrival} at your site, not the date of posting.


The \var{times} field may, however, be more complex than that.  It may
be a combination of up to three numbers, separated from one another by a
dash. The first denotes the number of days that have to pass before the
article is considered a candidate for expiration. It is rarely useful to
use a value other than zero. The second field is the above-mentioned
default number of days after which it will be expired. The third is the
number of days after which an article will be expired unconditionally,
regardless of whether it has an \mhdr{Expires:} field or not. If only
the middle number is given, the other two take default values. These may
be specified using the special entry \keyword{/bounds/}, which is
described below.


%\ditem[\var{archive}]
The fourth field, \var{archive}, denotes whether the newsgroup is to be
archived, and where.  If no archiving is intended, a dash should be
used.  Otherwise, you either use a full path name (pointing to a
directory), or an at sign (\keyword{@}). The at sign denotes the default
archive directory which must then be given to \prog{doexpire} by using
the \option{-a} flag on the command line.  An archive directory should
be owned by \user{news}. When \prog{doexpire} archives an article from,
say \ngrp{comp.sources.unix}, it stores it in the directory
\ngrp{comp/sources/unix} below the archive directory, creating it if not
existent. The archive directory itself, however, will not be created.
%\end{dispitems}


There are two special entries in your \file{explist} file that
\prog{doexpire} relies on.  Instead of a list of newsgroups, they have
the keywords \keyword{/bounds/} and \keyword{/expired/}. The
\keyword{/bounds/} entry contains the default values for the three
values of the \var{times} field described above.


The \keyword{/expired/} field determines how long C~News will hold on to
lines in the \file{history} file. This is needed because C~News will not
remove a line from the history file once the corresponding article(s)
have been expired, but will hold on to it in case a duplicate should
arrive after this date. If you are fed by only one site, you can keep
this value small. Otherwise, a couple of weeks is advisable on UUCP
networks, depending on the delays you experience with articles from
these sites.


A sample \file{explist} file with rather tight expiry intervals
is reproduced below:

\begin{tscreen}
\begin{verbatim}
# keep history lines for two weeks. Nobody gets more than three months
/expired/                       x       14      -
/bounds/                        x       0-1-90  -

# groups we want to keep longer than the rest
comp.os.linux.announce          m       10      -
comp.os.linux                   x       5       -
alt.folklore.computers          u       10      -
rec.humor.oracle                m       10      -
soc.feminism                    m       10      -

# Archive *.sources groups
comp.sources,alt.sources        x       5       @

# defaults for tech groups
comp,sci                        x       7       -

# enough for a long weekend
misc,talk                       x       4       -

# throw away junk quickly
junk                            x       1       -

# control messages are of scant interest, too
control                         x       1       -

# catch-all entry for the rest of it
all                             x       2       -
\end{verbatim}
\end{tscreen}



\index{C~News!update low water mark}
With expiring in C~News, there are a number of potential troubles
looming.  One is that your newsreader might rely on the third field of
the active file, which contains the number of the lowest article
on-line.  When expiring articles, C~News does not update this field. If
you need (or want) to have this field represent the real situation, you
need to run a program called \prog{updatemiin} after each run of
\prog{doexpire}.\footnote{
  In older versions of C News, this was done by a script called
  \prog{upact}.
}


\index{C News!history file@\file{history} file}
Second, C~News does not expire by scanning the newsgroup's directory,
but simply checks the \file{history} file if the article is due for
expiration.\footnote{
  The article's date of arrival is kept in the middle field of the
  history line, given in seconds since January~1, 1970.
} If your history file somehow gets out of sync, articles may be
around on your disk forever, because C~News has literally forgotten
them.\footnote{
 I don't know \emph{why} this happens, but for me, it does from time
 to time.
} You can repair this using the \prog{addmissing} script in
\newsbin\file{/maint}, which will add missing articles to the
\file{history} file, or \prog{mkhistory}, which re-builds the entire
file from scratch.  Don't forget to become \user{news} before invoking
it, else you will wind up with a \file{history} file unreadable by
C~News.


\index{C News!expiring|)}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Miscellaneous Files}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.misc}

There are a number of files that control C~News' behavior, but are not
essential to its functioning. All of them reside in \newslib. We will
describe them briefly.

\begin{dispitems}
\ditem[\file{newsgroups}]
        \index{C News!list of current groups}
        This is a companion file of \file{active} which contains a list
        of newsgroup names, along with a one-line description of its
        main topic.  This file is automatically updated when C~News
        receives a \keyword{checknews} control message (see
        section~\ref{cnews.control}).

\ditem[\file{localgroups}]
        If you have a number of local groups that you don't want C~News
        to complain about every time you receive a \keyword{checknews}
        message, put their names and descriptions in this file, just like
        they would appear in \file{newsgroups}.

\ditem[\file{mailpaths}]
        \index{C News!moderated groups}
        This file contains the moderator's address for each moderated
        group. Each line contains the group name, followed by the
        moderator's email address (offset by a tab).

        Two special entries are provided as default. These are
        \keyword{backbone} and \keyword{internet}. Both provide~--- in
        bang-path notation~--- the path to the nearest backbone site,
        and the site that understands RFC~822-style addresses
        (\email{user@host}).  The default entries are

        \begin{tscreen}
	 internet\hspace{6ex}%s\\
	 backbone\hspace{6ex}%s
        \end{tscreen}

        You will not have to change the \keyword{internet} entry if you
        have \prog{smail} or \prog{sendmail} installed, because they
        understand RFC~822-addressing.

        The \keyword{backbone} entry is used whenever a user posts to a
        moderated group whose moderator is not listed explicitly.  If
        the newsgroup's name is \ngrp{alt.sewer}, and the
        \keyword{backbone} entry contains \email{\var{path}!\%s}, C~News
        will mail the article to \email{\var{path}!alt-sewer}, hoping
        that the backbone machine is able to forward the article. To
        find out which path to use, ask the news admins at the site that
        feeds you.  As a last resort, you can also use
        \email{uunet.uu.net!\%s}.

\ditem[\file{distributions}]
        \index{C News!limit a feed}
        This file is not really a C~News file, but it is used by some
        newsreaders, and \prog{nntpd}. It contains the list of
        distributions recognized by your site, and a description of its
        (intended) effect. For example, Virtual Brewery has the
        following file:

        %% (Somehow know that one, Fred? :)
        %% Again, no verbatim environment here
        \begin{tscreen}
         \def\ex#1{\hspace{#1ex}}
	 world\ex{11}    everywhere in the world\\
	 local\ex{11}    Only local to this site\\
	 nl\ex{15}       Netherlands only\\
	 mugnet\ex{10}   MUGNET only\\
	 fr\ex{15}       France only\\
	 de\ex{15}       Germany only\\
	 brewery\ex{9}   Virtual Brewery only
        \end{tscreen}

%% These are only used by postnews.
%% \ditem[\file{replyusepath}]
%% \ditem[\file{postdfltdist}]
%% \ditem[\file{postdfltgroup}]

\ditem[\file{log}]
        \index{C News!log files}
        This file contains a log of all C~News activities. It is culled
        regularly by running \prog{newsdaily}; copies of the old logfiles
        are kept in \file{log.o}, \file{log.oo}, etc.

\ditem[\file{errlog}]
        This is a log of all error messages created by C~News. These do
        not include articles junked due to wrong group, etc. This file
        is mailed to the newsmaster (\user{usenet} by default)
        automatically by \prog{newsdaily} if it is found to be
        non-empty.

        \file{errlog} is cleared by \prog{newsdaily}. Old copies are kept
        in \file{errlog.o} and companions.

\ditem[\file{batchlog}]
        This logs all runs of \prog{sendbatches}. It is usually of scant
        interest only. It is also attended by \prog{newsdaily}.

\ditem[\file{watchtime}]
        This is an empty file created each time \prog{newswatch} is run.

\end{dispitems}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Control Messages}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.control}
\index{news!control messages}

The Usenet news protocol knows a special category of articles which
evoke certain responses or actions by the news system. These are called
\emph{control} messages. They are recognized by the presence of a
\mhdr{Control:} field in the article header, which contains the name of
the control operation to be performed. There are several types of them,
all of which are handled by shell scripts located in
\file{\newslib/ctl}.


Most of these will perform their action automatically at the time
the article is processed by C~News, without notifying the newsmaster.
By default, only \keyword{checkgroups} messages will be handed to the
newsmaster,\footnote{
 There's a funny typo in RFC~1036 (p.12):
    ``Implementors and administrators may choose to allow control
    messages to be carried out automatically, or to queue them for annual
    processing.''
} but you may change this by editing the scripts.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \keyword{cancel} Message}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.control.cancel}
\index{cancel control message@\keyword{cancel} control message}
\index{news!cancel article}

The most widely known message is \keyword{cancel}, with which a user may
cancel an article sent by her earlier. This effectively removes the
article from the spool directories, if it exists. The \keyword{cancel}
message is forwarded to all sites that receive news from the groups
affected, regardless of whether the article has been seen already or
not. This is to take into account the possibility that the original
article has been delayed over the cancellation message. Some news
systems allow users to cancel other person's messages; this is of course
a definite no-no.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\keyword{newgroup} and \keyword{rmgroup}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.control.addgroup}
\label{cnews.control.rmgroup}
\index{newgroup control message@\keyword{newgroup} control message}
\index{rmgroup control message@\keyword{rmgroup} control message}
\index{news!add new group}
\index{news!remove old group}

Two messages dealing with creation or removal of newsgroups are the
\keyword{newgroup} and \keyword{rmgroup} message. Newsgroups below the
``usual'' hierarchies may be created only after a discussion and voting
has been held among Usenet readers. The rules applying to the \ngrp{alt}
hierarchy allow for something close to anarchy.  For more information,
see the regular postings in \ngrp{news.announce.newusers} and
\ngrp{news.announce.newgroups}.  Never send a \keyword{newgroup} or
\keyword{rmgroup} message yourself unless you definitely know that you
are allowed to.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \keyword{checkgroups} Message}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.control.checkgroups}
\index{checkgroups control message@\keyword{checkgroups} control message}
\index{C News!update active file@update \file{active} file}
\index{news!update active file@update \file{active} file}

\keyword{checkgroups} messages are sent by news administrators to make
all sites within a network synchronize their \file{active} files with
the realities of Usenet. For example, commercial Internet service
providers might send out such a message to their customers' sites.  Once
a month, the ``official'' \keyword{checkgroups} message for the major
hierarchies is posted to \ngrp{comp.announce.newgroups} by its
moderator.  However, it is posted as an ordinary article, not as a
control message. To perform the \keyword{checkgroups} operation, save
this article to a file, say \file{/tmp/check}, remove everything up to
the beginning of the control message itself, and feed it to the
\keyword{checkgroups} script using the following command:


\begin{tscreen}
\# su news -c "\newsbin/ctl/checkgroups" < /tmp/check
\end{tscreen}


This will update your \file{newsgroups} file, adding the groups
listed in \file{localgroups}. The old \file{newsgroups} file will be 
moved to \file{newsgroups.bac}. Note that posting the message locally
will rarely work, because \prog{inews} refuses to accept that large
an article.


If C~News finds mismatches between the \keyword{checkgroups} list and the
\file{active} file, it will produce a list of commands that would bring
your site up to date, and mail it to the news administrator. The output
typically looks like this:


\begin{tscreen}
\begin{verbatim}
From news Sun Jan 30 16:18:11 1994
Date: Sun, 30 Jan 94 16:18 MET
From: news (News Subsystem)
To: usenet
Subject: Problems with your active file

The following newsgroups are not valid and should be removed.
        alt.ascii-art
        bionet.molbio.gene-org
        comp.windows.x.intrisics
        de.answers

You can do this by executing the commands:
         /usr/lib/news/bin/maint/delgroup alt.ascii-art
         /usr/lib/news/bin/maint/delgroup bionet.molbio.gene-org
         /usr/lib/news/bin/maint/delgroup comp.windows.x.intrisics
         /usr/lib/news/bin/maint/delgroup de.answers

The following newsgroups were missing.
        comp.binaries.cbm
        comp.databases.rdb
        comp.os.geos
        comp.os.qnx
        comp.unix.user-friendly
        misc.legal.moderated
        news.newsites
        soc.culture.scientists
        talk.politics.crypto
        talk.politics.tibet

\end{verbatim}
\end{tscreen}


When you receive a message like this from your news system, don't
believe it blindly. Depending on who sent the \keyword{checkgroups}
message, it may lack a few groups or even entire hierarchies; so
you should be careful about removing any groups. If you find
groups are listed as missing that you want to carry at your site, 
you have to add them using the \prog{addgroup} script. Save the list
of missing groups to a file and feed it to the following little
script:


\begin{tscreen}
\begin{verbatim}
#!/bin/sh
cd /usr/lib/news

while read group; do
    if grep -si "^$group[[:space:]].*moderated" newsgroup; then
        mod=m
    else
        mod=y
    fi
    /usr/lib/news/bin/maint/addgroup $group $mod
done
\end{verbatim}
\end{tscreen}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\keyword{sendsys}, \keyword{version}, and \keyword{senduuname}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.control.sendsys}
\label{cnews.control.version}
\label{cnews.control.uuname}
\index{senduuname control message@\keyword{checkgroups} control message}
\index{sendsys control message@\keyword{checkgroups} control message}
\index{version control message@\keyword{checkgroups} control message}

Finally, there are three messages that may be used to find out about the
network's topology. These are \keyword{sendsys}, \keyword{version}, and
\keyword{senduuname}. They cause C~News to return to the sender the
\file{sys} file, a software version string, and the output of
\prog{uuname(1)}, respectively. C~News is very laconic about
\keyword{version} messages; it returns a simple, unadorned ``C''.


Again, you should \emph{never} issue such a message, unless you have made
sure that it cannot leave a your (regional) network. Replies to
\keyword{sendsys} messages can quickly bring down a UUCP
network.\footnote{
 I wouldn't try this on the Internet, either.
}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{C~News in an NFS Environment}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{cnews.nfs}
\index{configuring!C News on a LAN}
\index{C News!LAN}
\index{LAN!news}

A simple way to distribute news within a local network is to keep all
news on a central host, and export the relevant directories via NFS, so
that newsreaders may scan the articles directly.  The advantage of this
method over NNTP is that the overhead involved in retrieving and
threading articles is significantly lower. NNTP, on the other hand, wins
in a heterogeneous network where equipment varies widely among hosts, or
where users don't have equivalent accounts on the server machine.


When using NFS, articles posted on a local host have to be forwarded to
the central machine, because accessing adminstrative files might
otherwise expose the system to race-conditions that leave the files
inconsistent. Also, you might want to protect your news spool area by
exporting it read-only, which requires forwarding to the central
machine, too.


C~News handles this transparently. When you post an article, your
newsreader usually invokes \prog{inews} to inject the article into the
news system. This command runs a number of checks on the article,
completes the header, and checks the file \file{server} in \newslib. If
this file exists and contains a hostname different from the local host's
name, \prog{inews} is invoked on that server host via \prog{rsh}. Since
the \prog{inews} script uses a number of binary commands and support files
from C~News, you have to either have C~News installed locally, or mount
the news software from the server.


For the \prog{rsh} invocation to work properly, each user must have an
equivalent account on the server system, i.e. one to which she can log
in without being asked for a password.


Make sure that the hostname given in \file{server} literally matches the
output of the \prog{hostname(1)} command on the server machine, else
C~News will loop forever when trying to deliver the article.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Maintenance Tools and Tasks}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\namedlabel{cnews.maint}{Maintenance Tools and Tasks}

Despite the complexity of C~News, a news administrator's life
can be fairly easy, because C~News provides you with a wide variety
of maintenance tools.  Some of these are intended to be run regularly
from \prog{cron}, like \prog{newsdaily}.  Using these scripts reduces
daily care and feeding requirements of your C~News installation greatly.


Unless stated otherwise, these commands are located in
\newsbin\file{/maint}.  Note that you must become user \user{news}
before invoking these commands. Running them as super-user may render
these files inaccessible to C~News.

\begin{dispitems}
\ditem[\prog{newsdaily}]
        The name already says it: runs this once a day.  It is an
        important script that helps you keep log files small, retaining
        copies of each from the last three runs.  It also tries to sense
        any anomalies, like stale batches in the incoming and outgoing
        directories, postings to unkown or moderated newsgroups, etc.
        Resulting error messages will be mailed to the newsmaster.

\ditem[\prog{newswatch}]
        This is a script that should be run regularly to look for
        anomalies in the news system, once an hour or so. It is intended
        to detect problems that will have immediate effect on the
        operability of your news system and mail a trouble report to the
        newsmaster.  Things checked include stale lock files that don't
        get removed, unattended input batches, and disk space shortage.

\ditem[\prog{addgroup}]
        Adds a group to your site locally. The proper invocation is

        \begin{tscreen}
         addgroup \var{groupname} {y|n|m|=\var{realgroup}}
        \end{tscreen}

        The second argument has the same meaning as the flag in the
        \file{active} file, meaning that anyone may post to the group
	(\keyword{y}), that no-one may post (\keyword{n}), that it is
        moderated (\keyword{m}), or that it is an alias for another
        group (\keyword{=\var{realgroup}}).

        You might also want to use \prog{addgroup} when the first
        articles in a newly created group arrive earlier than the
        \keyword{newgroup} control message that is intended to create
        it.

\ditem[\prog{delgroup}]
        Allows you to delete a group locally. Invoke it as

        \begin{tscreen}
         delgroup \var{groupname}
        \end{tscreen}

        You still have to delete the articles that remain in the
        newsgroup's spool directory. Alternatively, you might leave
        it to the natural course of events (a.k.a. \prog{expire}) to
        make them go away.

\ditem[\prog{addmissing}]
        Adds missing articles to the \file{history} file. Run this script
        when there are articles that seem to hang around forever.\footnote{
         Ever wondered how to get rid of that ``Help! I can't get X11 to
         work with 0.97.2!!!'' article?
        }

\ditem[\prog{newsboot}]
        This script should be run at system boot time. It removes any lock files
        left over when news processes were killed at shutdown, and closes
        and executes any batches left over from NNTP connections that were
        terminated when shutting down the system.

\ditem[\prog{newsrunning}]
        This resides in \newsbin\file{/input}, and may be used to
        disable unbatching of incoming news, for instance during work
        hours. You may turn off unbatching by invoking

        \begin{tscreen}
         \newsbin/input/newsrunning off
        \end{tscreen}

        It is turned on by using \keyword{on} instead of \keyword{off}.

\end{dispitems}

\index{configuring!C News|)}
\index{configuring!Usenet news|)}
\index{C News|)}
