Installing InterNetNews Rich $alz Updated by: James Brister Internet Software Consortium please send electronic mail to <inn@isc.org> 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 overview 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 maintaining public software, you should probably read this.

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 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 useful to read Managing UUCP and Usenet (get the most recent edition available), ISBN 0-937175-48-X. Both books are published by O'Reilly & Associates; send inquiries to to <nuts@ora.com>.

There is a chapter on INN in The Internet Connection: A Guide to Connectivity and Configuration, ISBN 0-201-54237-4 by Smoot Carl-Mitchell and John S. Quarterman. It is published by Addison-Wesley.

There is a book called Administering Usenet New 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 comfortable with host names and dotted-quad addresses. If you have installation problems, you should know about stream and datagram sockets and the like. In addition to any documentation available from your vendor, you might find it useful to read the two IPC tutorials in Programmer's Manual: Supplementary Documents 1. Copies can be purchased from the Usenix Association; send inquiries to <office@usenix.org>.

There are two RFCs that are important to InterNetNews. RFC 1036 describes the format of Usenet articles. It is incomplete and has some errors, but it is the only formal document available. RFC 977 defines NNTP, the Network News Transfer Protocol. RFCs are available from several places, including anonymous FTP to nnsc.nsf.net, where they can be found in the directory 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 interpretation 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 are B2.11 and C News. Both of them require a separate NNTP implementation. 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 News porting problems (see the DBZ sections in particular, and ignore most of the shell comments), while the third 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. 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. Distribution Roadmap

The INN sources are divided into the following directories:

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

include
    Header files 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} periodically.

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 to be done as root, except that inndstart needs to be installed setuid root, and so 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 replacement of the reference implementation's ``clientlib'' routines needed by remote rn.

MakeInews
    Script to build an inews distribution directory.

MakeRnews
    Script to build an rnews distribution directory.

sedf.xxx
    Various sed scripts to filter the output of lint.

README.perl_hook
    A description for PERL filtering.

README.tcl_hook
    A 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. 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 programs. The programs are then installed, and the INN data files are set up.

The configuration process is deliberately not interactive. Configure scripts like the one in rn are fun to watch, but they spend too much effort on the wrong job, like 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. Building subst

INN uses the C News subst program to automate the configuration. 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 If you get any compilation errors, you will have to edit the file config/subst.c. If you are using an early version of 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.) 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.

The format of the file is very strict. A line starting with a poundsign is a comment line. All other lines must be 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. 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 -Dregister= 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 format: 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.

Unfortunately, on some systems lint is all but useless, so complain to your vendor and take the output with a grain 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. 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) manpage 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 syslog(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. 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 administration tasks must be done as user NEWSUSER (see the explanation of SOCKETS CREATED BY INND OR CLIENTS section below). In addition, inews will only let the NEWSUSER user or members of the NEWSGROUP group post control messages other than cancel.

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. 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 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 syslog routines; see the end of the file syslog/README for details on this.)

INN needs to know how many descriptors are available to use for files and sockets. There are several ways to get this number; the FDCOUNT_STYLE parameter specifies which 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. C LIBRARY OMISSIONS

INN uses library routines that might not be present in all systems, although they should be. The lib directory 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-language versions of the string routines in the ATT library. To use these routines, add ``$(OSXATTOBJ)'' to the MISSING_OBJS parameter. This will cause lib/Makefile to extract the object files from the ATT library, and add them to the INN library. 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 general, 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 parameters.

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 probably 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 pathname 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.)

The xxx_TIMEOUT parameters control various timers within INN; you might want to change some of these depending 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''. PATHS TO COMMON PROGRAMS

INN uses a few standard programs like /bin/sh and sendmail. If you don't have sendmail then you must have a program that accepts a full message — including headers — on its standard input, and delivers it. This program is specified 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 summaries 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 you can run to see if your egrep will work. PATHS RELATED TO THE SPOOL DIRECTORY

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 outgoing batch files. Since no newsgroup can ever have a dot in its name, a directory like out.going can never be a newsgroup 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. EXECUTION PATHS FOR INND AND RNEWS

All control messages (other then ``cancel'') are carried 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 directory 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. SOCKETS CREATED BY INND OR CLIENTS

The innd server and its clients (most notably ctlinnd) create 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 directory is /usr/local/news/innd and that it is owned by user news in group news and has mode 0770. Using these permissions, 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 ``Ownerships and file modes'' section, above. 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. 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 system load average is low enough to allow article reception. There are two reasons for this. The first reason is philosophical: 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 incomplete.) The second reason is pragmatic: there is no portable way to get standard measurements for the information needed. For example, C News provides three different routines 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, INN uses an external program (shell script) that invokes ctlinnd to stop and start the server as necessary. The program, 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 probably 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 frequently innwatch should check the system — the other parameters 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 average 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. TCL Configuration

The innd server can be configured to include TCL hooks to be run whenever a new article is received and when certain 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 DONT, then this should be blank.

The _PATH_TCL_STARTUP parameter specifies the path of 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. PGP Configuration

Inn now has mechanisms in place that will do PGP verification of control messages (except for cancels). It is highly recommended that you use PGP if you can. Forged control 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 verification 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 authenticated 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 many large heirarchies is already enabled in control.ctl(5). To enable PGP verification for another heirachy, in addition 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 CONTROLPROGS 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 "newgroup". 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 lines. This time verification should fail. Keyword Configuration

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. Local Configuration

At this section local definitions like home directory of NEWSUSER are specified. This parameter is used for setting environment variable handed to innd when invoked by inndstart. 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. 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 supported 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 you need to link against to include perl support. Typically ``-lperl -lm'' are required. If you defined PERL_SUPPORT to 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 location 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 location 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 location you define here.

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

MISSING_SRC    memmove.c
MISSONG_OBJ    memmove.o

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 following near the end of the inittab file, just before the ``cons'' line: rcnews:wait:2:/usr/local/etc/rc.news >/dev/console 2>&1

LIBS    -lbsd
Make sure you don't use gcc version 1; it miscompiles the socket calls in innd/cc.c.

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 processing newgroup messages.

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.

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.

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.

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

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 mmap; the Ultrix version of the system call is for devices, not files. Some sites have reported problems with using the syslog that INN includes (output doesn't show up, or floating 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. Other Source Preparations

In addition to setting up the configuration file, it might be necessary to do some other setups. 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. 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, respectively. 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 of this issue.

Apparently the System V 386 compiler can't optimize dbz.c (the GNU C compiler doesn't have this problem). If you have ``-O'' in your DBZCFLAGS configuration parameter, then take it out. 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 parameters.

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

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 following: cd $inn/config make quiet cd .. This will use your already-tested subst program with your new config.data file. You should then follow the steps in the following sections. Building the Library

The next step is to build the INN library. Do the following 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 anything 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. Compiling the Programs

INN's programs are separated into six areas, as detailed in the roadmap. You'll need to build each one before you can install and use INN. 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 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 the news administrator, and then exec's innd with the open port. It also sets up a secure execution environment. It is a small program (about 100 lines) that is easily understood. You should use it because innd will run faster 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 example, you can have newsgroups within ``control'' for the different types of control messages. See innd.8, newsfeeds.5, and active.5 in the doc directory for details. 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. 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.

actsync
    A program to synchronize active file with remote site.

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 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, specifying 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.

convdate
    Converts between user-readable dates and the format used in the history file.

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 prunehistory; 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. 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 be the hardest part of your installation.

Prototypes for all these files are provided in the samples 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. Manual pages

INN comes with an extensive set of manual pages. You might want to edit the Makefile to set up the right ownership 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. 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 directories. 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. The former only replaces executables, not configuration files. When updating to a new INN release, you will probably 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 configuration 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 samples 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 control messages. You might want to look them over; in particular, look at the table in control.ctl and the newslog manpages 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 comments. They are documented in the manpages news.daily(8), newslog(5), and newslog(8).

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 downstream 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 permissions 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 navigating 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 database! 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! Heterogeneous Client Installations

The inews program is used by user newsreaders. Programs 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 implementation. 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 the same machine as where innd is running, then the MakeRnews script can be used in the same manner as the MakeInews script.