doc/pod/readme.pod

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