chiark / gitweb /
some todos
[inn-innduct.git] / INSTALL
1 Welcome to INN 2.4!
2
3     Please read this document thoroughly before trying to install INN. 
4     You'll be glad you did.
5
6     If you are upgrading from a major release of INN prior to 2.3, it is
7     recommended that you make copies of your old configuration files and use
8     them as guides for doing a clean installation and configuration of 2.4. 
9     Many config files have changed, some have been added, and some have been
10     removed.  You'll find it much easier to start with a fresh install than
11     to try to update your old installation.  This is particularly true if
12     you're upgrading from a version of INN prior to 2.0.
13
14     If you are upgrading from INN 2.3 or later, you may be able to just
15     update the binaries, scripts, and man pages by running:
16
17         make update
18
19     after building INN and then comparing the new sample configuration files
20     with your current ones to see if anything has changed.  If you take this
21     route, the old binaries, scripts, and man pages will be saved with an
22     extension of ".OLD" so that you can easily back out.  Be sure to
23     configure INN with the same options that you used previously if you take
24     this approach (in particular, INN compiled with --enable-largefiles
25     can't read the data structures written by INN compiled without that
26     flag, and vice versa).  If you don't remember what options you used but
27     you have your old build tree, look at the comments at the beginning of
28     config.status.
29
30     If you made ckpasswd setuid root so that you could use system passwords,
31     you'll have to do that again after make update.  (It's much better to
32     use PAM instead if you can.)
33
34     If you use "make update" to upgrade from INN 2.3, also look at the new
35     sample configuration files in samples to see if there are new options of
36     interest to you.  In particular, control.ctl has been updated and
37     inn.conf has various new options.
38
39     For more information about recent changes, see NEWS.
40
41 Supported Systems
42
43     As much as possible, INN is written in portable C and should work on any
44     Unix platform.  It does, however, make extensive use of mmap(2) and
45     certain other constructs that may be poorly or incompletely implemented,
46     particularly on very old operating systems.
47
48     INN has been confirmed to work on the following operating systems:
49
50         AIX 4.3
51         FreeBSD 2.2.x and up
52         HP-UX 10.20 and up
53         Linux 2.x (tested with libc 5.4, glibc 2.0 and up)
54         Mac OS X 10.2 and up
55         NetBSD 1.6 and up
56         OpenBSD 2.8 and up
57         SCO 5.0.4 (tested with gcc 2.8.1, cc)
58         Solaris 2.5.x and up
59         UnixWare 7.1
60         UX/4800 R11 and up
61
62     If you have gotten INN working on an operating system other than the
63     ones listed above, please let us know at <inn-bugs@isc.org>.
64
65 Before You Begin
66
67     INN requires several other packages be installed in order to be fully
68     functional (or in some cases, to work at all):
69
70     * In order to build INN, you will need a C compiler that understands
71       ANSI C.  If you are trying to install INN on an operating system that
72       doesn't have an ANSI C compiler (such as SunOS), installing gcc is
73       recommended.  You can get it from <ftp://ftp.gnu.org/gnu/gcc/> or its
74       mirrors.  INN is tested with gcc more thoroughly than with any other
75       compiler, so even if you have another compiler available, you may wish
76       to use gcc instead.
77
78     * Currently, in order to build INN, you will need an implementation of
79       yacc.  GNU bison (from <ftp://ftp.gnu.org/gnu/bison/> or its mirrors)
80       will work fine.  We hope to remove this requirement in the future.
81
82     * INN requires at least Perl 5.004_03 to build and to run several
83       subsystems.  INN is tested primarily with newer versions of Perl, so
84       it's generally recommended that you install the latest stable
85       distribution of Perl before compiling INN.  For instructions on
86       obtaining and installing Perl, see
87       <http://www.perl.com/pub/language/info/software.html>.  Note that you
88       may need to use the same compiler and options (particularly largefile
89       support) for Perl and INN.
90
91       If you're using a version of Perl prior to 5.6.0, you may need to make
92       sure that the Perl versions of your system header files have been
93       generated in order for Sys::Syslog to work properly (used by various
94       utility programs, including controlchan).  To do this, run the
95       following two commands:
96
97           # cd /usr/include
98           # h2ph * sys/*
99
100       An even better approach is to install Perl 5.6.1 or later, which have
101       a fixed version of Sys::Syslog that doesn't require this (as well as
102       many other improvements over earlier versions of Perl).
103
104     * The INN Makefiles use the syntax "include FILE", rather than the
105       syntax expected by some BSDish systems of ".include <FILE>".  If your
106       system expects the latter syntax, the recommended solution is to
107       install GNU make from <ftp://ftp.gnu.org/make/>.  You may have GNU
108       make already installed as gmake, in which case using gmake rather than
109       make to build INN should be sufficient.
110
111     * If you want to enable support for authenticated control messages (this
112       is not required, but is highly recommended for systems carrying public
113       Usenet hierarchies) then you will need to install some version of PGP.
114       The recommended version is GnuPG, since it's actively developed,
115       supports OpenPGP, is freely available and free to use for any purpose
116       (in the US and elsewhere), and (as of version 1.0.4 at least) supports
117       the RSA signatures used by most current control message senders.
118
119       Alternately, you can install PGP from <http://www.pgp.com/> or one of
120       the international versions of it.  Be warned, however, that the
121       licensing restrictions on PGP inside the United States are extremely
122       unclear; it's possible that if you are installing INN for a company in
123       the U.S., even if the news server is not part of the business of that
124       company, you would need to purchase a commercial license for PGP.  For
125       an educational or non-profit organization, this shouldn't be a
126       problem.
127
128     * If you want to use either the Python embedded hooks, you'll need to
129       have a suitable versions of Python installed.  See doc/hook-python for
130       more information.
131
132     * Many of INN's optional features require other packages (primarily
133       libraries) be installed.  If you wish to use any of these optional
134       features, you will need to install those packages first.  Here is a
135       table of configure options enabling optional features and the software
136       and versions you'll need:
137
138           --with-perl         Perl 5.004_03 or higher, 5.6.1+ recommended
139           --with-python       Python 1.5.2 or higher
140           --with-berkeleydb   BerkeleyDB 2.0 or higher, 4.2+ recommended
141           --with-openssl      OpenSSL 0.9.6 or higher
142           --with-sasl         SASL 2.x or higher
143           --with-kerberos     MIT Kerberos v5 1.2.x or higher
144
145       If any of these libraries (other than Perl or Python) are built shared
146       and installed in locations where your system doesn't search for shared
147       libraries by default, you may need to encode the paths to those shared
148       libraries in the INN binaries.  For more information on shared library
149       paths, see:
150
151           <http://www.eyrie.org/~eagle/notes/rpath.html>
152
153       For most systems, setting the environment variable LD_RUN_PATH to a
154       colon-separated list of additional directories in which to look for
155       shared libraries before building INN will be sufficient.
156
157 Unpacking the Distribution
158
159     Released versions of INN are available from ftp.isc.org in /isc/inn. 
160     New major releases will be announed on <inn-announce@isc.org> (see
161     README) when they're made.
162
163     If you want more a more cutting-edge version, you can obtain current
164     snapshots from from ftp.isc.org in directory /isc/inn/snapshots.  These
165     are snapshots of the INN CVS tree taken daily; there are two snapshots
166     made each night (one of the current development branch, and one of the
167     stable branch consisting of bug fixes to the previous major release). 
168     They are stored in date format; in other words the snapshots from April
169     6th, 2000, would be named inn-CURRENT-20000406.tar.gz and
170     inn-STABLE-20000406.tar.gz.  Choose the newest file of whichever branch
171     you prefer.  (Note that the downloading, configuring, and compiling
172     steps can be done while logged in as any user.)
173
174     The distribution is in gzip compressed tar archive format.  To extract
175     it, execute:
176
177         gunzip -c <inn-src-file> | tar -xf -
178
179     Extracting the source distribution will create a directory named
180     inn-<version> or inn-<BRANCH>-<date> where the source resides.
181
182 Installing INN
183
184     Before beginning installation, you should make sure that there is a user
185     on your system named "news", and that this user's primary group is set
186     to a group called "news".  You can change these with the
187     --with-news-user and --with-news-group options to configure (see below).
188     The home directory of this user should be set to the directory under
189     which you wish to install INN (/usr/local/news is the default and is a
190     good choice).  INN will install itself as this user and group.  You can
191     change these if you want, but these are the defaults and it's easier to
192     stick with them on a new installation.
193
194     By default, INN sends reports to the user "usenet".  This account isn't
195     used for any other purposes.  You can change it with the
196     --with-news-master option to configure (see below).
197
198     WARNING: By default, INN installs various configuration files as
199     group-writeable, and in general INN is not hardened from a security
200     standpoint against an attack by someone who is already in the news
201     group.  In general, you should consider membership in the news group as
202     equivalent to access to the news account.  You should not rely on being
203     able to keep anyone with access to the news GID from converting that
204     into access to the news UID.  The recommended configuration is to have
205     the only member of the group "news" be the user "news".
206
207     Installing INN so that all of its files are under a single directory
208     tree, rather than scattering binaries, libraries, and man pages
209     throughout the file system, is strongly recommended.  It helps keep
210     everything involved in the operation of INN together as a unit and will
211     make the installation instructions easier to follow.
212
213     As a side note, whenever doing anything with a running news server,
214     first log in as this user.  That way, you can ensure that all files
215     created by any commands you run are created with the right ownership to
216     be readable by the server.  Particularly avoid doing anything in the
217     news spool itself as root, and make sure you fix the ownership of any
218     created files if you have to.  INN doesn't like files in the news spool
219     owned by a user other than the news user.  However, since certain
220     binaries need to be setuid root, indiscriminate use of "chown news" is
221     not the solution.  (If you don't like to log in to system accounts,
222     careful use of "chmod g+s" on directories and a umask of 002 or 007 may
223     suffice.)
224
225     INN uses GNU autoconf and a generated configure script to make
226     configuration rather painless.  Unless you have a rather abnormal setup,
227     configure should be able to completely configure INN for your system. 
228     If you want to change the defaults, you can invoke the configure script
229     with one or more command line options.  Type:
230
231         ./configure --help
232
233     for a full list of supported options.  Some of the most commonly used
234     options are:
235
236     --prefix=PATH
237         Sets the installation prefix for INN.  The default is
238         /usr/local/news.  All of INN's programs and support files will be
239         installed under this directory.  This should match the home
240         directory of your news user (it will make installation and
241         maintenance easier).  It is not recommended to set this to /usr; if
242         you decide to do that anyway, make sure to point INN's temporary
243         directory at a directory that isn't world-writeable (see
244         --with-tmp-dir below).
245
246     --with-db-dir=PATH
247         Sets the prefix for INN database files.  The default is PREFIX/db,
248         where PREFIX is /usr/local/news unless overridden with the option
249         above.  The history and active files will be stored in this
250         directory, and writes to those files are an appreciable percentage
251         of INN's disk activity.  The history file can also be quite large
252         (requiring up to 2 GB or more during nightly expire), so this is a
253         common portion of INN to move to a different file system.
254
255     --with-spool-dir=PATH
256         Sets the prefix for the news spool (when using any storage method
257         other than CNFS) and the overview spool.  The default is
258         PREFIX/spool.  This is another common portion of INN to move to a
259         different file system (often /news).
260
261     --with-tmp-dir=PATH
262         Sets the directory in which INN will create temporary files.  This
263         should under no circumstances be the same as the system temporary
264         directory or otherwise be set to a world-writeable directory, since
265         INN doesn't take care to avoid symlink attacks and other security
266         problems possible with a world-writeable directory.  This directory
267         should be reserved for the exclusive use of INN and only writeable
268         by the news user.  Usage is generally light, so this is unlikely to
269         need a separate partition.
270
271         It's also possible to set the paths for most other sections of the
272         INN installation independently; see "./configure --help" and look
273         for the --with-*-dir=PATH options.
274
275     --enable-largefiles
276         Enables large file support.  This is not enabled by default, even on
277         platforms that support it, because it changes the format of INN's
278         on-disk databases (making it difficult to upgrade an earlier INN
279         installation) and can significantly increase the size of some of the
280         history database files.  Large file support is not necessary unless
281         your history database is so large that it exceeds 2 GB or you want
282         to use CNFS buffers larger than 2 GB.
283
284         The history, tradindexed and buffindexed overview, CNFS, and timecaf
285         databases written by an INN built with this option are incompatible
286         with those written by an INN without this option.
287
288     --enable-tagged-hash
289         Use tagged hash table for the history database.  The tagged hash
290         format uses much less memory but is somewhat slower.  This option is
291         recommended if you have less than 256 MB of RAM on your news server.
292         If you install INN without tagged hash (the default) and expire
293         takes an excessive amount of time, you should make sure the RAM in
294         your system satisfies the following formula:
295
296             ram > 10 * tablesize
297
298                   ram:  Amount of system RAM (in bytes)
299             tablesize:  3rd field on the 1st line of history.dir (bytes)
300
301         If you don't have at least that much RAM, try rebuilding INN with
302         tagged hash enabled.
303
304         NOTE: --enable-largefiles cannot be used with --enable-tagged-hash.
305
306     --with-perl
307         Enables support for embedded Perl, allowing you to install filter
308         scripts written in Perl.  Highly recommended, because many really
309         good spam filters are written in Perl.  See doc/hook-perl for all
310         the details.
311
312         Even if you do not use this option, INN still requires Perl as
313         mentioned above.
314
315     --with-python
316         Enables support for Python, allowing you to install filter and
317         authentication scripts written in Python.  You will need Python
318         1.5.2 or later installed on your system to enable this option.  See
319         doc/hook-python for all the details.  Note that there is an
320         incompatibility between INN and Python 2.0 when Python is compiled
321         with cycle garbage collection; this problem was reported fixed in
322         Python 2.1a1.
323
324     --with-innd-port=PORT
325         By default, inndstart(8) refuses to bind to any port under 1024
326         other than 119 and 433 for security reasons (to prevent attacks on
327         rsh(1)-based commands and replacing standard system daemons).  If
328         you want to run innd on a different port under 1024, you'll need to
329         tell configure what port you intend to use.  (You'll also still need
330         to set the port number in inn.conf or give it to inndstart on the
331         command line.)
332
333     --with-syslog-facility=FACILITY
334         Specifies the syslog facility that INN programs should log to.  The
335         default is LOG_NEWS unless configure detects that your system
336         doesn't understand that facility, in which case it uses LOG_LOCAL1. 
337         This flag overrides the automatic detection.  Be sure to specify a
338         facility not used by anything else on your system (one of LOG_LOCAL0
339         through LOG_LOCAL7, for example).
340
341     --enable-libtool
342         INN has optional support for libtool to generate shared versions of
343         INN's libraries.  This can significantly decrease the size of the
344         various binaries that come with a complete INN installation.  You
345         can also choose to use libtool even when only building static
346         libraries; a libtool build may be somewhat more portable on weird
347         systems.  libtool builds aren't the default because they take
348         somewhat longer.  See "./configure --help" for the various available
349         options related to libtool builds.
350
351         Please note that INN's shared library interface is not stable and
352         may change drastically in future releases.  For this reason, it's
353         also not properly versioned and won't be until some degree of
354         stability is guaranteed, and the relevant header files are not
355         installed.  Only INN should use INN's shared libraries, and you
356         should only use the shared libraries corresponding to the version of
357         INN that you're installing.
358
359         Also, when updating an existing version of INN, INN tries to save
360         backup copies of all files so that you can revert to the previous
361         installed version.  Unfortunately, when using shared libraries, this
362         confuses ldconfig on some systems (such as Linux) and the symbolic
363         links for the libraries may point to the .OLD versions.  If this
364         happens, you can either fix the links by hand or remove the .OLD
365         versions and re-run ldconfig.
366
367     --enable-uucp-rnews
368         If this option is given to configure, rnews will be installed setuid
369         news, owned by group uucp, and mode 4550.  This will allow the UUCP
370         subsystem to run rnews to process UUCP batches of news articles. 
371         Prior to INN 2.3, installing rnews setuid news was standard; since
372         most sites no longer use UUCP, it is no longer the default as of INN
373         2.3 and must be requested at configure time.  You probably don't
374         want to use this option unless your server accepts UUCP news
375         batches.
376
377     --enable-setgid-inews
378         If this option is given to configure, inews will be installed setgid
379         news and world-executable so that non-privileged users on the news
380         server machine can use inews to post articles locally (somewhat
381         faster than opening a new network connection).  For standalone news
382         servers, by far the most common configuration now, there's no need
383         to use this option; even if you have regular login accounts on your
384         news server, INN's inews can post fine via a network connection to
385         your running news server and doesn't need to use the local socket
386         (which is what setgid enables it to do).  Installing inews setgid
387         was the default prior to INN 2.3.
388
389     --with-berkeleydb=PATH
390         Enables support for Berkeley DB (2.x or 3.x), which means that it
391         will then be possible to use the ovdb overview method if you wish. 
392         Enabling this configure option doesn't mean you'll be required to
393         use ovdb, but it does require that Berkeley DB be installed on your
394         system (including the header files, not just the runtime libraries).
395         If a path is given, it sets the installed directory of Berkeley DB
396         (configure will search for it in some standard locations, but if you
397         have it installed elsewhere, you may need this option).
398
399     --with-openssl=PATH
400         Enables support for SSL for news reading, which means it will be
401         possible to have SSL or TLS encrypted NNTP connections between your
402         server and newsreaders.  This option requires OpenSSL be installed
403         on your system (including the header files, not just the runtime
404         libraries).  If a path is given, it sets the installed directory of
405         OpenSSL.  After compiling and installing INN with this option,
406         you'll still need to make a certificate and private key to use SSL. 
407         See below for details on how to do that.
408
409     --enable-ipv6
410         Enables support for IPv6 in innd, innfeed, nnrpd, and several of the
411         supporting programs.  This option should be considered developmental
412         at present.  For more information see doc/IPv6-info (and if you have
413         any particularly good or bad news to report, please let us know at
414         <inn-bugs@isc.org>).
415
416     For the most common installation, a standalone news server, a suggested
417     set of options is:
418
419         ./configure --with-perl
420
421     provided that you have the necessary version of Perl installed. 
422     (Compiling with an embedded Perl interpretor will allow you to use one
423     of the available excellent spam filters if you so choose.)
424
425     If the configure program runs successfully, then you are ready to build
426     the distribution.  From the root of the INN source tree, type:
427
428         make
429
430     At this point you can step away from the computer for a little while and
431     have a quick snack while INN compiles.  On a decently fast system it
432     should only take five or ten minutes at the most to build.
433
434     Once the build has completed successfully, you are ready to install INN
435     into its final home.  Type:
436
437         make install
438
439     You will need to run this command as root so that INN can create the
440     directories it needs, change ownerships (if you did not compile as the
441     news user) and install a couple of setuid wrapper programs needed to
442     raise resource limits and allow innd to bind to ports under 1024.  This
443     step will install INN under the install directory (/usr/local/news,
444     unless you specified something else to the configure script).
445
446     If you are configuring SSL support for newsreaders, you must make a
447     certificate and private key at least once.  Type:
448
449         make cert
450
451     as root in order to do this.
452
453     You are now ready for the really fun part:  configuring your copy of
454     INN!
455
456 Choosing an Article Storage Format
457
458     The first thing to decide is how INN should store articles on your
459     system.  There are four different methods for you to choose from, each
460     of which has its own advantages and disadvantages.  INN can support all
461     four at the same time, so you can store certain newsgroups in one method
462     and other newsgroups in another method.
463
464     The supported storage formats are:
465
466     tradspool
467         This is the storage method used by all versions of INN previous to
468         2.0.  Articles are stored as individual text files whose names are
469         the same as the article number.  The articles are divided up into
470         directories based on the newsgroup name.  For example, article 12345
471         in news.software.nntp would be stored as news/software/nntp/12345
472         relative to the root of the article spool.
473
474         Advantages:  Widely used and well-understood storage mechanism, can
475         read article spools written by older versions of INN, compatible
476         with all third-party INN add-ons, provides easy and direct access to
477         the articles stored on your server and makes writing programs that
478         fiddle with the news spool very easy, and gives you fine control
479         over article retention times.
480
481         Disadvantages:  Takes a very fast file system and I/O system to keep
482         up with current Usenet traffic volumes due to file system overhead. 
483         Groups with heavy traffic tend to create a bottleneck because of
484         inefficiencies in storing large numbers of article files in a single
485         directory.  Requires a nightly expire program to delete old articles
486         out of the news spool, a process that can slow down the server for
487         several hours or more.
488
489     timehash
490         Articles are stored as individual files as in tradspool, but are
491         divided into directories based on the arrival time to ensure that no
492         single directory contains so many files as to cause a bottleneck.
493
494         Advantages:  Heavy traffic groups do not cause bottlenecks, and fine
495         control of article retention time is still possible.
496
497         Disadvantages:  The ability to easily find all articles in a given
498         newsgroup and manually fiddle with the article spool is lost, and
499         INN still suffers from speed degredation due to file system overhead
500         (creating and deleting individual files is a slow operation).
501
502     timecaf
503         Similar to timehash, articles are stored by arrival time, but
504         instead of writing a separate file for each article, multiple
505         articles are put in the same file.
506
507         Advantages:  Roughly four times faster than timehash for article
508         writes, since much of the file system overhead is bypassed, while
509         still retaining the same fine control over article retention time.
510
511         Disadvantages:  Even worse than timehash, and similar to cnfs
512         (below), using this method means giving up all but the most careful
513         manually fiddling with your article spool.  As one of the newer and
514         least widely used storage types, timecaf has not been as thoroughly
515         tested as the other methods.
516
517     cnfs
518         CNFS stores articles sequentially in pre-configured buffer files. 
519         When the end of the buffer is reached, new articles are stored from
520         the beginning of the buffer, overwriting older articles.
521
522         Advantages:  Blazingly fast because no file creations or deletions
523         are necessary to store an article.  Unlike all other storage
524         methods, does not require manual article expiration; old articles
525         are deleted to make room for new ones when the buffers get too full.
526         Also, with CNFS your server will never throttle itself due to a full
527         spool disk, and groups are restricted to just the buffer files you
528         give them so that they can never use more than the amount of disk
529         space you allocate to them.
530
531         Disadvantages:  Article retention times are more difficult to
532         control because old articles are overwritten automatically.  Attacks
533         on Usenet, such as flooding or massive amounts of spam, can result
534         in wanted articles expiring much faster than you intended (with no
535         warning).
536
537     Some general recommendations:  If you are installing a transit news
538     server (one that just accepts news and sends it out again to other
539     servers and doesn't support any readers), use CNFS exclusively and don't
540     worry about any of the other storage methods.  Otherwise, put
541     high-volume groups and groups whose articles you don't need to keep
542     around very long (binaries groups, *.jobs*, news.lists.filters, etc.) in
543     CNFS buffers, and use timehash, timecaf, or tradspool (if you have a
544     fast I/O subsystem or need to be able to go through the spool manually)
545     for everything else.  You'll probably find it most convenient to keep
546     special hierarchies like local hierarchies and hierarchies that should
547     never expire in tradspool.
548
549     If your news server will be supporting readers, you'll also need to
550     choose an overview storage mechanism (by setting *ovmethod* in
551     inn.conf).  There are three overview mechanisms to choose from: 
552     tradindexed, buffindexed, and ovdb.  tradindexed is very fast for
553     readers, but it has to update two files for each incoming article and
554     can be quite slow to write.  buffindexed can keep up with a large feed
555     more easily, since it uses large buffers to store all overview
556     information, but it's somewhat slower for readers (although not as slow
557     as the unified overview in INN 2.2).  ovdb stores overview data in a
558     Berkeley DB database; it's fast and very robust, but requires more disk
559     space.  See the ovdb(5) man page for more information on it.
560
561     Note that ovdb has not been as widely tested as the other overview
562     mechanisms and should be considered experimental.  tradindexed is the
563     best tested and most widely used of the overview implementations.
564
565     If buffindexed is chosen, you will need to create the buffers for it to
566     use (very similar to creating CNFS buffers) and list the available
567     buffers in buffindexed.conf.  See buffindexed.conf(5) for more
568     information.
569
570 Configuring INN
571
572     All documentation from this point on assumes that you have set up the
573     news user on your system as suggested in "Installing INN" so that the
574     root of your INN installation is ~news/.  If you've moved things around
575     by using options with "configure", you'll need to adjust the
576     instructions to account for that.
577
578     All of INN's configuration files are located in ~news/etc.  Unless noted
579     otherwise, any files referred to below are in this directory.  When you
580     first install INN, a sample of each file (containing lots of comments)
581     is installed in ~news/etc; refer to these for concrete examples of
582     everything discussed in this section.
583
584     All of INN's configuration files, all of the programs that come with it,
585     and some of its library routines have documentation in the form of man
586     pages.  These man pages were installed in ~news/man as part of the INN
587     installation process and are the most complete reference to how INN
588     works.  You're strongly encouraged to refer to the man pages frequently
589     while configuring INN, and for quick reference afterwards.  Any detailed
590     questions about individual configuration files or the behavior of
591     specific programs should be answered in them.  You may want to add
592     ~news/man to your MANPATH environment variable; otherwise, you may have
593     to use a command like:
594
595         man -M ~news/man inn.conf
596
597     to see the inn.conf(5) man page (for example).
598
599     Before we begin, it is worth mentioning the wildmat pattern matching
600     syntax used in many configuration files.  These are simple wildcard
601     matches using the asterisk ("*") as the wildcard character, much like
602     the simple wildcard expansion used by Unix shells.
603
604     In many cases, wildmat patterns can be specified in a comma-separated
605     list to indicate a list of newsgroups.  When used in this fashion, each
606     pattern is checked in turn to see if it matches, and the last pattern in
607     the line that matches the group name is used.  Patterns beginning with
608     "!" mean to exclude groups matching that pattern.  For example:
609
610         *, !comp.*, comp.os.*
611
612     In this case, we're saying we match everything ("*"), except that we
613     don't match anything under comp ("!comp.*"), unless it is actually under
614     the comp.os hierarchy ("comp.os.*").  This is because non-comp groups
615     will match only the first pattern (so we want them), comp.os groups will
616     match all three patterns (so we want them too, because the third pattern
617     counts in this case), and all other comp groups will match the first and
618     second patterns and will be excluded by the second pattern.
619
620     Some uses of wildmat patterns also support "poison" patterns (patterns
621     starting with "@").  These patterns behave just like "!" patterns when
622     checked against a single newsgroup name.  Where they become special is
623     for articles crossposted to multiple newsgroups; normally, such an
624     article will be considered to match a pattern if any of the newsgroups
625     it is posted to matches the pattern.  If any newsgroup the article is
626     posted to matches an expression beginning with "@", however, that
627     article will not match the pattern even if other newsgroups to which it
628     was posted match other expressions.
629
630     See uwildmat(3) for full details on wildmat patterns.
631
632     In all INN configuration files, blank lines and lines beginning with a
633     "#" symbol are considered comments and are ignored.  Be careful, not all
634     files permit comments to begin in the middle of the line.
635
636   inn.conf
637
638     The first, and most important file is inn.conf.  This file is organized
639     as a series of parameter-value pairs, one per line.  The parameter is
640     first, followed by a colon and one or more whitespace characters, and
641     then the value itself.  For some parameters the value is a string or a
642     number; for others it is true or false.  (True values can be written as
643     "yes", "true", or "on", whichever you prefer.  Similarly, false values
644     can be written as "no", "false", or "off".)
645
646     inn.conf contains dozens of changeable parameters (see inn.conf(5) for
647     full details), but only a few really need to be edited during normal
648     operation:
649
650     allownewnews
651         If set to true then INN will support the NEWNEWS command for news
652         readers.  While this can be an expensive operation, its speed has
653         been improved considerably as of INN 2.3 and it's probably safe to
654         turn on without risking excessive server load.  The default is true.
655         (Note that the *access:* setting in readers.conf overrides this
656         value; see readers.conf(5) for more details.)
657
658     complaints
659         Used to set the value of the X-Complaints-To: header, which is added
660         to all articles posted locally.  The usual value would be something
661         like "abuse@example.com" or "postmaster@example.com".  If not
662         specified, the newsmaster email address will be used.
663
664     hiscachesize
665         The amount of memory (in kilobytes) to allocate for a cache of
666         recently used history file entries.  Setting this to 0 disables
667         history caching.  History caching can greatly increase the number of
668         articles per second that your server is capable of processing.  A
669         value of 256 is a good default choice.
670
671     logipaddr
672         If set to true (the default), INN will log the IP address (or
673         hostname, if the host is listed in incoming.conf with a hostname) of
674         the remote host from which it received an article.  If set to false,
675         the trailing Path: header entry is logged instead.  If you are using
676         controlchan (see below) and need to process ihave/sendme control
677         messages (this is very, very unlikely, so if you don't know what
678         this means, don't worry about it), make sure you set this to false,
679         since controlchan needs a site name, not an IP address.
680
681     organization
682         Set this to the name of your organization as you want it to appear
683         in the Organization: header of all articles posted locally and not
684         already containing that header.  This will be overridden by the
685         value of the ORGANIZATION environment variable (if it exists).  If
686         neither this parameter nor the environment variable or set, no
687         Organization: header will be added to posts which lack one.
688
689     pathhost
690         This is the name of your news server as you wish it to appear in the
691         Path: header of all postings which travel through your server (this
692         includes local posts and incoming posts that you forward out to
693         other sites).  If this parameter is unspecified, the fully-qualified
694         domain name (FQDN) of the machine will be used instead.  Please use
695         the FQDN of your server or an alias for your server unless you have
696         a very good reason not to; a future version of the news RFCs may
697         require this.
698
699     rlimitnofile
700         If set to a non-negative value (the default is -1), INN (both innd
701         and innfeed) will try to raise the maximum number of open file
702         descriptors to this value when it starts.  This may be needed if you
703         have lots of incoming and outgoing feeds.  Note that the maximum
704         value for this setting is very operating-system-dependent, and you
705         may have to reconfigure your system (possibly even recompile your
706         kernel) to increase it.  See "File Descriptor Limits" for complete
707         details.
708
709     There are tons of other possible settings; you may want to read through
710     inn.conf(5) to get a feel for your options.  Don't worry if you don't
711     understand the purpose of most of them right now.  Some of the settings
712     are only needed for very obscure things, and with more experience
713     running your news server the rest will make more sense.
714
715   newsfeeds
716
717     newsfeeds determines how incoming articles are redistributed to your
718     peers and to other INN processes.  newsfeeds is very versatile and
719     contains dozens of options; we will touch on just the basics here.  The
720     manpage contains more detailed information.
721
722     newsfeeds is organized as a series of feed entries.  Each feed entry is
723     composed of four fields separated by colons.  Entries may span multiple
724     lines by using a backslash ("\") to indicate that the next line is a
725     continuation of the current line.  (Note that comments don't interact
726     with backslashes in the way you might expect.  A commented-out line
727     ending in a backslash will still be considered continued on the next
728     line, possibly resulting in more commented out than you intended or
729     bizarre syntax errors.  In general, it's best to avoid commenting out
730     lines in the middle of continuation lines.)
731
732     The first field in an entry is the name of the feed.  It must be unique,
733     and for feeds to other news servers it is usually set to the actual
734     hostname of the remote server (this makes things easier).  The name can
735     optionally be followed by a slash and a comma-separated exclude list. 
736     If the feed name or any of the names in the exclude list appear in the
737     Path line of an article, then that article will not be forwarded to the
738     feed as it is assumed that it has passed through that site once already.
739     The exclude list is useful when a news server's hostname is not the same
740     as what it puts in the Path header of its articles, or when you don't
741     want a feed to receive articles from a certain source.
742
743     The second field specifies a set of desired newsgroups and distribution
744     lists, given as newsgroup-pattern/distribution-list.  The distribution
745     list is not described here; see newsfeeds(5) for information (it's not
746     used that frequently in practice).  The newsgroup pattern is a
747     wildmat-style pattern list as described above (supporting "@").
748
749     The third field is a comma-separated list of flags that determine both
750     the type of feed entry and sets certain parameters for the entry.  See
751     newsfeeds(5) for information on the flag settings; you can do a
752     surprising amount with them.  The three most common patterns, and the
753     ones mainly used for outgoing news feeds to other sites, are "Tf,Wnm"
754     (to write out a batch file of articles to be sent, suitable for
755     processing by nntpsend and innxmit), "Tm" (to send the article to a
756     funnel feed, used with innfeed), and "Tc,Wnm*" (to collect a funnel feed
757     and send it via a channel feed to an external program, used to send
758     articles to innfeed).
759
760     The fourth field is a multi-purpose parameter whose meaning depends on
761     the settings of the flags in the third field.  To get a feel for it
762     using the examples above, for file feeds ("Tf") it's the name of the
763     file to write, for funnel feeds ("Tm") it's the name of the feed entry
764     to funnel into, and for channel feeds ("Tc") it's the name of the
765     program to run and feed references to articles.
766
767     Now that you have a rough idea of the file layout, we'll begin to add
768     the actual feed entries.  First, we'll set up the special ME entry. 
769     This entry is required and serves two purposes:  the newsgroup pattern
770     specified here is prepended to the newsgroup list of all other feeds,
771     and the distribution pattern for this entry determines what
772     distributions (from the Distribution: header of incoming articles) are
773     accepted from remote sites by your server.  The example in the sample
774     newsfeeds file is a good starting point.  If you are going to create a
775     local hierarchy that should not be distributed off of your system, it
776     may be useful to exclude it from the default subscription pattern, but
777     default subscription patterns are somewhat difficult to use right so you
778     may want to just exclude it specifically from every feed instead.
779
780     The ME entry tends to confuse a lot of people, so this point is worth
781     repeating:  the newsgroup patterns set the default subscription for
782     *outgoing* feeds, and the distribution patterns set the acceptable
783     Distribution: header entries for *incoming* articles.  This is confusing
784     enough that it may change in later versions of INN.
785
786     There are two basic ways to feed articles to remote sites.  The most
787     common for large sites and particularly for transit news servers is
788     innfeed(8), which sends articles to remote sites in real time (the
789     article goes out to all peers that are supposed to receive it
790     immediately after your server accepts it).  For smaller sites,
791     particularly sites where the only outgoing messages will be locally
792     posted articles, it's more common to batch outgoing articles and send
793     them every ten minutes or so from cron using nntpsend(8) and innxmit(8).
794     Batching gives you more control and tends to be extremely stable and
795     reliable, but it's much slower and can't handle high volume very well.
796
797     Batching outgoing posts is easy to set up; for each peer, add an entry
798     to newsfeeds that looks like:
799
800         remote.example.com/news.example.com\
801             :<newsgroups>\
802             :Tf,Wnm:
803
804     where <newsgroups> is the wildmat pattern for the newsgroups that site
805     wants.  In this example, the actual name of the remote site is
806     "remote.example.com", but it puts "news.example.com" in the Path:
807     header.  If the remote site puts its actual hostname in the Path:
808     header, you won't need the "/news.example.com" part.
809
810     This entry will cause innd to write out a file in ~news/spool/outgoing
811     named remote.example.com and containing the Message-ID and storage token
812     of each message to send to that site.  (The storage token is INN's
813     internal pointer to where an article is stored; to retrieve an article
814     given its storage token, use sm(8)).  innxmit knows how to read files of
815     this format and send those articles to the remote site.  For information
816     on setting it up to run periodically, see "Setting Up the Cron Jobs"
817     below.  You will also need to set up a config file for nntpsend; see the
818     man page for nntpsend.ctl(5) for more information.
819
820     If instead you want to use innfeed to send outgoing messages
821     (recommended for sites with more than a couple of peers), you need some
822     slightly more complex magic.  You still set up a separate entry for each
823     of your peers, but rather than writing out batch files, they all
824     "funnel" into a special innfeed entry.  That special entry collects all
825     of the separate funnel feeds and sends the data through a special sort
826     of feed to an external program (innfeed in this case); this is a
827     "channel" feed.
828
829     First, the special channel feed entry for innfeed that will collect all
830     the funnel feeds:
831
832         innfeed!\
833             :!*\
834             :Tc,Wnm*:/usr/local/news/bin/startinnfeed -y
835
836     (adjust the path to startinnfeed(1) if you installed it elsewhere). 
837     Note that we don't feed this entry any articles directly (its newsgroup
838     pattern is "!*").  Note also that the name of this entry ends in an
839     exclamation point.  This is a standard convention for all special feeds;
840     since the delimiter for the Path: header is "!", no site name containing
841     that character can ever match the name of a real site.
842
843     Next, set up entries for each remote site to which you will be feeding
844     articles.  All of these entries should be of the form:
845
846         remote.example.com/news.example.com\
847             :<newsgroups>\
848             :Tm:innfeed!
849
850     specifying that they funnel into the "innfeed!" feed.  As in the
851     previous example for batching, "remote.example.com" is the actual name
852     of the remote peer, "news.example.com" is what it puts in the Path:
853     header (if different than the actual name of the server), and
854     <newsgroups> is the wildmat pattern of newsgroups to be sent.
855
856     As an alternative to NNTP, INN may also feed news out to an IMAP server,
857     by using imapfeed(8), which is almost identical to innfeed.  The
858     startinnfeed process can be told to start imapfeed instead of innfeed. 
859     The feed entry for this is as follows:
860
861         imapfeed!\
862             :!*\
863             :Tc,Wnm*,S16384:/usr/local/news/bin/startinnfeed imapfeed
864
865     And set up entries for each remote site like:
866
867         remote.example.com/news.example.com\
868             :<newsgroups>\
869             :Tm:imapfeed!
870
871     For more information on imapfeed, look at the innfeed/imap_connection.c.
872     For more information on IMAP in general, see RFC 2060.
873
874     Finally, there is a special entry for controlchan(8), which processes
875     newsgroup control messages, that should always be in newsfeeds unless
876     you never want to honor any control messages.  This entry should look
877     like:
878
879         controlchan!\
880             :!*,control,control.*,!control.cancel\
881             :Tc,Wnsm:/usr/local/news/bin/controlchan
882
883     (modified for the actual path to controlchan if you put it somewhere
884     else).  See "Processing Control Messages" for more details.
885
886     For those of you upgrading from earlier versions of INN, note that the
887     functionality of overchan(8) and crosspost is now incorporated into INN
888     and neither of those programs is necessary.  Unfortunately, crosspost
889     currently will not work even with the tradspool storage method.  You can
890     still use overchan if you make sure to set *useoverchan* to true in
891     inn.conf so that innd doesn't write overview data itself, but be
892     careful:  innd may accept articles faster than overchan can process the
893     data.
894
895   incoming.conf
896
897     incoming.conf file specifies which machines are permitted to connect to
898     your host and feed it articles.  Remote servers you peer with should be
899     listed here.  Connections from hosts not listed in this file will (if
900     you don't allow readers) be rejected or (if you allow readers) be handed
901     off to nnrpd and checked against the access restrictions in
902     readers.conf.
903
904     Start with the sample incoming.conf and, for each remote peer, add an
905     entry like:
906
907         peer remote.example.com { }
908
909     This uses the default parameters for that feed and allows incoming
910     connections from a machine named "remote.example.com".  If that peer
911     could be connecting from several different machines, instead use an
912     entry like:
913
914          peer remote.example.com {
915             hostname: "remote.example.com, news.example.com"
916          }
917
918     This will allow either "remote.example.com" or "news.example.com" to
919     feed articles to you.  (In general, you should add new peer lines for
920     each separate remote site you peer with, and list multiple host names
921     using the *hostname* key if one particular remote site uses multiple
922     servers.)
923
924     You can restrict the newsgroups a remote site is allowed to send you,
925     using the same sort of pattern that newsfeeds(5) uses.  For example, if
926     you want to prevent "example.com" hosts from sending you any articles in
927     the "local.*" hierarchy (even if they're crossposted to other groups),
928     change the above to:
929
930         peer remote.example.com {
931             patterns: "*, @local.*"
932             hostname: "remote.example.com, news.example.com"
933         }
934
935     Note, however, that restricting what a remote side can send you will
936     *not* reduce your incoming bandwidth usage.  The remote site will still
937     send you the entire article; INN will just reject it rather than saving
938     it to disk.  To reduce bandwidth, you have to contact your peers and ask
939     them not to send you the traffic you don't want.
940
941     There are various other things you can set, including the maximum number
942     of connections the remote host will be allowed.  See incoming.conf(5)
943     for all the details.
944
945     Note for those familiar with older versions of INN:  this file replaces
946     the old hosts.nntp configuration file.
947
948   cycbuff.conf
949
950     cycbuff.conf is only required if CNFS is used.  If you aren't using
951     CNFS, skip this section.
952
953     CNFS stores articles in logical objects called *metacycbuffs*.  Each
954     metacycbuff is in turn composed of one or more physical buffers called
955     *cycbuffs*.  As articles are written to the metacycbuff, each article is
956     written to the next cycbuff in the list in a round-robin fashion (unless
957     "sequential" mode is specified, in which case each cycbuff is filled
958     before moving on to the next).  This is so that you can distribute the
959     individual cycbuffs across multiple physical disks and balance the load
960     between them.
961
962     There are two ways to create your cycbuffs:
963
964     1.  Use a block device directly.  This will probably give you the most
965         speed since it avoids the file system overhead of large files, but
966         it requires your OS support mmap(2) on a block device.  Solaris
967         supports this, as do late Linux 2.4 kernels.  FreeBSD does not at
968         last report.  Also on many PC-based Unixes it is difficult to create
969         more than eight partitions, which may limit your options.
970
971     2.  Use a real file on a filesystem.  This will probably be a bit slower
972         than using a block device directly, but it should work on any Unix
973         system.
974
975     If you're having doubts, use option #2; it's easier to set up and should
976     work regardless of your operating system.
977
978     Now you need to decide on the sizes of your cycbuffs and metacycbuffs. 
979     You'll probably want to separate the heavy-traffic groups
980     ("alt.binaries.*" and maybe a few other things like "*.jobs*" and
981     "news.lists.filters") into their own metacycbuff so that they don't
982     overrun the server and push out articles on the more useful groups.  If
983     you have any local groups that you want to stay around for a while then
984     you should put them in their own metacycbuff as well, so that they don't
985     get pushed out by other traffic.  (Or you might store them in one of the
986     other storage methods, such as tradspool.)
987
988     For each metacycbuff, you now need to determine how many cycbuffs will
989     make up the metacycbuff, the size of those cycbuffs, and where they will
990     be stored.  Some OSes do not support files larger than 2 GB, which will
991     limit the size you can make a single cycbuff, but you can still combine
992     many cycbuffs into each metacycbuff.  Older versions of Linux are known
993     to have this limitation; FreeBSD does not.  Some OSes that support large
994     files don't support direct access to block devices for large partitions
995     (Solaris prior to Solaris 7, or not running in 64-bit mode, is in this
996     category); on those OSes, if you want cycbuffs over 2 GB, you'll have to
997     use regular files.  If in doubt, keep your cycbuffs smaller than 2 GB. 
998     Also, when laying out your cycbuffs, you will want to try to arrange
999     them across as many physical disks as possible (or use a striped disk
1000     array and put them all on that).
1001
1002     In order to use any cycbuff larger than 2 GB, you need to build INN with
1003     the --enable-largefiles option.  See "Installing INN" for more
1004     information and some caveats.
1005
1006     For each cycbuff you will be creating, add a line to cycbuff.conf like
1007     the following:
1008
1009         cycbuff:NAME:/path/to/buffer:SIZE
1010
1011     NAME must be unique and must be at most seven characters long. 
1012     Something simple like "BUFF00", "BUFF01", etc. is a decent choice, or
1013     you may want to use something that includes the SCSI target and slice
1014     number of the partition.  SIZE is the buffer size in kilobytes (if
1015     you're trying to stay under 2 GB, keep your sizes below 2097152).
1016
1017     Now, you need to tell INN how to group your cycbuffs into metacycbuffs. 
1018     This is similar to creating cycbuff entries:
1019
1020         metacycbuff:BUFFNAME:CYCBUFF,CYCBUFF,CYCBUFF
1021
1022     BUFFNAME is the name of the metacycbuff and must be unique and at most
1023     eight characters long.  These should be a bit more meaningful than the
1024     cycbuff names since they will be used in other config files as well. 
1025     Try to name them after what will be stored in them; for example, if this
1026     metacycbuff will hold alt.binaries postings, "BINARIES" would be a good
1027     choice.  The last part of the entry is a comma-separated list of all of
1028     the cycbuffs that should be used to build this metacycbuff.  Each
1029     cycbuff should only appear in one metacycbuff line, and all metacycbuff
1030     lines must occur after all cycbuff lines in the file.
1031
1032     If you want INN to fill each cycbuff before moving on to the next one
1033     rather than writing to them round-robin, add ":SEQUENTIAL" to the end of
1034     the metacycbuff line.  This may give noticeably better performance when
1035     using multiple cycbuffs on the same spindle (such as partitions or
1036     slices of a larger disk), but will probably give worse performance if
1037     your cycbuffs are spread out across a lot of spindles.
1038
1039     By default, CNFS data is flushed to disk every 25 articles.  If you're
1040     running a small server with a light article load, this could mean losing
1041     quite a few articles in a crash.  You can change this interval by adding
1042     a cycbuffupdate line to your cycbuff.conf file; see cycbuff.conf(5) for
1043     more details.
1044
1045     Finally, you have to create the cycbuffs.  See "Creating the Article
1046     Spool" for more information on how to do that.
1047
1048   storage.conf
1049
1050     storage.conf determines where incoming articles will be stored (what
1051     storage method, and in the case of CNFS, what metacycbuff).  Each entry
1052     in the file defines a storage class for articles.  The first matching
1053     storage class is used to store the article; if no storage class matches,
1054     INN will reject that article.  (This is almost never what you want, so
1055     make sure this file ends in a catch-all entry that will match
1056     everything.)
1057
1058     A storage class definition looks like this:
1059
1060         method <methodname> {
1061             newsgroups: <wildmat>
1062             class: <storage_class>
1063             size: <minsize>[,<maxsize>]
1064             expires: <mintime>[,<maxtime>]
1065             options: <options>
1066         }
1067
1068     <methodname> is the name of the storage method to use to store articles
1069     in this class ("cnfs", "timehash", "timecaf", "tradspool", or the
1070     special method "trash" that accepts the article and throws it away).
1071
1072     The first parameter is a wildmat pattern in the same format used by the
1073     newsfeeds(5) file, and determines what newsgroups are accepted by this
1074     storage class.
1075
1076     The second parameter is a unique number identifying this storage class
1077     and should be between 0 and 255.  It can be used to control article
1078     expiration, and for timehash and timecaf will set the top-level
1079     directory in which articles accepted by this storage class are stored. 
1080     The easiest way to deal with this parameter is to just number all
1081     storage classes in storage.conf sequentially.  The assignment of a
1082     particular number to a storage class is arbitrary but *permanent* (since
1083     it is used in storage tokens).
1084
1085     The third parameter can be used to accept only articles in a certain
1086     size range into this storage class.  A <maxsize> of 0 (or a missing
1087     <maxsize>) means no upper limit (and of course a <minsize> of 0 would
1088     mean no lower limit, because all articles are more than zero bytes
1089     long).  If you don't want to limit the size of articles accepted by this
1090     storage class, leave this parameter out entirely.
1091
1092     The fourth parameter you probably don't want to use; it lets you assign
1093     storage classes based on the Expires: header of incoming articles.  The
1094     exact details are in storage.conf(5).  It's very easy to use this
1095     parameter incorrectly; leave it out entirely unless you've read the man
1096     page and know what you're doing.
1097
1098     The fifth parameter is the options parameter.  Currently only CNFS uses
1099     this field; it should contain the name of the metacycbuff used to store
1100     articles in this storage class.
1101
1102     If you're using CNFS exclusively, just create one storage class for each
1103     metacycbuff that you have defined in cycbuff.conf and set the newsgroups
1104     pattern according to what newsgroups should be stored in that buffer.
1105
1106     If you're using timehash or timecaf, the storage class IDs are used to
1107     store articles in separate directory trees, which you can take advantage
1108     of to put particular storage classes on different disks.  Also,
1109     currently storage class is the only way to specify expiration time, so
1110     you will need to divide up your newsgroups based on how long you want to
1111     retain articles in those groups and create a storage class for each such
1112     collection of newsgroups.  Make note of the storage class IDs you assign
1113     as they will be needed when you edit expire.ctl a bit later.
1114
1115   expire.ctl
1116
1117     expire.ctl sets the expiration policy for articles stored on the server.
1118     Be careful, since the default configuration will expire most articles
1119     after 10 days; in most circumstances this deletion is *permanent*, so
1120     read this whole section carefully if you want to keep local hierarchies
1121     forever.  (See archive(8) for a way to automate backups of important
1122     articles.)
1123
1124     Only one entry is required for all storage classes; it looks like:
1125
1126         /remember/:10
1127
1128     This entry says how long to keep the Message-IDs for articles that have
1129     already expired in the history file so that the server doesn't accept
1130     them again.  Occasionally, fairly old articles will get regurgitated
1131     somewhere and offered to you again, so even after you've expired
1132     articles from your spool, you want to keep them around in your history
1133     file for a little while to ensure you don't get duplicates.
1134
1135     INN will reject any articles more than a certain number of days old (the
1136     *artcutoff* parameter in inn.conf, defaulting to 10); the number on the
1137     "/remember/" line should match that.
1138
1139     CNFS makes no further use of expire.ctl, since articles stored in CNFS
1140     buffers expire automatically when the buffer runs out of free space (but
1141     see the "-N" option in expireover(8) if you really want to expire them
1142     earlier).  For other storage methods, there are two different syntaxes
1143     of this file, depending on *groupbaseexpiry* in inn.conf.  If it is set
1144     to false, expire.ctl takes entries of the form:
1145
1146         <storage_class>:<keep>:<default>:<purge>
1147
1148     <storage_class> is the number assigned to a storage class in
1149     storage.conf.  <default> is the number of days to keep normal articles
1150     in that storage class (decimal values are allowed).  For articles that
1151     don't have an Expires: header, those are the only two values that
1152     matter.  For articles with an Expires: header, the other two values come
1153     into play; the date given in the Expires: header of an article will be
1154     honored, subject to the contraints set by <keep> and <purge>.  All
1155     articles in this storage class will be kept for at least <keep> days,
1156     regardless of their Expires: headers, and all articles in this storage
1157     class will be expired after <purge> days, even if their Expires: headers
1158     specify a longer life.
1159
1160     All three of these fields can also contain the special keyword "never". 
1161     If <default> is "never", only articles with explicit Expires: headers
1162     will ever be expired.  If <keep> is "never", articles with explicit
1163     Expires: headers will be kept forever.  Setting <purge> to "never" says
1164     to honor Expires: headers even if they specify dates far into the
1165     future.  (Note that if <keep> is set to "never", all articles with
1166     Expires: headers are kept forever and the value of <purge> is not used.)
1167
1168     If the value of "groupbaseexpiry" is true, expire.ctl takes entries of
1169     the form:
1170
1171         <wildmat>:<flag>:<keep>:<default>:<purge>
1172
1173     <wildmat> is a wildmat expression ("!" and "@" not permitted, and only a
1174     single expression, not a comma-separated set of them).  Each expiration
1175     line applies to groups matching the wildmat expression.  <flag> is "M"
1176     for moderated groups, "U" for unmoderated groups, and "A" for groups
1177     with any moderation status; the line only matches groups with the
1178     indicated expiration status.  All of the other fields have the same
1179     meaning as above.
1180
1181   readers.conf
1182
1183     Provided that *noreader* is set to false in inn.conf, any connection
1184     from a host that doesn't match an entry in incoming.conf (as well as any
1185     connection from a host that does match such an entry, but has issued a
1186     MODE READER command) will be handed off to nnrpd(8), the part of INN
1187     that supports newsreading clients.  nnrpd uses readers.conf to determine
1188     whether a given connection is allowed to read news, and if so what
1189     newsgroups the client can read and post to.
1190
1191     There are a variety of fairly complicated things that one can do with
1192     readers.conf, things like run external authentication programs that can
1193     query RADIUS servers.  See readers.conf(5) and the example file for all
1194     the gory details.  Here's an example of probably the simplest reasonable
1195     configuration, one that only allows clients in the example.com domain to
1196     read from the server and allows any host in that domain to read and post
1197     to all groups:
1198
1199         auth "example.com" {
1200             hosts: "example.com, *.example.com"
1201             default: "<user>"
1202             default-domain: "example.com"
1203         }
1204
1205         access "all" {
1206             users: "*@example.com"
1207             newsgroups: "*"
1208         }
1209
1210     If you're running a server for one particular domain, want to allow all
1211     hosts within that domain to read and post to any group on the server,
1212     and want to deny access to anyone outside that domain, just use the
1213     above and change "example.com" in the above to your domain and you're
1214     all set.  Lots of examples of more complicated things are in the sample
1215     file.
1216
1217 Creating the Article Spool (CNFS only)
1218
1219     If you are using actual files as your CNFS buffers, you will need to
1220     pre-create those files, ensuring they're the right size.  The easiest
1221     way to do this is with dd.  For each cycbuff in cycbuff.conf, create the
1222     buffer with the following commands (as the news user):
1223
1224         dd if=/dev/zero of=/path/to/buffer bs=1k count=BUFFERSIZE
1225         chmod 664 /path/to/buffer
1226
1227     Substitute the correct path to the buffer and the size of the buffer as
1228     specified in cycbuff.conf.  This will create a zero-filled file of the
1229     correct size; it may take a while, so be prepared to wait.
1230
1231     Here's a command that will print out the dd(1) commands that you should
1232     run:
1233
1234         awk -F: \
1235         '/^cy/ { printf "dd if=/dev/zero of=%s bs=1k count=%s\n", $3, $4 }' \
1236         ~news/etc/cycbuff.conf
1237
1238     If you are using block devices, you don't technically have to do
1239     anything at all (since INN is capable of using the devices in /dev), but
1240     you probably want to create special device files for those devices
1241     somewhere for INN's private use.  It s more convenient to keep all of
1242     INN's stuff together, but more importantly, the device files used by INN
1243     really should be owned by the news user and group, and you may not want
1244     to do that with the files in /dev.
1245
1246     To create the device files for INN, use mknod(8) with a type of "b",
1247     getting the major and minor device numbers from the existing devices in
1248     /dev.  There's a small shell script in cycbuff.conf(5) that may help
1249     with this.  Make sure to create the device files in the location INN
1250     expects them (specified in cycbuff.conf).
1251
1252     Solaris users please note:  on Solaris, do not use block devices that
1253     include the first cylinder of the disk.  Solaris doesn't protect the
1254     superblock from being overwritten by an application writing to block
1255     devices and includes it in the first cylinder of the disk, so unless you
1256     use a slice that starts with cylinder 1 instead of 0, INN will
1257     invalidate the partition table when it tries to initialize the cycbuff
1258     and all further accesses will fail until you repartition.
1259
1260 Creating the Database Files
1261
1262     At this point, you need to set up the news database directory
1263     (~news/db).  This directory will hold the active(5) file (the list of
1264     newsgroups you carry), the active.times(5) file (the creator and
1265     creation time of newsgroups created since the server was initialized),
1266     the newsgroups(5) file (descriptions for all the newsgroups you carry),
1267     and the history(5) file (a record of every article the server currently
1268     has or has seen in the past few days, used to decide whether to accept
1269     or refuse new incoming messages).
1270
1271     Before starting to work on this, make sure you're logged on as the news
1272     user, since all of these files need to be owned by that user.  This is a
1273     good policy to always follow; if you are doing any maintenance work on
1274     your news server, log on as the news user.  Don't do maintenance work as
1275     root.  Also make sure that ~news/bin is in the default path of the news
1276     user (and while you're at it, make sure ~news/man is in the default
1277     MANPATH) so that you can run INN maintenance commands without having to
1278     type the full path.
1279
1280     If you already have a server set up (if you're upgrading, or setting up
1281     a new server based on an existing server), copy active and newsgroups
1282     from that server into ~news/db.  Otherwise, you'll need to figure out
1283     what newsgroups you want to carry and create new active and newsgroups
1284     files for them.  If you plan to carry a full feed, or something close to
1285     that, go to <ftp://ftp.isc.org/pub/usenet/CONFIG/> and download active
1286     and newsgroups from there; that will start you off with reasonably
1287     complete files.  If you plan to only carry a small set of groups, the
1288     default minimal active file installed by INN is a good place to start;
1289     you can create additional groups after the server is running by using
1290     "ctlinnd newgroup".  (Another option is to use actsync(8) to synchronize
1291     your newsgroup list to that of another server.)
1292
1293     "control" and "junk" must exist as newsgroups in your active file for
1294     INN to start, and creating pseudogroups for the major types of control
1295     messages is strongly encouraged for all servers that aren't standalone. 
1296     If you don't want these groups to be visible to clients, do *not* delete
1297     them; simply hide them in readers.conf.  "to" must also exist as a
1298     newsgroup if you have mergetogroups set in inn.conf.
1299
1300     Next, you need to create an empty history database.  To do this, type:
1301
1302         cd ~news/db
1303         touch history
1304         makedbz -i
1305
1306     When it finishes, rename the files it created to remove the ".n" in the
1307     file names and then make sure the file permissions are correct on all
1308     the files you've just created:
1309
1310         chmod 644 *
1311
1312     Your news database files are now ready to go.
1313
1314 Configuring syslog
1315
1316     While some logs are handled internally, INN also logs a wide variety of
1317     information via syslog.  INN's nightly report programs know how to roll
1318     and summarize those syslog log files, but when you first install INN you
1319     need to set them up.
1320
1321     If your system understands the "news" syslog facility, INN will use it;
1322     otherwise, it will log to "local1".  Nearly every modern system has a
1323     "news" syslog facility so you can safely assume that yours does, but if
1324     in doubt take a look at the output from running "configure".  You should
1325     see a line that looks like:
1326
1327         checking log level for news... LOG_NEWS
1328
1329     If that says LOG_LOCAL1 instead, change the below instructions to use
1330     "local1" instead of "news".
1331
1332     Edit /etc/syslog.conf on your system and add lines that look like the
1333     following:
1334
1335         news.crit           /usr/local/news/log/news.crit
1336         news.err            /usr/local/news/log/news.err
1337         news.notice         /usr/local/news/log/news.notice
1338
1339     (Change the path names as necessary if you installed INN in a different
1340     location than /usr/local/news.)  These lines *must* be tab-delimited, so
1341     don't copy and paste from these instructions.  Type it in by hand and
1342     make sure you use a tab, or you'll get mysterious failures.  You'll also
1343     want to make sure that news log messages don't fill your other log files
1344     (INN generates a lot of log traffic); so for every entry in
1345     /etc/syslog.conf that starts with "*", add ";news.none" to the end of
1346     the first column.  For example, if you have a line like:
1347
1348         *.err               /dev/console
1349
1350     change it to:
1351
1352         *.err;news.none     /dev/console
1353
1354     (You can choose not to do this for the higher priority log messages, if
1355     you want to make sure they go to your normal high-priority log files as
1356     well as INN's.  Don't bother with anything lower priority than "crit",
1357     though.  "news.err" isn't interesting enough to want to see all the
1358     time.)  Now, make sure that the news log files exist; syslog generally
1359     won't create files automatically.  Enter the following commands:
1360
1361         touch /usr/local/news/log/news.crit
1362         touch /usr/local/news/log/news.err
1363         touch /usr/local/news/log/news.notice
1364         chown news /usr/local/news/log/news.*
1365         chgrp news /usr/local/news/log/news.*
1366
1367     (again adjusting the paths if necessary for your installation). 
1368     Finally, send a HUP signal to syslogd to make it re-read its
1369     configuration file.
1370
1371 Setting Up the Cron Jobs
1372
1373     INN requires a special cron job to be set up on your system to run
1374     news.daily(8) which performs daily server maintenance tasks such as
1375     article expiration and the processing and rotation of the server logs. 
1376     Since it will slow the server down while it is running, it should be run
1377     during periods of low server usage, such as in the middle of the night. 
1378     To run it at 3am, for example, add the following entry to the news
1379     user's crontab file:
1380
1381         0 3 * * * /usr/local/news/bin/news.daily expireover lowmark
1382
1383     or, if your system does not have per-user crontabs, put the following
1384     line into your system crontab instead:
1385
1386         0 3 * * * su -c "/usr/local/news/bin/news.daily expireover lowmark" news
1387
1388     If you're using any non-CNFS storage methods, add "delayrm" to the above
1389     option list for news.daily.
1390
1391     The news user obviously must be able to run cron jobs.  On Solaris, this
1392     means that it must have a valid /etc/shadow entry and must not be locked
1393     (although it may be a non-login account).  There may be similar
1394     restrictions with other operating systems.
1395
1396     If you use the batching method to send news, also set up a cron job to
1397     run nntpsend(8) every ten minutes.  nntpsend will run innxmit for all
1398     non-empty pending batch files to send pending news to your peers.  That
1399     cron entry should look something like:
1400
1401         0,10,20,30,40,50 * * * * /usr/local/news/bin/nntpsend
1402
1403     The pathnames and user ID used above are the installation defaults;
1404     change them to match your installation if you used something other than
1405     the defaults.
1406
1407     The parameters passed to news.daily in the above example are the most
1408     common (and usually the most efficient) ones to use.  More information
1409     on what these parameters do can be found in the news.daily(8) man page.
1410
1411 File Descriptor Limits
1412
1413     INN likes to use a lot of file descriptors, particularly if you have a
1414     lot of peers.  Depending on what your system defaults are, you may need
1415     to make sure the default limit is increased for INN (particularly for
1416     innd and innfeed).  This is vital on Solaris, which defaults (at least
1417     as of 2.6) to an absurdly low limit of 64 file descriptors per process.
1418
1419     One way to increase the number of file descriptors is to set
1420     *rlimitnofile* in inn.conf to a higher value.  This will cause both
1421     startinnfeed and inndstart (the setuid root wrapper scripts that start
1422     innfeed and innd, respectively) to increase the file descriptor limits
1423     before they run the regular INN programs.  Note, however, that INN won't
1424     be able to increase the limits above the hard limits set by your
1425     operating system; on some systems, that hard limit is normally 256 file
1426     descriptors (Linux, for example).  On others, like Solaris, it's 1024. 
1427     Increasing the limit beyond that value may require serious system
1428     configuration work.  (On some operating systems, it requires patching
1429     and recompiling the kernel.  On Solaris it can be changed in
1430     /etc/system, but for 2.6 or earlier the limit cannot be increased beyond
1431     1024 without breaking select(2) and thereby breaking all of INN.  For
1432     current versions of Linux, you may be able to change the maximum by
1433     writing to /proc/sys/fs/file-max.)
1434
1435     256 file descriptors will probably be enough for all but the largest
1436     sites.  There is no harm in setting the limits higher than you actually
1437     need (provided they're set to something lower than or equal to your
1438     system hard limit).  256 is therefore a reasonable value to try.
1439
1440     If you're installing INN on a Solaris system, particularly if you're
1441     installing it on a dedicated news server machine, it may be easier to
1442     just increase the default file descriptor limit across the board for all
1443     processes.  You can do that by putting the line:
1444
1445         set rlim_fd_cur = 256
1446
1447     in /etc/system and rebooting.  You can increase it all the way to 1024
1448     (and may need to if you have a particularly large site), but that can
1449     cause RPC and some stdio applications to break.  It therefore probably
1450     isn't a good idea on a machine that isn't dedicated to INN.
1451
1452 Starting and Stopping the System
1453
1454     INN is started via the shell script rc.news.  This must be run as the
1455     news user and not as root.  To start INN on system boot, you therefore
1456     want to put something like:
1457
1458         su - news -c /usr/local/news/bin/rc.news
1459
1460     in the system boot scripts.  If innd is stopped or killed, you can
1461     restart it by running rc.news by hand as the news user.
1462
1463     The rc.news script may also be used to shut down INN, with the "stop"
1464     option:
1465
1466         su - news -c '/usr/local/news/bin/rc.news stop'
1467
1468     In the contrib directory of this source tree is a sample init script for
1469     people using System V-style init.d directories.
1470
1471 Processing Newsgroup Control Messages
1472
1473     Control messages are specially-formatted messages that tell news servers
1474     to take various actions.  Cancels (commands to delete messages) are
1475     handled internally by INN, and all other control messages are processed
1476     by controlchan.  controlchan should be run out of newsfeeds if you want
1477     your news server to process any control messages; see "Configuring INN"
1478     for specific instructions.
1479
1480     The actions of controlchan are determined by control.ctl, which lists
1481     who can perform what actions.  The primary control messages to be
1482     concerned with are "newgroup" (to create a newsgroup), "rmgroup" (to
1483     remove a newsgroup), and "checkgroups" (to compare the list of groups
1484     carried in a hierarchy to a canonical list).  INN comes with a
1485     control.ctl file that processes control messages in most major public
1486     hierarchies; if you don't want to act on all those control messages, you
1487     should remove from that file all entries for hierarchies you don't want
1488     to carry.
1489
1490     You can tell INN to just authenticate control messages based on the From
1491     header of the message, but this is obviously perilous and control
1492     messages are widely forged.  Many hierarchies sign all of their control
1493     messages with PGP, allowing news servers to verify their authenticity,
1494     and checking those signatures for hierarchies that use them is highly
1495     recommended.  controlchan knows how to do this (using pgpverify) without
1496     additional configuration, but you do have to provide it with a public
1497     key ring containing the public keys of all of the hierarchy
1498     administrators whose control messages you want to check.
1499
1500     INN expects the public key ring to either be in the default location for
1501     a PGP public key ring for the news user (generally ~news/.gnupg for
1502     GnuPG and ~news/.pgp for old PGP implementations), or in pathetc/pgp
1503     (/usr/local/news/etc/pgp by default).  The latter is the recommended
1504     path.  To add a key to that key ring, use:
1505
1506         gpg --import --homedir=/usr/local/news/etc/pgp <file>
1507
1508     where <file> is a file containing the hierarchy key.  Change the homedir
1509     setting to point to pathetc/pgp if you have INN installed in a
1510     non-default location.  If you're using the old-style PGP program, an
1511     equivalent command is:
1512
1513         env PGPPATH=/usr/local/news/etc/pgp pgp <file>
1514
1515     You can safely answer "no" to questions about whether you want to sign,
1516     trust, or certify keys.
1517
1518     The URLs from which you can get hierarchy keys are noted in comments in
1519     control.ctl.  <ftp://ftp.isc.org/pub/pgpcontrol/PGPKEYS> tries to
1520     collect the major hierarchy keys.
1521
1522     If you are using GnuPG, please note that the first user ID on the key
1523     will be the one that's used by INN for verification and must match the
1524     key listed in control.ctl.  If a hierarchy key has multiple user IDs,
1525     you may have to remove all the user IDs except the one that matches the
1526     control.ctl entry using "gpg --edit-key" and the "delkey" command.
1527