








                  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.

          This is revision 1.26, dated 1997/07/23.


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

     There  is  a new (as of June 1997) 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
-----------
|- UNIX is a registered trademark of X/Open Company
Ltd.



                    Northern Summer 1997





                             -2-


McDermott  and  John E.  Phillips. Published by Addison-Wes
ley. It has good INN 1.5.1 coverage.

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





                    Northern Summer 1997





                             -3-


     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.

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



                    Northern Summer 1997





                             -4-


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




                    Northern Summer 1997





                             -5-


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

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




                    Northern Summer 1997





                             -6-


     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:

     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.




                    Northern Summer 1997





                             -7-


     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

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




                    Northern Summer 1997





                             -8-


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.

     implementation in the ``newlog'' package in the contrib
directory.  Unpack  and build that according to the instruc
tions enclosed within, and then include ``-lnewlog'' on  the
_L_I_B_S  line (and possibly a ``-L/path/to/newlog/library/dir''
if the linker needs help finding the  library.  There  is  a
file  README.newlog  in the top INN directory that will give
some hints for some systems that have trouble building it.

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

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

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

     The  _l_i_b  directory also builds a _l_i_n_t library, so that
you can make sure the other programs are properly using  the
library  routines.   The  _L_I_N_T_L_I_B_S_T_Y_L_E  parameter  (used  in
_l_i_b_/_M_a_k_e_f_i_l_e and  _l_i_b_/_m_a_k_e_l_l_i_b_._s_h)  controls  how  the  _l_i_n_t
library is built.  If your _l_i_n_t understands the ``-C'' flag,
then set it to ``BSD''.  If you  need  the  ``-o''  flag  to
build  a  library,  then  set it to ``SYSV''.  If neither of
these work, you can set it to ``NONE''; this will just  cre
ate  an  empty file so that the other Makefiles don't break.
If you come up with a fourth alternative, let me know.



                    Northern Summer 1997





                             -9-


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



                    Northern Summer 1997





                            -10-


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





                    Northern Summer 1997





                            -11-


     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.

     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.




                    Northern Summer 1997





                            -12-


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



                    Northern Summer 1997





                            -13-


     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 _K_E_Y_W_O_R_D_S parameter controls where innd generates  a
``Keywords'' overview header. This can be used by some read
ers (like GNUs). It is however, a tremendous CPU hog, so  if
you  enable  it (it's disabled by default), may attention to
how much of an effect it's having on your  machine.  If  you
enable  it  here,  you'll  also need to enable the header in
_o_v_e_r_v_i_e_w_._f_m_t. See section 4 of  this  document  for  further
details.

     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



                    Northern Summer 1997





                            -14-


the default _/_e_t_c_/_r_c_._n_e_w_s and make the link yourself.

     The daily maintenance script, _n_e_w_s_._d_a_i_l_y calls _s_c_a_n_l_o_g_s
to  rotate  and  trim  log files, as well as generating sum
maries using _e_g_r_e_p and _a_w_k.  On some systems the  log  files
are too big for these programs so you might have to complain
to your vendor and install the versions from the Free  Soft
ware  Foundation.   The _s_c_a_n_l_o_g_s script has a short test you
can run to see if your _e_g_r_e_p will work.

44..22..88..  PPAATTHHSS RREELLAATTEEDD TTOO TTHHEE SSPPOOOOLL DDIIRREECCTTOORRYY

     By default, all news articles are stored in directories
under  _/_u_s_r_/_s_p_o_o_l_/_n_e_w_s.   Be careful if you pick a different
value -- many newsreaders know about this directory name.

     INN uses a trick (which I first saw  in  C  News)  that
lets  it  use this same directory to store its incoming news
(spooled by _r_n_e_w_s when _i_n_n_d is not available), and its  out
going  batch  files.  Since no newsgroup can ever have a dot
in its name, a directory like _o_u_t_._g_o_i_n_g can never be a news
group  name,  and  it  is safe to put the news batchfiles in
there.  This is used by the ___P_A_T_H___S_P_O_O_L_N_E_W_S  parameter,  and
the ___P_A_T_H___B_A_T_C_H_D_I_R parameter.

     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.





                    Northern Summer 1997





                            -15-


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

44..22..1100..  SSOOCCKKEETTSS CCRREEAATTEEDD BBYY IINNNNDD OORR CCLLIIEENNTTSS

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

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

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



                    Northern Summer 1997





                            -16-


answered  by  moving  the  information to an external config
file, but any compiled rules are still likely to  be  incom
plete.)   The  second  reason  is  pragmatic:   there  is no
portable way to get standard measurements for  the  informa
tion  needed.   For example, C News provides three different
routines to get the filesystem statistics (with  conditional
compilation)  while  the  ``get  load  average'' file in IDA
sendmail has over 700 lines.

     Rather than get tangled up in such a mess of  #ifdef's,
INN  uses  an  external  program (shell script) that invokes
_c_t_l_i_n_n_d to stop and start the server as necessary.  The pro
gram,   _i_n_n_w_a_t_c_h,   reads  the  control  file  _i_n_n_w_a_t_c_h_._c_t_l.
_I_n_n_w_a_t_c_h is documented in _d_o_c_/_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.







                    Northern Summer 1997





                            -17-


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.

     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



                    Northern Summer 1997





                            -18-


this user to act as an introducer and certify other people's
public keys to you?" answer that you would not.

     After  you  have  added the appropriate key to your key
ring, you need to tell the news  software  to  validate  the
control  messages  received. As implemented, the system will
perform the requested action if the message can be authenti
cated and it will mail the message to the news system admin
istrator 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.





                    Northern Summer 1997





                            -19-


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

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

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

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

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



                    Northern Summer 1997





                            -20-


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 sup
ported 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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 Summer 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_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  --
will be difficult), you should type the following:





                    Northern Summer 1997





                            -37-


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



                    Northern Summer 1997





                            -38-


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


