README

   1 Welcome to INN 2.4!
   2
   3     This work is sponsored by Internet Systems Consortium.
   4
   5     Please see INSTALL for installation instructions, NEWS for what's
   6     changed from the previous release, and LICENSE for the copyright,
   7     license, and distribution terms.
   8
   9 What is INN?
  10
  11     INN (InterNetNews), originally written by Rich Salz, is an extremely
  12     flexible and configurable Usenet / netnews news server.  For a complete
  13     description of the protocols behind Usenet and netnews, see RFC 1036 and
  14     RFC 977 (or their replacements).  In brief, netnews is a set of
  15     protocols for exchanging messages between a decentralized network of
  16     news servers.  News articles are organized into newsgroups, which are
  17     themselves organized into hierarchies.  Each individual news server
  18     stores locally all articles it has received for a given newsgroup,
  19     making access to stored articles extremely fast.  Netnews does not
  20     require any central server; instead, each news server passes along
  21     articles it receives to all of the news servers it peers with, those
  22     servers pass the articles along to their peers, and so on, resulting in
  23     "flood fill" propagation of news articles.
  24
  25     A news server performs three basic functions:  it accepts articles from
  26     other servers and stores them on disk, sends articles it has received
  27     out to other servers, and offers stored news articles to readers on
  28     demand.  It additionally has to perform some periodic maintenance tasks,
  29     such as deleting older articles to make room for new ones.
  30
  31     Originally, a news server would just store all of the news articles it
  32     had received in a file system.  Users could then read news by reading
  33     the article files on disk (or more commonly using news reading software
  34     that did this efficiently).  These days, news servers are almost always
  35     stand-alone systems and news reading is supported via network
  36     connections.  A user who wants to read a newsgroup opens that newsgroup
  37     in their newsreader software, which opens a network connection to the
  38     news server and sends requests for articles and related information.
  39     The protocol that a newsreader uses to talk to a news server and that a
  40     news server uses to talk to another news server over TCP/IP is called
  41     NNTP (Network News Transport Protocol).
  42
  43     INN supports accepting articles via either NNTP connections or via UUCP.
  44     innd, the heart of INN, handles NNTP feeding connections directly; UUCP
  45     newsfeeds use rnews (included in INN) to hand articles off to innd.
  46     Other parts of INN handle feeding articles out to other news servers,
  47     most commonly innfeed (for real-time outgoing feeds) or nntpsend and
  48     innxmit (used to send batches of news created by innd to a remote site
  49     via TCP/IP).  INN can also handle outgoing UUCP feeds.
  50
  51     The part of INN that handles connections from newsreaders is nnrpd.
  52
  53     Also included in INN are a wide variety of supporting programs to handle
  54     periodic maintenance and recovery from crashes, process special control
  55     messages, maintain the list of active newsgroups, and generate and
  56     record a staggering variety of statistics and summary information on the
  57     usage and performance of the server.
  58
  59     INN also supports an extremely powerful filtering system that allows the
  60     server administrator to reject unwanted articles (such as spam and other
  61     abuses of Usenet).
  62
  63     INN is free software, supported by Internet Systems Consortium and
  64     volunteers around the world.  See "Supporting the INN Effort" below.
  65
  66 Prerequisites
  67
  68     Compiling INN requires an ANSI C compiler (gcc is recommended).  INN was
  69     originally written in K&R C, but supporting pre-ANSI compilers has
  70     become enough of a headache that a lot of the newer parts of INN will no
  71     longer compile with a non-ANSI compiler.  gcc itself will compile with
  72     most vendor non-ANSI compilers, however, so if you're stuck with one,
  73     installing gcc is highly recommended.  Not only will it let you build
  74     INN, it will make installing lots of other software much easier.  You
  75     may also need GNU make (particularly if your system make is
  76     BSD-derived), although most SysV make programs should work fine.
  77     Compiling INN also currently requires a yacc implementation (bison will
  78     do fine).
  79
  80     INN uses GNU autoconf to probe the capabilities of your system, and
  81     therefore should compile on nearly any Unix system.  It does, however,
  82     make extensive use of mmap(), which can cause problems on some older
  83     operating systems.  See INSTALL for a list of systems it is known to
  84     work on.  If you encounter problems compiling or running INN, or if you
  85     successfully run INN on a platform that isn't listed in INSTALL, please
  86     let us know (see "Reporting Bugs" below).
  87
  88     Perl 5.003 or later is required to build INN.  Perl 5.004 is required if
  89     you want the embedded Perl filter support (which is highly recommended;
  90     some excellent spam filters have been written for INN).  Since all
  91     versions of Perl previous to 5.004 are buggy (including security
  92     problems) and have fewer features, installing Perl 5.004 or later is
  93     recommended.
  94
  95     If you want to enable PGP verification of control messages (highly
  96     recommended), you will need to have a PGP implementation installed.  See
  97     INSTALL for more details.
  98
  99 Getting Started
 100
 101     A news server can be a fairly complicated piece of software to set up
 102     just because of the wide variety of pieces that have to be configured
 103     (who is authorized to read from the server, what newsgroups it carries,
 104     and how the articles are stored on disk at a bare minimum, and if the
 105     server isn't completely stand-alone -- and very few servers are -- both
 106     incoming and outgoing feeds have to be set up and tested).  Be prepared
 107     to take some time to understand what's going on and how all the pieces
 108     fit together.  If you have any specific suggestions for documentation,
 109     or comments about things that are unclear, please send them to the INN
 110     maintainers (see "Reporting Bugs" below).
 111
 112     See INSTALL for step-by-step instructions for setting up and configuring
 113     a news server.
 114
 115     INN also comes with a very complete set of man pages; there is a man
 116     page for every configuration file and program that comes with INN.  (If
 117     you find one that doesn't have a man page, that's a bug.  Please do
 118     report it.)  When trying to figure out some specific problem, reading
 119     the man pages for all of the configuration files involved is a very good
 120     start.
 121
 122 Reporting Bugs
 123
 124     We're interested in all bug reports.  Not just on the programs, but on
 125     the documentation too.  Please send *all* such reports to
 126
 127         inn-bugs@isc.org
 128
 129     (patches are certainly welcome, see below).  Even if you post to Usenet,
 130     please CC the above address.  All other INN mail should go to
 131
 132         inn@isc.org
 133
 134     (please do *not* send bug reports to this address).
 135
 136     If you have general "how do I do this" questions or problems configuring
 137     your server that you don't believe are due to a bug in INN, you should
 138     post them to news.software.nntp.  A lot of experienced INN users,
 139     including several of the INN maintainers, read that newsgroup regularly.
 140     Please don't send general questions to the above addresses; those
 141     addresses are specifically for INN, and the INN maintainers usually
 142     won't have time to answer general questions.
 143
 144 Contributing Code
 145
 146     If you have a patch or a utility that you'd like to be considered for
 147     inclusion into INN, please mail it to
 148
 149         inn-patches@isc.org
 150
 151     in the body of the message (not as an attachment), or put it on a
 152     webpage and send a link.  Patches included with a bug report as
 153     described above should follow the same procedure, but need not be sent
 154     to both addresses (either will do).
 155
 156     Have fun!
 157
 158 Mailing Lists
 159
 160     There are various INN-related mailing lists you can join or send
 161     messages to if you like.  Some of them you must be a member of before
 162     you can send mail to them (thank the spammers for that policy), and one
 163     of them is read-only (no postings allowed).
 164
 165     inn-announce@isc.org    Where announcements about INN are set (only
 166                             maintainers may post).
 167
 168     inn-workers@isc.org     Discussion of INN development (postings by
 169                             members only).
 170
 171     inn-patches@isc.org     Where to send patches for consideration for
 172                             inclusion into INN (open posting).
 173
 174     inn-committers@isc.org  CVS commit messages for INN are sent to this
 175                             list (only the automated messages are sent here,
 176                             no regular posting).
 177
 178     inn-bugs@isc.org        Where to send bug reports (open posting).  If
 179                             you're an INN expert and have the time to help
 180                             out other users, we encourage you to join this
 181                             mailing list to answer questions.  (You may also
 182                             want to read the newsgroup news.software.nntp,
 183                             which gets a lot of INN-related questions.)
 184
 185     To join these lists, send a subscription request to the "-request"
 186     address.  The addresses for the above lists are:
 187
 188        inn-announce-request@isc.org
 189        inn-workers-request@isc.org
 190        inn-patches-request@isc.org
 191        inn-committers-request@isc.org
 192        inn-bugs-request@isc.org
 193
 194 Who's Responsible / Who to Thank
 195
 196     See CONTRIBUTORS for a long list of past contributors as well as people
 197     from the inn-workers mailing list who have dedicated a lot of time and
 198     effort to getting this new version together.  They deserve a big round
 199     of applause.  They've certainly got our thanks.
 200
 201     This product includes software developed by UUNET Technologies, Inc. and
 202     by the University of California, Berkeley and its contributors.
 203
 204     Last, but certainly not least, Rich Salz, the original author of INN
 205     deserves a lion's share of the credit for writing INN in the first place
 206     and making it the most popular news server software on the planet (no
 207     NNTP yet to the moon, but we plan to be there first).
 208
 209 Related Packages
 210
 211     INN users may also be interested in the following software packages that
 212     work with INN or are based on it.  Please note that none of this
 213     software is developed or maintained by ISC; we don't support it and
 214     generally can't answer questions about it.
 215
 216     CleanFeed
 217         URL: <http://www.bofh.it/~md/cleanfeed/>
 218
 219         CleanFeed is an extremely powerful spam filter, probably the most
 220         widely used spam filter on Usenet currently.  It catches excessive
 221         multiposting and a host of other things, and is highly configurable.
 222         Note that it requires that INN be built with Perl support (the
 223         --with-perl option to configure).
 224
 225     GUP (Group Update Program)
 226         URL: <ftp://ftp.debian.org/debian/pool/main/g/gup/>
 227
 228         GUP provides a way for your peers to update their newsfeeds entries
 229         as they want without having to ask you to edit the configuration
 230         file all the time.  It's useful when feeding peers who take limited
 231         and very specific feeds that change periodically.
 232
 233     inflow
 234         URL: <http://www.switch.ch/netnews/wg/netnews-wg.html>
 235
 236         inflow generates graphs of news flow statistics in real time from
 237         INN's logs (things like articles accepted per peer, volume accepted
 238         per peer, and the like).
 239
 240     News-Portal
 241         URL: <http://floh.gartenhaus.net/newsportal/>
 242
 243         A PHP-based web news reader that works as a front-end to a regular
 244         news server such as INN and lets people read and post without
 245         learning a news reader.
 246
 247     PersonalINN
 248         URL: <http://www.ritual.org/summer/pinn/>
 249
 250         PersonalINN is a version of INN modified for personal use and with a
 251         friendly GUI built on top of it.  It is available for NeXTSTEP or
 252         OPENSTEP only, unfortunately.
 253
 254     suck
 255         URL: <http://home.comcast.net/~bobyetman/index.html>
 256
 257         suck is a separate package for downloading a news feed via a reading
 258         connection (rather than via a direct NNTP or UUCP feed) and sending
 259         outgoing local posts via POST.  It's intended primarily for personal
 260         or small-organization news servers who get their news via an ISP and
 261         are too small to warrant setting up a regular news feed.
 262
 263     newsx
 264         URL: <http://www.kvaleberg.com/newsx.html>
 265
 266         Serving the same purpose as suck, newsx is a separate package for
 267         downloading a news feed via a reading connectino and sending
 268         outgoing local posts via POST.  Some people find suck easier to
 269         configure and use, and some people find newsx easier.  If you have
 270         problems with one, try the other.
 271
 272 Supporting the INN Effort
 273
 274     Note that INN is supported by Internet Systems Consortium, and although
 275     it is free for use and redistribution and incorporation into vendor
 276     products and export and anything else you can think of, it costs money
 277     to produce.  That money comes from ISPs, hardware and software vendors,
 278     companies who make extensive use of the software, and generally
 279     kind-hearted folk such as yourself.
 280
 281     Internet Systems Consortium has also commissioned a DHCP server
 282     implementation and handles the official support/release of BIND.  You
 283     can learn more about the ISC's goals and accomplishments from the web
 284     page at <http://www.isc.org/>.
 285
 286                                             Russ Allbery
 287                                             Katsuhiro Kondou
 288                                             <inn@isc.org>