Installing InterNetNews
Rich $alz
Updated by: James Brister
Internet Software Consortium
please send electronic mail to <inn@isc.org>
ABSTRACT
This document discusses how to install and
set up InterNetNews. You should be familiar with
Usenet and networks; the first section gives
references to documentation for these topics, and
the appendix IV gives a Usenet installation over-
view for novices.
This document also describes what many of the
programs do and how they should be used. Even if
you are a world-class expert at building and main-
taining public software, you should probably read
this.
1. Things You Should Know Before You Do Anything
InterNetNews is abbreviated INN, which is pronounced as
the three letters, eye en en. It is a Usenet transport and
expiration system for larger UNIX- systems where NNTP is
used for most Usenet traffic.
This document is not a tutorial on Usenet. If you do
not have much Usenet experience, you should read Using UUCP
and Usenet, ISBN 0-937175-10-2. You might also find it use-
ful to read Managing UUCP and Usenet (get the most recent
edition available), ISBN 0-937175-48-X. Both books are pub-
lished by O'Reilly & Associates; send inquiries to to
The Internet Connection: A
Guide to Connectivity and Configuration, ISBN 0-201-54237-4
by Smoot Carl-Mitchell and John S. Quarterman. It is pub-
lished by Addison-Wesley.
_________________________
- UNIX is a registered trademark of X/Open Company Ltd.
Servers, ISBN 0-201-41967-X, by James McDermott and John E.
Phillips. Published by Addison-Wesley. It has good INN 1.5.1
coverage.
In November 1997, there was a new version of Managing
Usenet (note, no UUCP) about to come out from O'Reilly &
Associates. This has a large section on INN as well as
Cnews.
You should know BSD-derived TCP/IP - at least be com-
fortable with host names and dotted-quad addresses. If you
have installation problems, you should know about UNIX-
domain stream and datagram sockets and the like. In addi-
tion to any documentation available from your vendor, you
might find it useful to read the two IPC tutorials in UNIX
Programmer's Manual: Supplementary Documents 1. Copies can
be purchased from the Usenix Association; send inquiries to
rfc. RFC 977 is currently being
revised. The 1036 revision is most likely going to be a
``tightening-up''; since INN already has a strict interpre-
tation of the RFC, this revision will probably not affect
InterNetNews very much. The 977 revision is formally adding
new features and facilities which are currently implemented,
and while INN will not provide all of them, they will have
some impact.
InterNetNews does things differently from other news
software. Some other Usenet systems for UNIX are B2.11 and
C News. Both of them require a separate NNTP implementa-
tion. The one everyone uses is called ``NNTP.'' Because
this is confusing (they don't call sendmail ``SMTP''), I
will refer to it as the ``reference implementation.'' You
generally do not need to know anything about these other
systems, but if you are curious, the official sites are as
follows:
Package Host Directory
C News ftp.cs.toronto.edu pub/c-news
B2.11 ftp.uu.net news/bnews-2.11
nntp ftp.academ.com public/nntp
You might find the files doc/biblio, doc/problems, and
doc/rfcerrata in the C News distribution worthwhile reading.
The first is a bibliography, the second discusses known C
lists some technical and philosophical errors in RFC 1036.
The commands below assume that $inn is an abbreviation
for the top of the InterNetNews source tree.
INN could not have been written without access to the
freely-redistributable sources of B2.11, C News, and NNTP.
In particular, I want to thank Rick Adams; Geoff Collyer and
Henry Spencer; and Stan Barber, Erik Fair, Brian Kantor, and
Phil Lapsley. The financial support of UUNET Technologies
is also greatly appreciated. The beta-test sites gave
invaluable feedback.
2. If You Are Impatient
If you don't want to follow these directions, do the
following:
cd $inn/config
cp config.dist config.data
chmod 644 config.data
vi config.data (or emacs, or whatever)
cd ..
make world
mkdir -p /usr/news /var/news /var/news/spool
make install
Then go read the appendixes. If you have any problems, read
the rest of this document.
3. Distribution Roadmap
The INN sources are divided into the following direc-
tories:
frontends Programs to feed articles to the central
server and control it.
innd The central NNTP server. It accepts incoming
connections, receives articles, and arranges
for them to be sent to downstream newsfeeds.
backends Programs to transmit articles to other sites.
expire Programs to purge the article files and his-
tory database.
nnrpd An NNTP server for on-campus clients that do
newsreading (as opposed to bulk article
transfer).
lib Library routines used by all the above.
dbz DBZ database package.
syslog Syslog routines for the systems which don't
provide proper functions needed for INN.
The distribution also includes these directories:
samples Prototype scripts and configuration files
that might have to be edited before they are
installed.
site A place to store edited copies of the files
in the samples directory.
doc Manual pages for all the above.
config Tools to configure the release for your site.
sample-configs Sample configuration data for any system.
authprogs Sample program which can be used for an
authentication with nnrpd.
contrib Contributed programs useful for INN.
obsolete
FAQ Frequently Asked Questions on INN which is
posted at news.software.{b,nntp} periodi-
cally.
Finally, there are a handful of files in the top-level
directory:
README A basic introduction.
COPYRIGHT The distribution copyright. InterNetNews is
freely redistributable, provided proper
credit is given.
MANIFEST A one-line description of every file in the
distribution.
BUILD An interactive script to configure, build,
and install INN.
makedirs.sh A script to build INN's directories except
for the top levels: /usr/news /var/news and
/var/news/spool. As long as you have write
permission to install the programs, this is
the only part of the installation that needs
doing the install as root will make life
easier.
Makefile Rules to call the other Makefiles and make
distributions.
Install.ms This document. It requires the `` - ms''
nroff/troff macro package.
MakeLib Script to build a directory with a replace-
ment of the reference implementation's
``clientlib'' routines needed by remote rn.
MakeInews Script to build an inews distribution direc-
tory.
MakeRnews Script to build an rnews distribution direc-
tory.
sedf.xxx Various sed scripts to filter the output of
lint.
README.perl_hookA description for PERL filtering.
README.tcl_hookA description for TCL filtering.
CONTRIBUTORS Contributors to INN.
HISTORY History until INN 1.4.
iftrue.sh Script that does test(1).
installit.sh Script that installs programs, scripts and
configuration files for INN.
PGPKEYS PGP public keys used for control message
authentication.
4. Building the System
INN is built in steps. First, the subst program is
built. Next, a configuration file containing key/value
pairs is created. Subst reads this file and uses it to edit
a specific set of files in the INN distribution. (Most of
the files that get modified are Makefiles or header files.)
The library is then built; lint is usually a good way to see
if some of the basic configuration parameters are set up
right. The next step is to compile (and lint) all the pro-
grams. The programs are then installed, and the INN data
files are set up.
The configuration process is deliberately not interac-
whether grep returns an exit status. It is also difficult
to change one parameter and rebuild the software. (C News
has this same problem.)
INN's method also has its flaws. Because almost all
configuration data is in one header file, changing almost
anything will force everything to be recompiled.
4.1. Building subst
INN uses the C News subst program to automate the con-
figuration. Subst is a very clever way of safely editing a
file under the control of a configuration file. For more
details, see the documentation in doc/subst.1. Thanks to
Henry Spencer and Geoff Collyer for their permission to use
and redistribute subst.
We will use config.dist as the configuration file to
test the version of subst that you build. (You can always
replace your config file with the distribution file and do
another make to restore the original versions.)
The C News subst program is a shell script that uses
sed to do the editing. The INN configuration file is too
large for some versions of sed. The first step is to see if
your sed will work. To do this, type the following:
cd $inn/config
cp config.dist config.data
make sedtest
If you get any error messages from sed such as ``too much
command text'' (or if it dumps core) you have two choices.
(You should also complain to your vendor.) One choice is to
use another version of sed, such as the one distributed by
the Free Software Foundation. If you do this, edit
config/Makefile and change the line that defines the SED
variable. If you want to use the C News script, then do the
following:
cd $inn/config
make sh
The other choice is to use the C version of subst. You
might want to do this anyway, since it can be much faster.
To do this, type the following:
cd $inn/config
cp config.dist config.data
make c quiet
AFS, you will have edit the file to enable the USE_RENAME
macro. If you have to make any other changes, please let me
know.
Since subst changes source files, you might want to
make a backup copy of all the files that will be modified.
You can do this by typing ``make backup'' in the config
directory. This will create a local tar file that contains
all the files that will be modified into it. Doing ``make
restore'' will unpacks the tar file. (Since subst makes its
changes safely, this step is optional.)
4.2. Editing config.data
Once you have subst working, the next step is to set up
your configuration parameters. This is the hardest part of
installing INN. Don't panic! There are many configuration
parameters, but it should be very easy for you to determine
the answer for most of them. To do this, choose one of the
sample config files which is suitable for your system from
sample-configs directory, and copy it to config/config.data.
If there is no sample for your system, you should copy
config/config.dist, the distribution master, to
config/config.data, your local copy. INN is distributed to
compile and run under BSD/OS 2.1 by default.
The configuration file is divided into the following
sections:
MAKE CONFIG PARAMETERS
LOGGING LEVELS
OWNERSHIPS AND FILE MODES
C LIBRARY DIFFERENCES
C LIBRARY OMISSIONS
MISCELLANEOUS CONFIG DATA
PATHS TO COMMON PROGRAMS
PATHS RELATED TO THE SPOOL DIRECTORY
EXECUTION PATHS FOR INND AND RNEWS
SOCKETS CREATED BY INND OR CLIENTS
LOG AND CONFIG FILES
INNWATCH CONFIGURATION
TCL Configuration
PGP Configuration
Keyword Configuration
Local Configuration
Actsync Configuration
Perl Configuration
You should have a copy of config.data nearby as you read the
next few sections. It is probably a good idea to write down
your changes on paper before you edit the file.
in this format:
parameter <one-or-more-tabs> value
If there is no ``value'' the ``<one-or-more-tabs>'' is still
required. Do not put quote marks around the values - if you
do, you will usually get a syntax error while compiling the
system. The discussion below uses quotes only to show where
the values start and end.
4.2.1. MAKE CONFIG PARAMETERS
This section is used primarily to identify the path to
your C compiler, and what extra libraries or command-line
switches are needed. For example, you could put gcc - Wall
on the CC line. If you need extra -I flags put them on the
DEFS line. INN uses the register declaration a great deal.
If your compiler is very good, you might want to add -Dre-
gister= to the DEFS line so that INN's declarations are
ignored.
The DBZ package can be compiled so that the database is
memory-mapped. If you want to do this and have the mmap
system call, then add ``-DMMAP'' to the DBZCFLAGS parameter.
If you need to link in other libraries (e.g., - lnet)
put them on the LIBS line.
The Makefiles usually filter all lint output through a
sed script. If you are very paranoid, set LINTFILTER to
cat. If your lint output is in the broken multi-line for-
mat:
value type declared inconsistently
exit llib-lc(297) :: test.c(7)
function returns value which is always ignored
printf
Then set LINTFILTER to be the ``sedf.sysv'' line.
The lib directory also builds a lint library, so that
you can make sure the other programs are properly using the
library routines. The LINTLIBSTYLE parameter (used in
lib/Makefile and lib/makellib.sh) controls how the lint
library is built. If your lint understands the ``-C'' flag,
then set it to ``BSD''. If you need the ``-o'' flag to
build a library, then set it to ``SYSV''. If neither of
these work, you can set it to ``NONE''; this will just
create an empty file so that the other Makefiles don't
break. If you come up with a fourth alternative, let me
know.
of salt. You might get some warnings about
``struct _DDHANDLE'' being undefined. You can ignore them
and ask your vendor to support the BSD ``-z'' lint flag. If
you set HAVE_UNISTD to ``DO'' then you might get warnings
about prototype mismatches for various functions declared in
include/clibrary.h. You can ignore them or remove the lines
from the INN header file.
The MANPAGESTYLE parameter (used in doc/Makefile and
doc/putman.sh) controls how manual pages are installed into
your public directory while the MANx parameters specify the
directories where they get installed. If you do not want to
install any manpages, set MANPAGESTYLE to NONE.
4.2.2. LOGGING LEVELS
INN uses the modern syslog that separates messages into
both levels and categories. Look in your <syslog.h> header
file for a ``LOG_NEWS'' macro, and check your syslog(3) man-
page to make sure that openlog takes three arguments. If it
doesn't, then you will have to use the library routine and
server provided in the syslog directory. This is described
later.
The different levels that are described in the sys-
log(3) manpage are confusing, so INN uses its own names for
the four levels it uses:
L_FATAL Fatal error, about to exit
L_ERROR Error that might require attention
L_NOTICE Informational notice, no action needed
L_DEBUG Protocol tracing or other debugging messages
Depending on how your syslog.conf(5) file is set up, you
might want to change the L_xxx parameters in this section.
The scanlogs script assumes that the first three
categories above are each directed into separate files. See
doc/newslog.5, doc/newslog.8, and syslog/syslog.conf for
details. LOGGING is also described in more detail in the
LOG AND CONFIG FILES section.
4.2.3. OWNERSHIPS AND FILE MODES
The NNTP server needs to open the NNTP port; it is port
number 119, which requires root access. This is the only
part of INN that needs this privilege: all other programs
can run under the distinct user and group id specified by
the NEWSUSER and NEWSGROUP parameters. Most news adminis-
tration tasks must be done as user NEWSUSER (see the expla-
nation of SOCKETS CREATED BY INND OR CLIENTS section below).
In addition, inews will only let the NEWSUSER user or
Some INN scripts (primarily the control message scripts
and the daily maintenance script) need to send email to the
news maintainer. The NEWSMASTER parameter specifies the
right address. This is most often the login name of the
account which has NEWSUSER as its user id; use an alias to
forward it to the right people.
Some Usenet sites still use the Path header line to
generate their email reply messages. Using the Path has
never been guaranteed to work, and INN tries to help stop
this practice by refusing to generate valid Path addresses.
The PATHMASTER parameter specifies what inews should put at
the tail end of the Path line. If your NEWSMASTER mailbox
is getting cluttered, then you might want to change this to
be an alias that rejects the message or drops it into the
bit-bucket. The default value is ``not-for-mail'' which
usually results in bounced email.
The xxx_MODE parameters specify the permissions for
articles and directories created within the spool area, and
the active file, all of which are owned by user id NEWSUSER.
4.2.4. C LIBRARY DIFFERENCES
Editing the parameters in this section will require you
to look around at the files in your /usr/include directory.
The SIZE_T parameter is the datatype of the ``size''
parameters in subroutine calls like memchr and fread. The
LOCK_STYLE parameter specifies how file-locking should be
done. Innxmit is the only program that locks files; if you
use the provided scripts, this isn't even necessary, so you
can set this to ``NONE'' if you have any compile problems
(expireover, overchan and filechan use either!)
The DIR_STYLE parameter specifies what is returned by
your readdir(3) routine. This will be either a
``struct direct'' or a ``struct dirent''; set the parameter
to ``DIRECT'' or ``DIRENT'' as appropriate.
If you do not have UNIX-domain sockets, set
HAVE_UNIX_DOMAIN to ``DONT.'' This means that INN will use
a named pipe for the communication between innd and ctlinnd.
It also means that there will be no local ``private'' port
for rnews to use; this should not cause any problems,
although it makes it easier for anyone to use rnews and post
fake news articles. (You might also have to modify the sys-
log routines; see the end of the file syslog/README for
details on this.)
INN needs to know how many descriptors are available to
method to use. On most systems, the getdtablesize routine
will do this, so leave the default of ``GETDTAB.'' On other
systems you need to use the getrlimit, sysconf or ulimit
routine, so set the parameter to ``GETRLIMIT'', ``SYSCONF'',
or ``ULIMIT'', respectively. If you do not have any of
those calls then set the parameter to ``CONSTANT'' and edit
the file lib/getdtab.c to return the right number. To get
this number, look for an OPEN_MAX constant in your system
header files, or write a program that repeatedly opens
/dev/null until it gets an error.
The last few parameters in this section, xxxVAL, are
used primarily to keep lint quiet. These functions are
declared in include/clibrary.h, and the return values are
pretty much always ignored. You can usually determine what
these values should be by examining your manpages or your
lint libraries.
4.2.5. C LIBRARY OMISSIONS
INN uses library routines that might not be present in
all UNIX systems, although they should be. The lib direc-
tory provides versions of some of these routines, including
copies of the freely-redistributable BSD string routines.
The MISSING_SRC, MISSING_OBJ and MISSING_MAN parameters can
be set to list those routines that are missing from your C
library. If you don't have strcasecmp and strncasecmp then
you will need the strcasecmp module built into your INN
library. Add the ``.c'' and ``.o'' names to MISSING_SRC and
MISSING_OBJ, respectively.
The following routines are all found in the file of the
same name. If they are missing from your system, add them
the same way:
memchr strchr getopt
memcmp strrchr mkfifo
memcpy strspn strerror
memset strtok
memmove
If you are using version 1 of the GNU C compiler on a
Sparc running SunOS, you should add inet_ntoa as a missing
function. This is because the first version of gcc didn't
properly pass structures into routines compiled with the Sun
C compiler.
If you have an older version of syslog add syslog.c and
syslog.o to the appropriate parameters.
Pyramid machines running OSx have fast assembly-
MISSING_OBJS parameter. This will cause lib/Makefile to
extract the object files from the ATT library, and add them
to the INN library.
4.2.6. MISCELLANEOUS CONFIG DATA
All the parameters in this section become macros in the
file include/configdata.h. You should at least look through
the parameters up to VERIFY_CANCELS. (If set to ``DO'',
then innd will ignore cancel messages unless the From or
Sender header match those of the original poster.) In gen-
eral, however, you can leave this section pretty much alone
until you have some experience running INN. Nevertheless,
here are some comments on some of the more useful parame-
ters.
Innd can memory-map the active file if you set
ACT_STYLE to ``MMAP''. On some systems, however, when a
mapped file is updated its mtime is not updated. Apparently
some versions of System V Release 4 have this problem. This
causes problems for programs like nnmaster which look at the
st_mtime field of the stat structure in order to determine
if any new news has come in. The best work-around is prob-
ably an hourly cron job that touches the active file.
There are a number of parameters that control the
behavior of rnews. If you set RNEWS_SAVE_BAD to ``DO'' then
articles that innd rejects for reasons like bad headers will
be saved in the _PATH_BADNEWS directory; you will have to
periodically scan this directory and clean it up. You can
also control how rnews logs duplicates (those aren't saved
regardless of the value of RNEWS_SAVE_BAD), logging them
through syslog, to a file, or not. Note that if you set
RNEWS_LOG_DUPS to ``FILE'', then you will want to change
_PATH_RNEWS_DUP_LOG, which appears later in the file. If
you receive news from several UUCP feeds, you might want to
log duplicates so that you can cut down your phone bills by
optimizing your feeds. The RNEWSPROGS parameter says
whether or not to look in _PATH_NEWSPROGS for commands named
on the incoming ``#!'' line of news batches. You probably
want to set this to ``DO''. Make sure that the full path-
name of rnews, _PATH_RNEWS, does not conflict with the
directory where your unpackers are put, _PATH_NEWSPROGS.
If IPADDR_LOG is set to ``DO'' then the news log will
report the IP address of hosts that send articles, rather
then what they put in the Path line. This can be useful if
you run innd with the ``-a'' flag. (If you do this, you
might want to pick up ``hf.tar.Z'' via anonymous FTP to
ee.lbl.gov; it is a filter that turns IP addresses into host
names.)
on your system load.
The LIKE_PULLERS parameter controls how to handle
clients that appear to be doing a sucking feed from your
machine (many admins don't like such clients). If the value
is ``DO'' (the default), then nothing different happens. If
the value is ``DONT'', then after 100 articles have been
sent, each article transfer will be followed by a short (1
second) sleep. For most readers this isn't a problem, but
some clients doe article scoring based on the entire body of
the article. Such clients will be penalized when
LIKE_PULLERS is set to ``DONT''.
4.2.7. PATHS TO COMMON PROGRAMS
INN uses a few standard programs like /bin/sh and send-
mail. If you don't have sendmail then you must have a pro-
gram that accepts a full message - including headers - on
its standard input, and delivers it. This program is speci-
fied by the _PATH_SENDMAIL parameter, and is normally
``/usr/lib/sendmail -t''. The parameter is actually a
sprintf format string that will be given the destination
address as its only argument. On some sites (e.g., those
running MMDF) the ``-t'' could be replaced with a ``%s''.
INN puts most of its executables in the directory
specified by the _PATH_NEWSBIN parameter. Some programs
expect inews and rnews to be in certain places; for example,
UUCP usually wants rnews in /bin. The default configuration
puts these programs in only one spot; if you need to have
multiple links to the same file, you will have to do it
yourself after INN is installed. If you have additional
scripts and programs that you use to maintain your system,
you can put them in whatever directory you want. You will
probably need to add _PATH_NEWSBIN to the PATH of any such
scripts.
If you have an /etc/rc.local file you should make sure
that it invokes the script named by the _PATH_NEWSBOOT
parameter. On other systems (mostly System V derivatives),
the system boot procedure automatically runs all the scripts
in a particular directory, such as /etc/init.2. In that
case, you should pick a name like /etc/init.2/S99news and
have the news boot script installed there, or install it in
the default /etc/rc.news and make the link yourself.
The daily maintenance script, news.daily calls scanlogs
to rotate and trim log files, as well as generating sum-
maries using egrep and awk. On some systems the log files
are too big for these programs so you might have to complain
to your vendor and install the versions from the Free
Software Foundation. The scanlogs script has a short test
By default, all news articles are stored in directories
under /usr/spool/news. Be careful if you pick a different
value - many newsreaders know about this directory name.
INN uses a trick (which I first saw in C News) that
lets it use this same directory to store its incoming news
(spooled by rnews when innd is not available), and its out-
going batch files. Since no newsgroup can ever have a dot
in its name, a directory like out.going can never be a news-
group name, and it is safe to put the news batchfiles in
there. This is used by the _PATH_SPOOLNEWS parameter, and
the _PATH_BATCHDIR parameter.
Do not make _PATH_LOCKS be in the same filesystem as
_PATH_SPOOLNEWS. If you do this, then INN will not be able
to create any lock files when your spool directory is full.
This will probably mean that news.daily will not be able to
run and that it won't call expire to free up disk space.
You should also put _PATH_NEWSLIB on a separate partition if
you can, but that is not as important because it tends to
fill up less often.
If you change parameters in this section a great deal,
then there is a chance that the makedirs.sh script will fail
because some needed intermediate directories will not exist.
This should not be a problem, as you can just create the
directories yourself - make sure to set the ownership and
modes right - and re-run the script.
4.2.9. EXECUTION PATHS FOR INND AND RNEWS
All control messages (other then ``cancel'') are car-
ried out by scripts. Your system must be able to exec shell
scripts directly. All the scripts distributed with INN
start with ``#! /bin/sh.''
The _PATH_CONTROLPROGS parameter specifies the direc-
tory where these scripts exist. Do not set this to a public
directory like /bin because some bozo might send out an
``rm'' control message.
The _PATH_RNEWSPROGS directory serves the same purpose
for rnews when it needs to unpack batches. The RNEWSPROGS
parameter specifies if the directory is really used.
4.2.10. SOCKETS CREATED BY INND OR CLIENTS
The innd server and its clients (most notably ctlinnd)
create UNIX-domain sockets or named pipes. They are created
inside a ``firewall'' directory that gives access permission
to a limited set of users. For example, assume the direc-
sions, then only members of the news group can use ctlinnd
to create new groups because only they will be able to send
a message to the innd socket.
This directory (which is specified by the _PATH_INNDDIR
parameter) is also used to determine the user and group id
of all sub-processes spawned by innd, as well as the owner
of all news articles and files. The owner of this directory
is set at installation time and specified in the ``Owner-
ships and file modes'' section, above.
4.2.11. LOG AND CONFIG FILES
INN keeps its databases, and some control files their
own directory, typically named /usr/local/news. Log files
are kept in /var/log/news. There are many parameters in
this section that refer to files within this directory.
Some sites will want to globally replace ``/usr/local/news''
with something like ``/var/news'', and ``/usr/lib/newsbin''
with ``/var/newsbin.''
There are two files that contain access passwords,
_PATH_NNTPPASS and _PATH_NNRPACCESS. The default location
for these files is in /var/news/etc, so that it is generally
safe to export /usr/news (read-only is probably best).
INN programs do extensive logging, and the daily
maintenance scripts do extensive summary reports and
analysis of them. It might take you some time to learn your
way around the INN logging system; start by reading the
newslog manpages in the doc directory.
4.2.12. INNWATCH CONFIGURATION
The INN server, innd, does not contain any checks to
see if there is enough free space on the disk or if the sys-
tem load average is low enough to allow article reception.
There are two reasons for this. The first reason is philo-
sophical: it is a mistake to bury this kind of policy
information inside a program. For example, you don't want
to have to recompile the program just because you moved to a
different filesystem. (Yes, this could be partially
answered by moving the information to an external config
file, but any compiled rules are still likely to be incom-
plete.) The second reason is pragmatic: there is no port-
able way to get standard measurements for the information
needed. For example, C News provides three different rou-
tines to get the filesystem statistics (with conditional
compilation) while the ``get load average'' file in IDA
sendmail has over 700 lines.
Rather than get tangled up in such a mess of #ifdef's,
gram, innwatch, reads the control file innwatch.ctl.
Innwatch is documented in doc/innwatch.8, while innwatch.ctl
is documented in doc/innwatch.ctl.5.
The parameters in this section control when the server
should stop accepting articles, and when it should start
again. You will have to examine site/innwatch.ctl and prob-
ably modify it, usually to check the amount of free space on
the disks. For example, there is a line in the file that
has this fragment in it:
!!! df . | awk 'NR == 2 { print $4 }' ! ...
This is looking at the fourth field of the second line to
get the amount of freespace. You will have to change the
``2'' and ``4'' here (both can be changed by setting
INNWATCH_INODES and INNWATCH_BLOCKS respectively), and on
other lines, as appropriate for your system.
The parameter INNWATCH_SLEEPTIME specifies how fre-
quently innwatch should check the system - the other parame-
ters should be set with this in mind, eg: there needs to be
enough free space on the filesystem to last the next
INNWATCH_SLEEPTIME seconds.
The INNWATCH_xxxLOAD parameters specify the load aver-
age at which different actions should be taken. They are
integers, representing the load average multipled by 100.
For example, if you want to throttle the server when your
load reaches 7.5, set INNWATCH_HILOAD to ``750.''
The INNWATCH_xxxSPACE parameters specify the minimum
amount of disk space needed for each of INN's three major
filesystems. The numbers are in ``local units,'' equivalent
to whatever your df uses (512-byte units, 1K blocks, etc).
The INNWATCH_SPOOLNODES parameter specifies how many
inodes must be available in your spool directory.
4.2.13. TCL Configuration
The innd server can be configured to include TCL hooks
to be run whenever a new article is received and when cer-
tain other actions occur. See the file README.tcl_hook for
more details.
The TCL_SUPPORT parameter specifies whether you want to
compile in the Tcl support code. Select DO or DONT.
The TCL_LIB parameter specifies the extra libraries you
need to link against to include tcl support. Typically ``-
ltcl -lm'' are required. If you defined TCL_SUPPORT to
the tcl script that is to be loaded at process startup time.
A sample version is included in samples/startup.tcl which
will be installed in the location you define here.
The _PATH_TCL_FILTER parameter specifies the path of
the tcl script that is to be loaded upon command by ctlinnd.
See the ctlinnd.8 manpage for more details (the ``filter''
and ``reload'' commands). A sample is included in
samples/filter.tcl which will be installed in the location
defined by this parameter.
4.2.14. PGP Configuration
Inn now has mechanisms in place that will do PGP verif-
ication of control messages (except for cancels). It is
highly recommended that you use PGP if you can. Forged con-
trol messages are a serious problem in USENET. You can get
PGP from http://web.mit.edu/network/pgp.html.
The WANT_PGPVERIFY parameter defines whether PGP verif-
ication of control messages should be done. Select ``DO'' or
``DONT''.
To verify messages, you must have a PGP public key for
each signer that you wish to trust. It should be entered in
a key ring that is accessible to the user-id that runs the
news system by running pgp -ka on a file containing the key
to add. For example, at a site that runs the news server
software as news, the following command run by the news
user-id should add the key bounded by BEGIN and END "PGP
PUBLIC KEY BLOCK" lines in the file /tmp/key to the default
key ring that would be used for authentication:
pgp -ka /tmp/key
As a general policy rule, control message signers will
not use their control message keys to introduce other keys,
so when PGP asks you a question similar to, "Would you trust
this user to act as an introducer and certify other people's
public keys to you?" answer that you would not.
After you have added the appropriate key to your key
ring, you need to tell the news software to validate the
control messages received. As implemented, the system will
perform the requested action if the message can be authenti-
cated and it will mail the message to the news system
administrator if it cannot.
Automatic processing of control messages is handled by
control.ctl, Control.ctl has several lines at the beginning
of it that describe the format of the file, and there is an
even longer control.ctl(5) manual page. PGP verification for
to the normal authorization done by control.ctl, use the
action "verify-PGP_USERID" in the fourth field. The supplied
control.ctl file has samples that should be clear.
To test the PGP setup a signed sample control message
is in the file CONTROLPROGS/sample.control (where CONTROL-
PROGS is as defined in config.data). Copy this to
/tmp/sample.control. The file name /tmp/sample.control will
be used for this example.
To verify the control message, you will need the key
for news.announce.newgroups and authorization in your news
system for tale@uunet.uu.net to automatically perform "new-
group". Go ahead and enable it for the test even if you
don't want to really allow this, because it is easy enough
to rescind after the test by editing the control message
authorization file and removing the key with pgp -kr
news.announce.newgroups.
You can check that the pgpverify part of the system
will work properly simply by feeding it the sample control
message on stdin:
pgpverify < /tmp/sample.control
If it could run pgp and find the correct key in the
default key ring, the string "news.announce.newgroups"
should be printed. The exit status of the script, found in
most shells with the command
echo $?
as the next command after pgpverify, should be 0 (zero).
When pgpverify passes its test, use the procedure below
to verify the authorization system.
First, cd to the directory where parsecontrol is
installed. Then execute the following four lines, in order,
as the user who owns the news system:
/bin/sh
PROG=newgroup
set -- tale@uunet.uu.net "" /tmp/sample.control
(. ./parsecontrol "$@"; echo $ACTION)
If the message verified correctly, the echo command
should output doit; otherwise, verification failed and the
output should be mail.
Edit /tmp/sample.control and change all occurences of
newusers to newgroups. Then repeat the parsecontrol and echo
The keyword generating code, that has been added by
Karl Kleinpaste, is off by default, as it's a real CPU
sucker (does a lot of regexp matching). To enable it you
must:
1. Set KEYWORDS to DO in config.data (and possibly change
KEYLIMIT ABSURD and MAX_WORDS) and rebuild innd.
2. Uncomment the last line of the overview.fmt file so
that it looks like:
Keywords:full
3. Install and start the new innd.
Of course you need overview generation enabled -- see
elsewhere in this document for that.
4.2.16. Local Configuration
At this section local definitions like home directory
of NEWSUSER are specified. This parameter is used for set-
ting environment variable handed to innd when invoked by
inndstart.
4.2.17. Actsync configuration
Landon Curt Noll's actsync(8) program has been merged
into INN. This section defines some variables for the
default config file for actsync. See the man page for more
details on actsync.
The ACTSYNC_HOST variable defines which remote host
you'll be using to synchronize your active file. If you
don't have a good host to sync to, you can get (via anon
ftp) ftp://ftp.isc.org/pub/usenet/CONFIG/active.gz and have
actsync use that.
4.2.18. Perl Configuration
The innd server can be configured to include perl hooks
to be run the way TCL does whenever a new article is
received and when certain other actions occur. Further
more, nnrpd can be also configured to include perl hooks to
be run whenever a new article is posted. This is not sup-
ported in TCL. See the file README.perl_hook for more
details.
The PERL_SUPPORT parameter specifies whether you want
to compile in the perl support code. Select DO or DONT.
The PERL_LIB parameter specifies the extra libraries
DONT, then this should be blank.
The _PATH_PERL_STARTUP_INND parameter specifies the
path of the perl script that is to be loaded at process
startup time. A sample version is included in
samples/startup_innd.pl which will be installed in the loca-
tion you define here.
The _PATH_PERL_FILTER_INND parameter specifies the path
of the perl script that is to be loaded upon command by
ctlinnd. See the ctlinnd.8 manpage for more details (the
``filter'' and ``reload'' commands). A sample is included in
samples/filter_innd.pl which will be installed in the loca-
tion defined by this parameter.
The _PATH_PERL_FILTER_NNRPD parameter specifies the
path of the perl script that is to be loaded at process
startup time. A sample version is included in
samples/filter_nnrpd.pl which will be installed in the loca-
tion you define here.
4.3. Typical config.data changes
The following sections show some of the changes that
need to be made to config.data so that INN will compile.
They are only samples; ``your mileage may vary.''
Note that if you are using the first release of gcc2,
set USE_CHAR_CONST to ``DONT''.
SunOS4.x
MISSING_SRC memmove.c
MISSONG_OBJ memmove.o
AIX
DEFS -I../include -D_NO_PROTO -U__STR__
FORK fork
FREEVAL void
FUNCTYPE int
HAVE_ST_BLKSIZE DONT
HAVE_TM_GMTOFF DONT
LDFLAGS
LINTFILTER | sed -n -f ../sedf.aix
LINTFLAGS -wkD -b -h $(DEFS)
LINTLIBSTYLE SYSV
LOCK_STYLE FCNTL
MISSING_MAN
MISSING_SRC
NEED_TIME DO
POINTER void
USE_UNION_WAIT DONT
Under AIX 3.1, you must also use the syslog that comes
with INN. This is not necessary for 3.2. Some versions
also need USE_UNION_WAIT set to ``DONT''. You should also
run rc.news from init not /etc/rc; add a line like the fol-
lowing near the end of the inittab file, just before the
``cons'' line:
rcnews:wait:2:/usr/local/etc/rc.news >/dev/console 2>&1
A/UX
LIBS -lbsd
Make sure you don't use gcc version 1; it miscompiles
the socket calls in innd/cc.c.
BSDI
ABORTVAL void
ALARMVAL u_int
EXITVAL volatile void
_EXITVAL volatile void
FREEVAL void
GETPIDVAL pid_t
GID_T gid_t
HAVE_UNISTD DO
HAVE_VFORK DONT
HAVE_WAITPID DO
LSEEKVAL off_t
MISSING_OBJ
MISSING_SRC
_PATH_COMPRESS /usr/bin/compress
_PATH_EGREP /usr/bin/egrep
_PATH_MAILCMD /usr/bin/Mail
_PATH_SENDMAIL /usr/sbin/sendmail -t
PID_T pid_t
POINTER void
QSORTVAL void
SIZE_T size_t
SLEEPVAL u_int
UID_T uid_t
USE_UNION_WAIT DONT
VAR_STYLE STDARGS
Change the SHELL variable in config/Makefile and
site/Makefile to point to /usr/contrib/bin/bash. Edit
lib/Makefile so that the install target does not try to make
../llib-linn.ln. You must also use the GNU sed; the version
distributed with BSDI 0.9.4.1 enters an infinite loop pro-
cessing newgroup messages.
HP-UX8.0
ABORTVAL void
ALARMVAL unsigned int
CLX_STYLE FCNTL
CTYPE isXXXXX((c))
DEFS -I../include -DHPUX
FDCOUNT_STYLE SYSCONF
FREEVAL void
GETPIDVAL pid_t
GID_T gid_t
HAVE_SETBUFFER DONT
HAVE_ST_BLKSIZE DONT
HAVE_TM_GMTOFF DONT
HAVE_UNISTD DO
HAVE_WAITPID DO
LINTFILTER | sed -n -f ../sedf.sysv
LINTFLAGS -b -h $(DEFS)
LINTLIBSTYLE SYSV
LOCK_STYLE LOCKF
LOG_INN_PROG LOG_LOCAL7
LOG_INN_SERVER LOG_LOCAL7
LSEEKVAL off_t
_PATH_MAILCMD /usr/bin/mailx
NOFILE_LIMIT 200
PID_T pid_t
POINTER void
PROF
QSORTVAL void
RANLIB echo
RES_STYLE TIMES
SIZE_T size_t
SLEEPVAL unsigned int
UID_T uid_t
USE_UNION_WAIT DONT
_EXITVAL void
You will probably also need to use the bdf command
instead of df.
SGIIndigo
ABORTVAL void
ALARMVAL uint
ACT_STYLE MMAP
CFLAGS $(DEFS) -g -w
CLX_STYLE FCNTL
_EXITVAL void
FORK fork
FREEVAL void
GID_T gid_t
HAVE_ST_BLKSIZE DONT
HAVE_TM_GMTOFF DONT
HAVE_UNISTD DO
LDFLAGS
LIBS -lmld
LINTFILTER | sed -n -f ../sedf.sysv
LINTFLAGS $(DEFS)
LINTLIBSTYLE SYSV
LSEEKVAL off_t
POINTER void
QSORTVAL void
RANLIB echo
SIZE_T size_t
SLEEPVAL uint
UID_T uid_t
_PATH_COMPRESS /usr/bsd/compress
Also, the MISSING_xxx parameters should be empty.
Solaris2.X/SunOS
DEFS -I../include -DSUNOS5 -DPOLL_BUG
USE_CHAR_CONST DO
CFLAGS -O -Xa $(DEFS)
LDFLAGS
LIBS -lnsl -lsocket -lelf
LINTLIBSTYLE SYSV
LINTFLAGS -b -h $(DEFS)
LINTFILTER | sed -n -f ../sedf.sysv
RANLIB echo
VAR_STYLE STDARGS
SIZE_T size_t
UID_T uid_t
GID_T gid_t
PID_T pid_t
POINTER void
ALIGNPTR long
LOCK_STYLE LOCKF
HAVE_UNISTD DO
HAVE_SETSID DO
HAVE_TM_GMTOFF DONT
HAVE_WAITPID DO
USE_UNION_WAIT DONT
HAVE_VFORK DONT
HAVE_UNIX_DOMAIN DO
CLX_STYLE FCNTL
RES_STYLE TIMES
FDCOUNT_STYLE SYSCONF
ABORTVAL void
ALARMVAL unsigned
GETPIDVAL pid_t
SLEEPVAL unsigned
QSORTVAL void
LSEEKVAL off_t
FREEVAL void
_EXITVAL void
MISSING_SRC
MISSING_OBJ
PATH_COMPRESS /bin/compress
Make sure you use the C version of subst.
SystemV
FREEVAL void
GETPIDVAL long
HAVE_TM_GMTOFF DONT
HAVE_WAITPID DO
LDFLAGS
LIBS -lnsl -lsocket
LINTFILTER | sed -n -f ../sedf.sysv
LINTFLAGS -b -h $(DEFS)
LINTLIBSTYLE NONE
LOCK_STYLE FCNTL
MANPAGESTYLE NONE
MISSING_MAN strcasecmp.3
MISSING_OBJ strerror.o strcasecmp.o
MISSING_SRC strerror.c strcasecmp.c
_PATH_MAILCMD /usr/bin/mailx
POINTER void
QSORTVAL void
RANLIB
RES_STYLE TIMES
SIZE_T unsigned int
USE_CHAR_CONST DONT
USE_UNION_WAIT DONT
I was never able to get lint to be useful on the
machine I used. Some versions of System V (for example,
Esix 4.0.3) need the following LIBS value:
LIBS -lresolv -lsocket -lnsl -L/usr/ccs/lib -lelf
On a Dell System V machine, you have to set HAVE_UNIX_DOMAIN
to ``DONT.''
Ultrix4.x
ALARMVAL unsigned int
FREEVAL void
LDFLAGS
LINTFILTER | sed -n -f ../sedf.sysv
LINTFLAGS -b -u -x $(DEFS)
LSEEKVAL off_t
MISSING_MAN
MISSING_OBJ syslog.o strerror.o
MISSING_SRC syslog.c strerror.c
POINTER void
PROF -p
QSORTVAL void
SIZE_T unsigned int
SLEEPVAL unsigned int
_EXITVAL void
Ultrix also requires the new syslog. You cannot use
syslog that INN includes (output doesn't show up, or float-
ing point numbers are garbled, etc.). The file jtkohl-
syslog-complete.tar.Z in the /pub/DEC directory on
gatekeeper.dec.com has a ``for-Ultrix'' package that handles
both old and new syslog calls. While Ultrix has symlinks,
it does not have the ``-follow'' option in its find command.
This is used in expire/makeactive.c; you will have to either
install the GNU find or edit the source file.
5. Other Source Preparations
In addition to setting up the configuration file, it
might be necessary to do some other setups.
5.1. Systems with old syslogs
If you need to install the syslog that is distributed
with INN, go to the top of the distribution and type ``make
syslogfix''. This will also compile syslogd, the logging
daemon. You should install this to replace your existing
daemon, usually in /etc/syslog. You will also need to
install the new-style syslog.conf file.
If you cannot replace syslogd on your machine, then see
the file syslog/README for information on how to set it up
as an alternate daemon.
Ignore any complaints from lint about the INN sources
calling openlog with the wrong argument count. In fact, if
you don't get any complaints, then something is wrong with
the way syslog, <syslog.h>, or the lint libraries are set up
on your system.
5.2. The DBZ package
INN uses the DBZ database package. Thanks to Jon Zeeff
for his permission to use and redistribute DBZ, as modified
by Henry Spencer. INN has its own set of modifications to
DBZ. The changes are made with the patch program and the
context diff in lib/dbz.pch. If you don't have patch
installed, then you can make the changes manually. (If you
don't have Larry Wall's patch program get it from any
comp.sources.unix archive as well as many FSF archives and
other places - you'll be glad you did.)
Both innd and nnrpd have the option of keeping the DBZ
hash table in memory, under the control of the
INND_DBZINCORE and NNRP_DBZINCORE_DELAY parameters, respec-
tively. This can consume lots of RAM proportional to the
size of your history database, but it can also avoid a great
deal of disk I/O. You should probably see the DBZ manpage
in the doc directory for some (brief) additional discussion
dbz.c (the GNU C compiler doesn't have this problem). If
you have ``-O'' in your DBZCFLAGS configuration parameter,
then take it out.
5.3. Using writev
INN makes extensive use the writev system call to write
several I/O buffers in a single call. If you do not have
writev then you must copy include/uio.h to your
/usr/include/sys directory. You must also add ``writev.c''
and ``writev.o'' to the MISSING_SRC and MISSING_OBJ parame-
ters.
The ``fake'' writev found in the lib directory is not
highly efficient. You might want to write a better one that
tries to malloc a new buffer and join all the elements. Be
careful about doing this because innd can use very big
buffers.
6. Compiling the System
Once the INN sources have been configured, they are
ready to be compiled. If you are very confident of your
changes, type the following:
cd $inn
make all
If you do not get any errors, skip to the section titled
``Installing the System.''
If you are confident, but careful, type:
cd $inn
make world
cat */lint
This will compile everything, then run lint in all direc-
tories.
Another option is to run the BUILD script found at the
top of the source tree. This will interactively configure,
compile, and install the system. After running that script,
skip to the section titled ``Installing the System.''
If you are more cautious, you should type the follow-
ing:
cd $inn/config
make quiet
cd ..
the following sections.
6.1. Building the Library
The next step is to build the INN library. Do the fol-
lowing
cd $inn/lib
make libinn.a lint
This will build the library and run lint on the
sources, putting the output into a file named lint. If any-
thing fails to compile, you probably made a configuration
error, most likely in the ``C library differences'' section.
In particular, double-check the SIGHANDLER and xxx_STYLE
parameters.
The lint output should be almost empty, except for a
couple of ``possible pointer alignment problem'' warnings in
dbz.c. If you get much more than this, then you probably
did not define the POINTER or SIZE_T parameters properly.
The NEW and RENEW macros in include/macros.h try to capture
all the alignment problems associated with dynamic memory
allocation. Also double-check the ALIGNPTR parameter and
the CAST macro in include/macros.h.
If lint reports any other problems, you should take the
time to investigate them. Note that many lint libraries
have errors. Also, you may get some problems in yaccpar in
parsedate.y; these are most likely in the yacc-generated C
code. If you get any of these, complain to your vendor.
If you find a portability issue that I missed, please
let me know.
Once the library is built, you should install it in the
top-level INN directory. To do this type ``make install''
while still in the lib directory. This will also compile a
lint library for use in linting the programs in the other
directories.
Note that any time a change is made to the library you
must do ``make install''; it is not enough to type
``make libinn.a''. This is a deliberate decision - like a
program, compiling a library is different from making it
available for others to use, and installing a library should
make it possible to run lint against it.
6.2. Compiling the Programs
INN's programs are separated into six areas, as
6.2.1. The Frontend Programs
Frontends are those programs that talk to the main news
server, either offering it articles or controlling its
action. This includes the following programs:
inews The program that validates and prepares news
articles and gives them to innd. This is
mostly used by users (usually indirectly,
through programs like Pnews), but also
through special facilities such as news/mail
gateways.
rnews Unpacks news batches from UUCP sites and
offers them to innd.
ctlinnd This program controls innd, directing it to
do most of the tasks a news administrator
will have to do: create newsgroups, update
newsfeeds, and the like.
sys2nf A program to turn a B or C News sys file into
an INN newsfeeds file. This is a transition
aide that is only documented in the source.
To build these programs, type the following:
cd $inn/frontends
make all
6.2.2. Innd
The next program is the main news server, which
includes the following programs:
innd Innd accepts all incoming NNTP connections
and either processes their traffic or hands
them off to the NNTP ``newsreader'' server.
It accepts articles, files them, and queues
them so that they can be sent to downstream
feeds. Innd listens on the official NNTP
port. On most systems only root can do this.
Innd is careful to set the modes of any files
it creates, as well as the privileges of any
processes it spawns.
inndstart Sites that are concerned about large root-
access programs may wish to install
inndstart. This program opens the port,
changes its user and group ID to be that of
execution environment. It is a small program
(about 100 lines) that is easily understood.
You should use it because innd will run fas-
ter because it won't have to make any chown
system calls. If you make inndstart setuid
root then no news maintenance has to be done
as root.
To build these, type the following:
cd $inn/innd
make all
Note that innd handles the filing and distribution of
certain messages differently from other systems. For exam-
ple, you can have newsgroups within ``control'' for the dif-
ferent types of control messages. See innd.8, newsfeeds.5,
and active.5 in the doc directory for details.
6.2.3. Nnrpd
Innd implements a subset of the NNTP protocol - only
those commands that are needed for peer sites to feed news
articles. You must install nnrpd to allow users to read
news. If a connection comes in from a host that is not a
specified feed, then an nnrpd process is spawned to handle
it. (You can debug nnrpd by running it interactively; put
an entry for the host named ``stdin'' in your nnrp.access
file.)
Build the newsreader server by doing the following:
cd $inn/nnrpd
make all
Note that if users on a peer machine (one that feeds you
news) want to read news from your server, then you have two
choices. You can use nntpd from the reference platform (See
Appendix II) and make sure not to list the peer in your
nntp.access file. The other choice is to relink the reading
software on the other machine with the INN library so that
it uses the ``mode reader'' NNTP command extension.
6.2.4. The Backend Programs
The backend programs take articles that innd received
and offer them to your news neighbors. This includes the
following programs:
archive A simple program to archive news articles.
batcher Collects articles into batches for UUCP
delivery.
buffchan A program to split a single innd stream into
separate files. It can buffer data, flushing
files based on command-line switches.
crosspost A program that does link creation for cross-
posted articles. Runs as a channel feed and
lets innd hand off some of its i/o activity.
cvtbatch A program to turn a file list into an INN
batchfile. This is a transition aide.
filechan Another program to split a single innd stream
into separate files. It is system-call
intensive, but requires no locking protocol.
innxbatch A program to send articles with ``XBATCH''
NNTP command extension.
innxmit A replacement for nntpxmit from the reference
implementation. It reads a file containing a
list of articles, and sends them to a host.
nntpget A program to retrieve articles from a remote
site.
shlock A program to provide a locking protocol for
shell scripts.
shrinkfile A program to shrink a file by removing lines
from the beginning. It is useful for purging
backlogged batchfiles.
To build this set of programs, type the following:
cd $inn/backends
make all
6.2.5. Expire
This directory includes programs to modify the history
database as well as some utilities that might be useful in
this task. The database is called the history file, and it
contains one line for every article on the system, specify-
ing when it was received and where it was filed. This file
is indexed by the Message-ID, and the DBZ package provides
fast retrieval from it.
expire Scans the history database to purge old
entries, and remove old articles from the
spool area. You can specify how long to keep
sets of newsgroups.
makeactive This program can be used to rebuild the
active file if it is lost in a crash.
makehistory This program scans through the spool area and
rebuilds the history files.
newsrequeue This program can be used after a crash to
resend articles to your neighbors.
prunehistory This is a tool for other programs that expire
news. It reads a list of Message-ID's and
filenames, and updates the history file to
mark that the files have been deleted.
This directory also includes expire.pch and reap.pch.
The first is a patch to the C News expire program that lets
it cooperate better with innd, sending it messages when
articles have been removed. The second is a set of patches
to the reap program that lets it cooperate with prunehis-
tory; it also adds some other useful features. Both patch
files have additional information in them. Both programs
are unsupported, provided by members of the beta-test group.
To build these programs, type the following:
cd $inn/expire
make all
If you are currently running C News, note that it has a
directory named expire that is often the same pathname as
INN's expire program. You will have to move, or remove, the
directory before you can intall the INN program.
6.2.6. Script and data files
In addition to the programs, INN requires several
scripts. For example, one script starts the server when the
machine boots while another prunes the log files and runs
expire every night. Many of these scripts can be used as-is
until you get a feel for how INN works.
INN also requires several data files. One specifies
what sites feed you news, another what sites you feed, and
so on. INN cannot provide these, other than giving sample
entries. You'll probably find that writing these files will
ples directory. Your modified copies should be maintained
in the site directory. By splitting things up this way,
official updates will never wipe out any changes you have
made.
To create the initial set of files, do the following:
cd $inn/site
make all
See below for an explanation of each file.
6.3. Manual pages
INN comes with an extensive set of manual pages. You
might want to edit the Makefile to set up the right owner-
ship of the installed manual pages. Or you might want to
not bother installing them at all.
When it comes to reading them, you should start with
innd.8 and ctlinnd.8. From there follow the cross-
references as you want.
7. Installing the System
Although either innd or inndstart must be run with root
privileges, the build and most of the installation does not
have to be done as root - only the installation of the
inndstart executable requires root priviledges, as it is
installed as owned by root and setuid. The $inn/makedirs.sh
script creates all the necessary directories used by INN,
and sets up the right ownerships and modes: owned by
NEWSUSER in group NEWSGROUP with 0775 permissions (the
``firewall'' directory, _PATH_INDDDIR, has mode 0770). You
should review this script, then run it.
The rest of the installation should be done as the news
administrator or as root. The Makefiles are very strict
about setting the modes on the files that get installed. To
install the programs, do the following:
cd $inn
make update
This target does a ``make install'' in all program direc-
tories. It installs the programs and manpages, but does not
update or install any configuration files or scripts. This
is important: in any directory (including the top-level
one), a ``make install'' will install everything in that
directory into the right place. A ``make update'' can only
be done in the top-level directory or in the site directory.
ably want to do an ``update'' first, and then review the
changed files by doing ``make diff'' in the site directory,
and integrate your local changes as appropriate. The
Makefile also has other targets that you might find useful,
so the comments for entries like ``most'' and ``installed-
diff'', for example.
The next, and last, step is to build your INN confi-
guration files and utility scripts. If you have not already
done so, type the following:
cd $inn/site
make all
This will get copies of the scripts and files from the sam-
ples directories and run subst over them. Whenever patches
are issued, doing a make in this directory will let you know
what files have been updated, without destroying your local
changes. The getsafe.sh script does this. If you have
either an SCCS or an RCS directory then getsafe.sh will use
the appropriate source control system for the files in this
directory.
The first set of files are used to carry out the con-
trol messages. You might want to look them over; in partic-
ular, look at the table in control.ctl and the newslog man-
pages in doc. The control files are:
checkgroups rmgroup
control.ctl sendme
default sendsys
docheckgroups senduuname
ihave version
newgroup writelog
parsecontrol pgpverify
The following scripts are normally invoked by cron or
at system boot time, and should not require many changes:
innlog.pl scanlogs
innstat tally.control
news.daily tally.unwanted
rc.news
Rc.news starts the server. In versions 1.4 and earlier, this
script was run by user root. In this version, rc.news must
be run by the user defined as the NEWSUSER in the
config.data file. News.daily invokes expire and scanlogs.
Scanlogs calls the other scripts to process the logs. You
might want to review these scripts just to see what they do.
Do not get bogged down in the details, just read the com-
There are some utility scripts to send news to your
news feeds:
nntpsend send-nntp
nntpsend.ctl send-uucp
send-ihave sendbatch
They flush and lock the batch file for the specified site(s)
and then call innxmit to send the articles to your down-
stream feeds. Send-ihave is used for ``ihave/sendme'' feeds
and is described in an appendix. Sendbatch and send-uucp
flush and lock batchfiles and call batcher to queue up UUCP
jobs. You might want to modify these files to change the
flags given to uux; the default is to queue jobs up as grade
``d.'' You will almost definitely have to edit them to make
sure that they properly parse the output of df so that your
spool area is not overrun! Nntpsend and send-nntp do the
same thing for NNTP feeds. You must determine how you want
to propagate your articles - the scripts give common ways of
getting the job done.
The following files will have to be edited to contain
your local information. They all have manual pages in the
doc directory that describe them:
expire.ctl newsfeeds
hosts.nntp nnrp.access
inn.conf passwd.nntp
moderators
The last group of files are utility scripts you might
find useful:
inncheck innwatch
scanspool
Inncheck is a Perl script to check the syntax and permis-
sions of an installed INN system. Innreport is an alternate
way of summarizing the server's log file. It is a Perl
script. It will become the standard log reporting mechanism
in a future release. Innwatch is a shell script to monitor
the system and stop the server when you are running low on
disk space or inodes; it could be run out of your
_PATH_NEWSBOOT script - it is set to be run by default.
Scanspool is a Perl script to make sure that the active file
and the contents of your spool tree agree.
Once you have made the necessary modifications (and I
admit that some of this - especially the newsfeeds file -
will be difficult), you should type the following:
make install
Make sure you have rc.news installed in the right place, as
explained in the ``Paths to common programs'' section,
above. You might find it useful to read the ``First-Time
Usenet or NNTP Installation'' appendix for help on navigat-
ing through the INN configuration files.
There are now only a couple more things to check.
First, make sure you have an active file and a history data-
base! The appendices explain how to convert your existing
files; the BUILD script will create new ones for you. If
you have Perl, run inncheck to make sure that you have the
datafiles configured correctly. The second is make sure
that you have correctly updated your syslog.conf file to
match the filenames and logging levels required by INN. See
syslog/syslog.conf for an example of what to do.
Once you have done all of this, InterNetNews is now
installed, and ready to run - have fun!
8. Heterogeneous Client Installations
The inews program is used by user newsreaders. Pro-
grams such as rn (which call Pnews) prepare a news article
and feed it into inews. Inews validates the news headers,
adds its own, and feeds the article to the campus innd
server. The inews that comes with INN is more useful than
the ``mini-inews'' that comes with the reference implementa-
tion. You cannot run the standard B2.11 inews. You can run
the C News inews, but only on client machines (i.e., those
with a $NEWSCTL/server file). I recommend that you install
INN's inews on all the clients in your campus.
INN comes with a MakeInews script to make it easier to
build and install inews on a wide variety of hosts. This
script creates a directory and copies all the necessary
files (headers, sources, configuration files) into it. The
script takes an optional argument, which should name the
client machine's architecture. For example:
cd $inn
./MakeInews sun3
will create an inews.sun3 directory. You can then examine
the Makefile in that directory, and build and install inews
on your Sun-3 clients. This is easiest if the client NFS-
mounts the source directory - that way you can keep all your
inews sources in one place.
Rnews only has to be available on the machine where you
run UUCP (and perhaps a mail-news gateway). If this is not
eInews script.
Man(1) output converted with
man2html