








                  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
     appendix  IV  gives a Usenet installation overview
     for novices.

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



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  pub-
lished by Addison-Wesley.


-----------
|- UNIX is a registered trademark of X/Open Company
Ltd.



                    Northern Winter 1997





                             -2-


     There   is  a  book  called  _A_d_m_i_n_i_s_t_e_r_i_n_g  _U_s_e_n_e_t  _N_e_w
_S_e_r_v_e_r_s, ISBN 0-201-41967-X, by James McDermott and John  E.
Phillips. Published by Addison-Wesley. It has good INN 1.5.1
coverage.

     In November 1997, there was a new version  of  _M_a_n_a_g_i_n_g
_U_s_e_n_e_t  (note,  no  UUCP)  about to come out from O'Reilly &
Associates. This has a large  section  on  INN  as  well  as
Cnews.

     You  should know BSD-derived TCP/IP -- at least be com-
fortable with host names and dotted-quad addresses.  If  you
have  installation  problems,  you  should  know about UNIX-
domain stream and datagram sockets and the like.   In  addi-
tion  to  any  documentation available from your vendor, you
might find it useful to read the two IPC tutorials  in  _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.   RFC 977 is currently being
revised.  The 1036 revision is most likely  going  to  be  a
``tightening-up'';  since INN already has a strict interpre-
tation of the RFC, this revision will  probably  not  affect
InterNetNews very much.  The 977 revision is formally adding
new features and facilities which are currently implemented,
and  while  INN will not provide all of them, they will have
some impact.

     InterNetNews does things differently  from  other  news
software.   Some other Usenet systems for UNIX are B2.11 and
C News.  Both of them require a  separate  NNTP  implementa-
tion.   The  one  everyone uses is called ``NNTP.''  Because
this is confusing (they don't  call  _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,



                    Northern Winter 1997





                             -3-


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.

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.




                    Northern Winter 1997





                             -4-


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

_d_b_z            DBZ database package.

_s_y_s_l_o_g         Syslog  routines  for the systems which don't
               provide proper functions needed for INN.

     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.

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

_s_a_m_p_l_e_-_c_o_n_f_i_g_s Sample configuration data for any system.

_a_u_t_h_p_r_o_g_s      Sample program  which  can  be  used  for  an
               authentication with nnrpd.

_c_o_n_t_r_i_b        Contributed programs useful for INN.

_o_b_s_o_l_e_t_e

_F_A_Q            Frequently  Asked  Questions  on INN which is
               posted  at  news.software.{b,nntp}   periodi-
               cally.

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

_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



                    Northern Winter 1997





                             -5-


               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.

_R_E_A_D_M_E_._p_e_r_l___h_o_o_k
               A description for PERL filtering.

_R_E_A_D_M_E_._t_c_l___h_o_o_k
               A description for TCL filtering.

_C_O_N_T_R_I_B_U_T_O_R_S   Contributors to INN.

_H_I_S_T_O_R_Y        History until INN 1.4.

_i_f_t_r_u_e_._s_h      Script that does test(1).

_i_n_s_t_a_l_l_i_t_._s_h   Script  that  installs  programs, scripts and
               configuration files for INN.

_P_G_P_K_E_Y_S        PGP public  keys  used  for  control  message
               authentication.

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




                    Northern Winter 1997





                             -6-


     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.
To do this, type the following:







                    Northern Winter 1997





                             -7-


     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, choose one of the
sample config files which is suitable for your  system  from
_s_a_m_p_l_e_-_c_o_n_f_i_g_s directory, and copy it to _c_o_n_f_i_g_/_c_o_n_f_i_g_._d_a_t_a.
If there is no sample for your system, 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 Configuration
     PGP Configuration
     Keyword Configuration
     Local Configuration
     Actsync Configuration
     Perl Configuration




                    Northern Winter 1997





                             -8-


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.

     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



                    Northern Winter 1997





                             -9-


create an empty file  so  that  the  other  Makefiles  don't
break.   If  you  come  up with a fourth alternative, let me
know.

     Unfortunately, on some systems _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  in  the
LOG AND CONFIG FILES section.

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



                    Northern Winter 1997





                            -10-


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 SOCKETS CREATED BY INND OR CLIENTS section below).
In addition, _i_n_e_w_s will only let the _N_E_W_S_U_S_E_R user  or  mem-
bers of the _N_E_W_S_G_R_O_U_P group post control messages other than
cancel.

     Some INN scripts (primarily the control message scripts
and  the daily maintenance script) need to send email to the
news maintainer.  The  _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
(expireover, overchan and filechan use either!)

     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



                    Northern Winter 1997





                            -11-


_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
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, _M_I_S_S_I_N_G___O_B_J 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.




                    Northern Winter 1997





                            -12-


     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
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.  The best work-around is proba-
bly 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



                    Northern Winter 1997





                            -13-


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.

     The  _L_I_K_E___P_U_L_L_E_R_S  parameter  controls  how  to  handle
clients  that  appear  to  be doing a sucking feed from your
machine (many admins don't like such clients). If the  value
is  ``DO'' (the default), then nothing different happens. If
the value is ``DONT'', then after  100  articles  have  been
sent,  each  article transfer will be followed by a short (1
second) sleep. For most readers this isn't  a  problem,  but
some clients doe article scoring based on the entire body of
the  article.  Such   clients   will   be   penalized   when
_L_I_K_E___P_U_L_L_E_R_S is set to ``DONT''.

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



                    Northern Winter 1997





                            -14-


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.

     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.






                    Northern Winter 1997





                            -15-


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.

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 _/_v_a_r_/_n_e_w_s_/_e_t_c, so that it is generally
safe to export _/_u_s_r_/_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



                    Northern Winter 1997





                            -16-


information needed.  For example, C News provides three dif-
ferent  routines to get the filesystem statistics (with con-
ditional 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_/_i_n_n_w_a_t_c_h_._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:

     !!! df . | awk 'NR == 2 { print $4 }' ! ...

This  is  looking  at the fourth field of the second line to
get the amount of freespace.  You will have  to  change  the
``2''  and  ``4''  here  (both  can  be  changed  by setting
_I_N_N_W_A_T_C_H___I_N_O_D_E_S and _I_N_N_W_A_T_C_H___B_L_O_C_K_S  respectively),  and  on
other lines, as appropriate for your system.

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




                    Northern Winter 1997





                            -17-


     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
defined by this parameter.

44..22..1144..  PPGGPP CCoonnffiigguurraattiioonn

     Inn now has mechanisms in place that will do PGP  veri-
fication  of  control  messages  (except for cancels). It is
_h_i_g_h_l_y recommended that you use PGP if you can. Forged  con-
trol  messages are a serious problem in USENET.  You can get
PGP from hhttttpp::////wweebb..mmiitt..eedduu//nneettwwoorrkk//ppggpp..hhttmmll.

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

     To verify messages, you must have a PGP public key  for
each  signer that you wish to trust. It should be entered in
a key ring that is accessible to the user-id that  runs  the
news  system by running pgp -ka on a file containing the key
to add. For example, at a site that  runs  the  news  server
software  as  news,  the  following  command run by the news
user-id should add the key bounded by  BEGIN  and  END  "PGP
PUBLIC  KEY BLOCK" lines in the file /tmp/key to the default
key ring that would be used for authentication:

     pgp -ka /tmp/key

     As a general policy rule, control message signers  will
not  use their control message keys to introduce other keys,
so when PGP asks you a question similar to, "Would you trust
this user to act as an introducer and certify other people's
public keys to you?" answer that you would not.

     After you have added the appropriate key  to  your  key
ring,  you  need  to  tell the news software to validate the
control messages received. As implemented, the  system  will
perform   the   requested  action  if  the  message  can  be



                    Northern Winter 1997





                            -18-


authenticated and it will mail the message to the news  sys-
tem administrator if it cannot.

     Automatic  processing of control messages is handled by
control.ctl, _C_o_n_t_r_o_l_._c_t_l has several lines at the  beginning
of  it that describe the format of the file, and there is an
even longer _c_o_n_t_r_o_l_._c_t_l(5) manual page. PGP verification for
many large heirarchies is already enabled in _c_o_n_t_r_o_l_._c_t_l(5).
To enable PGP verification for another heirachy, in addition
to  the  normal  authorization  done by control.ctl, use the
action "verify-PGP_USERID" in the fourth field. The supplied
_c_o_n_t_r_o_l_._c_t_l file has samples that should be clear.

     To  test  the PGP setup a signed sample control message
is in the file CONTROLPROGS/sample.control  (where  CONTROL-
PROGS  is as defined in config.data). Copy this to /tmp/sam-
ple.control. The file name /tmp/sample.control will be  used
for this example.

     To  verify  the  control message, you will need the key
for news.announce.newgroups and authorization in  your  news
system  for tale@uunet.uu.net to automatically perform "new-
group". Go ahead and enable it for  the  test  even  if  you
don't  want  to really allow this, because it is easy enough
to rescind after the test by  editing  the  control  message
authorization  file  and  removing  the  key  with  pgp  -kr
news.announce.newgroups.

     You can check that the pgpverify  part  of  the  system
will  work  properly simply by feeding it the sample control
message on stdin:

     pgpverify < /tmp/sample.control

     If it could run pgp and find the  correct  key  in  the
default   key  ring,  the  string  "news.announce.newgroups"
should be printed. The exit status of the script,  found  in
most shells with the command

     echo $?

as the next command after pgpverify, should be 0 (zero).

     When pgpverify passes its test, use the procedure below
to verify the authorization system.

     First,  cd  to  the  directory  where  parsecontrol  is
installed.  Then execute the following four lines, in order,
as the user who owns the news system:

     /bin/sh
     PROG=newgroup
     set -- tale@uunet.uu.net "" /tmp/sample.control
     (. ./parsecontrol "$@"; echo $ACTION)



                    Northern Winter 1997





                            -19-


     If the message verified  correctly,  the  echo  command
should  output  doit; otherwise, verification failed and the
output should be mail.

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

44..22..1155..  KKeeyywwoorrdd CCoonnffiigguurraattiioonn

     The keyword generating code, that  has  been  added  by
Karl  Kleinpaste,  is  off  by  default,  as it's a real CPU
sucker (does a lot of regexp matching).  To  enable  it  you
must:

1.   Set  KEYWORDS to DO in config.data (and possibly change
     KEYLIMIT ABSURD and MAX_WORDS) and rebuild innd.

2.   Uncomment the last line of  the  overview.fmt  file  so
     that it looks like:
               Keywords:full

3.   Install and start the new innd.

     Of  course  you need overview generation enabled -- see
elsewhere in this document for that.

44..22..1166..  LLooccaall CCoonnffiigguurraattiioonn

     At this section local definitions like  home  directory
of  _N_E_W_S_U_S_E_R are specified.  This parameter is used for set-
ting environment variable handed to  innd  when  invoked  by
inndstart.

44..22..1177..  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. If you
don't have a good host to sync to, you  can  get  (via  anon
ftp)  ftp://ftp.isc.org/pub/usenet/CONFIG/active.gz and have
actsync use that.

44..22..1188..  PPeerrll CCoonnffiigguurraattiioonn

     The innd server can be configured to include perl hooks
to  be  run  the  way  TCL  does  whenever  a new article is
received and when  certain  other  actions  occur.   Further
more,  nnrpd can be also configured to include perl hooks to
be run whenever  a  new  article  is  posted.  This  is  not



                    Northern Winter 1997





                            -20-


supported  in  TCL.   See the file README.perl_hook for more
details.

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

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

     The  ___P_A_T_H___P_E_R_L___S_T_A_R_T_U_P___I_N_N_D  parameter  specifies  the
path  of  the  perl  script  that is to be loaded at process
startup  time.  A  sample  version  is  included   in   sam-
ples/startup_innd.pl which will be installed in the location
you define here.

     The ___P_A_T_H___P_E_R_L___F_I_L_T_E_R___I_N_N_D parameter specifies the path
of  the  perl  script  that  is to be loaded upon command by
ctlinnd. See the ctlinnd.8 manpage  for  more  details  (the
``filter'' and ``reload'' commands). A sample is included in
samples/filter_innd.pl which will be installed in the  loca-
tion defined by this parameter.

     The  ___P_A_T_H___P_E_R_L___F_I_L_T_E_R___N_N_R_P_D  parameter  specifies  the
path of the perl script that is  to  be  loaded  at  process
startup  time.  A sample version is included in samples/fil-
ter_nnrpd.pl which will be installed  in  the  location  you
define here.


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













                    Northern Winter 1997





                            -21-


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























                    Northern Winter 1997





                            -22-


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
























                    Northern Winter 1997





                            -23-


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



















                    Northern Winter 1997





                            -24-


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





























                    Northern Winter 1997





                            -25-


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
















                    Northern Winter 1997





                            -26-


     -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



                    Northern Winter 1997





                            -27-


_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.




                    Northern Winter 1997





                            -28-


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

     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



                    Northern Winter 1997





                            -29-


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



                    Northern Winter 1997





                            -30-


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.

_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 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.

_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



                    Northern Winter 1997





                            -31-


               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..  NNnnrrppdd

     _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
following programs:

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





                    Northern Winter 1997





                            -32-


_a_c_t_s_y_n_c        A  program  to  synchronize  active file with
               remote site.

_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.  This is a transition aide.

_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_b_a_t_c_h      A program to send  articles  with  ``XBATCH''
               NNTP command extension.

_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.

     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
is indexed by the Message-ID, and the DBZ  package  provides
fast retrieval from it.




                    Northern Winter 1997





                            -33-


_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.

     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



                    Northern Winter 1997





                            -34-


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 with root
privileges, the build and most of the installation does  not
have  to  be  done  as  root -- only the installation of the
inndstart executable requires root  priviledges,  as  it  is
installed as owned by root and setuid.  The _$_i_n_n_/_m_a_k_e_d_i_r_s_._s_h
script creates all the necessary directories  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 permissions (the  ``fire-
wall'' 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
directory into the right place.  A ``make update'' can  only



                    Northern Winter 1997





                            -35-


be done in the top-level directory or in the _s_i_t_e directory.
The former  only  replaces  executables,  not  configuration
files.   When updating to a new INN release, you will proba-
bly 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  Make-
file  also  has other targets that you might find useful, so
the comments for  entries  like  ``most''  and  ``installed-
diff'', for example.

     The  next, and last, step is to build your INN 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 _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.pl      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
might want to review these scripts just to see what they do.



                    Northern Winter 1997





                            -36-


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       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.  It will become the standard log reporting mechanism
in a future release.  _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  --  it  is set to be run by default.
_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  --



                    Northern Winter 1997





                            -37-


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  than
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-
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



                    Northern Winter 1997





                            -38-


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.

     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.



                    Northern Winter 1997





                            -39-


     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 set _M_M_A_P___S_Y_N_C parameter to ``DO.''

     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,  you  should  make sure to set
_S_E_T___S_O_C_K_O_P_T to ``DONT.''

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



                    Northern Winter 1997





                            -40-


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









































                    Northern Winter 1997





                            -41-


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  except
appendix II ``Converting from other News software''.

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.





                    Northern Winter 1997





                            -42-


_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.

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., ``group-admin@isc.org'', ``*'',



                    Northern Winter 1997





                            -43-


etc.), the control message is either acted upon,  mailed  to
the  news  administrator,  logged, or dropped.  For example,
messages from ``group-admin@isc.org'' 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.




















                    Northern Winter 1997





                            -44-


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 some people will be installing INN from scratch on top
of an older news system, this section should help you deter-
mine  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.






                    Northern Winter 1997





                            -45-


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
systems  because  the  right  solution  is to have a generic
interface that all readers can use.)

     For administrative convenience, however, you might wish
to have all your newsreaders use the INN library and 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  constantly  changing so these
instructions might be out of  date.   The  maintainers  have
agreed to officially support INN, however.

     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.



                    Northern Winter 1997





                            -46-


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:





                    Northern Winter 1997





                            -47-


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








                    Northern Winter 1997





                            -48-


     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.




















                    Northern Winter 1997





                            -49-


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



                    Northern Winter 1997





                            -50-


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





                    Northern Winter 1997





                            -51-


     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



                    Northern Winter 1997





                            -52-


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






























                    Northern Winter 1997





                            -53-


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 0000000001 \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



                    Northern Winter 1997





                            -54-


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.
Use this if needed.

     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!






                    Northern Winter 1997





                            -55-


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 client access routines, that let
the  current  threaded  newsreaders  use  a common, textual,
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
DIFFERENCES'' 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.









                    Northern Winter 1997





                            -56-


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.




                    Northern Winter 1997





                            -57-


     MIME  articles  can only be sent using _i_n_n_x_m_i_t.  Unless
the ``-M'' flag is used, no MIME conversions are  done.   If
the  flag  is  used,  the following happens: Articles with a
Content-Transfer-Encoding header of ``8bit''  or  ``binary''
are forwarded in ``quoted-printable'' format (the ``base64''
format is not supported yet).  All other articles -- in par-
ticular,  those  without  MIME headers, those of type ``mes-
sage'' or ``multipart,'' those with  Content-Transfer-Encod-
ing  header of ``7bit'' -- are forwarded without any change.
















































                    Northern Winter 1997


