chiark / gitweb /
use libinn logging where applicable
[inn-innduct.git] / 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>