chiark / gitweb /
debugging for thing that crashed
[innduct.git] / 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>