








                  IInnssttaalllliinngg IInntteerrNNeettNNeewwss

                         _R_i_c_h _$_a_l_z
                 _U_p_d_a_t_e_d _b_y_: _J_a_m_e_s _B_r_i_s_t_e_r
                Internet Software Consortium

        _p_l_e_a_s_e _s_e_n_d _e_l_e_c_t_r_o_n_i_c _m_a_i_l _t_o _<_i_n_n_@_i_s_c_._o_r_g_>


                          _A_B_S_T_R_A_C_T


          This  document  discusses  how to install and
     set up InterNetNews.  You should be familiar  with
     Usenet  and networks; the first section gives ref-
     erences to documentation for these topics, and the
     last appendix gives a Usenet overview for novices.

          This document also describes what many of the
     programs  do and how they should be used.  Even if
     you are a world-class expert at building and main-
     taining  public software, you should probably read
     this.

          This is revision 1.19, dated 1996/11/10.


11..  TThhiinnggss YYoouu SShhoouulldd KKnnooww BBeeffoorree YYoouu DDoo AAnnyytthhiinngg

     InterNetNews is abbreviated _I_N_N, which is pronounced as
the  three letters, _e_y_e _e_n _e_n.  It is a Usenet transport and
expiration  system  for  larger  UNIX|- systems where NNTP is
used for most Usenet traffic.

     This document is not a tutorial on Usenet.  If  you  do
not  have much Usenet experience, you should read _U_s_i_n_g _U_U_C_P
_a_n_d _U_s_e_n_e_t, ISBN 0-937175-10-2.  You might also find it use-
ful  to  read  _M_a_n_a_g_i_n_g _U_U_C_P _a_n_d _U_s_e_n_e_t (get the most recent
edition available), ISBN 0-937175-48-X.  Both books are pub-
lished  by  O'Reilly  &  Associates;  send  inquiries  to to
<nuts@ora.com>.  There is a chapter on INN in  _T_h_e  _I_n_t_e_r_n_e_t
_C_o_n_n_e_c_t_i_o_n_:  _A _G_u_i_d_e _t_o _C_o_n_n_e_c_t_i_v_i_t_y _a_n_d _C_o_n_f_i_g_u_r_a_t_i_o_n, ISBN
0-201-54237-4 by Smoot Carl-Mitchell and John S. Quarterman.
It  is  being published by Addison-Wesley and will be avail-
able in early 1994 or at the end of 1993.

     You should know BSD-derived TCP/IP -- at least be  com-
fortable  with host names and dotted-quad addresses.  If you
-----------
|- UNIX is a registered trademark of  Unix  Systems
Laboratories.



                      February 14, 1992





                             -2-


have installation problems,  you  should  know  about  UNIX-
domain  stream  and datagram sockets and the like.  In addi-
tion to any documentation available from  your  vendor,  you
might  find  it useful to read the two IPC tutorials in _U_N_I_X
_P_r_o_g_r_a_m_m_e_r_'_s _M_a_n_u_a_l_:  _S_u_p_p_l_e_m_e_n_t_a_r_y _D_o_c_u_m_e_n_t_s _1.  Copies can
be  purchased from the Usenix Association; send inquiries to
<office@usenix.org>.

     There are two RFCs that are important to  InterNetNews.
RFC  1036  describes  the  format of Usenet articles.  It is
incomplete and has some errors, but it is  the  only  formal
document  available.  RFC 977 defines NNTP, the Network News
Transfer Protocol.  RFCs are available from several  places,
including  anonymous  FTP to nnsc.nsf.net, where they can be
found in the directory _r_f_c.  Both RFCs are  currently  being
revised.   The  1036  revision  is most likely going to be a
``tightening-up''; since INN already has a strict  interpre-
tation  of  the  RFC, this revision will probably not affect
InterNetNews very much.  The 977 revision is adding new fea-
tures  and facilities, and while INN will not provide all of
them, they will have some impact.

     InterNetNews does things differently  from  other  news
software.  The most common Usenet systems for UNIX are B2.11
and C News.  Both of them require a separate NNTP  implemen-
tation.   The one everyone uses is called ``NNTP.''  Because
this is confusing (they don't  call  _s_e_n_d_m_a_i_l  ``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  _d_o_c_/_b_i_b_l_i_o,  _d_o_c_/_p_r_o_b_l_e_m_s,  and
_d_o_c_/_r_f_c_e_r_r_a_t_a in the C News distribution worthwhile reading.
The first is a bibliography, the second  discusses  known  C
News  porting  problems (see the DBZ sections in particular,
and ignore most of the  shell  comments),  while  the  third
lists some technical and philosophical errors in RFC 1036.

     The  commands below assume that _$_i_n_n is an abbreviation
for the top of the InterNetNews source tree.

     INN could not have been written without access  to  the
freely-redistributable  sources  of B2.11, C News, and NNTP.
In particular, I want to thank Rick Adams; Geoff Collyer and
Henry Spencer; and Stan Barber, Erik Fair, Brian Kantor, and
Phil Lapsley.  The financial support of  UUNET  Technologies
is  also  greatly  appreciated.   The  beta-test  sites gave
invaluable feedback.



                      February 14, 1992





                             -3-


22..  IIff YYoouu AArree IImmppaattiieenntt

     If you don't want to follow these  directions,  do  the
following:

     cd $inn/config
     cp config.dist config.data
     chmod 644 config.data
     vi config.data (or emacs, or whatever)
     cd ..
     make world
     mkdir -p /usr/news /var/news /var/news/spool
     make install

Then go read the appendixes.  If you have any problems, read
the rest of this document.

33..  DDiissttrriibbuuttiioonn RRooaaddmmaapp

     The INN sources are divided into the following directo-
ries:

_f_r_o_n_t_e_n_d_s      Programs  to  feed  articles  to  the central
               server and control it.

_i_n_n_d           The central NNTP server.  It accepts incoming
               connections,  receives articles, and arranges
               for them to be sent to downstream  newsfeeds.

_b_a_c_k_e_n_d_s       Programs to transmit articles to other sites.

_e_x_p_i_r_e         Programs to purge the article files and  his-
               tory database.

_n_n_r_p_d          An  NNTP server for on-campus clients that do
               newsreading  (as  opposed  to  bulk   article
               transfer).

_l_i_b            Library routines used by all the above.

_i_n_c_l_u_d_e        Header files used by all the above.

     The distribution also includes these directories:

_s_a_m_p_l_e_s        Prototype  scripts  and  configuration  files
               that might have to be edited before they  are
               installed.

_s_i_t_e           A  place  to store edited copies of the files
               in the _s_a_m_p_l_e_s directory.

_d_o_c            Manual pages for all the above.





                      February 14, 1992





                             -4-


_c_o_n_f_i_g         Tools to configure the release for your site.

     Finally,  there are a handful of files in the top-level
directory:

_R_E_A_D_M_E         A basic introduction.

_C_O_P_Y_R_I_G_H_T      The distribution copyright.  InterNetNews  is
               freely   redistributable,   provided   proper
               credit is given.

_M_A_N_I_F_E_S_T       A one-line description of every file  in  the
               distribution.

_B_U_I_L_D          An  interactive  script  to configure, build,
               and install INN.

_m_a_k_e_d_i_r_s_._s_h    A script to build  INN's  directories  except
               for  the  top levels: /usr/news /var/news and
               /var/news/spool.  As long as you  have  write
               permission  to  install the programs, this is
               the only part of the installation that  needs
               to  be  done  as  root, except that inndstart
               needs to be installed  setuid  root,  and  so
               doing the install as root will make life eas-
               ier.

_M_a_k_e_f_i_l_e       Rules to call the other  Makefiles  and  make
               distributions.

_I_n_s_t_a_l_l_._m_s     This   document.   It  requires  the  ``-ms''
               nroff/troff macro package.

_M_a_k_e_L_i_b        Script to build a directory with  a  replace-
               ment   of   the   reference  implementation's
               ``clientlib'' routines needed by remote _r_n.

_M_a_k_e_I_n_e_w_s      Script to build an _i_n_e_w_s distribution  direc-
               tory.

_M_a_k_e_R_n_e_w_s      Script  to build an _r_n_e_w_s distribution direc-
               tory.

_s_e_d_f_._x_x_x       Various _s_e_d scripts to filter the  output  of
               _l_i_n_t.

44..  BBuuiillddiinngg tthhee SSyysstteemm

     INN  is  built  in  steps.  First, the _s_u_b_s_t program is
built.  Next,  a  configuration  file  containing  key/value
pairs is created.  _S_u_b_s_t 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; _l_i_n_t is usually a good way to see



                      February 14, 1992





                             -5-


if  some  of  the  basic configuration parameters are set up
right.  The next step is to compile (and lint) all the  pro-
grams.   The  programs  are then installed, and the INN data
files are set up.

     The configuration process is deliberately not  interac-
tive.   Configure  scripts  like  the  one  in _r_n are fun to
watch, but they spend too much effort on the wrong job, like
whether  _g_r_e_p  returns an exit status.  It is also difficult
to change one parameter and rebuild the software.   (C  News
has this same problem.)

     INN's  method  also  has its flaws.  Because almost all
configuration data is in one header  file,  changing  almost
anything will force everything to be recompiled.

44..11..  BBuuiillddiinngg ssuubbsstt

     INN  uses the C News _s_u_b_s_t program to automate the con-
figuration.  _S_u_b_s_t is a very clever way of safely editing  a
file  under  the  control of a configuration file.  For more
details, see the documentation in  _d_o_c_/_s_u_b_s_t_._1.   Thanks  to
Henry  Spencer and Geoff Collyer for their permission to use
and redistribute _s_u_b_s_t.

     We will use _c_o_n_f_i_g_._d_i_s_t as the  configuration  file  to
test  the  version of _s_u_b_s_t that you build.  (You can always
replace your config file with the distribution file  and  do
another _m_a_k_e to restore the original versions.)

     The  C  News  _s_u_b_s_t program is a shell script that uses
_s_e_d to do the editing.  The INN configuration  file  is  too
large for some versions of _s_e_d.  The first step is to see if
your _s_e_d 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 _s_e_d such  as  ``too  much
command  text''  (or if it dumps core) you have two choices.
(You should also complain to your vendor.)  One choice is to
use  another  version of _s_e_d, such as the one distributed by
the Free Software Foundation.  If you  do  this,  edit  _c_o_n_-
_f_i_g_/_M_a_k_e_f_i_l_e  and change the line that defines the SED vari-
able.  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 _s_u_b_s_t.  You
might want to do this anyway, since it can be  much  faster.



                      February 14, 1992





                             -6-


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 _c_o_n_f_i_g_/_s_u_b_s_t_._c.  If you are using an early  version  of
AFS,  you  will  have edit the file to enable the USE_RENAME
macro.  If you have to make any other changes, please let me
know.

     Since  _s_u_b_s_t  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 _c_o_n_f_i_g
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 _s_u_b_s_t makes its
changes safely, this step is optional.)

44..22..  EEddiittiinngg ccoonnffiigg..ddaattaa

     Once you have _s_u_b_s_t working, the next step is to set up
your configuration parameters.  This is the hardest part  of
installing  INN.  _D_o_n_'_t _p_a_n_i_c_!  There are many configuration
parameters, but it should be very easy for you to  determine
the  answer  for  most of them.  To do this, you should copy
_c_o_n_f_i_g_/_c_o_n_f_i_g_._d_i_s_t, the distribution master, to  _c_o_n_f_i_g_/_c_o_n_-
_f_i_g_._d_a_t_a,  your  local  copy.  INN is distributed to compile
and run under BSD/OS 2.1 by default.

     The configuration file is divided  into  the  following
sections:

     Make config parameters
     Logging levels
     Ownerships and file modes
     C library differences
     C library omissions
     Miscellaneous config data
     Paths to common programs
     Paths related to the spool directory
     Execution paths for innd and rnews
     Sockets created by innd or clients
     Log and config files
     Innwatch configuration
     Tcl filtering configuration
     PGP control-message verification configuration
     Local configuration
     Actsync configuration

You should have a copy of _c_o_n_f_i_g_._d_a_t_a 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.



                      February 14, 1992





                             -7-


     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 _<_o_n_e_-_o_r_-_m_o_r_e_-_t_a_b_s_> value

If there is no ``value'' the ``<one-or-more-tabs>'' is still
required.  Do not put quote marks around the  values  --  if
you  do, you will usually get a syntax error while compiling
the system.  The discussion below uses quotes only  to  show
where the values start and end.

44..22..11..  MMaakkee ccoonnffiigg ppaarraammeetteerrss

     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 _g_c_c _-_W_a_l_l
on the _C_C line.  If you need extra _-_I flags put them on  the
_D_E_F_S  line.  INN uses the _r_e_g_i_s_t_e_r declaration a great deal.
If your compiler is very good, you might want to add  _-_D_r_e_g_-
_i_s_t_e_r_=  to  the  _D_E_F_S  line  so  that INN's declarations are
ignored.

     The DBZ package can be compiled so that the database is
memory-mapped.   If  you  want  to do this and have the _m_m_a_p
system call, then add ``-DMMAP'' to the _D_B_Z_C_F_L_A_G_S parameter.

     If  you  need  to link in other libraries (e.g., _-_l_n_e_t)
put them on the _L_I_B_S line.

     The Makefiles usually filter all _l_i_n_t output through  a
_s_e_d  script.   If  you  are very paranoid, set _L_I_N_T_F_I_L_T_E_R to
_c_a_t.  If your lint output is in the broken  multi-line  for-
mat:

     value type declared inconsistently
         exit        llib-lc(297) :: test.c(7)
     function returns value which is always ignored
         printf

Then set _L_I_N_T_F_I_L_T_E_R to be the ``sedf.sysv'' line.

     The  _l_i_b  directory also builds a _l_i_n_t library, so that
you can make sure the other programs are properly using  the
library  routines.   The  _L_I_N_T_L_I_B_S_T_Y_L_E  parameter  (used  in
_l_i_b_/_M_a_k_e_f_i_l_e and  _l_i_b_/_m_a_k_e_l_l_i_b_._s_h)  controls  how  the  _l_i_n_t
library is built.  If your _l_i_n_t 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  cre-
ate  an  empty file so that the other Makefiles don't break.
If you come up with a fourth alternative, let me know.





                      February 14, 1992





                             -8-


     Unfortunately, on some systems _l_i_n_t 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 _DDHAN-
DLE''  being  undefined.   You  can ignore them and ask your
vendor to support the BSD ``-z''  lint  flag.   If  you  set
_H_A_V_E___U_N_I_S_T_D to ``DO'' then you might get warnings about pro-
totype  mismatches  for  various   functions   declared   in
_i_n_c_l_u_d_e_/_c_l_i_b_r_a_r_y_._h.  You can ignore them or remove the lines
from the INN header file.

     The _M_A_N_P_A_G_E_S_T_Y_L_E parameter (used  in  _d_o_c_/_M_a_k_e_f_i_l_e  and
_d_o_c_/_p_u_t_m_a_n_._s_h)  controls how manual pages are installed into
your public directory while the _M_A_N_x parameters specify  the
directories where they get installed.  If you do not want to
install any manpages, set _M_A_N_P_A_G_E_S_T_Y_L_E to _N_O_N_E.

44..22..22..  LLooggggiinngg lleevveellss

     INN uses the modern _s_y_s_l_o_g that separates messages into
both  levels and categories.  Look in your _<_s_y_s_l_o_g_._h_> header
file for a ``LOG_NEWS'' macro, and check your _s_y_s_l_o_g(3) man-
page to make sure that _o_p_e_n_l_o_g takes three arguments.  If it
doesn't, then you will have to use the library  routine  and
server  provided in the _s_y_s_l_o_g directory.  This is described
later.

     The different levels that are  described  in  the  _s_y_s_-
_l_o_g(3)  manpage are confusing, so INN uses its own names for
the four levels it uses:

     L_FATAL   Fatal error, about to exit
     L_ERROR   Error that might require attention
     L_NOTICE  Informational notice, no action needed
     L_DEBUG   Protocol tracing or other debugging messages

Depending on how your _s_y_s_l_o_g_._c_o_n_f(5) file  is  set  up,  you
might want to change the _L___x_x_x parameters in this section.

     The  _s_c_a_n_l_o_g_s script assumes that the first three cate-
gories above are each directed  into  separate  files.   See
_d_o_c_/_n_e_w_s_l_o_g_._5,  _d_o_c_/_n_e_w_s_l_o_g_._8,  and  _s_y_s_l_o_g_/_s_y_s_l_o_g_._c_o_n_f  for
details.  Logging is also described in more detail later.

44..22..33..  OOwwnneerrsshhiippss aanndd ffiillee mmooddeess

     The NNTP server needs to open the NNTP port; it is port
number  119,  which  requires root access.  This is the only
part of INN that needs this privilege:  all  other  programs
can  run  under  the distinct user and group id specified by
the _N_E_W_S_U_S_E_R and _N_E_W_S_G_R_O_U_P parameters.  Most  news  adminis-
tration  tasks must be done as user _N_E_W_S_U_S_E_R (see the expla-
nation of _c_t_l_i_n_n_d below).  In addition, _i_n_e_w_s will only  let
the  _N_E_W_S_U_S_E_R  user  or  members of the _N_E_W_S_G_R_O_U_P group post
control messages other than cancel.



                      February 14, 1992





                             -9-


     Some INN scripts (primarily the control message scripts
and  the daily maintenance script) need to send email to the
news maintainer.  The  _N_E_W_S_M_A_S_T_E_R  parameter  specifies  the
right  address.   This  is  most often the login name of the
account which has _N_E_W_S_U_S_E_R as its user id; use an  alias  to
forward it to the right people.

     Some  Usenet  sites  still  use the Path header line to
generate their email reply messages.   Using  the  Path  has
never  been  guaranteed  to work, and INN tries to help stop
this practice by refusing to generate valid Path  addresses.
The  _P_A_T_H_M_A_S_T_E_R parameter specifies what _i_n_e_w_s should put at
the tail end of the Path line.  If your  _N_E_W_S_M_A_S_T_E_R  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 _x_x_x___M_O_D_E 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 _N_E_W_S_U_S_E_R.

44..22..44..  CC lliibbrraarryy ddiiffffeerreenncceess

     Editing the parameters in this section will require you
to look around at the files in your _/_u_s_r_/_i_n_c_l_u_d_e  directory.

     The  _S_I_Z_E___T  parameter  is the datatype of the ``size''
parameters in subroutine calls like _m_e_m_c_h_r and  _f_r_e_a_d.   The
_L_O_C_K___S_T_Y_L_E  parameter  specifies  how file-locking should be
done.  _I_n_n_x_m_i_t 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.

     The _D_I_R___S_T_Y_L_E parameter specifies what is  returned  by
your   _r_e_a_d_d_i_r(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
_H_A_V_E___U_N_I_X___D_O_M_A_I_N to ``DONT.''  This means that INN will  use
a named pipe for the communication between _i_n_n_d and _c_t_l_i_n_n_d.
It also means that there will be no local  ``private''  port
for  _r_n_e_w_s  to  use;  this  should  not  cause any problems,
although it makes it easier for anyone to use _r_n_e_w_s and post
fake news articles.  (You might also have to modify the _s_y_s_-
_l_o_g routines; see the end  of  the  file  _s_y_s_l_o_g_/_R_E_A_D_M_E  for
details on this.)

     INN needs to know how many descriptors are available to
use for files and sockets.  There are several  ways  to  get
this  number;  the  _F_D_C_O_U_N_T___S_T_Y_L_E  parameter specifies which
method to use.  On most systems, the  _g_e_t_d_t_a_b_l_e_s_i_z_e  routine
will do this, so leave the default of ``GETDTAB.''  On other



                      February 14, 1992





                            -10-


systems you need to use the  _g_e_t_r_l_i_m_i_t,  _s_y_s_c_o_n_f  or  _u_l_i_m_i_t
routine, so set the parameter to ``GETRLIMIT'', ``SYSCONF'',
or ``ULIMIT'', respectively.  If you  do  not  have  any  of
those  calls then set the parameter to ``CONSTANT'' and edit
the file _l_i_b_/_g_e_t_d_t_a_b_._c to return the right number.   To  get
this  number,  look  for an _O_P_E_N___M_A_X constant in your system
header files, or  write  a  program  that  repeatedly  opens
_/_d_e_v_/_n_u_l_l until it gets an error.

     The  last  few  parameters in this section, _x_x_x_V_A_L, are
used primarily to keep  _l_i_n_t  quiet.   These  functions  are
declared  in  _i_n_c_l_u_d_e_/_c_l_i_b_r_a_r_y_._h,  and the return values are
pretty much always ignored.  You can usually determine  what
these  values  should  be by examining your manpages or your
_l_i_n_t libraries.

44..22..55..  CC lliibbrraarryy oommiissssiioonnss

     INN uses library routines that might not be present  in
all  UNIX  systems, although they should be.  The _l_i_b direc-
tory provides versions of some of these routines,  including
copies  of  the  freely-redistributable BSD string routines.
The _M_I_S_S_I_N_G___S_R_C and _M_I_S_S_I_N_G___M_A_N parameters  can  be  set  to
list  those  routines  that are missing from your C library.
If you don't have _s_t_r_c_a_s_e_c_m_p and _s_t_r_n_c_a_s_e_c_m_p then  you  will
need the _s_t_r_c_a_s_e_c_m_p module built into your INN library.  Add
the ``.c'' and ``.o'' names to _M_I_S_S_I_N_G___S_R_C and  _M_I_S_S_I_N_G___O_B_J,
respectively.

     The following routines are all found in the file of the
same name.  If they are missing from your system,  add  them
the same way:

     memchr         strchr         getopt
     memcmp         strrchr        mkfifo
     memcpy         strspn         strerror
     memset         strtok
     memmove


     If  you  are using version 1 of the GNU C compiler on a
Sparc running SunOS, you should add _i_n_e_t___n_t_o_a as  a  missing
function.   This  is because the first version of _g_c_c didn't
properly pass structures into routines compiled with the Sun
C compiler.

     If you have an older version of _s_y_s_l_o_g add _s_y_s_l_o_g_._c and
_s_y_s_l_o_g_._o to the appropriate parameters.

     Pyramid machines running OSx  have  fast  assembly-lan-
guage  versions  of  the string routines in the ATT library.
To use these routines, add  ``$(OSXATTOBJ)''  to  the  _M_I_S_S_-
_I_N_G___O_B_J_S parameter.  This will cause _l_i_b_/_M_a_k_e_f_i_l_e to extract
the object files from the ATT library, and add them  to  the



                      February 14, 1992





                            -11-


INN library.

44..22..66..  MMiisscceellllaanneeoouuss ccoonnffiigg ddaattaa

     All the parameters in this section become macros in the
file _i_n_c_l_u_d_e_/_c_o_n_f_i_g_d_a_t_a_._h.  You should at least look through
the  parameters  up  to  _V_E_R_I_F_Y___C_A_N_C_E_L_S.  (If set to ``DO'',
then _i_n_n_d will ignore cancel messages  unless  the  From  or
Sender  header match those of the original poster.)  In gen-
eral, however, you can leave this section pretty much  alone
until  you  have some experience running INN.  Nevertheless,
here are some comments on some of the  more  useful  parame-
ters.

     _I_n_n_d   can  memory-map  the  _a_c_t_i_v_e  file  if  you  set
_A_C_T___S_T_Y_L_E to ``MMAP''.  On some  systems,  however,  when  a
mapped file is updated its mtime is not updated.  Apparently
some versions of System V Release 4 have this problem.  This
causes problems for programs like _n_n_m_a_s_t_e_r which look at the
_s_t___m_t_i_m_e field of the _s_t_a_t structure in order  to  determine
if  any  new  news has come in.  (_N_n_m_a_s_t_e_r is part of the _n_n
newsreading program.)  The best work-around is  probably  an
hourly _c_r_o_n job that touches the _a_c_t_i_v_e file.

     There  are  a  number  of  parameters  that control the
behavior of _r_n_e_w_s.  If you set _R_N_E_W_S___S_A_V_E___B_A_D to ``DO'' then
articles that _i_n_n_d rejects for reasons like bad headers will
be saved in the ___P_A_T_H___B_A_D_N_E_W_S directory; you  will  have  to
periodically  scan  this directory and clean it up.  You can
also control how _r_n_e_w_s logs duplicates (those  aren't  saved
regardless  of  the  value  of _R_N_E_W_S___S_A_V_E___B_A_D), logging them
through _s_y_s_l_o_g, to a file, or not.  Note  that  if  you  set
_R_N_E_W_S___L_O_G___D_U_P_S  to  ``FILE'',  then  you will want to change
___P_A_T_H___R_N_E_W_S___D_U_P___L_O_G, which appears later in  the  file.   If
you  receive news from several UUCP feeds, you might want to
log duplicates so that you can cut down your phone bills  by
optimizing   your  feeds.   The  _R_N_E_W_S_P_R_O_G_S  parameter  says
whether or not to look in ___P_A_T_H___N_E_W_S_P_R_O_G_S for commands named
on  the  incoming ``#!'' line of news batches.  You probably
want to set this to ``DO''.  Make sure that the  full  path-
name  of  _r_n_e_w_s,  ___P_A_T_H___R_N_E_W_S,  does  not  conflict with the
directory where your unpackers are put, ___P_A_T_H___N_E_W_S_P_R_O_G_S.

     If _I_P_A_D_D_R___L_O_G 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  _i_n_n_d  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  _x_x_x___T_I_M_E_O_U_T  parameters  control  various   timers
within INN; you might want to change some of these depending
on your system load.



                      February 14, 1992





                            -12-


44..22..77..  PPaatthhss ttoo ccoommmmoonn pprrooggrraammss

     INN uses a few standard programs like _/_b_i_n_/_s_h and _s_e_n_d_-
_m_a_i_l.   If you don't have _s_e_n_d_m_a_i_l then you must have a pro-
gram that accepts a full message -- including headers --  on
its standard input, and delivers it.  This program is speci-
fied  by  the  ___P_A_T_H___S_E_N_D_M_A_I_L  parameter,  and  is  normally
``/usr/lib/sendmail -t''.    The  parameter  is  actually  a
_s_p_r_i_n_t_f format string that will  be  given  the  destination
address  as  its  only argument.  on some sites (e.g., those
running MMDF) the ``-t'' could be replaced with a ``%s''.

     INN puts most of its executables in the directory spec-
ified  by the ___P_A_T_H___N_E_W_S_B_I_N parameter.  Some programs expect
_i_n_e_w_s and _r_n_e_w_s to be in certain places; for  example,  UUCP
usually wants _r_n_e_w_s in _/_b_i_n.  The default configuration puts
these programs in only one spot; if you need to have  multi-
ple  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 ___P_A_T_H___N_E_W_S_B_I_N to the PATH of any such scripts.

     If  you have an _/_e_t_c_/_r_c_._l_o_c_a_l file you should make sure
that it invokes  the  script  named  by  the  ___P_A_T_H___N_E_W_S_B_O_O_T
parameter.   On other systems (mostly System V derivatives),
the system boot procedure automatically runs all the scripts
in  a  particular  directory,  such as _/_e_t_c_/_i_n_i_t_._2.  In that
case, you should pick a name  like  _/_e_t_c_/_i_n_i_t_._2_/_S_9_9_n_e_w_s  and
have  the news boot script installed there, or install it in
the default _/_e_t_c_/_r_c_._n_e_w_s and make the link yourself.

     The daily maintenance script, _n_e_w_s_._d_a_i_l_y calls _s_c_a_n_l_o_g_s
to  rotate  and  trim  log files, as well as generating sum-
maries using _e_g_r_e_p and _a_w_k.  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  Soft-
ware  Foundation.   The _s_c_a_n_l_o_g_s script has a short test you
can run to see if your _e_g_r_e_p will work.

44..22..88..  PPaatthhss rreellaatteedd ttoo tthhee ssppooooll ddiirreeccttoorryy

     By default, all news articles are stored in directories
under  _/_u_s_r_/_s_p_o_o_l_/_n_e_w_s.   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 _r_n_e_w_s when _i_n_n_d is not available), and its  out-
going  batch  files.  Since no newsgroup can ever have a dot
in its name, a directory like _o_u_t_._g_o_i_n_g can never be a news-
group  name,  and  it  is safe to put the news batchfiles in
there.  This is used by the ___P_A_T_H___S_P_O_O_L_N_E_W_S  parameter,  and
the ___P_A_T_H___B_A_T_C_H_D_I_R parameter.



                      February 14, 1992





                            -13-


     Do  not  make  ___P_A_T_H___L_O_C_K_S be in the same filesystem as
___P_A_T_H___S_P_O_O_L_N_E_W_S.  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 _n_e_w_s_._d_a_i_l_y will not be able  to
run  and  that  it  won't call _e_x_p_i_r_e to free up disk space.
You should also put ___P_A_T_H___N_E_W_S_L_I_B 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 _m_a_k_e_d_i_r_s_._s_h script will fail
because some needed intermediate directories will not exist.
This  should  not  be  a problem, as you can just create the
directories yourself -- make sure to set the  ownership  and
modes right -- and re-run the script.

44..22..99..  EExxeeccuuttiioonn ppaatthhss ffoorr iinnnndd aanndd rrnneewwss

     All  control  messages (other then ``cancel'') are car-
ried out by scripts.  Your system must be able to _e_x_e_c shell
scripts  directly.   All  the  scripts  distributed with INN
start with ``#! /bin/sh.''

     The ___P_A_T_H___C_O_N_T_R_O_L_P_R_O_G_S parameter specifies  the  direc-
tory where these scripts exist.  Do not set this to a public
directory like _/_b_i_n because some  bozo  might  send  out  an
``rm'' control message.

     The  ___P_A_T_H___R_N_E_W_S_P_R_O_G_S directory serves the same purpose
for _r_n_e_w_s when it needs to unpack batches.   The  _R_N_E_W_S_P_R_O_G_S
parameter specifies if the directory is really used.

44..22..1100..  SSoocckkeettss ccrreeaatteedd bbyy iinnnndd oorr cclliieennttss

     The  _i_n_n_d server and its clients (most notably _c_t_l_i_n_n_d)
create UNIX-domain sockets or named pipes.  They are created
inside a ``firewall'' directory that gives access permission
to a limited set of users.  For example, assume  the  direc-
tory  is  _/_u_s_r_/_l_o_c_a_l_/_n_e_w_s_/_i_n_n_d  and that it is owned by user
news in group news and has mode 0770.  Using  these  permis-
sions,  then  only members of the news group can use _c_t_l_i_n_n_d
to create new groups because only they will be able to  send
a message to the _i_n_n_d socket.

     This directory (which is specified by the ___P_A_T_H___I_N_N_D_D_I_R
parameter) is also used to determine the user and  group  id
of  all  sub-processes spawned by _i_n_n_d, as well as the owner
of all news articles and files.  The owner of this directory
is  set  at  installation time and specified in the ``Owner-
ships and file modes'' section, above.







                      February 14, 1992





                            -14-


44..22..1111..  LLoogg aanndd ccoonnffiigg ffiilleess

     INN keeps its databases, and some control  files  their
own  directory,  typically named _/_u_s_r_/_l_o_c_a_l_/_n_e_w_s.  Log files
are kept in _/_v_a_r_/_l_o_g_/_n_e_w_s.  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,
___P_A_T_H___N_N_T_P_P_A_S_S  and  ___P_A_T_H___N_N_R_P_A_C_C_E_S_S.  The default location
for these files is in _/_u_s_r_/_l_o_c_a_l_/_e_t_c, so that it  is  gener-
ally  safe  to export _/_u_s_r_/_l_o_c_a_l_/_n_e_w_s (read-only is probably
best).

     INN programs do extensive logging, and the daily  main-
tenance 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 man-
pages in the _d_o_c directory.

44..22..1122..  IInnnnwwaattcchh ccoonnffiigguurraattiioonn

     The INN server, _i_n_n_d, does not contain  any  checks  to
see if there is enough free space on the disk or if the sys-
tem load average is low enough to allow  article  reception.
There  are two reasons for this.  The first reason is philo-
sophical:  it is a mistake  to  bury  this  kind  of  policy
information  inside  a program.  For example, you don't want
to have to recompile the program just because you moved to a
different   filesystem.    (Yes,  this  could  be  partially
answered by moving the information  to  an  external  config
file,  but  any compiled rules are still likely to be incom-
plete.)  The  second  reason  is  pragmatic:   there  is  no
portable  way  to get standard measurements for the informa-
tion 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
_c_t_l_i_n_n_d to stop and start the server as necessary.  The pro-
gram,  _i_n_n_w_a_t_c_h,  reads  the  control   file   _i_n_n_w_a_t_c_h_._c_t_l.
_I_n_n_w_a_t_c_h    is   documented   in   _d_o_c_/_n_e_w_s_._d_a_i_l_y_._8,   while
_i_n_n_w_a_t_c_h_._c_t_l is documented in _d_o_c_/_i_n_n_w_a_t_c_h_._c_t_l_._5.

     The parameters in this section control when the  server
should  stop  accepting  articles,  and when it should start
again.  You will have to examine _s_i_t_e_/_i_n_n_w_a_t_c_h_._c_t_l and prob-
ably modify it, usually to check the amount of free space on
the disks.  For example, there is a line in  the  file  that
has this fragment in it:



                      February 14, 1992





                            -15-


     !!! 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, and on other lines, as appropriate for
your system.  (Changing the output of _d_f seems to be one  of
the  things vendors like to do most; it is not worth my time
to have INN keep track of all of them.)

     The parameter  _I_N_N_W_A_T_C_H___S_L_E_E_P_T_I_M_E  specifies  how  fre-
quently _i_n_n_w_a_t_c_h should check the system -- the other param-
eters should be set with this in mind, eg: there needs to be
enough  free  space  on  the  filesystem  to  last  the next
_I_N_N_W_A_T_C_H___S_L_E_E_P_T_I_M_E seconds.

     The _I_N_N_W_A_T_C_H___x_x_x_L_O_A_D parameters specify the load  aver-
age  at  which  different actions should be taken.  They are
integers, representing the load average  multipled  by  100.
For  example,  if  you want to throttle the server when your
load reaches 7.5, set _I_N_N_W_A_T_C_H___H_I_L_O_A_D to ``750.''

     The _I_N_N_W_A_T_C_H___x_x_x_S_P_A_C_E 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 _d_f uses (512-byte units, 1K blocks, etc).

     The  _I_N_N_W_A_T_C_H___S_P_O_O_L_N_O_D_E_S  parameter  specifies how many
inodes must be available in your spool directory.

44..22..1133..  TTccll ffiilltteerriinngg ccoonnffiigguurraattiioonn..

     The innd server can be configured to include TCL  hooks
to  be  run whenever a new article is received and when cer-
tain other actions occur. See the file  README.tcl_hook  for
more details.

     The _T_C_L___S_U_P_P_O_R_T parameter specifies whether you want to
compile in the Tcl support code. Select DO or DONT.

     The _T_C_L___L_I_B parameter specifies the extra libraries you
need  to  link  against  to  include  tcl support. Typically
``-ltcl -lm'' are required. If you defined  _T_C_L___S_U_P_P_O_R_T   to
DONT, then this should be blank.

     The  ___P_A_T_H___T_C_L___S_T_A_R_T_U_P  parameter specifies the path of
the tcl script that is to be loaded at process startup time.
A  sample  version  is included in samples/startup.tcl which
will be installed in the location you define here.

     The ___P_A_T_H___T_C_L___F_I_L_T_E_R 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 sam-
ples/filter.tcl which will  be  installed  in  the  location



                      February 14, 1992





                            -16-


defined by this parameter.

44..22..1144..  PPGGPP ccoonnttrrooll mmeessssaaggee vveerriiffiiccaattiioonn..

     Inn  now has mecahnisms in place that will do PGP veri-
fication of control messages.

     The _W_A_N_T___P_G_P_V_E_R_I_F_Y parameter defines whether PGP  veri-
fication  of  control  messages should be done. Select DO or
DONT. See the file README.pgp for more details on this  sub-
ject.

44..22..1155..  AAccttssyynncc ccoonnffiigguurraattiioonn..

     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 _A_C_T_S_Y_N_C___H_O_S_T variable  defines  which  remote  host
you'll be using to synchronize your active file.


44..33..  TTyyppiiccaall ccoonnffiigg..ddaattaa cchhaannggeess

     The  following  sections  show some of the changes that
need to be made to _c_o_n_f_i_g_._d_a_t_a so  that  INN  will  compile.
They are only samples; ``your mileage may vary.''

     Note  that  if you are using the first release of _g_c_c_2,
set _U_S_E___C_H_A_R___C_O_N_S_T to ``DONT''.


     -S-u-n-O-S--4-.-x-
     MISSING_SRC    memmove.c
     MISSONG_OBJ    memmove.o





















                      February 14, 1992





                            -17-


     -A-I-X-
     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 _s_y_s_l_o_g that comes  with
INN.   This  is  not  necessary for 3.2.  Some versions also
need _U_S_E___U_N_I_O_N___W_A_I_T set to ``DONT''.  You  should  also  run
_r_c_._n_e_w_s from _i_n_i_t not _/_e_t_c_/_r_c; add a line like the following
near the end of the _i_n_i_t_t_a_b file, just before  the  ``cons''
line:

     rcnews:wait:2:/usr/local/etc/rc.news >/dev/console 2>&1



     -A-/-U-X-
     LIBS              -lbsd

Make  sure  you  don't use _g_c_c version 1; it miscompiles the
socket calls in _i_n_n_d_/_c_c_._c.























                      February 14, 1992





                            -18-


     -B-S-D-I-
     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 _S_H_E_L_L variable in _c_o_n_f_i_g_/_M_a_k_e_f_i_l_e and  _s_i_t_e_/_M_a_k_e_-
_f_i_l_e  to  point to _/_u_s_r_/_c_o_n_t_r_i_b_/_b_i_n_/_b_a_s_h.  Edit _l_i_b_/_M_a_k_e_f_i_l_e
so that the _i_n_s_t_a_l_l target does not  try  to  make  _._._/_l_l_i_b_-
_l_i_n_n_._l_n.   You  must  also use the GNU _s_e_d; the version dis-
tributed with BSDI 0.9.4.1 enters an infinite loop  process-
ing newgroup messages.
























                      February 14, 1992





                            -19-


     -H-P---U-X--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 _b_d_f command instead
of _d_f.



















                      February 14, 1992





                            -20-


     -S-G-I--I-n-d-i-g-o--w-i-t-h--I-R-I-X--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 _M_I_S_S_I_N_G___x_x_x parameters should be empty.





























                      February 14, 1992





                            -21-


     -S-o-l-a-r-i-s--2-.-X-/-S-u-n-O-S--5-.-X-,--u-s-i-n-g--S-P-A-R-C-o-m-p-i-l-e-r--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.
















                      February 14, 1992





                            -22-


     -S-y-s-t-e-m--V--R-e-l-e-a-s-e--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 _l_i_n_t to be useful on the  machine  I
used.   Some  versions of System V (for example, Esix 4.0.3)
need the following LIBS value:

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

On a Dell System V machine, you have to set _H_A_V_E___U_N_I_X___D_O_M_A_I_N
to ``DONT.''


     -U-l-t-r-i-x--4-.-x--(-R-I-S-C-)-
     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 _s_y_s_l_o_g.  You cannot use _m_m_a_p;
the Ultrix version of the system call is  for  devices,  not
files.   Some  sites  have  reported problems with using the



                      February 14, 1992





                            -23-


_s_y_s_l_o_g that INN includes (output doesn't show up, or  float-
ing  point numbers are garbled, etc.).  The file _j_t_k_o_h_l_-_s_y_s_-
_l_o_g_-_c_o_m_p_l_e_t_e_._t_a_r_._Z  in  the  _/_p_u_b_/_D_E_C  directory  on   gate-
keeper.dec.com  has  a  ``for-Ultrix''  package that handles
both old and new _s_y_s_l_o_g calls.  While Ultrix  has  symlinks,
it does not have the ``-follow'' option in its _f_i_n_d command.
This is used in _e_x_p_i_r_e_/_m_a_k_e_a_c_t_i_v_e_._c; you will have to either
install the GNU _f_i_n_d or edit the source file.

55..  OOtthheerr SSoouurrccee PPrreeppaarraattiioonnss

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

55..11..  SSyysstteemmss wwiitthh oolldd ssyyssllooggss

     If you need to install the _s_y_s_l_o_g that  is  distributed
with  INN, go to the top of the distribution and type ``make
syslogfix''.  This will also compile  _s_y_s_l_o_g_d,  the  logging
daemon.   You  should  install this to replace your existing
daemon, usually in  _/_e_t_c_/_s_y_s_l_o_g.   You  will  also  need  to
install the new-style _s_y_s_l_o_g_._c_o_n_f file.

     If you cannot replace _s_y_s_l_o_g_d on your machine, then see
the file _s_y_s_l_o_g_/_R_E_A_D_M_E for information on how to set  it  up
as an alternate daemon.

     Ignore  any  complaints from _l_i_n_t about the INN sources
calling _o_p_e_n_l_o_g with the wrong argument count.  In fact,  if
you  ddoonn''tt  get any complaints, then something is wrong with
the way _s_y_s_l_o_g, _<_s_y_s_l_o_g_._h_>, or the _l_i_n_t libraries are set up
on your system.

55..22..  TThhee DDBBZZ ppaacckkaaggee

     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 _p_a_t_c_h  program  and  the
context  diff  in  _l_i_b_/_d_b_z_._p_c_h.   If  you  don't  have _p_a_t_c_h
installed, then you can make the changes manually.  (If  you
don't  have  Larry  Wall's  _p_a_t_c_h  program  get  it from any
_c_o_m_p_._s_o_u_r_c_e_s_._u_n_i_x archive as well as many FSF  archives  and
other places -- you'll be glad you did.)

     Both  _i_n_n_d and _n_n_r_p_d have the option of keeping the DBZ
hash table in memory, under the control of  the  INND_DBZIN-
CORE   and  NNRP_DBZINCORE_DELAY  parameters,  respectively.
This can consume lots of RAM proportional  to  the  size  of
your history database, but it can also avoid a great deal of
disk I/O.  You should probably see the DBZ  manpage  in  the
_d_o_c directory for some (brief) additional discussion of this
issue.




                      February 14, 1992





                            -24-


     If you are using _v_f_o_r_k (specified in the  _F_O_R_K  parame-
ter),  or you want to _m_m_a_p the database, then you mmuusstt apply
the patch.  The Makefile in _l_i_b will normally do it for  you
automatically,  anyway.   The  beginning  of  the patch file
describes the changes made in more detail.  If  you  do  not
apply  the  patch,  then  you  must add add ``dbzalt.c'' and
``dbzalt.o'' to the MISSING_SRC and MISSING_OBJ  parameters.

     Apparently  the  System  V  386 compiler can't optimize
_d_b_z_._c (the GNU C compiler doesn't have  this  problem).   If
you  have  ``-O'' in your _D_B_Z_C_F_L_A_G_S configuration parameter,
then take it out.

55..33..  UUssiinngg wwrriitteevv

     INN makes extensive use the _w_r_i_t_e_v system call to write
several  I/O  buffers  in a single call.  If you do not have
_w_r_i_t_e_v  then   you   must   copy   _i_n_c_l_u_d_e_/_u_i_o_._h   to   your
_/_u_s_r_/_i_n_c_l_u_d_e_/_s_y_s  directory.  You must also add ``writev.c''
and ``writev.o'' to the MISSING_SRC and MISSING_OBJ  parame-
ters.

     The  ``fake''  _w_r_i_t_e_v found in the _l_i_b directory is not
highly efficient.  You might want to write a better one that
tries  to _m_a_l_l_o_c a new buffer and join all the elements.  Be
careful about doing this  because  _i_n_n_d  can  use  very  big
buffers.

66..  CCoommppiilliinngg tthhee SSyysstteemm

     Once  the  INN  sources  have been configured, they are
ready to be compiled.  If you are  very  confident  of  your
changes, type the following:

     cd $inn
     make all

If  you  do  not  get any errors, skip to the section titled
``Installing the System.''

     If you are confident, but careful, type:

     cd $inn
     make world
     cat */lint

This will compile everything, then run _l_i_n_t in all  directo-
ries.

     Another  option is to run the _B_U_I_L_D 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.''




                      February 14, 1992





                            -25-


     If you are more cautious, you should type  the  follow-
ing:

     cd $inn/config
     make quiet
     cd ..

This  will  use  your already-tested _s_u_b_s_t program with your
new _c_o_n_f_i_g_._d_a_t_a file.  You should then follow the  steps  in
the following sections.

66..11..  BBuuiillddiinngg tthhee LLiibbrraarryy

     The next step is to build the INN library.  Do the fol-
lowing

     cd $inn/lib
     make libinn.a lint


     This will  build  the  library  and  run  _l_i_n_t  on  the
sources, putting the output into a file named _l_i_n_t.  If any-
thing fails to compile, you probably  made  a  configuration
error, most likely in the ``C library differences'' section.
In particular, double-check  the  _S_I_G_H_A_N_D_L_E_R  and  _x_x_x___S_T_Y_L_E
parameters.

     The  _l_i_n_t  output  should be almost empty, except for a
couple of ``possible pointer alignment problem'' warnings in
_d_b_z_._c.   If  you  get much more than this, then you probably
did not define the _P_O_I_N_T_E_R or  _S_I_Z_E___T  parameters  properly.
The  _N_E_W and _R_E_N_E_W macros in _i_n_c_l_u_d_e_/_m_a_c_r_o_s_._h try to capture
all the alignment problems associated  with  dynamic  memory
allocation.   Also  double-check  the _A_L_I_G_N_P_T_R parameter and
the _C_A_S_T macro in _i_n_c_l_u_d_e_/_m_a_c_r_o_s_._h.

     If _l_i_n_t reports any other problems, you should take the
time  to  investigate  them.   Note that many _l_i_n_t libraries
have errors.  Also, you may get some problems in _y_a_c_c_p_a_r  in
_p_a_r_s_e_d_a_t_e_._y;  these  are most likely in the _y_a_c_c-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 _l_i_b directory.  This will also compile a
_l_i_n_t library for use in linting the programs  in  the  other
directories.

     Note  that any time a change is made to the library you
must  do  ``make install'';  it  is  not  enough   to   type
``make libinn.a''.   This is a deliberate decision -- like a



                      February 14, 1992





                            -26-


program, compiling a library is  different  from  making  it
available for others to use, and installing a library should
make it possible to run _l_i_n_t against it.

66..22..  CCoommppiilliinngg tthhee PPrrooggrraammss

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

66..22..11..  TThhee FFrroonntteenndd PPrrooggrraammss

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

_i_n_e_w_s          The program that validates and prepares  news
               articles  and  gives  them  to _i_n_n_d.  This is
               mostly used  by  users  (usually  indirectly,
               through   programs   like  _P_n_e_w_s),  but  also
               through special facilities such as  news/mail
               gateways.

_r_n_e_w_s          Unpacks  news  batches  from  UUCP  sites and
               offers them to _i_n_n_d.

_c_t_l_i_n_n_d        This program controls _i_n_n_d, directing  it  to
               do  most  of  the  tasks a news administrator
               will have to do:  create  newsgroups,  update
               newsfeeds, and the like.

     To build these programs, type the following:

     cd $inn/frontends
     make all


66..22..22..  IInnnndd

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

_i_n_n_d           _I_n_n_d accepts all  incoming  NNTP  connections
               and  either  processes their traffic or hands
               them off to the NNTP  ``newsreader''  server.
               It  accepts  articles, files them, and queues
               them so that they can be sent  to  downstream
               feeds.   _I_n_n_d  listens  on  the official NNTP
               port.  On most systems only root can do this.
               _I_n_n_d is careful to set the modes of any files
               it creates, as well as the privileges of  any
               processes it spawns.





                      February 14, 1992





                            -27-


_i_n_n_d_s_t_a_r_t      Sites  that  are  concerned about large root-
               access programs may  wish  to  install  _i_n_n_d_-
               _s_t_a_r_t.   This program opens the port, changes
               its user and group ID to be that of the  news
               administrator,  and then _e_x_e_c's _i_n_n_d with the
               open port.  It also sets up a  secure  execu-
               tion  environment.   It  is  a  small program
               (about 100 lines) that is easily  understood.
               You  should  use  it  because  _i_n_n_d  will run
               faster because it  won't  have  to  make  any
               _c_h_o_w_n  system  calls.   If you make _i_n_n_d_s_t_a_r_t
               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  _i_n_n_d handles the filing and distribution of
certain messages differently from other systems.  For  exam-
ple, you can have newsgroups within ``control'' for the dif-
ferent types of control messages.  See _i_n_n_d_._8,  _n_e_w_s_f_e_e_d_s_._5,
and _a_c_t_i_v_e_._5 in the _d_o_c directory for details.

66..22..33..  TThhee NNeettNNeewwss RReeaaddiinngg DDaaeemmoonn

     _I_n_n_d  implements  a subset of the NNTP protocol -- only
those commands that are needed for peer sites to  feed  news
articles.   You  must  install  _n_n_r_p_d to allow users to read
news.  If a connection comes in from a host that  is  not  a
specified  feed,  then an _n_n_r_p_d process is spawned to handle
it.  (You can debug _n_n_r_p_d by running it  interactively;  put
an  entry  for  the host named ``stdin'' in your _n_n_r_p_._a_c_c_e_s_s
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 _n_n_t_p_d from the reference platform (See
Appendix  II)  and  make  sure  not to list the peer in your
_n_n_t_p_._a_c_c_e_s_s file.  The other choice is to relink the reading
software  on  the other machine with the INN library so that
it uses the ``mode reader'' NNTP command extension.

66..22..44..  TThhee BBaacckkeenndd PPrrooggrraammss

     The backend programs take articles that  _i_n_n_d  received
and  offer  them  to your news neighbors.  This includes the



                      February 14, 1992





                            -28-


following programs:

_a_r_c_h_i_v_e        A simple program to archive news articles.

_b_a_t_c_h_e_r        Collects  articles  into  batches  for   UUCP
               delivery.

_b_u_f_f_c_h_a_n       A  program to split a single _i_n_n_d stream into
               separate files.  It can buffer data, flushing
               files based on command-line switches.

_c_r_o_s_s_p_o_s_t      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.

_c_v_t_b_a_t_c_h       A program to turn a file  list  into  an  INN
               batchfile.   A  transition  aide that is only
               documented in the source.

_f_i_l_e_c_h_a_n       Another program to split a single _i_n_n_d stream
               into   separate  files.   It  is  system-call
               intensive, but requires no locking  protocol.

_i_n_n_x_m_i_t        A replacement for _n_n_t_p_x_m_i_t from the reference
               implementation.  It reads a file containing a
               list of articles, and sends them to a host.

_n_n_t_p_g_e_t        A  program to retrieve articles from a remote
               site.

_s_h_l_o_c_k         A program to provide a locking  protocol  for
               shell scripts.

_s_h_r_i_n_k_f_i_l_e     A  program to shrink a file by removing lines
               from the beginning.  It is useful for purging
               backlogged batchfiles.

_s_y_s_2_n_f         A program to turn a B or C News _s_y_s file into
               an INN _n_e_w_s_f_e_e_d_s file.  This is a  transition
               aide that is only documented in the source.

     To build this set of programs, type the following:

     cd $inn/backends
     make all


66..22..55..  EExxppiirree

     This  directory includes programs to modify the history
database as well as some utilities that might be  useful  in
this  task.  The database is called the _h_i_s_t_o_r_y file, and it
contains one line for every article on the system,  specify-
ing  when it was received and where it was filed.  This file



                      February 14, 1992





                            -29-


is indexed by the Message-ID, and the DBZ  package  provides
fast retrieval from it.

_c_o_n_v_d_a_t_e       Converts  between user-readable dates and the
               format used in the history file.

_e_x_p_i_r_e         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.

_m_a_k_e_a_c_t_i_v_e     This  program  can  be  used  to  rebuild the
               _a_c_t_i_v_e file if it is lost in a crash.

_m_a_k_e_h_i_s_t_o_r_y    This program scans through the spool area and
               rebuilds the history files.

_n_e_w_s_r_e_q_u_e_u_e    This  program  can  be  used after a crash to
               resend articles to your neighbors.

_p_r_u_n_e_h_i_s_t_o_r_y   This is a tool for other programs that expire
               news.   It  reads  a list of Message-ID's and
               filenames, and updates the  history  file  to
               mark that the files have been deleted.

     This  directory  also includes _e_x_p_i_r_e_._p_c_h and _r_e_a_p_._p_c_h.
The first is a patch to the C News expire program that  lets
it  cooperate  better  with  _i_n_n_d,  sending it messages when
articles have been removed.  The second is a set of  patches
to  the  _r_e_a_p  program that lets it cooperate with _p_r_u_n_e_h_i_s_-
_t_o_r_y; it also adds some other useful features.   Both  patch
files  have  additional  information in them.  Both programs
are unsupported, provided by members of the beta-test group.

     To build these programs, type the following:

     cd $inn/expire
     make all


     If you are currently running C News, note that it has a
directory named _e_x_p_i_r_e that is often the  same  pathname  as
INN's _e_x_p_i_r_e program.  You will have to move, or remove, the
directory before you can intall the INN program.

66..22..66..  SSccrriipptt aanndd ddaattaa ffiilleess

     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
_e_x_p_i_r_e every night.  Many of these scripts can be used as-is
until you get a feel for how INN works.





                      February 14, 1992





                            -30-


     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 _s_a_m_-
_p_l_e_s  directory.   Your modified copies should be maintained
in the _s_i_t_e directory.  By splitting  things  up  this  way,
official  updates  will  never wipe out any changes you have
made.

     To create the initial set of files, do the following:

     cd $inn/site
     make all


     See below for an explanation of each file.

66..33..  MMaannuuaall ppaaggeess

     INN comes with an extensive set of manual  pages.   You
might  want  to edit the Makefile to set up the right owner-
ship of the installed manual pages.  Or you  might  want  to
not bother installing them at all.

     When  it  comes  to reading them, you should start with
_i_n_n_d_._8 and _c_t_l_i_n_n_d_._8.  From there  follow  the  cross-refer-
ences as you want.

77..  IInnssttaalllliinngg tthhee SSyysstteemm

     Although  either _i_n_n_d or _i_n_n_d_s_t_a_r_t must be run by root,
most of the installation does not have to be done  as  root.
The _$_i_n_n_/_m_a_k_e_d_i_r_s_._s_h script creates all the necessary direc-
tories used by INN, and sets up  the  right  ownerships  and
modes:  owned  by _N_E_W_S_U_S_E_R in group _N_E_W_S_G_R_O_U_P with 0775 per-
missions (the  ``firewall''  directory,  ___P_A_T_H___I_N_D_D_D_I_R,  has
mode 0770).  You should review this script, then run it.

     The rest of the installation should be done as the news
administrator or as root.  The  Makefiles  are  very  strict
about setting the modes on the files that get installed.  To
install the programs, do the following:

     cd $inn
     make update

This target does a ``make install'' in all program  directo-
ries.   It  installs the programs and manpages, but does not
update or install any configuration files or scripts.   This
is  important:   in  any  directory (including the top-level
one), a ``make install'' will  install  everything  in  that



                      February 14, 1992





                            -31-


directory  into the right place.  A ``make update'' can only
be done in the top-level directory or in the _s_i_t_e directory,
and it only replaces scripts, 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  _s_i_t_e  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 exam-
ple.

     The next, and last, step is to build your INN  configu-
ration  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 _b_a_c_k_-
_e_n_d_s  and  the  _s_a_m_p_l_e_s directories and run _s_u_b_s_t over them.
Whenever patches are issued, doing a _m_a_k_e in this  directory
will  let  you  know  what  files have been updated, without
destroying your local changes.  The _g_e_t_s_a_f_e_._s_h  script  does
this.   If  you have either an _S_C_C_S or an _R_C_S directory then
_g_e_t_s_a_f_e_._s_h will use the appropriate  source  control  system
for the files in this directory.

     The  first  set of files are used to carry out the con-
trol messages.  You might want to look them over; in partic-
ular,  look at the table in _c_o_n_t_r_o_l_._c_t_l and the newslog man-
pages in _d_o_c.  The control files are:

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


     The following scripts are normally invoked by  _c_r_o_n  or
at system boot time, and should not require many changes:

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

_R_c_._n_e_w_s starts the server. In versions 1.4 and earlier, this
script was run by user root. In this version,  _r_c_._n_e_w_s  must
be  run  by  the  user  defined  as the _N_E_W_S_U_S_E_R in the con-
fig.data file.   _N_e_w_s_._d_a_i_l_y  invokes  _e_x_p_i_r_e  and  _s_c_a_n_l_o_g_s.
_S_c_a_n_l_o_g_s  calls  the other scripts to process the logs.  You



                      February 14, 1992





                            -32-


might want to review these scripts just to see what they do.
Do  not  get  bogged down in the details, just read the com-
ments.  They are documented in  the  manpages  news.daily(8)
newslog(5), and newslog(8).

     There  are  some  utility  scripts to send news to your
news feeds:

     nntpsend       send-nntp
     nntpsend.ctl   send-uucp
     send-ihave     sendbatch

They flush and lock the batch file for the specified site(s)
and  then  call  _i_n_n_x_m_i_t  to send the articles to your down-
stream feeds.  _S_e_n_d_-_i_h_a_v_e is used for ``ihave/sendme'' feeds
and  is  described  in an appendix.  _S_e_n_d_b_a_t_c_h and _s_e_n_d_-_u_u_c_p
flush and lock batchfiles and call _b_a_t_c_h_e_r to queue up  UUCP
jobs.   You  might  want to modify these files to change the
flags given to _u_u_x; 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 _d_f so that  your
spool  area  is  not overrun!  _N_n_t_p_s_e_n_d and _s_e_n_d_-_n_n_t_p 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
_d_o_c directory that describe them:

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


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

     inncheck       makegroup
     innwatch       scanspool

_I_n_n_c_h_e_c_k  is  a  Perl script to check the syntax and permis-
sions of an installed INN system.  _I_n_n_r_e_p_o_r_t is an alternate
way  of  summarizing  the  server's  log file.  It is a Perl
script.  _I_n_n_w_a_t_c_h 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  ___P_A_T_H___N_E_W_S_B_O_O_T
script.   You  might  have  to edit it to understand your _d_f
output format.  _M_a_k_e_g_r_o_u_p is a front-end to _r_n_e_w_s that helps
you  write  a  control  message  to create a newsgroup.  You
should review this script because you might have  to  change
the  way  the  output  of  the  _d_a_t_e  command is parsed, and
because  you  might  might  want  to  change   the   default



                      February 14, 1992





                            -33-


distribution.   _S_c_a_n_s_p_o_o_l is a Perl script to make sure that
the active file and the contents of your spool tree agree.

     Once you have made the necessary modifications  (and  I
admit  that some of this -- especially the _n_e_w_s_f_e_e_d_s file --
will be difficult), you should type the following:

     make install

Make sure you have _r_c_._n_e_w_s installed in the right place,  as
explained  in  the  ``Paths  to  common  programs'' section,
above.  You might find it useful to  read  the  ``First-Time
Usenet  or NNTP Installation'' appendix for help on navigat-
ing through the INN configuration files.

     There are now only  a  couple  more  things  to  check.
First,  make  sure  you  have  an  _a_c_t_i_v_e file and a _h_i_s_t_o_r_y
database!  The appendices explain how to convert your exist-
ing  files;  the  _B_U_I_L_D script will create new ones for you.
If you have Perl, run _i_n_n_c_h_e_c_k to make sure  that  you  have
the datafiles configured correctly.  The second is make sure
that you have correctly updated  your  _s_y_s_l_o_g_._c_o_n_f  file  to
match the filenames and logging levels required by INN.  See
_s_y_s_l_o_g_/_s_y_s_l_o_g_._c_o_n_f for an example of what to do.

     Once you have done all of  this,  InterNetNews  is  now
installed, and ready to run -- have fun!

88..  HHeetteerrooggeenneeoouuss CClliieenntt IInnssttaallllaattiioonnss

     The  _i_n_e_w_s  program  is used by user newsreaders.  Pro-
grams such as _r_n (which call _P_n_e_w_s) prepare a  news  article
and  feed  it into _i_n_e_w_s.  _I_n_e_w_s validates the news headers,
adds its own, and feeds  the  article  to  the  campus  _i_n_n_d
server.   The  _i_n_e_w_s that comes with INN is more useful then
the ``mini-inews'' that comes with the reference implementa-
tion.  You cannot run the standard B2.11 _i_n_e_w_s.  You can run
the C News _i_n_e_w_s, but only on client machines  (i.e.,  those
with  a _$_N_E_W_S_C_T_L_/_s_e_r_v_e_r file).  I recommend that you install
INN's _i_n_e_w_s on all the clients in your campus.

     INN comes with a _M_a_k_e_I_n_e_w_s script to make it easier  to
build  and  install  _i_n_e_w_s on a wide variety of hosts.  This
script creates a directory  and  copies  all  the  necessary
files  (headers, sources, configuration files) into it.  The
script takes an optional argument,  which  should  name  the
client machine's architecture.  For example:

     cd $inn
     ./MakeInews sun3

will  create  an _i_n_e_w_s_._s_u_n_3 directory.  You can then examine
the Makefile in that directory, and build and install  _i_n_e_w_s
on  your  Sun-3 clients.  This is easiest if the client NFS-



                      February 14, 1992





                            -34-


mounts the source directory -- that way  you  can  keep  all
your _i_n_e_w_s sources in one place.

     _R_n_e_w_s 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 _i_n_n_d is running, then the _M_a_k_-
_e_R_n_e_w_s script  can  be  used  in  the  same  manner  as  the
_M_a_k_e_I_n_e_w_s script.

99..  KKnnoowwnn PPrroobblleemmss

     If  you  use  NIS (formerly Yellow Pages) on SunOS, you
will need to add a ``domainname''  entry  to  your  _i_n_n_._c_o_n_f
file  if  your  hosts  do not contain fully-qualified domain
names.  The most common symptom of this is that  _i_n_e_w_s  will
fail because it cannot generate a Message-ID.  Another prob-
lem 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 _n_n_r_p_._a_c_c_e_s_s file.

     SunOS4.1.1  has  a bug where _w_r_i_t_e(2) can return EINTR.
The most common symptom is the following fatal error message
from _i_n_n_d:

     Can't sync history, interrupted system call

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

     If  you  have _N_O_F_I_L_E___L_I_M_I_T set you should know that the
standard I/O library in SunOS4.x has trouble with more  than
127  descriptors.   The most common symptom is the following
fatal error message from _i_n_n_d:

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

This occurs after doing a _c_t_l_i_n_n_d ``reload'' command.  For a
work-around,   reboot  your  server  instead  of  trying  to
``reload.''  Another symptom is that _i_n_n_d will exit  if  you
do a _c_t_l_i_n_n_d ``flush'' command while the server is paused or
throttled.  This is Sun bug 1045141.  Sun does not  plan  to
fix it for any 4.x release.

     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 _x_f_o_p_e_n_a routine with the following, it will work:

     return fopen(p, "a+");

This is in the file _l_i_b_/_x_f_o_p_e_n_a_._c.



                      February 14, 1992





                            -35-


     If you use Sun's unbundled compiler, _a_c_c, you must make
sure to use the unbundled assembler, too.   You  might  also
get  lots  of  ``left  operand  must  be modifiable lvalue''
errors.  Setting _U_S_E___C_H_A_R___C_O_N_S_T to ``DONT'' will help.

     There have been reports that the VAX Ultrix 4.2  _m_a_l_l_o_c
doesn't  work  well  with _i_n_n_d, causing it to slowly fill up
all swap space.  I believe that all of the memory  leaks  in
_i_n_n_d  have been fixed, but you might want to look at using a
different _m_a_l_l_o_c package.  The Kingsley/Perl _m_a_l_l_o_c  package
is  provided  in  the  _l_i_b  directory.  Add ``malloc.c'' and
``malloc.o'' to the MISSING_SRC  and  MISSING_OBJ  lines  in
_c_o_n_f_i_g_._d_a_t_a and rebuild.

     I  have been told that on SunSoft Interactive UNIX Sys-
tem 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
_i_n_c_l_u_d_e_/_c_l_i_b_r_a_r_y_._h.

     If  you use 386BSD (the Jolitz port, not the BSDI prod-
uct) you will have to set _A_C_T___S_T_Y_L_E to ``READ''.  If you  do
not  do  this  then  the  active  file will not get updated.
Another work-around is to insert an ``msync''  call  in  the
ICDwriteactive routine in _i_n_n_d_/_i_c_d_._c.  This is not supported
because I consider the 386BSD behavior to be buggy.

     The default configuration of some Sequent kernels  does
not  provide  enough descriptors for _i_n_n_d to run.  You might
have to rebuild your kernel with the  ``MAXNOFILE=128''  and
``NOFILEEXT=64''  options.   You  will  also  have  to had a
``setdtablesize(nnn)'' call in the main routine of _i_n_n_d, and
a ``setdtablesize(0)'' call in the Spawn routine.

     I  have  been  told that some older versions of the SCO
_o_p_e_n_d_i_r  routine  have  file  descriptor  leaks.   The  most
noticeable symptom is probably that _i_n_n_d will die while try-
ing to renumber the _a_c_t_i_v_e file.  You might want  to  use  a
freely-redistributable  ``dirent''  package such as one dis-
tributed by the Free Software Foundation.  You  should  also
make  sure  to set _C_L_X___S_T_Y_L_E to ``FCNTL'' Finally, you might
also want to edit _i_n_n_d_/_i_n_n_d_._c where it calculates the ``Max-
Outgoing'' parmater and increase the fudge number to four.

     On  some  SVR4  systems,  attempting  to set the socket
buffer size is either not supported or,  even  worse,  might
result  in  _i_n_n_d's  data  size growing.  The most noticeable
symptom is ``cant setsockopt(SNDBUF)'' messages in your _s_y_s_-
_l_o_g  output.   To  fix this, either comment out the calls to
_s_e_t_s_o_c_k_o_p_t in _i_n_n_d_/_n_c_._c or add ``-USO_SNDBUF'' to your  _D_E_F_S
config parameter.

     I  have heard that Sony SVR4 systems have lots of prob-
lems.  You must set _H_A_V_E___U_N_I_X___D_O_M_A_I_N to ``DONT''; sockets in



                      February 14, 1992





                            -36-


general  seem to have problems, including kernel crashes and
a blocked _i_n_n_d.

     If you use the GNU _s_e_d in the  ___P_A_T_H___S_E_D  configuration
parameter,  make sure you get version 1.13; earlier versions
have a bug that breaks the _p_a_r_s_e_c_o_n_t_r_o_l 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 _c_a_s_e
statement.  The most noticeable symptom is  that  _n_e_w_s_._d_a_i_l_y
does  not properly expire articles if _i_n_n_w_a_t_c_h 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  _A_C_T___S_T_Y_L_E  set to
``MMAP'' and/or have ``-DMMAP'' in _D_B_Z_C_F_L_A_G_S.  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 _i_n_n_d  never  exit.
The  most  likely  cause  is that _C_L_X___S_T_Y_L_E should be set to
``FCNTL.''
































                      February 14, 1992





                            -37-


AAppppeennddiixx II::  DDiiffffeerreenncceess ffrroomm ootthheerr NNeewwss ssooffttwwaarree

     Administrators will find that INN is fairly  incompati-
ble  with  B  and C News.  This section tries to mention the
most important 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 men-
tioned  here,  please let me know.  Note, however, that this
is _n_o_t a tutorial on how to set up a new INN system, or con-
vert older software to it; no such document exists.

11..  CCoonnffiigguurraattiioonn FFiilleess

     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.

_e_x_p_l_i_s_t        This is replaced by  the  similar  _e_x_p_i_r_e_._c_t_l
               file.   Archiving  is done by a separate pro-
               gram.

_m_a_i_l_p_a_t_h_s      This is replaced by the _m_o_d_e_r_a_t_o_r_s file.  The
               ``default'' entry in _m_a_i_l_p_a_t_h_s is replaced by
               either a full wildcard (``*'') entry  in  the
               _m_o_d_e_r_a_t_o_r_s  file, or by a ``moderatormailer''
               entry in the _i_n_n_._c_o_n_f file.

_n_n_t_p_._a_c_c_e_s_s    This is replaced by the _h_o_s_t_s_._n_n_t_p (for  NNTP
               peers)   and  _n_n_r_p_._a_c_c_e_s_s  (for  newsreading)
               files.

_n_n_t_p_._s_y_s       This is a password file used if NNTP is  com-
               piled   with  the  ``AUTH''  option.   It  is
               replaced by the _p_a_s_s_w_d_._n_n_t_p file.  Note  that
               _i_n_e_w_s   and  _r_n_e_w_s  will  also  try  to  read
               _p_a_s_s_w_d_._n_n_t_p.  Therefore,  you  will  probably
               want to have one-line versions of it for your
               on-campus clients.

_o_r_g_a_n_i_z_a_t_i_o_n   This  is  replaced  by  the  ``organization''
               entry in the _i_n_n_._c_o_n_f file.

_r_n_/_s_e_r_v_e_r      This  is  replaced by the ``server'' entry in
               the _i_n_n_._c_o_n_f file.

_w_h_o_a_m_i         This is  replaced  by  the  ``pathhost''  and
               ``fromhost'' entries in the _i_n_n_._c_o_n_f file.



                      February 14, 1992





                            -38-


22..  NNeewwssggrroouuppss,, AAccttiivvee,, SSyyss,, aanndd NNeewwssffeeeeddss

     The  biggest  difference is how the _n_e_w_s_f_e_e_d_s file com-
pares  with  the  _s_y_s   file.    Newsgroup   patterns   like
``all.all.ctl'' are completely gone.  All newsgroup patterns
are shell-style wildcards, matched against the _a_c_t_i_v_e  file.

     The  _a_c_t_i_v_e  file is taken to be the definitive list of
newsgroups 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 _s_y_s file.  If it matches, each newsgroup
is  then looked up in the _a_c_t_i_v_e file.  If none of the news-
groups are found, then the article is filed into  the  news-
group named ``junk''.

     INN's  behavior  is  much simpler.  If a newsgroup does
not appear in the _a_c_t_i_v_e 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 _a_c_t_i_v_e 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 arti-
cle.

     You can change INN's behavior so that it resembles  the
other  systems.   To do this, compile with _W_A_N_T___T_R_A_S_H set to
``DO.''  Note that this  will  accept  _e_v_e_r_y_t_h_i_n_g.   Because
there  is no subscription 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 _a_c_t_i_v_e file.

     INN  strictly  believes  in distributions.  If the site
named _M_E 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 _M_E entry.  Distributions are  fixed  strings
--  there are no patterns or special wildcards like ``all.''

     For more details on these items, see _d_o_c_/_n_e_w_s_f_e_e_d_s_._5.

33..  CCoonnttrrooll MMeessssaaggeess

     Like C News, INN implements all control messages  other
than cancel as shell scripts.  The number and type of param-
eters is different from that of C News.   All  control  mes-
sages consult the file _c_o_n_t_r_o_l_._c_t_l before acting on the mes-
sage.  If the sender's address  matches  with  the  list  of
authorized  addresses  (e.g.,  ``tale@uunet.uu.net'', ``*'',
etc.), the control message is either acted upon,  mailed  to
the  news  administrator,  or logged.  For example, messages
from  ``tale@uunet.uu.net''  (the   current   moderator   of



                      February 14, 1992





                            -39-


news.announce.newgroups) are honored.

     The ``control'', ``junk'', and ``to'' newsgroups can be
explicitly  sent  or  not  sent.   See  _d_o_c_/_n_e_w_s_f_e_e_d_s_._5  and
_d_o_c_/_i_n_n_d_._8.

     The  _c_t_l_i_n_n_d  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 _c_t_l_i_n_n_d to send a message back to the server
telling it to create or remove the group.

44..  LLoocckkiinngg

     A running news system has many open files.  These files
can  be  divided  into two groups.  The first group includes
the history database and  _a_c_t_i_v_e  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 _i_n_e_w_s does ``atomic appends,''
no locking is necessary.   C  news  uses  the  _l_o_c_k_n_e_w_s  and
_n_e_w_s_l_o_c_k  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 _c_t_l_i_n_n_d.  The first
group  is  generally  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 _d_o_c_/_c_t_l_i_n_n_d_._8
manpage; examples of their  use  can  be  found  in  various
scripts in the _s_a_m_p_l_e_s directory.






















                      February 14, 1992





                            -40-


AAppppeennddiixx IIII::  CCoonnvveerrttiinngg ffrroomm ootthheerr NNeewwss ssooffttwwaarree

     INN is a complete news transport and expiration system.
Since few people will be installing INN from  scratch,  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 careful.

11..  CC NNeewwss EExxppiirree

     The _e_x_p_i_r_e 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
_e_x_p_i_r_e  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 _e_x_p_i_r_e.)  There are
three ways to do this.

     The first way is to change your _d_o_e_x_p_i_r_e script so that
it  calls  _c_t_l_i_n_n_d  to  ``throttle'' _i_n_n_d just before _e_x_p_i_r_e
runs.  It should then issue a _c_t_l_i_n_n_d ``go''  command  after
_e_x_p_i_r_e  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 _l_i_b_/_l_o_c_k_._c and add it to
your C News library _l_i_b_c_n_e_w_s_._a, replacing the provided  lock
functions.   You  should  then  remove _e_x_p_i_r_e 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 _e_x_p_i_r_e to talk to
_i_n_n_d and tell it to cancel articles that  it  would  remove.
To do this, apply the patch file _e_x_p_i_r_e_/_e_x_p_i_r_e_._p_c_h to your C
News _e_x_p_i_r_e_._c sources.  You will also have to add  _l_i_b_/_i_n_n_d_-
_c_o_m_m_._o to _l_i_b_c_n_e_w_s_._a and then rebuild _e_x_p_i_r_e.

22..  SSttaannddaarrdd NNNNTTPP ddaaeemmoonn

     You  can use the ``standard'' _n_n_t_p_d 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 _n_n_t_p_d so that it is  using
DBZ,  and  have  it  feed  each individual article to _i_n_e_w_s;
don't use the ``batched input'' option.  It should  also  be
set up so that it acts as if it is running under _i_n_e_t_d.  You
should also make sure that _i_n_e_t_d does nothing with the  NNTP
port, number 119.







                      February 14, 1992





                            -41-


33..  NNNNTTPP--bbaasseedd nneewwssrreeaaddeerrss

     If   you   already  have  your  NNTP-using  newsreaders
installed and running, you do not have to do anything.  This
includes  _x_v_n_e_w_s,  _x_r_n,  _r_r_n  and so on.  INN implements the
standard NNTP protocol, with some extensions.  INN does  not
provide  the  extensions used by _t_r_n, _t_i_n or other newsread-
ers.  INN will not implement all the different indexing sys-
tems  because the right solution is to have a generic inter-
face that all readers can use.)

     For administrative convenience, however, you might wish
to have all your newsreaders use the INN library and config-
uration files to talk  to  the  server.   The  next  section
describes how to do that for _r_n.  It is provided as an exam-
ple, to help you convert other programs you might have.  INN
does not provide, nor fully support, any newsreaders.

44..  RReemmoottee rrnn

     The  ``remote''  version of _r_n (also called _r_r_n) uses a
set of routines in the NNTP  ``clientlib''  file.   INN  can
emulate these routines; see _d_o_c_/_c_l_i_e_n_t_l_i_b_._3.  If you need to
build _r_n for client machines that don't have the entire  INN
distribution  available,  use  the _M_a_k_e_L_i_b script to build a
distribution directory of the necessary routines.  Use  this
script the same way you use the _M_a_k_e_I_n_e_w_s script.

     _R_n,  _r_r_n,  and _t_r_n are moving targets so these instruc-
tions may be out of date.  The maintainers  have  agreed  to
officially support INN, however, which is a good thing.

     There  are two ways to build _r_n so that it uses the INN
library.  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 _r_n _C_o_n_-
_f_i_g_u_r_e script and then execute it and rebuild  the  program.
To do this, type the following:

     cd _r_n___s_o_u_r_c_e
     patch <$inn/frontends/rn.pch
     ./Configure
     make

At some point, _C_o_n_f_i_g_u_r_e will ask you if you want to use the
InterNetNews library; answer _y_e_s.  You can then  use  either
the  full  sources,  or a special library that contains just
the needed header and sources  files.   Tell  _C_o_n_f_i_g_u_r_e  the
appropriate pathnames, and then proceed with the rest of the
_r_n installation.

     The second way is to edit a couple of files  after  you
have  run  _C_o_n_f_i_g_u_r_e  and  set it up to build the remote rn.



                      February 14, 1992





                            -42-


First, replace the  _r_n  file  _s_e_r_v_e_r_._h  with  the  INN  file
_i_n_c_l_u_d_e_/_m_y_s_e_r_v_e_r_._h.   The  next step is to edit the _r_n Make-
file to remove the ``clientlib'' file from  the  source  and
object  file lists.  This can probably be done by commenting
out the definitions of the _c_5 and _o_b_j_5 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 _l_i_b_s variable so that the
full pathname to _l_i_b_i_n_n_._a is the first item after the  equal
sign.

55..  RReemmoovviinngg tthhee OOtthheerr SSttuuffff

     The  names  below  assume  a  ``standard''  news setup;
things might be different on your machine.  Also, many  pro-
grams  have  alternate  names and links; make sure you chase
down and remove aallll of them.

     You might find it easiest to rename your  _/_u_s_r_/_l_i_b_/_n_e_w_s
(and  _/_u_s_r_/_l_i_b_/_n_e_w_s_b_i_n)  directories  to  something else and
start with a clean slate, copying over the files as they are
needed.   Make  ssuurree that your news processing is completely
stopped before you begin this process.   That  includes  any
_c_r_o_n jobs that may be running.

     The  _/_u_s_r_/_l_i_b_/_n_e_w_s  directory  can  become cluttered --
that's why C News split everything up into separate directo-
ries.   The  following  files are compatible with C News and
B2.11 News, and should be _k_e_p_t:

     active         active.times

If you are running C News keep these files, otherwise delete
them and use _m_a_k_e_h_i_s_t_o_r_y to rebuild them:

     history
     history.dir
     history.pag


     _R_n 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 _r_n to use the INN library, remove this file:

     /usr/local/lib/rn/server


     The input system is completely  replaced.   Remove  the
following programs and their manpages:





                      February 14, 1992





                            -43-


     /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:

     /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 require some changes to make sure that  batchfiles  are
properly  flushed;  see  the  _s_e_n_d_-_x_x_x 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 _n_n_t_p_l_i_n_k, _n_e_w_s_x_d, and the like, sub-
ject 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 _e_x_p_i_r_e directory, you will probably
have problems installing INN's _e_x_p_i_r_e, which  is  a  program
that often has the same name as the C News directory.

     The  following  programs  in  _/_u_s_r_/_l_i_b_/_n_e_w_s_b_i_n  are not
needed and can be deleted.  Keeping them around is harmless,
and if you find them useful don't delete them:








                      February 14, 1992





                            -44-


     canonhdr       newshostname
     ctime          newslock
     dbz            queuelen
     getabsdate     sizeof
     getdate        spacefor
     gngp

Note  that  _c_t_i_m_e,  _g_e_t_a_b_s_d_a_t_e,  and _g_e_t_d_a_t_e are replaced by
_c_o_n_v_d_a_t_e.  More importantly, _n_e_w_s_l_o_c_k does not lock _i_n_n_d; it
is best to remove it.

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

     mailname       sys
     mailpaths      whoami
     organization

If you have other software that uses them (except _s_y_s),  you
can  keep them.  The following will be rebuilt (or overwrit-
ten) by _i_n_n_d and _s_c_a_n_l_o_g_s 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
discarded.




















                      February 14, 1992





                            -45-


AAppppeennddiixx IIIIII::  SSeettttiinngg uupp ddiiffffeerreenntt ffeeeeddss

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

11..  IIhhaavvee//sseennddmmee ffeeeedd

     For a standard UUCP newsfeed, a site batches up all the
articles  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
specialized  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 _i_n_n_d processes the message it will invoke the appropri-
ate  control script, _/_u_s_r_/_l_o_c_a_l_/_n_e_w_s_/_b_i_n_/_c_o_n_t_r_o_l_/_i_h_a_v_e.  The
script will filter the body using  _g_r_e_p_h_i_s_t_o_r_y,  creating  a
list  of Message-ID's not found in the _h_i_s_t_o_r_y database.  It
uses this output to  create  a  ``sendme''  control  article
which  is posted to the ``to.remote'' newsgroup using _i_n_e_w_s.
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  compli-
cated.  First, you must create two entries in your _n_e_w_s_f_e_e_d_s
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 _s_e_n_d_-_i_h_a_v_e script and make
sure it is invoked as needed  (usually  out  of  _c_r_o_n).   It
splits  the  batchfile from the remote.ihave _n_e_w_s_f_e_e_d_s entry



                      February 14, 1992





                            -46-


and posts ``ihave'' control messages into the  ``to.remote''
newsgroup.   These  messages  will get queued for the remote
entry.

     The next step is to send out any  articles  queued  for
the  remote  entry.   Treat  this  as  a standard UUCP feed,
invoking _s_e_n_d_-_u_u_c_p or _s_e_n_d_b_a_t_c_h as appropriate, typically  a
few minutes after _s_e_n_d_-_i_h_a_v_e 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 _i_n_n_d processes
this message it will invoke the appropriate control  script,
_/_u_s_r_/_l_o_c_a_l_/_n_e_w_s_/_b_i_n_/_c_o_n_t_r_o_l_/_s_e_n_d_m_e.   This  script will call
_g_r_e_p_h_i_s_t_o_r_y to turn the list into a list of  files  appended
to the batchfile for remote.  Examine this script (the file-
name should probably match the filename in the remote  _n_e_w_s_-
_f_e_e_d_s  entry)  and  send the batch to the remote site (using
_b_a_t_c_h_e_r, often called by _s_e_n_d_-_u_u_c_p or _s_e_n_d_b_a_t_c_h).

22..  FFeeeeddiinngg aa llaarrggee nnuummbbeerr ooff ssiitteess

     _I_n_n_d 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 descrip-
tors,  _i_n_n_d  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 article.  To reduce this, you can have
_i_n_n_d use an internal buffer for a site by  using  the  ``I''
parameter  in  the  _n_e_w_s_f_e_e_d_s 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 _i_n_n_d was started with ``-o10''
and there are 12 sites, all with ``I512'' in their _n_e_w_s_f_e_e_d_s
entry.  If each article generates 50 bytes (a pathname and a
Message-ID), then _i_n_n_d will close and re-assign two descrip-
tors every 10 or so articles.

     A better alternative is to use funnels and an exploder.
Funnels, specified in the _n_e_w_s_f_e_e_d_s 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 individual sites.  (Since most feeds will
want either ``Wn'' or ``Wnm'' entries, this is usually not a
problem.)





                      February 14, 1992





                            -47-


     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 exploders, _f_i_l_e_c_h_a_n and _b_u_f_f_c_h_a_n.

     _F_i_l_e_c_h_a_n  is  the  simplest,  and   most   inefficient,
exploder.   It does not keep any files open and is very sys-
tem-call intensive.  It can be used to provide behavior (and
performance!)  that is similar to B2.11 _i_n_e_w_s.  It can, how-
ever, be used as the  funnel  for  an  unlimited  number  of
sites.

     _B_u_f_f_c_h_a_n  keeps all its output files open all the time.
It should not be used for more sites then a  single  process
can  have  open.   _B_u_f_f_c_h_a_n  also has flags to automatically
flush its files, as well as close and  re-open  them,  every
specified  number  of  articles.  (The re-open capability is
useful for things like _n_n_t_p_l_i_n_k in its  ``watch  the  batch-
file''  mode.)   Using  _b_u_f_f_c_h_a_n with the ``-l1 -c50'' flags
will give behavior that is similar to the C News  _r_e_l_a_y_n_e_w_s.

     _B_u_f_f_c_h_a_n  can be run as a full exploder (``Tx'') in the
_n_e_w_s_f_e_e_d_s file.  This means that you can use _c_t_l_i_n_n_d to send
a  command  line  down  _b_u_f_f_c_h_a_n's input stream.  (_I_n_n_d will
also send a command whenever newsgroups are modified.)   The
only  useful  message 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 acknowl-
edgement back.

33..  MMaasstteerr//ssllaavvee rreepplliiccaattiioonn

     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 _i_n_n_d 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
___P_A_T_H___N_E_W_S_B_O_O_T script.  If _i_n_n_d is started with  the  ``-S''
flag  it  will  pass this flag on to _n_n_r_p_d.  This means that
when anyone connects to the slave and does a  ``POST''  com-
mand,  _n_n_r_p_d  will connect to the master and offer the arti-
cle.

     You must make sure that the slave's entry in  the  mas-
ter's  _n_e_w_s_f_e_e_d_s  file  sends all articles (e.g., don't have
any exclusions).  Since the _n_n_r_p_d on  the  slave  host  will
usually  add  its  name  to  the Path header, you should add



                      February 14, 1992





                            -48-


``Ap'' to the _f_l_a_g_s field of the slave's entry on  the  mas-
ter.

     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 _i_n_n_d_._8.  In order to do this you will  have
to set up a _n_e_w_s_f_e_e_d_s entry for the slave.  This should be a
standard entry except that you will need to  have  both  the
filename  and  the  replication  information written int the
batchfile.  To do this, put ``WnR'' in the  _f_l_a_g_s  field  of
the entry.

     When  you  want  to  actually  send the articles to the
slave site you will have to specify the ``-S'' flag in  your
_i_n_n_x_m_i_t  command.   Current  versions  of  _n_n_t_p_l_i_n_k  use the
``-x'' flag.

     When running as a slave, _i_n_n_d is  very  paranoid  about
staying  synchronized with its master.  Most noticeably, you
should make sure that all newgroup and rmgroup control  mes-
sages are handled identically on both systems.

     Finally,  note  that  postings  made  on the slave (via
_n_n_r_p_d) are actualy sent to the _i_n_n_d on the  master,  so  the
slave  must  be treated as a sending host, not a newsreading
host.






























                      February 14, 1992





                            -49-


AAppppeennddiixx IIVV::  FFiirrsstt--ttiimmee UUsseenneett oorr NNNNTTPP IInnssttaallllaattiioonn

     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 unfortunately 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 installa-
tion 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
_n_n_t_p_g_e_t  program  is  primarily a debugging 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, remember  to  send
it to nntp-managers-request, nnoott nntp-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 manpage 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 fol-
lowing command will zap an active file, setting up the arti-
cle numbers for a new site:

     sed <active.old >active.new \
        -e 's/^\([^ ]*\) [0-9]* [0-9]* \([^ ]*\)$/\1 0000000000 000000001 \2/'


     Once the groups are set up, your newsfeed will periodi-
cally connect to your NNTP server and offer it any new arti-
cles that have arrived since the last connection.  _I_n_n_d will
accept  the connection, receive the articles, and queue them



                      February 14, 1992





                            -50-


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 _n_e_w_s_f_e_e_d_s
entry, 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, _i_n_n_d  will
record  the  filename  in  the  batch file for your upstream
site.  Either _s_e_n_d_-_n_n_t_p or _n_n_t_p_s_e_n_d will flush and lock  the
batchfile,  and  then  call _i_n_n_x_m_i_t 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 _c_r_o_n
to run this script on a regular basis.  You can  run  it  as
often as you like, but 10 minutes 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  _n_e_w_s_f_e_e_d_s
file,  and  arrange to have _c_r_o_n run the _s_e_n_d_-_u_u_c_p 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
_n_e_w_s_._d_a_i_l_y script should be run by _c_r_o_n in the middle of the
night.  It will summarize that day's  log  files,  and  then
call  _e_x_p_i_r_e to purge old news.  You might also want to have
_c_r_o_n run _r_n_e_w_s  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 _i_n_n_d does not currently time-out
DNS entries.

     You will generally want to set up the _c_r_o_n jobs so that
they  are run as the news administrator, and not as root.  A
good version of _c_r_o_n that makes it easy to do  this  can  be
found on gatekeeper.dec.com in pub/misc/vixie/cron.tar.Z.

     You  will also need to get one or more programs to read
news.  There are several freely-available  programs  around.
_R_n is popular, and is probably the best place to start.  The
official distribution is  available  for  anonymous  FTP  at
tmc.edu in the _r_n directory.

     Welcome to Usenet, and have fun!







                      February 14, 1992





                            -51-


AAppppeennddiixx VV::  NNeewwss oovveerrvviieeww ddaattaabbaassee

     There  are now many newsreaders available that are able
to do ``threading.''  This is the ability to track a discus-
sion  within  a newsgroup by using the References header (or
other data), regardless of changes in headers like the  Sub-
ject  line.   Examples of these readers include _n_n, _t_r_n, and
_g_n_u_s, and more are becoming available.   Until  recently,  a
major problem with these readers is that they all required a
specialized external database that contained  the  threading
data.

     In   late  1992,  Geoff  Collyer  <geoff@world.std.com>
released the  _n_o_v,  or  ``news  overview,''  package.   This
included  database  tools  and,  and client access routines,
that let the current threaded newsreaders use a common, tex-
tual,  database.   An  overview database 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 ___P_A_T_H___O_V_E_R_V_I_E_W_D_I_R parameter.

     INN  includes  full  support  for creating and expiring
news overview databases.  To do this, add an entry like  the
following to your _n_e_w_s_f_e_e_d_s file:

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

(Make  sure  to  replace _/_p_a_t_h_/_t_o_/_b_i_n with the value of your
___P_A_T_H___N_E_W_S_B_I_N parameter.)  Then reload the _n_e_w_s_f_e_e_d_s file or
restart  your  server.   To create the initial database, run
the following command after you have started _o_v_e_r_c_h_a_n:

     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
_c_r_o_n job that runs _n_e_w_s_._d_a_i_l_y.

     The _n_n_r_p_d server includes  two  command  extensions  to
access  the  database; they are documented in the ``protocol
extensions'' part of _d_o_c_/_n_n_r_p_d_._8.  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,  including 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 _r_e_a_d_e_r.dist.tar.Z.









                      February 14, 1992





                            -52-


AAppppeennddiixx VVII::  LLiimmiitteedd MMIIMMEE SSuuppppoorrtt

     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 _n_n_r_p_d can add MIME headers to
all local postings that do not have them.

     In addition, there are patches available  for  _n_n_t_p_l_i_n_k
that  allow  it  to  do MIME transport.  The patches are not
(yet) part of the official release; if you need  them,  con-
tact Christophe Wolfhugel <Christophe.Wolfhugel@hsc-sec.fr>;
he did most of the INN work, too.

     You should be very careful if you have _n_n_r_p_d  add  MIME
headers.    To  do  this,  edit  _i_n_n_._c_o_n_f  as  indicated  in
_d_o_c_/_i_n_n_._c_o_n_f_._5.  Once this is done, aallll articles posted will
get  MIME  headers added.  Existing MIME headers will not be
modified, but missing ones will be added.  The default  val-
ues to add to _i_n_n_._c_o_n_f 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 arrange-
ments  with your peers, however, you must transmit seven-bit
data.  Doing this  will  require  special  transmit  agents.
Note  that  _n_n_r_p_d is not a Mime-compatible reader.  You must
have software to extract the data and present  it  appropri-
ately.

     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.   _N_n_r_p_d  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 postings, 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 _n_n_r_p_d does not do any conversion.

     In general, be very cautious.




                      February 14, 1992





                            -53-


     MIME articles can only be sent using _i_n_n_x_m_i_t;  work  on
_b_a_t_c_h_e_r  is in progress.  Unless the ``-M'' flag is used, no
MIME conversions are done.  If the flag is used, the follow-
ing   happens:  Articles  with  a  Content-Transfer-Encoding
header of ``8bit'' or ``binary'' are forwaded  in  ``quoted-
printable''  format (the ``base64'' format will be available
soon).  All other articles -- in particular,  those  without
MIME  headers,  those  of type ``message'' or ``multipart,''
those with Content-Transfer-Encoding header of  ``7bit''  --
are forwarded without any change.















































                      February 14, 1992


