








                     [1mInstalling InterNetNews[0m


                            [4mRich[24m [4m$alz[0m
                    [4mUpdated[24m [4mby:[24m [4mJames[24m [4mBrister[0m
                  Internet Software Consortium

          [4mplease[24m [4msend[24m [4melectronic[24m [4mmail[24m [4mto[24m [4m<inn@isc.org>[0m


                            [4mABSTRACT[0m

          This  document discusses how to install and set up
     InterNetNews.  You should be familiar with  Usenet  and
     networks;  the  first section gives references to docu‐
     mentation for these topics, and the appendix IV gives a
     Usenet installation overview for novices.

          This document also describes what many of the pro‐
     grams 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.



[1m1.  Things You Should Know Before You Do Anything[0m

     InterNetNews  is abbreviated [4mINN[24m, which is pronounced as the
three letters, [4meye[24m [4men[24m [4men[24m.  It is a Usenet transport  and  expira‐
tion  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 [4mUsing[24m [4mUUCP[24m [4mand[0m
[4mUsenet[24m, ISBN 0‐937175‐10‐2.  You might also  find  it  useful  to
read [4mManaging[24m [4mUUCP[24m [4mand[24m [4mUsenet[24m (get the most recent edition avail‐
able),  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  [4mThe[24m  [4mInternet[24m  [4mConnection:[24m  [4mA[0m
[4mGuide[24m  [4mto[24m  [4mConnectivity[24m  [4mand[24m [4mConfiguration[24m, ISBN 0‐201‐54237‐4 by
Smoot Carl‐Mitchell and John S. Quarterman.  It is  published  by
Addison‐Wesley.

     There  is  a  book  called [4mAdministering[24m [4mUsenet[24m [4mNew[24m [4mServers[24m,
ISBN 0‐201‐41967‐X, by James McDermott  and  John  E.   Phillips.
Published by Addison‐Wesley. It has good INN 1.5.1 coverage.


───────────
† UNIX is a registered trademark of X/Open Company Ltd.


                       Northern Winter 1997






                               ‐2‐


     In November 1997, there was a new version of [4mManaging[24m [4mUsenet[0m
(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  comfort‐
able  with host names and dotted‐quad addresses.  If you have in‐
stallation problems, you should know about UNIX‐domain 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  [4mUNIX[24m  [4mProgrammer’s[24m  [4mManual:[24m   [4mSupplementary[0m
[4mDocuments[24m  [4m1[24m.   Copies  can be purchased from the Usenix Associa‐
tion; 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  avail‐
able.   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 [4mrfc[24m.
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 imple‐
mented, and while INN will not provide all  of  them,  they  will
have some impact.

     InterNetNews  does  things differently from other news soft‐
ware.  Some other Usenet systems for UNIX 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  [4msendmail[24m ‘‘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 [4mdoc/biblio[24m, [4mdoc/problems[24m, and [4mdoc/rfcer‐[0m
[4mrata[24m in the C News distribution worthwhile reading.  The first is
a bibliography, the second discusses known C News  porting  prob‐
lems  (see the DBZ sections in particular, and ignore most of the
shell comments), while the third lists some technical and  philo‐
sophical errors in RFC 1036.

     The  commands  below assume that [4m$inn[24m 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


                       Northern Winter 1997






                               ‐3‐


Spencer; and Stan Barber, Erik Fair, Brian Kantor, and Phil Laps‐
ley.  The financial support of UUNET Technologies is also greatly
appreciated.  The beta‐test sites gave invaluable feedback.

[1m2.  If You Are Impatient[0m

     If you don’t want to follow these directions, do the follow‐
ing:

     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.

[1m3.  Distribution Roadmap[0m

     The INN sources are divided into the following directories:

[4mfrontends[24m      Programs to feed articles to  the  central  server
               and control it.

[4minnd[24m           The central NNTP server.  It accepts incoming con‐
               nections, receives articles, and arranges for them
               to be sent to downstream newsfeeds.

[4mbackends[24m       Programs to transmit articles to other sites.

[4mexpire[24m         Programs  to  purge  the article files and history
               database.

[4mnnrpd[24m          An NNTP server for on‐campus clients that do news‐
               reading (as opposed to bulk article transfer).

[4mlib[24m            Library routines used by all the above.

[4minclude[24m        Header files used by all the above.

[4mdbz[24m            DBZ database package.

[4msyslog[24m         Syslog routines for the systems which  don’t  pro‐
               vide proper functions needed for INN.

     The distribution also includes these directories:

[4msamples[24m        Prototype  scripts  and  configuration  files that
               might have to be edited before they are installed.



                       Northern Winter 1997






                               ‐4‐


[4msite[24m           A place to store edited copies of the files in the
               [4msamples[24m directory.

[4mdoc[24m            Manual pages for all the above.

[4mconfig[24m         Tools to configure the release for your site.

[4msample‐configs[24m Sample configuration data for any system.

[4mauthprogs[24m      Sample program which can be used for an  authenti‐
               cation with nnrpd.

[4mcontrib[24m        Contributed programs useful for INN.

[4mobsolete[0m

[4mFAQ[24m            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  di‐
rectory:

[4mREADME[24m         A basic introduction.

[4mCOPYRIGHT[24m      The   distribution   copyright.   InterNetNews  is
               freely redistributable, provided proper credit  is
               given.

[4mMANIFEST[24m       A  one‐line  description of every file in the dis‐
               tribution.

[4mBUILD[24m          An interactive script to configure, build, and in‐
               stall INN.

[4mmakedirs.sh[24m    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 per‐
               mission 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.

[4mMakefile[24m       Rules to call the other Makefiles and make distri‐
               butions.

[4mInstall.ms[24m     This    document.    It   requires   the   ‘‘−ms’’
               nroff/troff macro package.

[4mMakeLib[24m        Script to build a directory with a replacement  of
               the  reference implementation’s ‘‘clientlib’’ rou‐
               tines needed by remote [4mrn[24m.




                       Northern Winter 1997






                               ‐5‐


[4mMakeInews[24m      Script to build an [4minews[24m distribution directory.

[4mMakeRnews[24m      Script to build an [4mrnews[24m distribution directory.

[4msedf.xxx[24m       Various [4msed[24m scripts to filter the output of [4mlint[24m.

[4mREADME.perl_hook[0m
               A description for PERL filtering.

[4mREADME.tcl_hook[0m
               A description for TCL filtering.

[4mCONTRIBUTORS[24m   Contributors to INN.

[4mHISTORY[24m        History until INN 1.4.

[4miftrue.sh[24m      Script that does test(1).

[4minstallit.sh[24m   Script that installs programs, scripts and config‐
               uration files for INN.

[4mPGPKEYS[24m        PGP public keys used for control message authenti‐
               cation.

[1m4.  Building the System[0m

     INN is built in steps.  First, the [4msubst[24m program  is  built.
Next, a configuration file containing key/value pairs is created.
[4mSubst[24m 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;  [4mlint[0m
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 [4mrn[24m are fun to watch,  but  they
spend too much effort on the wrong job, like whether [4mgrep[24m 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 config‐
uration data is in one header file, changing almost anything will
force everything to be recompiled.

[1m4.1.  Building subst[0m

     INN uses the C News [4msubst[24m program to automate the configura‐
tion.   [4mSubst[24m is a very clever way of safely editing a file under
the control of a configuration file.  For more details,  see  the
documentation  in [4mdoc/subst.1[24m.  Thanks to Henry Spencer and Geoff
Collyer for their permission to use and redistribute [4msubst[24m.



                       Northern Winter 1997






                               ‐6‐


     We will use [4mconfig.dist[24m as the configuration  file  to  test
the  version  of  [4msubst[24m  that you build.  (You can always replace
your config file with the distribution file and do  another  [4mmake[0m
to restore the original versions.)

     The  C News [4msubst[24m program is a shell script that uses [4msed[24m to
do the editing.  The INN configuration file is too large for some
versions of [4msed[24m.  The first step is to see if your [4msed[24m 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 [4msed[24m 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 ver‐
sion  of  [4msed[24m,  such  as the one distributed by the Free Software
Foundation.  If you do this, edit [4mconfig/Makefile[24m 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  [4msubst[24m.   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
[4mconfig/subst.c[24m.   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  [4msubst[24m  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 [4mconfig[24m 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 [4msubst[24m makes its changes safely,  this  step
is optional.)

[1m4.2.  Editing config.data[0m

     Once you have [4msubst[24m working, the next step is to set up your
configuration parameters.  This is the hardest part of installing
INN.   [4mDon’t[24m [4mpanic![24m  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 [4msample‐configs[24m directory, and


                       Northern Winter 1997






                               ‐7‐


copy it to [4mconfig/config.data[24m. If there is  no  sample  for  your
system, you should copy [4mconfig/config.dist[24m, the distribution mas‐
ter,  to [4mconfig/config.data[24m, 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  sec‐
tions:

     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 [4mconfig.data[24m 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 [4m<one‐or‐more‐tabs>[24m value

If  there is no ‘‘value’’ the ‘‘<one‐or‐more‐tabs>’’ is still re‐
quired.  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.

[1m4.2.1.  MAKE CONFIG PARAMETERS[0m

     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 [4mgcc[24m [4m−Wall[24m on the [4mCC[24m line.  If
you need extra [4m−I[24m flags put them on the [4mDEFS[24m line.  INN uses  the
[4mregister[24m  declaration  a  great  deal.   If your compiler is very
good, you might want to add [4m−Dregister=[24m to the [4mDEFS[24m line so  that
INN’s declarations are ignored.




                       Northern Winter 1997






                               ‐8‐


     The DBZ package can be compiled so that the database is mem‐
ory‐mapped.   If  you  want  to  do this and have the [4mmmap[24m system
call, then add ‘‘−DMMAP’’ to the [4mDBZCFLAGS[24m parameter.

     If you need to link in other  libraries  (e.g.,  [4m−lnet[24m)  put
them on the [4mLIBS[24m line.

     The  Makefiles  usually filter all [4mlint[24m output through a [4msed[0m
script.  If you are very paranoid, set  [4mLINTFILTER[24m  to  [4mcat[24m.   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 [4mLINTFILTER[24m to be the ‘‘sedf.sysv’’ line.

     The  [4mlib[24m  directory  also builds a [4mlint[24m library, so that you
can make sure the other programs are properly using  the  library
routines.   The  [4mLINTLIBSTYLE[24m parameter (used in [4mlib/Makefile[24m and
[4mlib/makellib.sh[24m) controls how the [4mlint[24m library is built.  If your
[4mlint[24m 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 [4mlint[24m 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 un‐
defined.  You can ignore them and ask your vendor to support  the
BSD  ‘‘−z’’ lint flag.  If you set [4mHAVE_UNISTD[24m to ‘‘DO’’ then you
might get warnings about prototype mismatches for  various  func‐
tions declared in [4minclude/clibrary.h[24m.  You can ignore them or re‐
move the lines from the INN header file.

     The   [4mMANPAGESTYLE[24m   parameter  (used  in  [4mdoc/Makefile[24m  and
[4mdoc/putman.sh[24m) controls how manual pages are installed into  your
public  directory  while the [4mMANx[24m parameters specify the directo‐
ries where they get installed.  If you do not want to install any
manpages, set [4mMANPAGESTYLE[24m to [4mNONE[24m.

[1m4.2.2.  LOGGING LEVELS[0m

     INN uses the modern [4msyslog[24m that separates messages into both
levels and categories.  Look in your [4m<syslog.h>[24m header file for a
‘‘LOG_NEWS’’ macro, and check your [4msyslog[24m(3) manpage to make sure
that [4mopenlog[24m takes three arguments.  If it doesn’t, then you will
have to use the library routine and server provided in the [4msyslog[0m
directory.  This is described later.

     The different levels that are  described  in  the  [4msyslog[24m(3)
manpage  are  confusing,  so  INN uses its own names for the four


                       Northern Winter 1997






                               ‐9‐


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 [4msyslog.conf[24m(5) file is set  up,  you  might
want to change the [4mL_xxx[24m parameters in this section.

     The  [4mscanlogs[24m script assumes that the first three categories
above are each directed into separate files.  See  [4mdoc/newslog.5[24m,
[4mdoc/newslog.8[24m,  and  [4msyslog/syslog.conf[24m  for details.  LOGGING is
also described in more detail in the LOG AND  CONFIG  FILES  sec‐
tion.

[1m4.2.3.  OWNERSHIPS AND FILE MODES[0m

     The NNTP server needs to open the NNTP port; it is port num‐
ber  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 [4mNEWSUSER[24m and
[4mNEWSGROUP[24m parameters.  Most news  administration  tasks  must  be
done  as user [4mNEWSUSER[24m (see the explanation of SOCKETS CREATED BY
INND OR CLIENTS section below).  In addition, [4minews[24m will only let
the [4mNEWSUSER[24m user or members of the [4mNEWSGROUP[24m 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  [4mNEWSMASTER[24m  parameter  specifies the right ad‐
dress.  This is most often the login name of  the  account  which
has  [4mNEWSUSER[24m  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  guar‐
anteed  to  work, and INN tries to help stop this practice by re‐
fusing to generate valid Path addresses.  The [4mPATHMASTER[24m  parame‐
ter  specifies  what [4minews[24m should put at the tail end of the Path
line.  If your [4mNEWSMASTER[24m 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 [4mxxx_MODE[24m 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 [4mNEWSUSER[24m.

[1m4.2.4.  C LIBRARY DIFFERENCES[0m

     Editing the parameters in this section will require  you  to
look around at the files in your [4m/usr/include[24m directory.



                       Northern Winter 1997






                               ‐10‐


     The [4mSIZE_T[24m parameter is the datatype of the ‘‘size’’ parame‐
ters  in  subroutine calls like [4mmemchr[24m and [4mfread[24m.  The [4mLOCK_STYLE[0m
parameter specifies how file‐locking should be done.  [4mInnxmit[24m  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 [4mDIR_STYLE[24m parameter specifies what is returned  by  your
[4mreaddir[24m(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 [4mHAVE_UNIX_DOMAIN[0m
to ‘‘DONT.’’  This means that INN will use a named pipe  for  the
communication between [4minnd[24m and [4mctlinnd[24m.  It also means that there
will  be  no local ‘‘private’’ port for [4mrnews[24m to use; this should
not cause any problems, although it makes it easier for anyone to
use [4mrnews[24m and post fake news articles.  (You might also  have  to
modify the [4msyslog[24m routines; see the end of the file [4msyslog/README[0m
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  num‐
ber;  the  [4mFDCOUNT_STYLE[24m parameter specifies which method to use.
On most systems, the [4mgetdtablesize[24m routine will do this, so leave
the default of ‘‘GETDTAB.’’  On other systems you need to use the
[4mgetrlimit[24m, [4msysconf[24m or [4mulimit[24m 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  ‘‘CON‐
STANT’’  and edit the file [4mlib/getdtab.c[24m to return the right num‐
ber.  To get this number, look for an [4mOPEN_MAX[24m constant  in  your
system  header  files,  or  write a program that repeatedly opens
[4m/dev/null[24m until it gets an error.

     The last few parameters in this section,  [4mxxxVAL[24m,  are  used
primarily  to  keep  [4mlint[24m quiet.  These functions are declared in
[4minclude/clibrary.h[24m, and the return values are pretty much  always
ignored.   You  can usually determine what these values should be
by examining your manpages or your [4mlint[24m libraries.

[1m4.2.5.  C LIBRARY OMISSIONS[0m

     INN uses library routines that might not be present  in  all
UNIX  systems,  although  they should be.  The [4mlib[24m directory pro‐
vides versions of some of these routines, including copies of the
freely‐redistributable BSD  string  routines.   The  [4mMISSING_SRC[24m,
[4mMISSING_OBJ[24m  and  [4mMISSING_MAN[24m parameters can be set to list those
routines that are missing from your C library.  If you don’t have
[4mstrcasecmp[24m and [4mstrncasecmp[24m then you will need the [4mstrcasecmp[24m mod‐
ule built into your INN library.  Add the ‘‘.c’’ and ‘‘.o’’ names
to [4mMISSING_SRC[24m and [4mMISSING_OBJ[24m, respectively.




                       Northern Winter 1997






                               ‐11‐


     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 [4minet_ntoa[24m as  a  missing  function.
This  is  because  the  first version of [4mgcc[24m didn’t properly pass
structures into routines compiled with the Sun C compiler.

     If you have an older version of [4msyslog[24m add [4msyslog.c[24m and [4msys‐[0m
[4mlog.o[24m 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 [4mMISSING_OBJS[24m parameter.
This will cause [4mlib/Makefile[24m to extract the object files from the
ATT library, and add them to the INN library.

[1m4.2.6.  MISCELLANEOUS CONFIG DATA[0m

     All the parameters in this section become macros in the file
[4minclude/configdata.h[24m.  You should at least look through the para‐
meters up to [4mVERIFY_CANCELS[24m.  (If set to ‘‘DO’’, then  [4minnd[24m  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 experi‐
ence running INN.  Nevertheless, here are some comments  on  some
of the more useful parameters.

     [4mInnd[24m  can memory‐map the [4mactive[24m file if you set [4mACT_STYLE[24m to
‘‘MMAP’’.  On some systems, however, when a mapped  file  is  up‐
dated its mtime is not updated.  Apparently some versions of Sys‐
tem V Release 4 have this problem.  This causes problems for pro‐
grams  like [4mnnmaster[24m which look at the [4mst_mtime[24m field of the [4mstat[0m
structure in order to determine if any new news has come in.  The
best work‐around is probably an hourly [4mcron[24m job that touches  the
[4mactive[24m file.

     There  are  a number of parameters that control the behavior
of [4mrnews[24m.  If you set [4mRNEWS_SAVE_BAD[24m to ‘‘DO’’ then articles that
[4minnd[24m rejects for reasons like bad headers will be  saved  in  the
[4m_PATH_BADNEWS[24m  directory; you will have to periodically scan this
directory and clean it up.  You can also control how  [4mrnews[24m  logs
duplicates  (those  aren’t  saved  regardless  of  the  value  of
[4mRNEWS_SAVE_BAD[24m), logging them through [4msyslog[24m, to a file, or  not.
Note  that  if  you set [4mRNEWS_LOG_DUPS[24m to ‘‘FILE’’, then you will
want to change [4m_PATH_RNEWS_DUP_LOG[24m, which appears  later  in  the
file.   If  you  receive  news from several UUCP feeds, you might


                       Northern Winter 1997






                               ‐12‐


want to log duplicates so that you can cut down your phone  bills
by  optimizing your feeds.  The [4mRNEWSPROGS[24m parameter says whether
or not to look in [4m_PATH_NEWSPROGS[24m for commands named on  the  in‐
coming  ‘‘#!’’  line  of  news batches.  You probably want to set
this to ‘‘DO’’.  Make sure  that  the  full  pathname  of  [4mrnews[24m,
[4m_PATH_RNEWS[24m,  does not conflict with the directory where your un‐
packers are put, [4m_PATH_NEWSPROGS[24m.

     If [4mIPADDR_LOG[24m 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  [4minnd[24m  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 [4mxxx_TIMEOUT[24m parameters  control  various  timers  within
INN;  you  might  want  to change some of these depending on your
system load.

     The [4mLIKE_PULLERS[24m 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  de‐
fault), 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 [4mLIKE_PULLERS[24m is set to ‘‘DONT’’.

[1m4.2.7.  PATHS TO COMMON PROGRAMS[0m

     INN uses a few standard programs like [4m/bin/sh[24m and  [4msendmail[24m.
If  you don’t have [4msendmail[24m then you must have a program that ac‐
cepts a full message —— including headers —— on its standard  in‐
put,   and  delivers  it.   This  program  is  specified  by  the
[4m_PATH_SENDMAIL[24m  parameter,  and  is   normally   ‘‘/usr/lib/send‐
mail ‐t’’.   The  parameter  is  actually a [4msprintf[24m 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 re‐
placed with a ‘‘%s’’.

     INN puts most of its executables in the directory  specified
by  the  [4m_PATH_NEWSBIN[24m parameter.  Some programs expect [4minews[24m and
[4mrnews[24m to be in certain places; for example,  UUCP  usually  wants
[4mrnews[24m  in [4m/bin[24m.  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 [4m_PATH_NEWSBIN[24m to the  PATH  of  any
such scripts.

     If  you have an [4m/etc/rc.local[24m file you should make sure that
it invokes the script named by the [4m_PATH_NEWSBOOT[24m parameter.   On


                       Northern Winter 1997






                               ‐13‐


other systems (mostly System V derivatives), the system boot pro‐
cedure  automatically runs all the scripts in a particular direc‐
tory, such as [4m/etc/init.2[24m.  In that case, you should pick a  name
like  [4m/etc/init.2/S99news[24m and have the news boot script installed
there, or install it in the default  [4m/etc/rc.news[24m  and  make  the
link yourself.

     The  daily  maintenance script, [4mnews.daily[24m calls [4mscanlogs[24m to
rotate and trim log files, as well as generating summaries  using
[4megrep[24m  and  [4mawk[24m.   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
[4mscanlogs[24m script has a short test you can run to see if your [4megrep[0m
will work.

[1m4.2.8.  PATHS RELATED TO THE SPOOL DIRECTORY[0m

     By default, all news articles are stored in directories  un‐
der [4m/usr/spool/news[24m.  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
[4mrnews[24m  when [4minnd[24m is not available), and its outgoing batch files.
Since no newsgroup can ever have a dot in its name,  a  directory
like  [4mout.going[24m  can never be a newsgroup name, and it is safe to
put  the  news  batchfiles  in  there.   This  is  used  by   the
[4m_PATH_SPOOLNEWS[24m parameter, and the [4m_PATH_BATCHDIR[24m parameter.

     Do  not  make  [4m_PATH_LOCKS[24m  be  in  the  same  filesystem as
[4m_PATH_SPOOLNEWS[24m.  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 [4mnews.daily[24m will not be able  to  run  and
that it won’t call [4mexpire[24m to free up disk space.  You should also
put [4m_PATH_NEWSLIB[24m 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 [4mmakedirs.sh[24m 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.

[1m4.2.9.  EXECUTION PATHS FOR INND AND RNEWS[0m

     All control messages (other then ‘‘cancel’’) are carried out
by scripts.  Your system must be able to [4mexec[24m shell  scripts  di‐
rectly.    All  the  scripts  distributed  with  INN  start  with
‘‘#! /bin/sh.’’

     The [4m_PATH_CONTROLPROGS[24m  parameter  specifies  the  directory
where these scripts exist.  Do not set this to a public directory
like  [4m/bin[24m  because  some  bozo  might send out an ‘‘rm’’ control


                       Northern Winter 1997






                               ‐14‐


message.

     The [4m_PATH_RNEWSPROGS[24m directory serves the same  purpose  for
[4mrnews[24m  when it needs to unpack batches.  The [4mRNEWSPROGS[24m parameter
specifies if the directory is really used.

[1m4.2.10.  SOCKETS CREATED BY INND OR CLIENTS[0m

     The [4minnd[24m server and its clients (most notably [4mctlinnd[24m)  cre‐
ate  UNIX‐domain sockets or named pipes.  They are created inside
a ‘‘firewall’’ directory that gives access permission to  a  lim‐
ited set of users.  For example, assume the directory is [4m/usr/lo‐[0m
[4mcal/news/innd[24m 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 [4mctlinnd[24m to create new groups because only they
will be able to send a message to the [4minnd[24m socket.

     This  directory (which is specified by the [4m_PATH_INNDDIR[24m pa‐
rameter) is also used to determine the user and group id  of  all
sub‐processes  spawned  by [4minnd[24m, as well as the owner of all news
articles and files.  The owner of this directory is  set  at  in‐
stallation  time  and  specified  in  the  ‘‘Ownerships  and file
modes’’ section, above.

[1m4.2.11.  LOG AND CONFIG FILES[0m

     INN keeps its databases, and some control  files  their  own
directory,  typically  named [4m/usr/local/news[24m.  Log files are kept
in [4m/var/log/news[24m.  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,
[4m_PATH_NNTPPASS[24m  and  [4m_PATH_NNRPACCESS[24m.   The default location for
these files is in [4m/var/news/etc[24m, so that it is generally safe  to
export [4m/usr/news[24m (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  [4mdoc[24m  direc‐
tory.

[1m4.2.12.  INNWATCH CONFIGURATION[0m

     The  INN server, [4minnd[24m, does not contain any checks to see if
there is enough free space on the disk or if the system load  av‐
erage  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


                       Northern Winter 1997






                               ‐15‐


config file, but any compiled rules are still likely to be incom‐
plete.)  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  [4mctlinnd[24m  to
stop  and  start the server as necessary.  The program, [4minnwatch[24m,
reads the control file [4minnwatch.ctl[24m.  [4mInnwatch[24m is  documented  in
[4mdoc/innwatch.8[24m,  while  [4minnwatch.ctl[24m  is  documented  in  [4mdoc/in‐[0m
[4mnwatch.ctl.5[24m.

     The parameters in  this  section  control  when  the  server
should  stop  accepting articles, and when it should start again.
You will have to examine [4msite/innwatch.ctl[24m  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 [4mINNWATCH_INODES[24m and [4mIN‐[0m
[4mNWATCH_BLOCKS[24m respectively), and on other lines,  as  appropriate
for your system.

     The  parameter  [4mINNWATCH_SLEEPTIME[24m  specifies how frequently
[4minnwatch[24m 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 [4mINNWATCH_SLEEPTIME[24m seconds.

     The  [4mINNWATCH_xxxLOAD[24m parameters specify the load average at
which different actions should be taken.  They are integers, rep‐
resenting the load average multipled by 100.  For example, if you
want to throttle the server when your load reaches 7.5,  set  [4mIN‐[0m
[4mNWATCH_HILOAD[24m to ‘‘750.’’

     The  [4mINNWATCH_xxxSPACE[24m 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
[4mdf[24m uses (512‐byte units, 1K blocks, etc).

     The [4mINNWATCH_SPOOLNODES[24m parameter specifies how many  inodes
must be available in your spool directory.

[1m4.2.13.  TCL Configuration[0m

     The innd server can be configured to include TCL hooks to be
run whenever a new article is received and when certain other ac‐
tions occur. See the file README.tcl_hook for more details.



                       Northern Winter 1997






                               ‐16‐


     The [4mTCL_SUPPORT[24m parameter specifies whether you want to com‐
pile in the Tcl support code. Select DO or DONT.

     The [4mTCL_LIB[24m parameter specifies the extra libraries you need
to  link  against to include tcl support. Typically ‘‘‐ltcl ‐lm’’
are required. If you defined  [4mTCL_SUPPORT[24m   to  DONT,  then  this
should be blank.

     The  [4m_PATH_TCL_STARTUP[24m  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  in‐
stalled in the location you define here.

     The [4m_PATH_TCL_FILTER[24m 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.

[1m4.2.14.  PGP Configuration[0m

     Inn  now  has mechanisms in place that will do PGP verifica‐
tion of control messages (except for cancels). It is [4mhighly[24m  rec‐
ommended that you use PGP if you can. Forged control messages are
a   serious   problem   in   USENET.    You   can  get  PGP  from
[1mhttp://web.mit.edu/network/pgp.html[22m.

     The [4mWANT_PGPVERIFY[24m parameter defines whether  PGP  verifica‐
tion  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 follow‐
ing 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 mes‐
sages received. As implemented, the system will perform  the  re‐
quested  action  if  the message can be authenticated and it will
mail the message to the news system administrator if it cannot.



                       Northern Winter 1997






                               ‐17‐


     Automatic processing of control messages is handled by  con‐
trol.ctl,  [4mControl.ctl[24m  has  several lines at the beginning of it
that describe the format of the file, and there is an even longer
[4mcontrol.ctl[24m(5) manual  page.  PGP  verification  for  many  large
heirarchies  is  already enabled in [4mcontrol.ctl[24m(5). To enable PGP
verification for another heirachy, in addition to the normal  au‐
thorization   done   by  control.ctl,  use  the  action  "verify‐
PGP_USERID" in the fourth field. The  supplied  [4mcontrol.ctl[24m  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 com‐
mand

     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.



                       Northern Winter 1997






                               ‐18‐


     Edit   /tmp/sample.control  and  change  all  occurences  of
newusers to newgroups. Then  repeat  the  parsecontrol  and  echo
lines. This time verification should fail.

[1m4.2.15.  Keyword Configuration[0m

     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 else‐
where in this document for that.

[1m4.2.16.  Local Configuration[0m

     At this section local definitions  like  home  directory  of
[4mNEWSUSER[24m are specified.  This parameter is used for setting envi‐
ronment variable handed to innd when invoked by inndstart.

[1m4.2.17.  Actsync configuration[0m

     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  [4mACTSYNC_HOST[24m  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.

[1m4.2.18.  Perl Configuration[0m

     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 [4mPERL_SUPPORT[24m parameter specifies  whether  you  want  to
compile in the perl support code. Select DO or DONT.

     The  [4mPERL_LIB[24m  parameter  specifies  the extra libraries you
need to link against to include perl support. Typically  ‘‘‐lperl


                       Northern Winter 1997






                               ‐19‐


‐lm’’  are  required.  If you defined [4mPERL_SUPPORT[24m  to DONT, then
this should be blank.

     The [4m_PATH_PERL_STARTUP_INND[24m 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  [4m_PATH_PERL_FILTER_INND[24m  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  ‘‘re‐
load’’  commands). A sample is included in samples/filter_innd.pl
which will be installed in the location defined by  this  parame‐
ter.

     The  [4m_PATH_PERL_FILTER_NNRPD[24m 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.


[1m4.3.  Typical config.data changes[0m

     The following sections show some of the changes that need to
be made to [4mconfig.data[24m so that INN will compile.  They  are  only
samples; ‘‘your mileage may vary.’’

     Note  that  if  you are using the first release of [4mgcc2[24m, set
[4mUSE_CHAR_CONST[24m to ‘‘DONT’’.


     _SunOS 4.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 [4msyslog[24m that comes with  INN.


                       Northern Winter 1997






                               ‐20‐


This   is  not  necessary  for  3.2.   Some  versions  also  need
[4mUSE_UNION_WAIT[24m set to ‘‘DONT’’.  You should also run [4mrc.news[24m from
[4minit[24m not [4m/etc/rc[24m; add a line like the following near the  end  of
the [4minittab[24m 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 [4mgcc[24m version 1; it miscompiles the socket
calls in [4minnd/cc.c[24m.


     _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 [4mSHELL[24m variable in [4mconfig/Makefile[24m and [4msite/Makefile[24m to
point to [4m/usr/contrib/bin/bash[24m.  Edit [4mlib/Makefile[24m  so  that  the
[4minstall[24m  target  does  not try to make [4m../llib‐linn.ln[24m.  You must
also use the GNU [4msed[24m; the version distributed with  BSDI  0.9.4.1
enters an infinite loop processing newgroup messages.










                       Northern Winter 1997






                               ‐21‐


     _HP‐UX 8.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 [4mbdf[24m command instead of [4mdf[24m.



















                       Northern Winter 1997






                               ‐22‐


     _SGI Indigo with IRIX 4.0.1_
     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 [4mMISSING_xxx[24m parameters should be empty.




























                       Northern Winter 1997






                               ‐23‐


     _Solaris 2.X/SunOS 5.X, using SPARCompiler C 2.X_
     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.















                       Northern Winter 1997






                               ‐24‐


     _System V Release 4_
     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 [4mlint[24m to be useful on the machine I used.
Some versions of System V (for example, Esix 4.0.3) need the fol‐
lowing LIBS value:

     LIBS              ‐lresolv ‐lsocket ‐lnsl ‐L/usr/ccs/lib ‐lelf

On a Dell System V machine, you have to set  [4mHAVE_UNIX_DOMAIN[24m  to
‘‘DONT.’’


     _Ultrix 4.x (RISC)_
     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 [4msyslog[24m.  You cannot use [4mmmap[24m; the
Ultrix version of the system call  is  for  devices,  not  files.
Some  sites have reported problems with using the [4msyslog[24m that INN


                       Northern Winter 1997






                               ‐25‐


includes (output doesn’t show up, or floating point  numbers  are
garbled,  etc.).   The  file  [4mjtkohl‐syslog‐complete.tar.Z[24m in the
[4m/pub/DEC[24m directory on  gatekeeper.dec.com  has  a  ‘‘for‐Ultrix’’
package that handles both old and new [4msyslog[24m calls.  While Ultrix
has symlinks, it does not have the ‘‘−follow’’ option in its [4mfind[0m
command.   This  is used in [4mexpire/makeactive.c[24m; you will have to
either install the GNU [4mfind[24m or edit the source file.

[1m5.  Other Source Preparations[0m

     In addition to setting up the configuration file,  it  might
be necessary to do some other setups.

[1m5.1.  Systems with old syslogs[0m

     If  you  need to install the [4msyslog[24m that is distributed with
INN, go to the top of the distribution and  type  ‘‘make  syslog‐
fix’’.   This will also compile [4msyslogd[24m, the logging daemon.  You
should install this to replace your existing daemon,  usually  in
[4m/etc/syslog[24m.   You  will  also need to install the new‐style [4msys‐[0m
[4mlog.conf[24m file.

     If you cannot replace [4msyslogd[24m on your machine, then see  the
file  [4msyslog/README[24m for information on how to set it up as an al‐
ternate daemon.

     Ignore any complaints from [4mlint[24m about the INN sources  call‐
ing [4mopenlog[24m with the wrong argument count.  In fact, if you [1mdon’t[0m
get  any complaints, then something is wrong with the way [4msyslog[24m,
[4m<syslog.h>[24m, or the [4mlint[24m libraries are set up on your system.

[1m5.2.  The DBZ package[0m

     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 [4mpatch[24m program and the context diff in
[4mlib/dbz.pch[24m.  If you don’t have [4mpatch[24m  installed,  then  you  can
make the changes manually.  (If you don’t have Larry Wall’s [4mpatch[0m
program get it from any [4mcomp.sources.unix[24m archive as well as many
FSF archives and other places —— you’ll be glad you did.)

     Both  [4minnd[24m and [4mnnrpd[24m 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 prob‐
ably  see  the  DBZ manpage in the [4mdoc[24m directory for some (brief)
additional discussion of this issue.

     Apparently the System V 386 compiler  can’t  optimize  [4mdbz.c[0m
(the  GNU  C  compiler  doesn’t  have this problem).  If you have
‘‘−O’’ in your [4mDBZCFLAGS[24m configuration parameter,  then  take  it
out.


                       Northern Winter 1997






                               ‐26‐


[1m5.3.  Using writev[0m

     INN makes extensive use the [4mwritev[24m system call to write sev‐
eral  I/O  buffers  in  a single call.  If you do not have [4mwritev[0m
then you must copy [4minclude/uio.h[24m to your [4m/usr/include/sys[24m  direc‐
tory.   You  must  also  add ‘‘writev.c’’ and ‘‘writev.o’’ to the
MISSING_SRC and MISSING_OBJ parameters.

     The ‘‘fake’’ [4mwritev[24m found in the [4mlib[24m directory is not highly
efficient.  You might want to write a better one  that  tries  to
[4mmalloc[24m  a new buffer and join all the elements.  Be careful about
doing this because [4minnd[24m can use very big buffers.

[1m6.  Compiling the System[0m

     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  ‘‘In‐
stalling the System.’’

     If you are confident, but careful, type:

     cd $inn
     make world
     cat */lint

This will compile everything, then run [4mlint[24m in all directories.

     Another  option  is to run the [4mBUILD[24m 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 [4msubst[24m  program  with  your  new
[4mconfig.data[24m  file.   You should then follow the steps in the fol‐
lowing sections.

[1m6.1.  Building the Library[0m

     The next step is to build the INN library.  Do the following





                       Northern Winter 1997






                               ‐27‐


     cd $inn/lib
     make libinn.a lint

     This will build the library and run  [4mlint[24m  on  the  sources,
putting  the output into a file named [4mlint[24m.  If anything fails to
compile, you probably made a configuration error, most likely  in
the  ‘‘C  library  differences’’ section.  In particular, double‐
check the [4mSIGHANDLER[24m and [4mxxx_STYLE[24m parameters.

     The [4mlint[24m output should be almost empty, except for a  couple
of  ‘‘possible pointer alignment problem’’ warnings in [4mdbz.c[24m.  If
you get much more than this, then you probably did not define the
[4mPOINTER[24m or [4mSIZE_T[24m parameters properly.  The [4mNEW[24m and [4mRENEW[24m  macros
in [4minclude/macros.h[24m try to capture all the alignment problems as‐
sociated  with  dynamic memory allocation.  Also double‐check the
[4mALIGNPTR[24m parameter and the [4mCAST[24m macro in [4minclude/macros.h[24m.

     If [4mlint[24m reports any other problems, you should take the time
to investigate them.  Note that many [4mlint[24m libraries have  errors.
Also,  you may get some problems in [4myaccpar[24m in [4mparsedate.y[24m; these
are most likely in the [4myacc[24m‐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 [4mlib[24m directory.  This will also compile  a  [4mlint[24m  li‐
brary 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 li‐
brary is different from making it available for  others  to  use,
and  installing  a  library  should  make it possible to run [4mlint[0m
against it.

[1m6.2.  Compiling the Programs[0m

     INN’s programs are separated into six areas, as detailed  in
the  roadmap.   You’ll  need to build each one before you can in‐
stall and use INN.

[1m6.2.1.  The Frontend Programs[0m

     Frontends are those programs that  talk  to  the  main  news
server,  either  offering  it articles or controlling its action.
This includes the following programs:

[4minews[24m          The program that validates and prepares news arti‐
               cles and gives them to [4minnd[24m.  This is mostly  used
               by  users  (usually  indirectly,  through programs
               like [4mPnews[24m), but also through  special  facilities


                       Northern Winter 1997






                               ‐28‐


               such as news/mail gateways.

[4mrnews[24m          Unpacks  news  batches  from UUCP sites and offers
               them to [4minnd[24m.

[4mctlinnd[24m        This program controls [4minnd[24m,  directing  it  to  do
               most  of  the tasks a news administrator will have
               to do:  create newsgroups, update  newsfeeds,  and
               the like.

[4msys2nf[24m         A  program  to turn a B or C News [4msys[24m file into an
               INN [4mnewsfeeds[24m 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

[1m6.2.2.  Innd[0m

     The next program is the main news server, which includes the
following programs:

[4minnd[24m           [4mInnd[24m accepts all incoming NNTP connections and ei‐
               ther  processes their traffic or hands them off to
               the NNTP ‘‘newsreader’’ server.  It accepts  arti‐
               cles, files them, and queues them so that they can
               be  sent to downstream feeds.  [4mInnd[24m listens on the
               official NNTP port.  On most systems only root can
               do this.  [4mInnd[24m is careful to set the modes of  any
               files it creates, as well as the privileges of any
               processes it spawns.

[4minndstart[24m      Sites  that  are concerned about large root‐access
               programs may wish to install [4minndstart[24m.  This pro‐
               gram opens the port, changes its user and group ID
               to be that of the  news  administrator,  and  then
               [4mexec[24m’s [4minnd[24m with the open port.  It also sets up a
               secure  execution environment.  It is a small pro‐
               gram (about 100 lines) that is easily  understood.
               You should use it because [4minnd[24m will run faster be‐
               cause  it  won’t  have  to  make  any [4mchown[24m system
               calls.  If you make [4minndstart[24m 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  [4minnd[24m handles the filing and distribution of cer‐
tain messages differently from other systems.  For  example,  you
can have newsgroups within ‘‘control’’ for the different types of


                       Northern Winter 1997






                               ‐29‐


control  messages.   See [4minnd.8[24m, [4mnewsfeeds.5[24m, and [4mactive.5[24m in the
[4mdoc[24m directory for details.

[1m6.2.3.  Nnrpd[0m

     [4mInnd[24m implements a subset of the NNTP protocol —— only  those
commands  that  are  needed for peer sites to feed news articles.
You must install [4mnnrpd[24m to allow users to read news.  If a connec‐
tion comes in from a host that is not a specified feed,  then  an
[4mnnrpd[24m  process  is spawned to handle it.  (You can debug [4mnnrpd[24m by
running it  interactively;  put  an  entry  for  the  host  named
‘‘stdin’’ in your [4mnnrp.access[24m 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 [4mnntpd[24m from the reference platform (See Appendix II)
and make sure not to list the peer in your [4mnntp.access[24m file.  The
other choice is to relink the reading software on the  other  ma‐
chine  with  the  INN library so that it uses the ‘‘mode reader’’
NNTP command extension.

[1m6.2.4.  The Backend Programs[0m

     The backend programs take articles that  [4minnd[24m  received  and
offer  them  to your news neighbors.  This includes the following
programs:

[4marchive[24m        A simple program to archive news articles.

[4mactsync[24m        A program to synchronize active file  with  remote
               site.

[4mbatcher[24m        Collects articles into batches for UUCP delivery.

[4mbuffchan[24m       A program to split a single [4minnd[24m stream into sepa‐
               rate  files.   It  can buffer data, flushing files
               based on command‐line switches.

[4mcrosspost[24m      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.

[4mcvtbatch[24m       A  program  to turn a file list into an INN batch‐
               file.  This is a transition aide.

[4mfilechan[24m       Another program to split a single [4minnd[24m stream into
               separate files.  It is system‐call intensive,  but
               requires no locking protocol.



                       Northern Winter 1997






                               ‐30‐


[4minnxbatch[24m      A  program  to  send articles with ‘‘XBATCH’’ NNTP
               command extension.

[4minnxmit[24m        A replacement for [4mnntpxmit[24m from the reference  im‐
               plementation.   It  reads a file containing a list
               of articles, and sends them to a host.

[4mnntpget[24m        A program to retrieve articles from a remote site.

[4mshlock[24m         A program to provide a locking protocol for  shell
               scripts.

[4mshrinkfile[24m     A  program to shrink a file by removing lines from
               the beginning.  It is  useful  for  purging  back‐
               logged batchfiles.

     To build this set of programs, type the following:

     cd $inn/backends
     make all

[1m6.2.5.  Expire[0m

     This directory includes programs to modify the history data‐
base as well as some utilities that might be useful in this task.
The database is called the [4mhistory[24m 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.

[4mconvdate[24m       Converts  between user‐readable dates and the for‐
               mat used in the history file.

[4mexpire[24m         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.

[4mmakeactive[24m     This program can be used  to  rebuild  the  [4mactive[0m
               file if it is lost in a crash.

[4mmakehistory[24m    This  program scans through the spool area and re‐
               builds the history files.

[4mnewsrequeue[24m    This program can be used after a crash  to  resend
               articles to your neighbors.

[4mprunehistory[24m   This  is  a  tool  for  other programs that expire
               news.  It reads a list of Message‐ID’s  and  file‐
               names,  and  updates the history file to mark that
               the files have been deleted.

     This directory also includes [4mexpire.pch[24m and  [4mreap.pch[24m.   The
first  is a patch to the C News expire program that lets it coop‐
erate better with [4minnd[24m, sending it messages  when  articles  have


                       Northern Winter 1997






                               ‐31‐


been removed.  The second is a set of patches to the [4mreap[24m program
that lets it cooperate with [4mprunehistory[24m; 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  di‐
rectory named [4mexpire[24m that is often the same pathname as INN’s [4mex‐[0m
[4mpire[24m  program.   You  will have to move, or remove, the directory
before you can intall the INN program.

[1m6.2.6.  Script and data files[0m

     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 [4mexpire[24m  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 [4msamples[0m
directory.  Your modified copies should be maintained in the [4msite[0m
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.

[1m6.3.  Manual pages[0m

     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 in‐
stalling them at all.

     When it comes to reading them, you should start with  [4minnd.8[0m
and  [4mctlinnd.8[24m.   From  there  follow the cross‐references as you
want.




                       Northern Winter 1997






                               ‐32‐


[1m7.  Installing the System[0m

     Although either [4minnd[24m or [4minndstart[24m  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 exe‐
cutable requires root priviledges, as it is installed as owned by
root and setuid.  The [4m$inn/makedirs.sh[24m  script  creates  all  the
necessary  directories  used by INN, and sets up the right owner‐
ships and modes: owned by [4mNEWSUSER[24m in group [4mNEWSGROUP[24m  with  0775
permissions  (the ‘‘firewall’’ directory, [4m_PATH_INDDDIR[24m, has mode
0770).  You should review this script, then run it.

     The rest of the installation should be done as the news  ad‐
ministrator or as root.  The Makefiles are very strict about set‐
ting  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 in‐
stall 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 [4msite[24m 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 [4msite[24m  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 [4msamples[0m
directories and run [4msubst[24m over them.  Whenever  patches  are  is‐
sued, doing a [4mmake[24m in this directory will let you know what files
have  been  updated,  without destroying your local changes.  The
[4mgetsafe.sh[24m script does this.  If you have either an  [4mSCCS[24m  or  an
[4mRCS[24m  directory  then  [4mgetsafe.sh[24m  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 [4mcontrol.ctl[24m and the newslog manpages in [4mdoc[24m.  The
control files are:



                       Northern Winter 1997






                               ‐33‐


     checkgroups    rmgroup
     control.ctl    sendme
     default        sendsys
     docheckgroups  senduuname
     ihave          version
     newgroup       writelog
     parsecontrol   pgpverify

     The following scripts are normally invoked  by  [4mcron[24m  or  at
system boot time, and should not require many changes:

     innlog.pl      scanlogs
     innstat        tally.control
     news.daily     tally.unwanted
     rc.news

[4mRc.news[24m  starts  the  server.  In  versions 1.4 and earlier, this
script was run by user root. In this version, [4mrc.news[24m must be run
by the user defined as the  [4mNEWSUSER[24m  in  the  config.data  file.
[4mNews.daily[24m invokes [4mexpire[24m and [4mscanlogs[24m.  [4mScanlogs[24m 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 man‐
pages 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 [4minnxmit[24m to send the articles to your downstream feeds.
[4mSend‐ihave[24m is used for ‘‘ihave/sendme’’ feeds and is described in
an appendix.  [4mSendbatch[24m and [4msend‐uucp[24m flush and  lock  batchfiles
and call [4mbatcher[24m to queue up UUCP jobs.  You might want to modify
these  files  to change the flags given to [4muux[24m; 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  [4mdf[0m
so  that  your spool area is not overrun!  [4mNntpsend[24m and [4msend‐nntp[0m
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 [4mdoc[24m direc‐
tory that describe them:

     expire.ctl     newsfeeds
     hosts.nntp     nnrp.access
     inn.conf       passwd.nntp
     moderators



                       Northern Winter 1997






                               ‐34‐


     The last group of files are utility scripts you  might  find
useful:

     inncheck       innwatch
     scanspool

[4mInncheck[24m  is a Perl script to check the syntax and permissions of
an installed INN system.  [4mInnreport[24m is an alternate way of summa‐
rizing the server’s log file.  It is a Perl script. It  will  be‐
come  the  standard  log reporting mechanism in a future release.
[4mInnwatch[24m 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 [4m_PATH_NEWSBOOT[24m script —— it is set to be run
by default.  [4mScanspool[24m is a Perl script to make sure that the ac‐
tive 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 [4mnewsfeeds[24m file —— will be
difficult), you should type the following:

     make install

Make sure you have [4mrc.news[24m installed in the right place,  as  ex‐
plained  in the ‘‘Paths to common programs’’ section, above.  You
might find it useful to read the ‘‘First‐Time Usenet or NNTP  In‐
stallation’’ appendix for help on navigating through the INN con‐
figuration files.

     There  are  now  only a couple more things to check.  First,
make sure you have an [4mactive[24m file and a  [4mhistory[24m  database!   The
appendices  explain how to convert your existing files; the [4mBUILD[0m
script will create new ones for you.  If you have Perl,  run  [4min‐[0m
[4mncheck[24m  to  make sure that you have the datafiles configured cor‐
rectly.  The second is make sure that you have correctly  updated
your  [4msyslog.conf[24m  file to match the filenames and logging levels
required by INN.  See [4msyslog/syslog.conf[24m for an example  of  what
to do.

     Once  you  have  done  all  of this, InterNetNews is now in‐
stalled, and ready to run —— have fun!

[1m8.  Heterogeneous Client Installations[0m

     The [4minews[24m program is used  by  user  newsreaders.   Programs
such  as [4mrn[24m (which call [4mPnews[24m) prepare a news article and feed it
into [4minews[24m.  [4mInews[24m validates the news headers, adds its own,  and
feeds  the  article  to  the  campus [4minnd[24m server.  The [4minews[24m that
comes with INN is more useful than the ‘‘mini‐inews’’ that  comes
with  the  reference implementation.  You cannot run the standard
B2.11 [4minews[24m.  You can run the C News [4minews[24m, but  only  on  client
machines  (i.e., those with a [4m$NEWSCTL/server[24m file).  I recommend
that you install INN’s [4minews[24m on all the clients in your campus.




                       Northern Winter 1997






                               ‐35‐


     INN comes with a [4mMakeInews[24m script to make it easier to build
and install [4minews[24m on a wide variety of hosts.  This  script  cre‐
ates  a  directory  and  copies all the necessary files (headers,
sources, configuration files) into it.  The script takes  an  op‐
tional argument, which should name the client machine’s architec‐
ture.  For example:

     cd $inn
     ./MakeInews sun3

will  create  an  [4minews.sun3[24m directory.  You can then examine the
Makefile in that directory, and build and install [4minews[24m  on  your
Sun‐3  clients.   This  is  easiest  if the client NFS‐mounts the
source directory —— that way you can keep all your [4minews[24m  sources
in one place.

     [4mRnews[24m  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 [4minnd[24m is running, then the [4mMakeRnews[24m script can
be used in the same manner as the [4mMakeInews[24m script.

[1m9.  Known Problems[0m

     If you use NIS (formerly Yellow Pages) on  SunOS,  you  will
need  to add a ‘‘domainname’’ entry to your [4minn.conf[24m file if your
hosts do not contain fully‐qualified domain names.  The most com‐
mon symptom of this is that [4minews[24m will  fail  because  it  cannot
generate  a Message‐ID.  Another problem with NIS is that reverse
name lookups do not return the fully‐qualified domain  name.   If
you  know  that none of your local clients have a period in their
name, you can use a pattern like ‘‘*[ˆ.]*’’ in  your  [4mnnrp.access[0m
file.

     SunOS4.1.1  has  a bug where [4mwrite[24m(2) can return EINTR.  The
most common symptom is the following  fatal  error  message  from
[4minnd[24m:

     Can’t sync history, interrupted system call

This  is  Sun  bug 1052649.  It is fixed in patch 100293‐01.  Ac‐
cording to the release manual, it is also fixed in  all  releases
of SunOS since 4.1.2.

     If  you have [4mNOFILE_LIMIT[24m set you should know that the stan‐
dard I/O library in SunOS4.x has trouble with more than  127  de‐
scriptors.   The most common symptom is the following fatal error
message from [4minnd[24m:

     can’t fopen /usr/local/news/history, invalid argument

This occurs after doing a  [4mctlinnd[24m  ‘‘reload’’  command.   For  a
work‐around,  reboot your server instead of trying to ‘‘reload.’’
Another symptom is that [4minnd[24m  will  exit  if  you  do  a  [4mctlinnd[0m
‘‘flush’’  command while the server is paused or throttled.  This


                       Northern Winter 1997






                               ‐36‐


is Sun bug 1045141.  Sun does not plan to fix it for any 4.x  re‐
lease.

     One  site  has reported the same error message happens after
doing a sequence of ‘‘throttle’’ and ‘‘go’’  commands.   It  does
not appear to be related to the bug mentioned above, although the
symptom  is  the  same.  If you replace the body of INN’s [4mxfopena[0m
routine with the following, it will work:

     return fopen(p, "a+");

This is in the file [4mlib/xfopena.c[24m.

     If you use Sun’s unbundled compiler, [4macc[24m, you must make sure
to use the unbundled assembler, too.  You might also get lots  of
‘‘left  operand  must  be  modifiable  lvalue’’  errors.  Setting
[4mUSE_CHAR_CONST[24m to ‘‘DONT’’ will help.

     There have been reports  that  the  VAX  Ultrix  4.2  [4mmalloc[0m
doesn’t  work  well  with  [4minnd[24m, causing it to slowly fill up all
swap space.  I believe that all of the memory leaks in [4minnd[24m  have
been  fixed, but you might want to look at using a different [4mmal‐[0m
[4mloc[24m package.  The Kingsley/Perl [4mmalloc[24m package is provided in the
[4mlib[24m directory.  Add ‘‘malloc.c’’ and ‘‘malloc.o’’  to  the  MISS‐
ING_SRC and MISSING_OBJ lines in [4mconfig.data[24m and rebuild.

     I  have  been told that on SunSoft Interactive UNIX System V
Release 3.2 Version 3.0 systems <errno.h> has been broken up into
separate files.  The easiest way to work around this  problem  is
to add ‘‘#include <net/errno.h>’’ to [4minclude/clibrary.h[24m.

     If  you  use  386BSD (the Jolitz port, not the BSDI product)
you will have to set [4mACT_STYLE[24m to ‘‘READ’’.  If  you  do  not  do
this  then  the  active file will not get updated.  Another work‐
around is to set [4mMMAP_SYNC[24m parameter to ‘‘DO.’’

     The default configuration of some Sequent kernels  does  not
provide  enough  descriptors  for [4minnd[24m to run.  You might have to
rebuild your kernel  with  the  ‘‘MAXNOFILE=128’’  and  ‘‘NOFILE‐
EXT=64’’  options.   You  will  also  have  to had a ‘‘setdtable‐
size(nnn)’’ call in the main routine of [4minnd[24m, and a  ‘‘setdtable‐
size(0)’’ call in the Spawn routine.

     I have been told that some older versions of the SCO [4mopendir[0m
routine  have file descriptor leaks.  The most noticeable symptom
is probably that [4minnd[24m will die while trying to renumber  the  [4mac‐[0m
[4mtive[24m  file.   You  might  want  to  use  a freely‐redistributable
‘‘dirent’’ package such as one distributed by the  Free  Software
Foundation.   You should also make sure to set [4mCLX_STYLE[24m to ‘‘FC‐
NTL.’’  Finally, you might also want to edit [4minnd/innd.c[24m where it
calculates the ‘‘MaxOutgoing’’ parmater and  increase  the  fudge
number to four.




                       Northern Winter 1997






                               ‐37‐


     On  some  SVR4  systems, attempting to set the socket buffer
size is either not supported or,  even  worse,  might  result  in
[4minnd[24m’s  data size growing.  The most noticeable symptom is ‘‘cant
setsockopt(SNDBUF)’’ messages in  your  [4msyslog[24m  output.   To  fix
this, you should make sure to set [4mSET_SOCKOPT[24m to ‘‘DONT.’’

     I  have  heard that Sony SVR4 systems have lots of problems.
You must set [4mHAVE_UNIX_DOMAIN[24m to  ‘‘DONT’’;  sockets  in  general
seem  to  have  problems,  including kernel crashes and a blocked
[4minnd[24m.

     If you use the GNU [4msed[24m in the [4m_PATH_SED[24m configuration  para‐
meter,  make  sure  you get version 1.13; earlier versions have a
bug that breaks the [4mparsecontrol[24m scripts.   The  most  noticeable
symptom  is that all ‘‘newgroup’’ control messages result in mail
saying that they are unparseable.

     Some versions of the shell in HP‐UX do not properly parse  a
quoted  ‘‘[’’  when it is in a pattern for a [4mcase[24m statement.  The
most noticeable symptom is that [4mnews.daily[24m does not properly  ex‐
pire  articles  if [4minnwatch[24m has throttled the server.  Contact HP
and get a fix for SR # 5003‐009811.

     On some versions of AIX on the RS/6000, using memory‐mapping
can eat up all the page space or crash the machine.  This will be
noticeable if you have [4mACT_STYLE[24m  set  to  ‘‘MMAP’’  and/or  have
‘‘‐DMMAP’’  in  [4mDBZCFLAGS[24m.   Ask  your IBM representative for the
‘‘U413090’’ PTF and prerequisites to apply  it;  it  is  believed
that this will fix it.

     On  some  systems processes spawned by [4minnd[24m never exit.  The
most likely cause is that [4mCLX_STYLE[24m should be set to ‘‘FCNTL.’’
























                       Northern Winter 1997






                               ‐38‐


[1mAppendix I:  Differences from other News software[0m

     Administrators will find that  INN  is  fairly  incompatible
with B and C News.  This section tries to mention the most impor‐
tant  places  where  INN differs from the other news systems.  If
you have not maintained B or C News,  you  should  probably  skip
this section.

     Users  will  generally only notice is that INN is faster; it
should be 100% compatible with the  other  systems  at  the  user
level.   If  you  had  particular  problems that aren’t mentioned
here, please let me know.  Note, however, that this is [4mnot[24m a  tu‐
torial  on how to set up a new INN system, or convert older soft‐
ware to it; no such document exists except appendix II ‘‘Convert‐
ing from other News software’’.

[1m1.  Configuration Files[0m

     Below is a list of the data files used by B and C News,  and
the  reference NNTP implementation, along with a short summary of
how they map into INN configuration files.  The syntax is  always
different:  INN  files are almost always a set of colon‐separated
fields where lines beginning with a poundsign are ignored.

[4mexplist[24m        This is replaced by the similar  [4mexpire.ctl[24m  file.
               Archiving is done by a separate program.

[4mmailpaths[24m      This  is  replaced  by  the  [4mmoderators[24m file.  The
               ‘‘default’’ entry in [4mmailpaths[24m is replaced by  ei‐
               ther  a full wildcard (‘‘*’’) entry in the [4mmodera‐[0m
               [4mtors[24m file, or by a  ‘‘moderatormailer’’  entry  in
               the [4minn.conf[24m file.

[4mnntp.access[24m    This  is  replaced  by  the  [4mhosts.nntp[24m  (for NNTP
               peers) and [4mnnrp.access[24m (for newsreading) files.

[4mnntp.sys[24m       This is a password file used if NNTP  is  compiled
               with  the  ‘‘AUTH’’ option.  It is replaced by the
               [4mpasswd.nntp[24m file.  Note that [4minews[24m and [4mrnews[24m  will
               also try to read [4mpasswd.nntp[24m.  Therefore, you will
               probably  want to have one‐line versions of it for
               your on‐campus clients.

[4morganization[24m   This is replaced by the ‘‘organization’’ entry  in
               the [4minn.conf[24m file.

[4mrn/server[24m      This  is  replaced  by the ‘‘server’’ entry in the
               [4minn.conf[24m file.

[4mwhoami[24m         This  is  replaced   by   the   ‘‘pathhost’’   and
               ‘‘fromhost’’ entries in the [4minn.conf[24m file.





                       Northern Winter 1997






                               ‐39‐


[1m2.  Newsgroups, Active, Sys, and Newsfeeds[0m

     The  biggest  difference  is how the [4mnewsfeeds[24m file compares
with the [4msys[24m file.  Newsgroup patterns like  ‘‘all.all.ctl’’  are
completely  gone.   All  newsgroup patterns are shell‐style wild‐
cards, matched against the [4mactive[24m file.

     The [4mactive[24m file is taken to be the definitive list of  news‐
groups  that  you want to receive.  With B and C news, an article
must match the subscription list of the local site  as  specified
in the [4msys[24m file.  If it matches, each newsgroup is then looked up
in  the  [4mactive[24m  file.  If none of the newsgroups are found, then
the article is filed into the newsgroup named ‘‘junk’’.

     INN’s behavior is much simpler.  If a newsgroup does not ap‐
pear in the [4mactive[24m file, it is ignored.  If none  of  the  groups
are  mentioned,  then the article is rejected: nothing is written
to disk.  This is a deliberate design decision:  if  you  do  not
want a particular newsgroup to take up your disk space, remove it
from the [4mactive[24m file; if your neighbors have not gotten around to
updating  your  newsfeed, then the only thing that will happen is
that some network bandwidth will have been wasted when they  send
you the article.

     You can change INN’s behavior so that it resembles the other
systems.   To  do  this,  compile  with [4mWANT_TRASH[24m set to ‘‘DO.’’
Note that this will accept [4meverything[24m.  Because there is no  sub‐
scription list, you cannot say ‘‘give me all of the foo hierarchy
(filed  into  junk),  but not the alt hierarchy.’’  You must list
the group in the [4mactive[24m file.

     INN strictly believes in distributions.  If the  site  named
[4mME[24m has any distributions, then incoming articles must either have
no Distribution header, or the header must match the distribution
list.  If you want to blindly accept all distributions, make sure
you  do  not  have  a  ‘‘/distrib,...’’ section in your [4mME[24m entry.
Distributions are fixed strings —— there are no patterns or  spe‐
cial wildcards like ‘‘all.’’

     For more details on these items, see [4mdoc/newsfeeds.5[24m.

[1m3.  Control Messages[0m

     Like  C News, INN implements all control messages other than
cancel as shell scripts.  The number and type  of  parameters  is
different  from that of C News.  All control messages consult the
file [4mcontrol.ctl[24m before acting on the message.  If  the  sender’s
address  matches  with  the  list  of authorized addresses (e.g.,
‘‘group‐admin@isc.org’’, ‘‘*’’, etc.), the control message is ei‐
ther acted upon, mailed to the  news  administrator,  logged,  or
dropped.   For example, messages from ‘‘group‐admin@isc.org’’ are
honored.




                       Northern Winter 1997






                               ‐40‐


     The ‘‘control’’, ‘‘junk’’, and ‘‘to’’ newsgroups can be  ex‐
plicitly sent or not sent.  See [4mdoc/newsfeeds.5[24m and [4mdoc/innd.8[24m.

     The  [4mctlinnd[24m  program  is  what really directs the server to
create or remove newsgroups.  This results  in  a  semi‐recursive
process:  the control message arrives, and a script is invoked to
process  the message.  If approved, the script invokes [4mctlinnd[24m to
send a message back to the server telling it to create or  remove
the group.

[1m4.  Locking[0m

     A  running news system has many open files.  These files can
be divided into two groups.  The first group includes the history
database and [4mactive[24m file.  The second group includes the logfiles
and batch files used to send articles to your feeds.

     B news uses an internal protocol for the first  group.   For
the second group, since [4minews[24m does ‘‘atomic appends,’’ no locking
is  necessary.  C news uses the [4mlocknews[24m and [4mnewslock[24m scripts for
the first group, and provides no  fine‐grain  mechanism  for  the
second group.

     With INN, the server is running all the time and all locking
is  done under the direction of [4mctlinnd[24m.  The first group is gen‐
erally handled by using the ‘‘throttle,’’ ‘‘pause,’’  and  ‘‘go’’
commands  (sometimes  ‘‘reload’’  will be necessary).  The second
group is handled by the  ‘‘flushlogs’’  and  ‘‘flush’’  commands.
See the [4mdoc/ctlinnd.8[24m manpage; examples of their use can be found
in various scripts in the [4msamples[24m directory.


























                       Northern Winter 1997






                               ‐41‐


[1mAppendix II:  Converting from other News software[0m

     INN  is  a  complete  news  transport and expiration system.
Since some people will be installing INN from scratch on  top  of
an older news system, this section should help you determine what
you  can ‘‘throw out’’ from your earlier news setups.  It is also
compatible with much of the existing news software,  so  you  can
create  a  mixed environment if you want to, and if you are care‐
ful.

[1m1.  C News Expire[0m

     The [4mexpire[24m program that is distributed with INN does not  do
any  archiving.   Since  the history databases currently have the
same format, it is possible to use the C News [4mexpire[24m if you  want
to.  (The INN history database may change, however, so you should
only do this if you really have to —— you really should use INN’s
[4mexpire[24m.)  There are three ways to do this.

     The  first  way is to change your [4mdoexpire[24m script so that it
calls [4mctlinnd[24m to ‘‘throttle’’ [4minnd[24m just before [4mexpire[24m  runs.   It
should  then issue a [4mctlinnd[24m ‘‘go’’ command after [4mexpire[24m is done.
The drawback to this method is that no incoming news is  accepted
until all expiration is finished.

     The second way is to compile [4mlib/lock.c[24m and add it to your C
News  library  [4mlibcnews.a[24m, replacing the provided lock functions.
You should then remove [4mexpire[24m and relink it.  This method has not
been tested very thoroughly, but it is rather simple.

     The third way is to teach the C News [4mexpire[24m to talk to  [4minnd[0m
and tell it to cancel articles that it would remove.  To do this,
apply  the  patch  file [4mexpire/expire.pch[24m to your C News [4mexpire.c[0m
sources.  You will also have to add [4mlib/inndcomm.o[24m to  [4mlibcnews.a[0m
and then rebuild [4mexpire[24m.

[1m2.  Standard NNTP daemon[0m

     You  can use the ‘‘standard’’ [4mnntpd[24m server.  You should only
have to do this if you have hosts that feed you news,  and  where
the users on that machine also want to read news on your machine.

     Make  sure that you configure [4mnntpd[24m so that it is using DBZ,
and have it feed each individual article to [4minews[24m; don’t use  the
‘‘batched  input’’  option.   It should also be set up so that it
acts as if it is running under [4minetd[24m.  You should also make  sure
that [4minetd[24m does nothing with the NNTP port, number 119.

[1m3.  NNTP‐based newsreaders[0m

     If  you  already  have your NNTP‐using newsreaders installed
and running, you do not  have  to  do  anything.   This  includes
[4mxvnews[24m,  [4mxrn[24m,  [4mrrn[24m  and  so on.  INN implements the standard NNTP
protocol,  with  some  extensions.   INN  does  not  provide  the


                       Northern Winter 1997






                               ‐42‐


extensions  used by [4mtrn[24m, [4mtin[24m or other newsreaders.  (INN will not
implement all the different indexing systems  because  the  right
solution  is  to  have  a  generic interface that all readers can
use.)

     For administrative convenience, however, you might  wish  to
have  all  your newsreaders use the INN library and configuration
files to talk to the server.  The next section describes  how  to
do  that  for [4mrn[24m.  It is provided as an example, to help you con‐
vert other programs you might have.  INN does  not  provide,  nor
fully support, any newsreaders.

[1m4.  Remote rn[0m

     The ‘‘remote’’ version of [4mrn[24m (also called [4mrrn[24m) uses a set of
routines  in  the NNTP ‘‘clientlib’’ file.  INN can emulate these
routines; see [4mdoc/clientlib.3[24m.  If  you  need  to  build  [4mrn[24m  for
client  machines  that  don’t  have  the  entire INN distribution
available, use the [4mMakeLib[24m script to build a distribution  direc‐
tory of the necessary routines.  Use this script the same way you
use the [4mMakeInews[24m script.

     [4mRn[24m,  [4mrrn[24m,  and [4mtrn[24m are constantly changing so these instruc‐
tions might be out of date.  The maintainers have agreed to offi‐
cially support INN, however.

     There are two ways to build [4mrn[24m so that it uses the  INN  li‐
brary.   If  you  don’t  have the NNTP distribution installed you
will have to use the first way.

     The first way is to apply a patch to the latest [4mrn[24m [4mConfigure[0m
script and then execute it and rebuild the program.  To do  this,
type the following:

     cd [4mrn_source[0m
     patch <$inn/frontends/rn.pch
     ./Configure
     make

At  some point, [4mConfigure[24m will ask you if you want to use the In‐
terNetNews library; answer [4myes[24m.  You can then use either the full
sources, or a special  library  that  contains  just  the  needed
header  and  sources files.  Tell [4mConfigure[24m the appropriate path‐
names, and then proceed with the rest of the [4mrn[24m installation.

     The second way is to edit a couple of files after  you  have
run  [4mConfigure[24m  and set it up to build the remote rn.  First, re‐
place the [4mrn[24m file [4mserver.h[24m with the INN file  [4minclude/myserver.h[24m.
The  next  step  is  to  edit  the  [4mrn[24m  Makefile  to  remove  the
‘‘clientlib’’ file from the source and object file  lists.   This
can  probably be done by commenting out the definitions of the [4mc5[0m
and [4mobj5[24m variables.  You must also edit the Makefile to  add  the
INN  library  to  the list of libraries that are linked in.  This
can probably be done by editing the line that  defines  the  [4mlibs[0m


                       Northern Winter 1997






                               ‐43‐


variable  so that the full pathname to [4mlibinn.a[24m is the first item
after the equal sign.

[1m5.  Removing the Other Stuff[0m

     The names below assume a  ‘‘standard’’  news  setup;  things
might be different on your machine.  Also, many programs have al‐
ternate  names and links; make sure you chase down and remove [1mall[0m
of them.

     You might find it easiest to rename your [4m/usr/lib/news[24m  (and
[4m/usr/lib/newsbin[24m)  directories to something else and start with a
clean slate, copying over the files as  they  are  needed.   Make
[1msure  [22mthat  your news processing is completely stopped before you
begin this process.  That includes any [4mcron[24m jobs that may be run‐
ning.

     The [4m/usr/lib/news[24m directory can become cluttered  ——  that’s
why  C  News  split everything up into separate directories.  The
following files are compatible with C News and  B2.11  News,  and
should be [4mkept[24m:

     active         active.times

If you are running C News keep these files, otherwise delete them
and use [4mmakehistory[24m to rebuild them:

     history
     history.dir
     history.pag

     [4mRn[24m  does  not  have  to  be modified so leave this directory
alone (or copy it back if you moved your original):

     /usr/local/lib/rn

If you set up [4mrn[24m to use the INN library, remove this file:

     /usr/local/lib/rn/server

     The input system is completely replaced.  Remove the follow‐
ing programs and their manpages:

     /bin/cunbatch
     /bin/inews, /usr/lib/news/inews, etc...
     /bin/rnews, /usr/bin/rnews, etc...
     /usr/lib/news/rnews.stall
     /etc/nntpd, /usr/etc/nntpd, etc...

Also remove the following directories and everything within them:






                       Northern Winter 1997






                               ‐44‐


     /usr/lib/news/bin/input
     /usr/lib/news/bin/relay
     /usr/lib/news/bin/ctl
     /usr/lib/news/bin/inject
     /usr/lib/news/nntp (mkgrdates, nntp_access, shlock, etc)

     The transmission facility is completely replaced.   You  may
keep  your current feed subsystem if you want to, but it will re‐
quire some changes to make  sure  that  batchfiles  are  properly
flushed;  see  the  [4msend‐xxx[24m  scripts for examples.  Remove these
files and programs:

     /usr/lib/news/batchparms
     /usr/man/man8/newsbatch.8

Remove the following directory and everything within it:

     /usr/lib/news/bin/batch

You can continue to use [4mnntplink[24m, [4mnewsxd[24m, and the  like,  subject
to the caveat just mentioned.

     Article expiration and maintenance of the history and active
files is completely replaced.  Remove this file:

     /usr/lib/news/explist

Remove the following directories and everything within them:

     /usr/lib/news/bin/expire
     /usr/lib/news/bin/maint

If you do not remove the [4mexpire[24m directory, you will probably have
problems  installing  INN’s [4mexpire[24m, which is a program that often
has the same name as the C News directory.

     The following programs in [4m/usr/lib/newsbin[24m  are  not  needed
and  can be deleted.  Keeping them around is harmless, and if you
find them useful don’t delete them:

     canonhdr       newshostname
     ctime          newslock
     dbz            queuelen
     getabsdate     sizeof
     getdate        spacefor
     gngp

Note that [4mctime[24m, [4mgetabsdate[24m, and [4mgetdate[24m are  replaced  by  [4mconv‐[0m
[4mdate[24m.   More importantly, [4mnewslock[24m does not lock [4minnd[24m; it is best
to remove it.

     The following files are replaced by INN configuration files.
You should delete them, just to avoid confusion:



                       Northern Winter 1997






                               ‐45‐


     mailname       sys
     mailpaths      whoami
     organization

If you have other software that uses them (except [4msys[24m),  you  can
keep  them.   The  following  will be rebuilt (or overwritten) by
[4minnd[24m and [4mscanlogs[24m so you should remove them:

     errlog         log

     In addition to the manpages for the programs  listed  above,
the following manual pages should be removed:

     active.times.5 newsmail.8
     expire.8       newsmaint.8
     mkgrdates.8c   nntpd.8c
     news.5         nntpxmit.1
     newsaux.8

     Any  other  files  and directories can probably also be dis‐
carded.



































                       Northern Winter 1997






                               ‐46‐


[1mAppendix III:  Setting up different feeds[0m

     This section gives some notes and advice on how  to  set  up
different  types  of  outgoing news feeds.  It duplicates and ex‐
pands upon the information in the manual pages.

[1m1.  Ihave/sendme feed[0m

     For a standard UUCP newsfeed, a site batches up all the  ar‐
ticles  it  receives and sends them to the downstream site, which
unpacks the batch and processes each article.  If the  downstream
site has multiple feeds, however, it might want to ‘‘filter’’ the
articles  that get sent.  This is done by having the feeding site
send a list of Message‐ID’s as an ‘‘ihave’’ control message.  The
receiving site examines the list to see which  articles  it  does
not  currently  have, and sends it back to the upstream site as a
‘‘sendme’’ message.  The original site receives this message  and
prepares a batch in the standard way.

     Note  that  this  has nothing to do with NNTP.  It is a spe‐
cialized type of batched feed that is not used very often.  To do
ihave/sendme with a site named remote, the local site must either
have   a   ‘‘to.remote’’   newsgroup   or   be   compiled    with
MERGE_TO_GROUPS set to ‘‘DO.’’

     Accepting   an   ihave/sendme  feed  is  easy.   Suppose  an
‘‘ihave’’ message is received from a  site  named  remote.   When
[4minnd[24m processes the message it will invoke the appropriate control
script,  [4m/usr/local/news/bin/control/ihave[24m.  The script will fil‐
ter the body using [4mgrephistory[24m, creating a list  of  Message‐ID’s
not found in the [4mhistory[24m database.  It uses this output to create
a ‘‘sendme’’ control article which is posted to the ‘‘to.remote’’
newsgroup using [4minews[24m.  This article will then be queued and sent
to  remote in the normal way.  The remote site will then send the
desired articles back.

     Providing an ihave/sendme feed is a  bit  more  complicated.
First,  you  must create two entries in your [4mnewsfeeds[24m file.  The
first should be named remote.ihave.  Make this a  ‘‘Tf,Wm’’  feed
that contains the remote’s subscription list.  This entry results
in  a  a  file  that accumulates the Message‐ID’s of all articles
that remote might want.  The other entry should be named  remote.
This  should  be  a  ‘‘Tf,Wn’’  feed  that only subscribes to the
‘‘to.remote’’ newsgroup.  (Actually, if you feed some groups as a
standard feed, you can put them on the remote entry, rather  then
the remote.ihave entry.)

     The next step is to have the ‘‘ihave’’ control messages sent
out.   To  do this, review the [4msend‐ihave[24m script and make sure it
is invoked as needed (usually out of [4mcron[24m).  It splits the batch‐
file from the remote.ihave [4mnewsfeeds[24m entry  and  posts  ‘‘ihave’’
control  messages  into  the ‘‘to.remote’’ newsgroup.  These mes‐
sages will get queued for the remote entry.



                       Northern Winter 1997






                               ‐47‐


     The next step is to send out any articles queued for the re‐
mote entry.  Treat this as a standard UUCP feed,  invoking  [4msend‐[0m
[4muucp[24m  or  [4msendbatch[24m as appropriate, typically a few minutes after
[4msend‐ihave[24m runs.

     When the remote site receives the ‘‘ihave’’ message it  will
filter  it  and  send back a ‘‘sendme’’ message whose body is the
list of desired Message‐ID’s.  When [4minnd[24m processes  this  message
it   will   invoke   the  appropriate  control  script,  [4m/usr/lo‐[0m
[4mcal/news/bin/control/sendme[24m.  This script will  call  [4mgrephistory[0m
to  turn  the list into a list of files appended to the batchfile
for remote.  Examine this script (the  filename  should  probably
match  the  filename  in the remote [4mnewsfeeds[24m entry) and send the
batch to the remote site (using [4mbatcher[24m, often  called  by  [4msend‐[0m
[4muucp[24m or [4msendbatch[24m).

[1m2.  Feeding a large number of sites[0m

     [4mInnd[24m  tries  to  keep as many batchfiles open for as long as
possible.  It will normally open as many as it can, using all the
available descriptors minus a fixed number for internal use  (log
files, etc.).  You can explicitly set the number of files to open
by using the ‘‘−o’’ flag.

     If  you have more outgoing feeds than available descriptors,
[4minnd[24m will recycle the files on a a ‘‘least recently used’’ basis.
If most of your feeds get most articles (or you have vastly  more
feeds  then  available  descriptors),  this  will  lead to ‘‘file
thrashing,’’ closing and opening all the excess feeds on each ar‐
ticle.  To reduce this, you can have [4minnd[24m use an internal  buffer
for  a  site  by using the ‘‘I’’ parameter in the [4mnewsfeeds[24m file.
If a site does not have its batchfile open, the server  will  not
try  to  open it until there is more data to be written then will
fit in the buffer.  For example, suppose [4minnd[24m  was  started  with
‘‘−o10’’ and there are 12 sites, all with ‘‘I512’’ in their [4mnews‐[0m
[4mfeeds[24m  entry.  If each article generates 50 bytes (a pathname and
a Message‐ID), then [4minnd[24m will close and re‐assign two descriptors
every 10 or so articles.

     A better alternative is to  use  funnels  and  an  exploder.
Funnels, specified in the [4mnewsfeeds[24m file, let multiple sites send
their  output  down a single stream.  The advantage of funnels is
that this stream can be a channel; the  primary  disadvantage  is
that the funnel specifies what data is to be written, not the in‐
dividual  sites.   (Since  most  feeds will want either ‘‘Wn’’ or
‘‘Wnm’’ entries, this is usually not a problem.)

     In order for the funnel output to be useful, it usually must
be split into individual, per‐site, files.  Programs that do this
type of splitting are called ‘‘exploders.’’  INN provides two ex‐
ploders, [4mfilechan[24m and [4mbuffchan[24m.

     [4mFilechan[24m is the simplest, and  most  inefficient,  exploder.
It  does  not  keep  any  files  open  and  is  very  system‐call


                       Northern Winter 1997






                               ‐48‐


intensive.  It can be used to provide behavior (and performance!)
that is similar to B2.11 [4minews[24m.  It can, however, be used as  the
funnel for an unlimited number of sites.

     [4mBuffchan[24m  keeps  all its output files open all the time.  It
should not be used for more sites then a single process can  have
open.   [4mBuffchan[24m also has flags to automatically flush its files,
as well as close and re‐open them, every specified number of  ar‐
ticles.   (The  re‐open capability is useful for things like [4mnnt‐[0m
[4mplink[24m in its ‘‘watch the batchfile’’ mode.)  Using [4mbuffchan[24m  with
the  ‘‘−l1 −c50’’ flags will give behavior that is similar to the
C News [4mrelaynews[24m.

     [4mBuffchan[24m can be run as a full exploder (‘‘Tx’’) in the [4mnews‐[0m
[4mfeeds[24m file.  This means that you can use [4mctlinnd[24m to send  a  com‐
mand  line  down [4mbuffchan[24m’s input stream.  ([4mInnd[24m will also send a
command whenever newsgroups are modified.)  The only useful  mes‐
sage  is  ‘‘flush’’  which will close, and re‐open, the specified
site files.  You should also note that the flow is one‐way;  full
exploders cannot send any acknowledgement back.

[1m3.  Master/slave replication[0m

     INN  supports a simple model of replicated news databases: a
single master host pushes out updates to its slaves.  The  master
is  the  only  host  that receives articles —— this includes both
outside newsfeeds and  articles  written  by  local  users.   The
slaves only receive articles from the master.

     No special work is required to set up a master host.

     A  slave  is set up by starting [4minnd[24m with the ‘‘−S’’ flag to
specify the name or IP address of the master host.   This  should
be done by modifying the ‘‘FLAG’’ variable in your [4m_PATH_NEWSBOOT[0m
script.   If  [4minnd[24m  is  started with the ‘‘−S’’ flag it will pass
this flag on to [4mnnrpd[24m.  This means that when anyone  connects  to
the  slave and does a ‘‘POST’’ command, [4mnnrpd[24m will connect to the
master and offer the article.

     You must make sure that the slave’s entry  in  the  master’s
[4mnewsfeeds[24m  file  sends  all articles (e.g., don’t have any exclu‐
sions).  Since the [4mnnrpd[24m on the slave host will usually  add  its
name to the Path header, you should add ‘‘Ap’’ to the [4mflags[24m field
of the slave’s entry on the master.

     Once  the  slave has been set up it is necessary to have the
master feed it.  This is done by using an extension to  the  NNTP
protocol.  This extension, the ‘‘XREPLIC’’ command, is documented
in  [4minnd.8[24m.   In order to do this you will have to set up a [4mnews‐[0m
[4mfeeds[24m entry for the slave.  This should be a standard  entry  ex‐
cept  that you will need to have both the filename and the repli‐
cation information written int the batchfile.  To  do  this,  put
‘‘WnR’’ in the [4mflags[24m field of the entry.



                       Northern Winter 1997






                               ‐49‐


     When  you  want  to  actually send the articles to the slave
site you will have to specify the ‘‘−S’’  flag  in  your  [4minnxmit[0m
command.  Current versions of [4mnntplink[24m use the ‘‘−x’’ flag.

     When running as a slave, [4minnd[24m is very paranoid about staying
synchronized  with  its master.  Most noticeably, you should make
sure that all newgroup and rmgroup control messages  are  handled
identically on both systems.

     Finally,  note  that  postings made on the slave (via [4mnnrpd[24m)
are actualy sent to the [4minnd[24m on the master, so the slave must  be
treated as a sending host, not a newsreading host.












































                       Northern Winter 1997






                               ‐50‐


[1mAppendix IV:  First‐time Usenet or NNTP Installation[0m

     Since  the  needs  and  administration  of systems varies so
much, I can only give some general guidelines and advice in  this
section.   Like  UNIX system administration in general, it is un‐
fortunately still true that most of the job will be learned  ‘‘in
the  heat of the moment.’’  Once you have INN set up, however, it
should not require much attention.   For  general  problems,  try
posting  to  ‘‘news.admin.misc’’;  use ‘‘news.software.nntp’’ and
‘‘news.software.b’’ for installation problems.

     Once all the software has been compiled and  installed,  you
must  now  get  a  newsfeed.   This involves having one (or more)
sites pass along to you all the articles that they have received.
Getting articles is a passive action,  because  it  is  generally
more efficient that way.  (The [4mnntpget[24m program is primarily a de‐
bugging  aide and utility program.  It is not the recommended way
to get a newsfeed, and most sites will prefer you not to  use  it
for that.)

     If  you already have Usenet access, you could post a note to
‘‘news.admin.misc’’ asking for a feed.  Make sure to say that you
are looking for an NNTP connection!  If you are a  member  of  an
NSFNet regional network, or subscribe to a commercial IP network,
ask  your  contact  there  at the network center.  If they do not
provide feeds directly, they can probably help you find one.  You
also might try writing to the  <nntp‐managers@colossus.apple.com>
mailing  list.   This  will reach the news administrators of many
NNTP sites on the Internet.  (If you want to join the  list,  re‐
member to send it to nntp‐managers‐request, [1mnot [22mnntp‐managers!)

     Once have a site willing to give you a feed, you need to get
the  list  of  groups  that they will give you.  You also need to
create those groups on your machine.  The easiest way to do  this
is  usually  to ask them for a copy of their active file, and for
you to add the entries of the groups that you’re  interested  in.
The location of the active file is system‐dependent, but the man‐
page  should  tell  you (or the other administrator) where it is,
often within the first paragraph.  If your feed  can’t  send  you
their  active  file, then you might want to find a more competent
feed!  The following command will zap an active file, setting  up
the article numbers for a new site:

     sed <active.old >active.new \
        ‐e ’s/ˆ\([ˆ ]*\) [0‐9]* [0‐9]* \([ˆ ]*\)$/\1 0000000000 0000000001 \2/’

     Once  the groups are set up, your newsfeed will periodically
connect to your NNTP server and offer it any  new  articles  that
have  arrived  since  the  last connection.  [4mInnd[24m will accept the
connection, receive the articles, and queue them up for any sites
that you feed.

     The next step is to set it up so that your articles are sent
back to your newsfeed.  To do this,  create  a  [4mnewsfeeds[24m  entry,


                       Northern Winter 1997






                               ‐51‐


using  the  same  name  that shows up in the Path header that you
see.  (If you use a different name,  then  use  the  ‘‘excludes’’
sub‐field  to  avoid  offering  back  everything they offer you.)
This is usually done by giving them all non‐local articles  as  a
file  feed.  For example, ‘‘Foo, Incorporated’’ does not give any
foo.* articles to anyone else.

     When someone at your  site  writes  an  article,  [4minnd[24m  will
record  the  filename  in  the batch file for your upstream site.
Either [4msend‐nntp[24m or [4mnntpsend[24m will flush and lock  the  batchfile,
and  then  call  [4minnxmit[24m  to  connect to the remote site and send
these queued articles out.  You should edit the  script  to  list
the  sites you want, and arrange for [4mcron[24m to run this script on a
regular basis.  You can run it as often as you like, but 10  min‐
utes is a common interval.

     If  you  want to feed any sites via UUCP, then you will have
to set up file feed entries for them in the [4mnewsfeeds[24m  file,  and
arrange  to have [4mcron[24m run the [4msend‐uucp[24m script as desired.  (UUCP
batches are typically only done every few hours.)

     Once you have news flowing in and out  of  the  system,  you
will  have  to  expire  it  or  your  disks  will  fill  up.  The
[4mnews.daily[24m script should be run by [4mcron[24m  in  the  middle  of  the
night.  It will summarize that day’s log files, and then call [4mex‐[0m
[4mpire[24m  to  purge  old  news.  You might also want to have [4mcron[24m run
[4mrnews[24m hourly to pick up any stalled batches.   Finally,  if  your
feeds  change  IP  address,  you might want a daily job that does
‘‘ctlinnd reload hosts.nntp "flush  cache"’’.   This  is  because
[4minnd[24m does not currently time‐out DNS entries.

     You will generally want to set up the [4mcron[24m jobs so that they
are  run as the news administrator, and not as root.  A good ver‐
sion of [4mcron[24m that makes it easy to do this can be found on  gate‐
keeper.dec.com in pub/misc/vixie/cron.tar.Z.  Use this if needed.

     You will also need to get one or more programs to read news.
There  are several freely‐available programs around.  [4mRn[24m is popu‐
lar, and is probably the best place to start.  The official  dis‐
tribution is available for anonymous FTP at tmc.edu in the [4mrn[24m di‐
rectory.

     Welcome to Usenet, and have fun!













                       Northern Winter 1997






                               ‐52‐


[1mAppendix V:  News overview database[0m

     There are now many newsreaders available that are able to do
‘‘threading.’’   This is the ability to track a discussion within
a newsgroup by using the References header (or other  data),  re‐
gardless  of  changes in headers like the Subject line.  Examples
of these readers include [4mnn[24m, [4mtrn[24m, and [4mgnus[24m, and more are becoming
available.  Until recently, a major problem with these readers is
that they all required a specialized external database that  con‐
tained the threading data.

     In  late  1992, Geoff Collyer <geoff@world.std.com> released
the [4mnov[24m, or ‘‘news overview,’’ package.  This  included  database
tools  and  client access routines, that let the current threaded
newsreaders use a common, textual, database.  An  overview  data‐
base typically adds adds about 7‐9% to your storage requirements.
By default, the overview files are stored in the spool directory;
you  can  change  this  to use an alternate tree that mirrors the
spool hierarchy by changing the [4m_PATH_OVERVIEWDIR[24m parameter.

     INN includes full support for  creating  and  expiring  news
overview  databases.  To do this, add an entry like the following
to your [4mnewsfeeds[24m file:

     overview:*:Tc,WO:/path/to/bin/overchan

(Make sure  to  replace  [4m/path/to/bin[24m  with  the  value  of  your
[4m_PATH_NEWSBIN[24m  parameter.)   Then  reload  the  [4mnewsfeeds[24m file or
restart your server.  To create the  initial  database,  run  the
following command after you have started [4moverchan[24m:

     expireover ‐a ‐s

You  will also need to expire the overview data.  The easiest way
to do this is to add the ‘‘expireover’’ keyword to the  [4mcron[24m  job
that runs [4mnews.daily[24m.

     The  [4mnnrpd[24m  server includes two command extensions to access
the database; they are documented in the ‘‘PROTOCOL DIFFERENCES’’
part of [4mdoc/nnrpd.8[24m.  INN does not include  any  client  code  or
modifications  to any newsreaders to use the overview data.  Most
maintainers have agreed to support the overview database, includ‐
ing the INN extensions for remote access.  You can find prototype
versions of many readers (work done by Geoff) on world.std.com in
the directory src/news; look for files named [4mreader[24m.dist.tar.Z.











                       Northern Winter 1997






                               ‐53‐


[1mAppendix VI:  Limited MIME Support[0m

     This version of INN includes limited support for  MIME,  the
Multipurpose  Internet  Mail  Extensions,  described in RFC 1341.
The support is the ability to do limited transport  of  arbitrary
MIME  messages, and [4mnnrpd[24m can add MIME headers to all local post‐
ings that do not have them.

     In addition, there are patches available for  [4mnntplink[24m  that
allow it to do MIME transport.  The patches are not (yet) part of
the  official  release;  if  you  need  them,  contact Christophe
Wolfhugel <Christophe.Wolfhugel@hsc‐sec.fr>; he did most  of  the
INN work, too.

     You  should be very careful if you have [4mnnrpd[24m add MIME head‐
ers.  To do this, edit [4minn.conf[24m as indicated  in  [4mdoc/inn.conf.5[24m.
Once  this  is  done,  [1mall  [22marticles posted will get MIME headers
added.  Existing MIME headers will not be modified,  but  missing
ones  will  be  added.  The default values to add to [4minn.conf[24m are
these:

     mime‐version: 1.0
     mime‐contenttype: text/plain; charset=us‐ascii
     mime‐encoding: 7bit

An internationalized site might want to use these values:

     mime‐version: 1.0
     mime‐contenttype: text/plain; charset=iso‐8859‐1
     mime‐encoding: 8bit

It is possible to use these values because INN provides  a  clean
eight‐bit  data  path.  Unless you make special arrangements with
your peers, however, you must  transmit  seven‐bit  data.   Doing
this  will  require  special transmit agents.  Note that [4mnnrpd[24m is
not a Mime‐compatible reader.  You must have software to  extract
the data and present it appropriately.

     If  you  configure your site to use seven‐bit data, then you
must also make sure that none of your software creates  eight‐bit
articles.   [4mNnrpd[24m  does  not  verify this.  If you configure your
site to use eight‐bit data, then ASCII works fine,  but  remember
that  in  quoted‐printable  long lines are cut and that the equal
sign (‘‘=’’) is quoted; this is really bad for source code  post‐
ings, among others.

     The  character  set  can  also  cause  problems.  If you use
‘‘iso‐8859‐1’’ you must make sure that your posting software uses
this character set (e.g., not CP‐437 under MS‐DOS) because  [4mnnrpd[0m
does not do any conversion.

     In general, be very cautious.




                       Northern Winter 1997






                               ‐54‐


     MIME  articles  can  only be sent using [4minnxmit[24m.  Unless the
‘‘−M’’ flag is used, no MIME conversions are done.  If  the  flag
is used, the following happens: Articles with a Content‐Transfer‐
Encoding  header  of  ‘‘8bit’’  or  ‘‘binary’’  are  forwarded in
‘‘quoted‐printable’’ format (the ‘‘base64’’ format  is  not  sup‐
ported  yet).  All other articles —— in particular, those without
MIME headers, those of type ‘‘message’’ or  ‘‘multipart,’’  those
with  Content‐Transfer‐Encoding  header  of  ‘‘7bit’’ —— are for‐
warded without any change.















































                       Northern Winter 1997



