








                  Installing InterNetNews


                         Rich $alz

                  Open Software Foundation
                    11 Cambridge Center
                    Cambridge, MA  02142

        _O_r_g_a_n_i_z_a_t_i_o_n _g_i_v_e_n _f_o_r _i_d_e_n_t_i_f_i_c_a_t_i_o_n _o_n_l_y;
    _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 <_r_s_a_l_z@_u_u_n_e_t._u_u._n_e_t>


                          _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
     references  to documentation for these topics, and
     the last appendix  gives  a  Usenet  overview  for
     novices.

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

          This is revision 1.13, dated 1993/03/19.



_1.  _T_h_i_n_g_s _Y_o_u _S_h_o_u_l_d _K_n_o_w _B_e_f_o_r_e _Y_o_u _D_o _A_n_y_t_h_i_n_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>.

_________________________
|- UNIX is a registered trademark of  Unix  Systems  La-
boratories.




                    February 14, 1992





                           - 2 -


     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.  Both RFCs are  currently  being
revised.   The  1036  revision  is most likely going to be a
``tightening-up''; since INN already has a strict  interpre-
tation  of  the  RFC, this revision will probably not affect
InterNetNews very much.  The  977  revision  is  adding  new
features  and facilities, and while INN will not provide all
of them, they will have some impact.

     InterNetNews does things differently  from  other  news
software.  The most common Usenet systems for UNIX are B2.11
and C News.  Both of them require a separate NNTP  implemen-
tation.   The  one everyone uses is called ``NNTP.'' Because
this is confusing (they don't  call  _s_e_n_d_m_a_i_l  ``SMTP''),  I
will  refer  to  it as the ``reference implementation.'' You
generally do not need to know  anything  about  these  other
systems,  but  if you are curious, the official sites are as
follows:

        Package      Host                  Directory
        C News       ftp.cs.toronto.edu    pub/c-news
        B2.11        ftp.uu.net            news/bnews-2.11
        nntp         lib.tmc.edu           public

You might  find  the  files  _d_o_c/_b_i_b_l_i_o,  _d_o_c/_p_r_o_b_l_e_m_s,  and
_d_o_c/_r_f_c_e_r_r_a_t_a in the C News distribution worthwhile reading.
The first is a bibliography, the second  discusses  known  C
News  porting  problems (see the DBZ sections in particular,
and ignore most of the  shell  comments),  while  the  third
lists some technical and philosophical errors in RFC 1036.

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

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



                    February 14, 1992





                           - 3 -


is  also  greatly  appreciated.   The  beta-test  sites gave
invaluable feedback.

_2.  _I_f _Y_o_u _A_r_e _I_m_p_a_t_i_e_n_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 install

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

_3.  _D_i_s_t_r_i_b_u_t_i_o_n _R_o_a_d_m_a_p

     The INN sources are divided into the  following  direc-
tories:

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

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

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

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

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

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

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

     The distribution also includes these directories:

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

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

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




                    February 14, 1992





                           - 4 -


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

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

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

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

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

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

_m_a_k_e_d_i_r_s._s_h    A script to build INN's directories.  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.

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

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

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

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

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

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

_4.  _B_u_i_l_d_i_n_g _t_h_e _S_y_s_t_e_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.




                    February 14, 1992





                           - 5 -


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

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

_4._1.  _B_u_i_l_d_i_n_g _s_u_b_s_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
variable.  If you want to use the C News script, then do the
following:

        cd $inn/config
        make sh


     The other choice is to use the C version of _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



                    February 14, 1992





                           - 6 -


If you get any compilation errors, you will have to edit the
file  _c_o_n_f_i_g/_s_u_b_s_t._c.   If you are using an early version of
AFS, you will have edit the file to  enable  the  USE_RENAME
macro.  If you have to make any other changes, please let me
know.

     Since _s_u_b_s_t changes source files,  you  might  want  to
make  a  backup copy of all the files that will be modified.
You can do this by typing  ``make  backup''  in  the  _c_o_n_f_i_g
directory.   This will create a local tar file that contains
all the files that will be modified into it.   Doing  ``make
restore'' will unpacks the tar file.  (Since _s_u_b_s_t makes its
changes safely, this step is optional.)

_4._2.  _E_d_i_t_i_n_g _c_o_n_f_i_g._d_a_t_a

     Once you have _s_u_b_s_t working, the next step is to set up
your  configuration parameters.  This is the hardest part of
installing INN.  _D_o_n'_t _p_a_n_i_c!  There are many  configuration
parameters,  but it should be very easy for you to determine
the answer for most of them.  To do this,  you  should  copy
_c_o_n_f_i_g/_c_o_n_f_i_g._d_i_s_t,     the    distribution    master,    to
_c_o_n_f_i_g/_c_o_n_f_i_g._d_a_t_a, your local copy.  INN is distributed  to
compile and run under SunOS4.1 (without using <unistd.h> and
other POSIX facilities) 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

You should have a copy of _c_o_n_f_i_g._d_a_t_a nearby as you read the
next few sections.  It is probably a good idea to write down
your changes on paper before you edit the file.

     The format of the file is very strict.  A line starting
with a poundsign is a comment line.  All other lines must be
in this format:

        parameter <_o_n_e-_o_r-_m_o_r_e-_t_a_b_s> value

If there is no ``value'' the ``<one-or-more-tabs>'' is still
required.  Do not put quote marks around the values - if you



                    February 14, 1992





                           - 7 -


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._2._1.  _M_a_k_e _c_o_n_f_i_g _p_a_r_a_m_e_t_e_r_s

     This section is used primarily to identify the path  to
your  C  compiler,  and what extra libraries or command-line
switches are needed.  For example, you could put  _g_c_c  -_W_a_l_l
on  the _C_C line.  If you need extra -_I flags put them on the
_D_E_F_S line.  INN uses the _r_e_g_i_s_t_e_r declaration a great  deal.
If  your  compiler is very good, you might want to add -_D_r_e_-
_g_i_s_t_e_r= to the _D_E_F_S line  so  that  INN's  declarations  are
ignored.

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

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

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

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

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

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

     Unfortunately, on some systems _l_i_n_t is all but useless,
so  complain to your vendor and take the output with a grain
of   salt.    You   might   get    some    warnings    about
``struct _DDHANDLE''  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 prototype 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



                    February 14, 1992





                           - 8 -


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._2._2.  _L_o_g_g_i_n_g _l_e_v_e_l_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
categories above are each directed into separate files.  See
_d_o_c/_n_e_w_s_l_o_g._5,  _d_o_c/_n_e_w_s_l_o_g._8,  and  _s_y_s_l_o_g/_s_y_s_l_o_g._c_o_n_f  for
details.  Logging is also described in more detail later.

_4._2._3.  _O_w_n_e_r_s_h_i_p_s _a_n_d _f_i_l_e _m_o_d_e_s

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

     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.




                    February 14, 1992





                           - 9 -


     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._2._4.  _C _l_i_b_r_a_r_y _d_i_f_f_e_r_e_n_c_e_s

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

     The _S_I_Z_E__T parameter is the datatype  of  the  ``size''
parameters  in  subroutine calls like _m_e_m_c_h_r and _f_r_e_a_d.  The
_L_O_C_K__S_T_Y_L_E parameter specifies how  file-locking  should  be
done.   _I_n_n_x_m_i_t is the only program that locks files; if you
use the provided scripts, this isn't even necessary, so  you
can set this to ``NONE'' if you have any compile problems.

     The _D_I_R__S_T_Y_L_E parameter specifies what is  returned  by
your   _r_e_a_d_d_i_r(3)   routine.    This   will   be   either  a
``struct direct'' or a ``struct dirent''; set the  parameter
to ``DIRECT'' or ``DIRENT'' as appropriate.

     If  you  do   not   have   UNIX-domain   sockets,   set
_H_A_V_E__U_N_I_X__D_O_M_A_I_N to ``DONT.'' This means that INN will use a
named pipe for the communication between _i_n_n_d  and  _c_t_l_i_n_n_d.
It  also  means that there will be no local ``private'' port
for _r_n_e_w_s to  use;  this  should  not  cause  any  problems,
although it makes it easier for anyone to use _r_n_e_w_s and post
fake news articles.  (You might also have to modify the _s_y_s_-
_l_o_g  routines;  see  the  end  of the file _s_y_s_l_o_g/_R_E_A_D_M_E for
details on this.)

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



                    February 14, 1992





                           - 10 -


/_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._2._5.  _C _l_i_b_r_a_r_y _o_m_i_s_s_i_o_n_s

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

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

        memchr         strchr         getopt
        memcmp         strrchr        mkfifo
        memcpy         strspn         strerror
        memset         strtok


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

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

     Pyramid  machines  running  OSx  have  fast   assembly-
language 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._2._6.  _M_i_s_c_e_l_l_a_n_e_o_u_s _c_o_n_f_i_g _d_a_t_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



                    February 14, 1992





                           - 11 -


Sender header match those of the original poster.)  In  gen-
eral,  however, you can leave this section pretty much alone
until you have some experience running  INN.   Nevertheless,
here  are  some  comments on some of the more useful parame-
ters.

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

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

     If _I_P_A_D_D_R__L_O_G is set to ``DO'' then the news  log  will
report  the  IP  address of hosts that send articles, rather
then what they put in the Path line.  This can be useful  if
you  run  _i_n_n_d  with  the ``-a'' flag.  (If you do this, you
might want to pick up  ``hf.tar.Z''  via  anonymous  FTP  to
ee.lbl.gov; it is a filter that turns IP addresses into host
names.)

     The  _x_x_x__T_I_M_E_O_U_T  parameters  control  various   timers
within INN; you might want to change some of these depending
on your system load.

_4._2._7.  _P_a_t_h_s _t_o _c_o_m_m_o_n _p_r_o_g_r_a_m_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



                    February 14, 1992





                           - 12 -


``/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
specified  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
multiple  links  to  the  same  file, you will have to do it
yourself after INN is installed.   If  you  have  additional
scripts  and  programs that you use to maintain your system,
you can put them in whatever directory you want.   You  will
probably  need  to add __P_A_T_H__N_E_W_S_B_I_N to the PATH of any such
scripts.

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

     The daily maintenance script, _n_e_w_s._d_a_i_l_y calls _s_c_a_n_l_o_g_s
to  rotate  and  trim  log files, as well as generating sum-
maries using _e_g_r_e_p and _a_w_k.  On some systems the  log  files
are too big for these programs so you might have to complain
to your vendor  and  install  the  versions  from  the  Free
Software  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._2._8.  _P_a_t_h_s _r_e_l_a_t_e_d _t_o _t_h_e _s_p_o_o_l _d_i_r_e_c_t_o_r_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.



                    February 14, 1992





                           - 13 -


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._2._9.  _E_x_e_c_u_t_i_o_n _p_a_t_h_s _f_o_r _i_n_n_d _a_n_d _r_n_e_w_s

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

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

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

_4._2._1_0.  _S_o_c_k_e_t_s _c_r_e_a_t_e_d _b_y _i_n_n_d _o_r _c_l_i_e_n_t_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._2._1_1.  _L_o_g _a_n_d _c_o_n_f_i_g _f_i_l_e_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''



                    February 14, 1992





                           - 14 -


with ``/var/newsbin''

     There are two  files  that  contain  access  passwords,
__P_A_T_H__N_N_T_P_P_A_S_S  and  __P_A_T_H__N_N_R_P_A_C_C_E_S_S.  The default location
for these files is in /_u_s_r/_l_o_c_a_l/_e_t_c, so  that  it  is  gen-
erally safe to export /_u_s_r/_l_o_c_a_l/_n_e_w_s (read-only is probably
best).

     INN  programs  do  extensive  logging,  and  the  daily
maintenance   scripts   do  extensive  summary  reports  and
analysis of them.  It might take you some time to learn your
way  around  the  INN  logging  system; start by reading the
newslog manpages in the _d_o_c directory.

_4._2._1_2.  _I_n_n_w_a_t_c_h _c_o_n_f_i_g_u_r_a_t_i_o_n

     The INN server, _i_n_n_d, does not contain  any  checks  to
see if there is enough free space on the disk or if the sys-
tem load average is low enough to allow  article  reception.
There  are two reasons for this.  The first reason is philo-
sophical:  it is a mistake  to  bury  this  kind  of  policy
information  inside  a program.  For example, you don't want
to have to recompile the program just because you moved to a
different   filesystem.    (Yes,  this  could  be  partially
answered by moving the information  to  an  external  config
file,  but  any compiled rules are still likely to be incom-
plete.) The second reason is pragmatic:  there is  no  port-
able  way  to  get standard measurements for the information
needed.  For example, C News provides three  different  rou-
tines  to  get  the  filesystem statistics (with conditional
compilation) while the ``get  load  average''  file  in  IDA
sendmail has over 700 lines.

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

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

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

This is looking at the fourth field of the  second  line  to
get  the  amount  of freespace.  You will have to change the
``2'' and ``4'' here, and on other lines, as appropriate for
your  system.  (Changing the output of _d_f seems to be one of
the things vendors like to do most; it is not worth my  time



                    February 14, 1992





                           - 15 -


to have INN keep track of all of them.)

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

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

     The _I_N_N_W_A_T_C_H__x_x_x_S_P_A_C_E parameters  specify  the  minimum
amount  of  disk  space needed for each of INN's three major
filesystems.  The numbers are in ``local units,'' equivalent
to whatever your _d_f uses (512-byte units, 1K blocks, etc).

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

_4._3.  _T_y_p_i_c_a_l _c_o_n_f_i_g._d_a_t_a _c_h_a_n_g_e_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''.


        _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        FNCTL
        MISSING_MAN
        MISSING_SRC
        NEED_TIME         DO
        POINTER           void

     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 USE_UNION_WAIT _s_e_t _t_o ``_D_O_N_T''.





                    February 14, 1992





                           - 16 -



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


        _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
distributed with BSDI 0.9.4.1 enters an infinite  loop  pro-
cessing newgroup messages.
















                    February 14, 1992





                           - 17 -



        _H_P-_U_X8.0
        ABORTVAL          void
        ALARMVAL          unsigned int
        CLX_STYLE         FCNTL
        CTYPE             isXXXXX((c))
        DEFS              -I../include -DHPUX
        FDCOUNT_STYLE     SYSCONF
        FREEVAL           void
        GETPIDVAL         pid_t
        GID_T             gid_t
        HAVE_SETBUFFER    DONT
        HAVE_ST_BLKSIZE   DONT
        HAVE_TM_GMTOFF    DONT
        HAVE_UNISTD       DO
        HAVE_WAITPID      DO
        LINTFILTER        | sed -n -f ../sedf.sysv
        LINTFLAGS         -b -h $(DEFS)
        LINTLIBSTYLE      SYSV
        LOCK_STYLE        LOCKF
        LOG_INN_PROG      LOG_LOCAL7
        LOG_INN_SERVER    LOG_LOCAL7
        LSEEKVAL          off_t
        _PATH_MAILCMD     /usr/bin/mailx
        NOFILE_LIMIT      200
        PID_T             pid_t
        POINTER           void
        PROF
        QSORTVAL          void
        RANLIB            echo
        RES_STYLE         TIMES
        SIZE_T            size_t
        SLEEPVAL          unsigned int
        UID_T             uid_t
        USE_UNION_WAIT    DONT
        _EXITVAL          void

     You will probably also need  to  use  the  _b_d_f  command
instead of _d_f.


















                    February 14, 1992





                           - 18 -



        _S_G_IIndigo
        ABORTVAL          void
        ALARMVAL          uint
        ACT_STYLE         MMAP
        CFLAGS            $(DEFS) -g -w
        CLX_STYLE         FCNTL
        _EXITVAL          void
        FORK              fork
        FREEVAL           void
        GID_T             gid_t
        HAVE_ST_BLKSIZE   DONT
        HAVE_TM_GMTOFF    DONT
        HAVE_UNISTD       DO
        LDFLAGS
        LIBS              -lmld
        LINTFILTER        | sed -n -f ../sedf.sysv
        LINTFLAGS          $(DEFS)
        LINTLIBSTYLE      SYSV
        LSEEKVAL          off_t
        POINTER           void
        QSORTVAL          void
        RANLIB            echo
        SIZE_T            size_t
        SLEEPVAL          uint
        UID_T             uid_t
        _PATH_COMPRESS    /usr/bsd/compress

     Also, the _M_I_S_S_I_N_G__x_x_x parameters should be empty.




























                    February 14, 1992





                           - 19 -



        _S_o_l_a_r_i_s2.X/SunOS
        DEFS              -I../include -DSUNOS5
        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  DONT
        CLX_STYLE         FCNTL
        RES_STYLE         TIMES
        FDCOUNT_STYLE     SYSCONF
        ABORTVAL          void
        ALARMVAL          unsigned
        GETPIDVAL         pid_t
        SLEEPVAL          unsigned
        QSORTVAL          void
        LSEEKVAL          off_t
        FREEVAL           void
        _EXITVAL          void
        MISSING_SRC
        MISSING_OBJ
        PATH_COMPRESS     /bin/compress

     Make sure you use the C version of subst.















                    February 14, 1992





                           - 20 -



        _S_y_s_t_e_mV
        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_x4.x
        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.  Some  sites  have
reported  problems  with using the _s_y_s_l_o_g that INN includes.



                    February 14, 1992





                           - 21 -


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 direc-
tory on gatekeeper.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.  _O_t_h_e_r _S_o_u_r_c_e _P_r_e_p_a_r_a_t_i_o_n_s

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

_5._1.  _S_y_s_t_e_m_s _w_i_t_h _o_l_d _s_y_s_l_o_g_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 don'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._2.  _T_h_e _D_B_Z _p_a_c_k_a_g_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.)

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

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



                    February 14, 1992





                           - 22 -


then take it out.

_5._3.  _U_s_i_n_g _w_r_i_t_e_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.  _C_o_m_p_i_l_i_n_g _t_h_e _S_y_s_t_e_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  direc-
tories.

     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
new  _c_o_n_f_i_g._d_a_t_a  file.  You should then follow the steps in
the following sections.




                    February 14, 1992





                           - 23 -


_6._1.  _B_u_i_l_d_i_n_g _t_h_e _L_i_b_r_a_r_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._2.  _C_o_m_p_i_l_i_n_g _t_h_e _P_r_o_g_r_a_m_s

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





                    February 14, 1992





                           - 24 -


_6._2._1.  _T_h_e _F_r_o_n_t_e_n_d _P_r_o_g_r_a_m_s

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

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

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

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

     To build these programs, type the following:

        cd $inn/frontends
        make all


_6._2._2.  _I_n_n_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 open port.  It also sets up a secure
               execution environment.  It is a small program
               (about  100 lines) that is easily understood.
               You should use it because _i_n_n_d will run  fas-
               ter  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



                    February 14, 1992





                           - 25 -


               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._2._3.  _T_h_e _N_e_t_N_e_w_s _R_e_a_d_i_n_g _D_a_e_m_o_n

     _I_n_n_d implements a subset of the NNTP  protocol  -  only
those  commands  that are needed for peer sites to feed news
articles.  You must install _n_n_r_p_d to  allow  users  to  read
news.   If  a  connection comes in from a host that is not a
specified feed, then an _n_n_r_p_d process is spawned  to  handle
it.   (You  can debug _n_n_r_p_d by running it interactively; put
an entry for the host named ``stdin''  in  your  _n_n_r_p._a_c_c_e_s_s
file.)

     Build the newsreader server by doing the following:

        cd $inn/nnrpd
        make all

Note that if users on a peer machine  (one  that  feeds  you
news)  want to read news from your server, then you have two
choices.  You can use _n_n_t_p_d from the reference platform (See
Appendix  II)  and  make  sure  not to list the peer in your
_n_n_t_p._a_c_c_e_s_s file.  The other choice is to relink the reading
software  on  the other machine with the INN library so that
it uses the ``mode reader'' NNTP command extension.

_6._2._4.  _T_h_e _B_a_c_k_e_n_d _P_r_o_g_r_a_m_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.

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




                    February 14, 1992





                           - 26 -


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

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

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

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

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

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

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

     To build this set of programs, type the following:

        cd $inn/backends
        make all


_6._2._5.  _E_x_p_i_r_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.

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



                    February 14, 1992





                           - 27 -


               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._2._6.  _S_c_r_i_p_t _a_n_d _d_a_t_a _f_i_l_e_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
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



                    February 14, 1992





                           - 28 -


     See below for an explanation of each file.

_6._3.  _M_a_n_u_a_l _p_a_g_e_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-
references as you want.

_7.  _I_n_s_t_a_l_l_i_n_g _t_h_e _S_y_s_t_e_m

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

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

        cd $inn
        make update

This target does a ``make install'' in  all  program  direc-
tories.  It installs the programs and manpages, but does not
update or install any configuration files or scripts.   This
is  important:   in  any  directory (including the top-level
one), a ``make install'' will  install  everything  in  that
directory  into the right place.  A ``make update'' can only
be done in the top-level directory or in the _s_i_t_e directory,
and it only replaces scripts, not configuration files.  When
updating to a new INN release, you will probably want to  do
an  ``update''  first,  and then review the changed files by
doing ``make diff'' in the  _s_i_t_e  directory,  and  integrate
your  local  changes  as appropriate.  The Makefile also has
other targets that you might find useful,  so  the  comments
for  entries  like ``most'' and ``installed-diff', for exam-
ple.

     The next, and last, step is to build  your  INN  confi-
guration files and utility scripts.  If you have not already
done so, type the following:

        cd $inn/site
        make all




                    February 14, 1992





                           - 29 -


This will get copies of the scripts and files from the _b_a_c_k_-
_e_n_d_s  and  the  _s_a_m_p_l_e_s directories and run _s_u_b_s_t over them.
Whenever patches are issued, doing a _m_a_k_e in this  directory
will let you know what files have been updated, without des-
troying 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


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

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

_R_c._n_e_w_s starts the server.  _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.  Do not get bogged down in the details, just
read the comments.  They  are  documented  in  the  manpages
news.daily(8) newslog(5), and newslog(8).

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

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

They flush and lock the batch file for the specified site(s)
and  then  call  _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



                    February 14, 1992





                           - 30 -


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:

        ctlrun         makegroup
        inncheck       scanspool
        innwatch

_C_t_l_r_u_n reads all the  articles  filed  in  your  ``control''
newsgroup  and  calls the appropriate control message script
to parse them.  _I_n_n_c_h_e_c_k is a Perl script to check the  syn-
tax  and  permissions of an installed INN system.  _I_n_n_r_e_p_o_r_t
is an alternate way of summarizing the  server's  log  file.
It  is a Perl script.  _I_n_n_w_a_t_c_h is a shell script to monitor
the system and stop the server when you are running  low  on
disk   space  or  inodes;  it  could  be  run  out  of  your
__P_A_T_H__N_E_W_S_B_O_O_T script.  You might have to edit it to  under-
stand  your  _d_f  output format.  _M_a_k_e_g_r_o_u_p is a front-end to
_r_n_e_w_s that helps you write a control  message  to  create  a
newsgroup.   You should review this script because you might
have to change the way the output of  the  _d_a_t_e  command  is
parsed,  and  because  you  might  might  want to change the
default distribution.  _S_c_a_n_s_p_o_o_l is a Perl  script  to  make
sure  that  the  active  file and the contents of your spool
tree agree.

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

        make install

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

     There are now only  a  couple  more  things  to  check.
First,  make  sure  you  have  an  _a_c_t_i_v_e file and a _h_i_s_t_o_r_y



                    February 14, 1992





                           - 31 -


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.  _H_e_t_e_r_o_g_e_n_e_o_u_s _C_l_i_e_n_t _I_n_s_t_a_l_l_a_t_i_o_n_s

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

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

        cd $inn
        ./MakeInews sun3

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

     _R_n_e_w_s only has to be available on the machine where you
run  UUCP (and perhaps a mail-news gateway).  If this is not
the same machine as where _i_n_n_d is running, then  the  _M_a_k_e_R_-
_n_e_w_s  script can be used in the same manner as the _M_a_k_e_I_n_e_w_s
script.

_9.  _K_n_o_w_n _P_r_o_b_l_e_m_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



                    February 14, 1992





                           - 32 -


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.

     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



                    February 14, 1992





                           - 33 -


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  pro-
duct) you will have to set _A_C_T__S_T_Y_L_E to ``READ''.  If you do
not do this then the  active  file  will  not  get  updated.
Another  work-around  is  to insert an ``msync'' call in the
ICDwriteactive routine in _i_n_n_d/_i_c_d._c.  This is not supported
because I consider the 386BSD behavior to be buggy.

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

     I have been told that some older versions  of  the  SCO
_o_p_e_n_d_i_r  routine  have  file  descriptor  leaks.   The  most
noticeable symptom is probably that _i_n_n_d will die while try-
ing  to  renumber  the _a_c_t_i_v_e file.  You might want to use a
freely-redistributable ``dirent'' package such as  one  dis-
tributed by the Free Software Foundation.

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

     I have heard that Sony SVR4 systems have lots of  prob-
lems.  You must set _H_A_V_E__U_N_I_X__D_O_M_A_I_N to ``DONT''; sockets in
general seem to have problems, including kernel crashes  and
a blocked _i_n_n_d.

     If you use the GNU _s_e_d in the  __P_A_T_H__S_E_D  configuration
parameter,  make sure you get version 1.13; earlier versions
have a bug that breaks the _p_a_r_s_e_c_o_n_t_r_o_l scripts.   The  most
noticeable symptom is that all ``newgroup'' control messages
result in mail saying that they are unparseable.

     Some versions of the shell in  HP-UX  do  not  properly
parse  a  quoted  ``[''  when  it is in a pattern for a _c_a_s_e
statement.  The most noticeable symptom is  that  _n_e_w_s._d_a_i_l_y
does  not properly expire articles if _i_n_n_w_a_t_c_h has throttled
the server.  Contact HP and get a fix for SR # 5003-009811.

     On some versions of AIX on the RS/6000,  using  memory-
mapping  can eat up all the page space or crash the machine.
This will  be  noticeable  if  you  have  _A_C_T__S_T_Y_L_E  set  to
``MMAP''  and/or have ``-DMMAP'' in _D_B_Z_C_F_L_A_G_S.  Ask your IBM



                    February 14, 1992





                           - 34 -


representative for the ``U413090'' PTF and prerequisites  to
apply it; it is believed that this will fix it.























































                    February 14, 1992





                           - 35 -


_A_p_p_e_n_d_i_x _I:  _D_i_f_f_e_r_e_n_c_e_s _f_r_o_m _o_t_h_e_r _N_e_w_s _s_o_f_t_w_a_r_e

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

     Users will generally only notice is that INN is faster;
it  should  be 100% compatible with the other systems at the
user level.  If you had particular problems that aren't men-
tioned  here,  please let me know.  Note, however, that this
is _n_o_t a tutorial on how to set up a new INN system, or con-
vert older software to it; no such document exists.

_1.  _C_o_n_f_i_g_u_r_a_t_i_o_n _F_i_l_e_s

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

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

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

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

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

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

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

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



                    February 14, 1992





                           - 36 -


_2.  _N_e_w_s_g_r_o_u_p_s, _A_c_t_i_v_e, _S_y_s, _a_n_d _N_e_w_s_f_e_e_d_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__J_U_N_K 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.  _C_o_n_t_r_o_l _M_e_s_s_a_g_e_s

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



                    February 14, 1992





                           - 37 -


news.announce.newgroups) are honored.

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

     The _c_t_l_i_n_n_d program is what really directs  the  server
to  create  or  remove  newsgroups.  This results in a semi-
recursive process:   the  control  message  arrives,  and  a
script  is invoked to process the message.  If approved, the
script invokes _c_t_l_i_n_n_d to send a message back to the  server
telling it to create or remove the group.

_4.  _L_o_c_k_i_n_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  ``flush-
logs''  and  ``flush'' commands.  See the _d_o_c/_c_t_l_i_n_n_d._8 man-
page; examples of their use can be found in various  scripts
in the _s_a_m_p_l_e_s directory.






















                    February 14, 1992





                           - 38 -


_A_p_p_e_n_d_i_x _I_I:  _C_o_n_v_e_r_t_i_n_g _f_r_o_m _o_t_h_e_r _N_e_w_s _s_o_f_t_w_a_r_e

     INN is a complete news transport and expiration system.
Since  few  people will be installing INN from scratch, this
section should help you determine what you can ``throw out''
from  your  earlier news setups.  It is also compatible with
much of the existing news software,  so  you  can  create  a
mixed environment if you want to, and if you are careful.

_1.  _C _N_e_w_s _E_x_p_i_r_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.  _S_t_a_n_d_a_r_d _N_N_T_P _d_a_e_m_o_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.

_3.  _N_N_T_P-_b_a_s_e_d _n_e_w_s_r_e_a_d_e_r_s

     If  you  already  have  your   NNTP-using   newsreaders



                    February 14, 1992





                           - 39 -


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  news-
readers.   (You  can enable the _t_r_n ``XTHREADS'' by modifing
_n_n_r_p_d/_n_n_r_p_d._h;    change    the    ``DONT_DO_XTHREAD''    to
``DO_DO_XTHREAD''  and  verify the other macros in that sec-
tion.  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 confi-
guration 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.  _R_e_m_o_t_e _r_n

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

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

     There are two ways to build _r_n so that it uses the  INN
library.   If you don't have the NNTP distribution installed
you will have to use the first way.

     The first way is to apply a patch to the latest _r_n _C_o_n_-
_f_i_g_u_r_e  script  and then execute it and rebuild the program.
To do this, type the following:

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

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

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



                    February 14, 1992





                           - 40 -


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
Makefile to remove the ``clientlib'' file  from  the  source
and  object  file  lists.  This can probably be done by com-
menting 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.  _R_e_m_o_v_i_n_g _t_h_e _O_t_h_e_r _S_t_u_f_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 all 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  sure 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 direc-
tories.  The following files are compatible with C News  and
B2.11 News, and should be _k_e_p_t:

        active         active.times

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

        history
        history.dir
        history.pag


     _R_n does not have to be modified so leave this directory
alone (or copy it back if you moved your original):

        /usr/local/lib/rn

If you set up _r_n to use the INN library, remove this file:

        /usr/local/lib/rn/server


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





                    February 14, 1992





                           - 41 -



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

Also remove the following directories and everything  within
them:

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


     The transmission facility is completely replaced.   You
may  keep your current feed subsystem if you want to, but it
will require some changes to make sure that  batchfiles  are
properly  flushed;  see  the  _s_e_n_d-_x_x_x scripts for examples.
Remove these files and programs:

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

Remove the following directory and everything within it:

        /usr/lib/news/bin/batch

You can continue to use _n_n_t_p_l_i_n_k, _n_e_w_s_x_d, and the like, sub-
ject to the caveat just mentioned.

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

        /usr/lib/news/explist

Remove the following directories and everything within them:

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

If you do not remove the _e_x_p_i_r_e directory, you will probably
have  problems  installing  INN's _e_x_p_i_r_e, which is a program
that often has the same name as the C News directory.

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







                    February 14, 1992





                           - 42 -



        canonhdr       newshostname
        ctime          newslock
        dbz            queuelen
        getabsdate     sizeof
        getdate        spacefor
        gngp

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

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

        mailname       sys
        mailpaths      whoami
        organization

If you have other software that uses them (except _s_y_s),  you
can  keep them.  The following will be rebuilt (or overwrit-
ten) by _i_n_n_d and _s_c_a_n_l_o_g_s so you should remove them:

        errlog         log


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

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


     Any other files and directories can  probably  also  be
discarded.



















                    February 14, 1992





                           - 43 -


_A_p_p_e_n_d_i_x _I_I_I:  _S_e_t_t_i_n_g _u_p _d_i_f_f_e_r_e_n_t _f_e_e_d_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.  _I_h_a_v_e/_s_e_n_d_m_e _f_e_e_d

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

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

     Accepting an ihave/sendme feed  is  easy.   Suppose  an
``ihave''  message  is  received  from  a site named remote.
When _i_n_n_d processes the message it will invoke the appropri-
ate  control script, /_u_s_r/_l_o_c_a_l/_n_e_w_s/_b_i_n/_c_o_n_t_r_o_l/_i_h_a_v_e.  The
script will filter the body using  _g_r_e_p_h_i_s_t_o_r_y,  creating  a
list  of Message-ID's not found in the _h_i_s_t_o_r_y database.  It
uses this output to  create  a  ``sendme''  control  article
which  is posted to the ``to.remote'' newsgroup using _i_n_e_w_s.
This article will then be queued and sent to remote  in  the
normal  way.   The  remote  site  will then send the desired
articles back.

     Providing an ihave/sendme feed is a  bit  more  compli-
cated.  First, you must create two entries in your _n_e_w_s_f_e_e_d_s
file.  The first should be named remote.ihave.  Make this  a
``Tf,Wm'' feed that contains the remote's subscription list.
This  entry  results  in  a  a  file  that  accumulates  the
Message-ID's  of  all  articles that remote might want.  The
other entry should  be  named  remote.   This  should  be  a
``Tf,Wn''  feed  that  only  subscribes to the ``to.remote''
newsgroup.  (Actually, if you feed some groups as a standard
feed,  you can put them on the remote entry, rather then the
remote.ihave entry.)

     The next step is to have the ``ihave'' control messages
sent out.  To do this, review the _s_e_n_d-_i_h_a_v_e script and make
sure it is invoked as needed  (usually  out  of  _c_r_o_n).   It
splits  the  batchfile from the remote.ihave _n_e_w_s_f_e_e_d_s entry



                    February 14, 1992





                           - 44 -


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
filename  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.  _F_e_e_d_i_n_g _a _l_a_r_g_e _n_u_m_b_e_r _o_f _s_i_t_e_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.)

     In order for the funnel output to be useful, it usually



                    February 14, 1992





                           - 45 -


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
system-call intensive.  It can be used to  provide  behavior
(and  performance!) that is similar to B2.11 _i_n_e_w_s.  It can,
however, 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  ack-
nowledgement back.

_3.  _M_a_s_t_e_r/_s_l_a_v_e _r_e_p_l_i_c_a_t_i_o_n

     INN supports a simple model of  replicated  news  data-
bases:  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.

     Since the _n_n_r_p_d on the slave host will usually add  its
name  to the Path header, you should add ``Ap'' to the _f_l_a_g_s
field of the slave's entry on the master.

     Once the slave has been set up it is necessary to  have



                    February 14, 1992





                           - 46 -


the  master  feed it.  This is done by using an extension to
the NNTP protocol.  This extension, the ``XREPLIC'' command,
is  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.







































                    February 14, 1992





                           - 47 -


_A_p_p_e_n_d_i_x _I_V:  _F_i_r_s_t-_t_i_m_e _U_s_e_n_e_t _o_r _N_N_T_P _I_n_s_t_a_l_l_a_t_i_o_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 gen-
eral  problems,  try  posting  to   ``news.sysadmin'';   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'' 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 com-
mercial 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, not 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.

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



                    February 14, 1992





                           - 48 -


else.

     When someone at your site writes an article, _i_n_n_d  will
record  the  filename  in  the  batch file for your upstream
site.  Either _s_e_n_d-_n_n_t_p or _n_n_t_p_s_e_n_d will flush and lock  the
batchfile,  and  then  call _i_n_n_x_m_i_t to connect to the remote
site and send these queued articles out.   You  should  edit
the  script to list the sites you want, and arrange for _c_r_o_n
to run this script on a regular basis.  You can  run  it  as
often as you like, but 10 minutes is a common interval.

     If you want to feed any sites via UUCP, then  you  will
have  to  set up file feed entries for them in the _n_e_w_s_f_e_e_d_s
file, and arrange to have _c_r_o_n run the _s_e_n_d-_u_u_c_p  script  as
desired.   (UUCP  batches  are typically only done every few
hours.)

     Once you have news flowing in and out  of  the  system,
you  will have to expire it or your disks will fill up.  The
_n_e_w_s._d_a_i_l_y script should be run by _c_r_o_n in the middle of the
night.   It  will  summarize  that day's log files, and then
call _e_x_p_i_r_e to purge old news.  You might also want to  have
_c_r_o_n  run  _r_n_e_w_s  hourly  to  pick  up  any stalled batches.
Finally, if your feeds change IP address, you might  want  a
daily  job  that  does  ``ctlinnd  reload  hosts.nntp "flush
cache"''.  This is because _i_n_n_d does not currently  time-out
DNS entries.

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

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

     Welcome to Usenet, and have fun!

















                    February 14, 1992





                           - 49 -


_A_p_p_e_n_d_i_x _V:  _N_e_w_s _o_v_e_r_v_i_e_w _d_a_t_a_b_a_s_e

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

     In  late  1992,  Geoff  Collyer   <geoff@world.std.com>
released  the  _n_o_v,  or  ``news  overview,''  package.  This
included database tools and,  and  client  access  routines,
that let the current threaded newsreaders use a common, tex-
tual, database.  An overview database  typically  adds  adds
about  7-9%  to  your storage requirements.  By default, the
overview files are stored in the spool  directory;  you  can
change  this to use an alternate tree that mirrors the spool
hierarchy by changing the __P_A_T_H__O_V_E_R_V_I_E_W_D_I_R parameter.

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

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

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

        expireover -a -s

You will also need to expire the overview data.  The easiest
way  to  do this is to add the ``expireover'' keyword to the
_c_r_o_n job that runs _n_e_w_s._d_a_i_l_y.

     The _n_n_r_p_d server includes  two  command  extensions  to
access  the  database; they are documented in the ``protocol
extensions'' part of _d_o_c/_n_n_r_p_d._8.  INN does not include  any
client  code  or modifications to any newsreaders to use the
overview data.  Most maintainers have agreed to support  the
overview  database,  including the INN extensions for remote
access.  You can find prototype  versions  of  many  readers
(work  done  by  Geoff)  on  world.std.com  in the directory
src/news; look for files named _r_e_a_d_e_r.dist.tar.Z.









                    February 14, 1992





                           - 50 -


_A_p_p_e_n_d_i_x _V_I:  _L_i_m_i_t_e_d _M_I_M_E _S_u_p_p_o_r_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, all articles posted will
get  MIME  headers added.  Existing MIME headers will not be
modified, but missing  ones  will  be  added.   The  default
values to add to _i_n_n._c_o_n_f are these:

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

An internationalized site might want to use these values:

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

It is possible to use these values because  INN  provides  a
clean eight-bit data path.  Unless you make special arrange-
ments with your peers, however, you must transmit  seven-bit
data.   Doing  this  will  require  special transmit agents.
Note that _n_n_r_p_d is not a Mime-compatible reader.   You  must
have  software  to extract the data and present it appropri-
ately.

     If you configure your site to use seven-bit data,  then
you  must  also make sure that none of your software creates
eight-bit articles.  _N_n_r_p_d does not  verify  this.   If  you
configure  your site to use eight-bit data, then ASCII works
fine, but remember that in quoted-printable long  lines  are
cut  and  that  the  equal  sign  (``='') is quoted; this is
really bad for source code postings, among others.

     The character set can also cause problems.  If you  use
``iso-8859-1'' you must make sure that your posting software
uses this character set  (e.g.,  not  CP-437  under  MS-DOS)
because _n_n_r_p_d does not do any conversion.

     In general, be very cautious.




                    February 14, 1992





                           - 51 -


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















































                    February 14, 1992


