3 Please read this document thoroughly before trying to install INN.
4 You'll be glad you did.
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.
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:
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
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.)
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.
39 For more information about recent changes, see NEWS.
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.
48 INN has been confirmed to work on the following operating systems:
53 Linux 2.x (tested with libc 5.4, glibc 2.0 and up)
57 SCO 5.0.4 (tested with gcc 2.8.1, cc)
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>.
67 INN requires several other packages be installed in order to be fully
68 functional (or in some cases, to work at all):
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
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.
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.
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:
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).
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.
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.
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
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
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:
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
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
151 <http://www.eyrie.org/~eagle/notes/rpath.html>
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.
157 Unpacking the Distribution
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.
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.)
174 The distribution is in gzip compressed tar archive format. To extract
177 gunzip -c <inn-src-file> | tar -xf -
179 Extracting the source distribution will create a directory named
180 inn-<version> or inn-<BRANCH>-<date> where the source resides.
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.
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).
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".
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.
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
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:
233 for a full list of supported options. Some of the most commonly used
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).
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.
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).
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.
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.
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.
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.
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:
298 ram: Amount of system RAM (in bytes)
299 tablesize: 3rd field on the 1st line of history.dir (bytes)
301 If you don't have at least that much RAM, try rebuilding INN with
304 NOTE: --enable-largefiles cannot be used with --enable-tagged-hash.
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
312 Even if you do not use this option, INN still requires Perl as
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
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
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).
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.
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.
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.
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
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.
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).
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.
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
416 For the most common installation, a standalone news server, a suggested
419 ./configure --with-perl
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.)
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:
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.
434 Once the build has completed successfully, you are ready to install INN
435 into its final home. Type:
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).
446 If you are configuring SSL support for newsreaders, you must make a
447 certificate and private key at least once. Type:
451 as root in order to do this.
453 You are now ready for the really fun part: configuring your copy of
456 Choosing an Article Storage Format
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.
464 The supported storage formats are:
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.
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.
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.
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.
494 Advantages: Heavy traffic groups do not cause bottlenecks, and fine
495 control of article retention time is still possible.
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).
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.
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.
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.
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.
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.
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
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.
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.
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.
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
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.
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.
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:
595 man -M ~news/man inn.conf
597 to see the inn.conf(5) man page (for example).
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.
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:
610 *, !comp.*, comp.os.*
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.
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.
630 See uwildmat(3) for full details on wildmat patterns.
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.
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".)
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
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.)
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.
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.
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.
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.
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
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
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.
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.
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.)
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.
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 "@").
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).
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.
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.
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.
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.
797 Batching outgoing posts is easy to set up; for each peer, add an entry
798 to newsfeeds that looks like:
800 remote.example.com/news.example.com\
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.
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.
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
829 First, the special channel feed entry for innfeed that will collect all
834 :Tc,Wnm*:/usr/local/news/bin/startinnfeed -y
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.
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:
846 remote.example.com/news.example.com\
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.
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:
863 :Tc,Wnm*,S16384:/usr/local/news/bin/startinnfeed imapfeed
865 And set up entries for each remote site like:
867 remote.example.com/news.example.com\
871 For more information on imapfeed, look at the innfeed/imap_connection.c.
872 For more information on IMAP in general, see RFC 2060.
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
880 :!*,control,control.*,!control.cancel\
881 :Tc,Wnsm:/usr/local/news/bin/controlchan
883 (modified for the actual path to controlchan if you put it somewhere
884 else). See "Processing Control Messages" for more details.
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
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
904 Start with the sample incoming.conf and, for each remote peer, add an
907 peer remote.example.com { }
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
914 peer remote.example.com {
915 hostname: "remote.example.com, news.example.com"
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
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),
930 peer remote.example.com {
931 patterns: "*, @local.*"
932 hostname: "remote.example.com, news.example.com"
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.
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)
945 Note for those familiar with older versions of INN: this file replaces
946 the old hosts.nntp configuration file.
950 cycbuff.conf is only required if CNFS is used. If you aren't using
951 CNFS, skip this section.
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
962 There are two ways to create your cycbuffs:
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.
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
975 If you're having doubts, use option #2; it's easier to set up and should
976 work regardless of your operating system.
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.)
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).
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.
1006 For each cycbuff you will be creating, add a line to cycbuff.conf like
1009 cycbuff:NAME:/path/to/buffer:SIZE
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).
1017 Now, you need to tell INN how to group your cycbuffs into metacycbuffs.
1018 This is similar to creating cycbuff entries:
1020 metacycbuff:BUFFNAME:CYCBUFF,CYCBUFF,CYCBUFF
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.
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.
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
1045 Finally, you have to create the cycbuffs. See "Creating the Article
1046 Spool" for more information on how to do that.
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
1058 A storage class definition looks like this:
1060 method <methodname> {
1061 newsgroups: <wildmat>
1062 class: <storage_class>
1063 size: <minsize>[,<maxsize>]
1064 expires: <mintime>[,<maxtime>]
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).
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
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).
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.
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.
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.
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.
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.
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
1124 Only one entry is required for all storage classes; it looks like:
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.
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.
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:
1146 <storage_class>:<keep>:<default>:<purge>
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.
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.)
1168 If the value of "groupbaseexpiry" is true, expire.ctl takes entries of
1171 <wildmat>:<flag>:<keep>:<default>:<purge>
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
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.
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
1199 auth "example.com" {
1200 hosts: "example.com, *.example.com"
1202 default-domain: "example.com"
1206 users: "*@example.com"
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
1217 Creating the Article Spool (CNFS only)
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):
1224 dd if=/dev/zero of=/path/to/buffer bs=1k count=BUFFERSIZE
1225 chmod 664 /path/to/buffer
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.
1231 Here's a command that will print out the dd(1) commands that you should
1235 '/^cy/ { printf "dd if=/dev/zero of=%s bs=1k count=%s\n", $3, $4 }' \
1236 ~news/etc/cycbuff.conf
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.
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).
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.
1260 Creating the Database Files
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).
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
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.)
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.
1300 Next, you need to create an empty history database. To do this, type:
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:
1312 Your news database files are now ready to go.
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.
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:
1327 checking log level for news... LOG_NEWS
1329 If that says LOG_LOCAL1 instead, change the below instructions to use
1330 "local1" instead of "news".
1332 Edit /etc/syslog.conf on your system and add lines that look like the
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
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:
1352 *.err;news.none /dev/console
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:
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.*
1367 (again adjusting the paths if necessary for your installation).
1368 Finally, send a HUP signal to syslogd to make it re-read its
1371 Setting Up the Cron Jobs
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:
1381 0 3 * * * /usr/local/news/bin/news.daily expireover lowmark
1383 or, if your system does not have per-user crontabs, put the following
1384 line into your system crontab instead:
1386 0 3 * * * su -c "/usr/local/news/bin/news.daily expireover lowmark" news
1388 If you're using any non-CNFS storage methods, add "delayrm" to the above
1389 option list for news.daily.
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.
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:
1401 0,10,20,30,40,50 * * * * /usr/local/news/bin/nntpsend
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
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.
1411 File Descriptor Limits
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.
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.)
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.
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:
1445 set rlim_fd_cur = 256
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.
1452 Starting and Stopping the System
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:
1458 su - news -c /usr/local/news/bin/rc.news
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.
1463 The rc.news script may also be used to shut down INN, with the "stop"
1466 su - news -c '/usr/local/news/bin/rc.news stop'
1468 In the contrib directory of this source tree is a sample init script for
1469 people using System V-style init.d directories.
1471 Processing Newsgroup Control Messages
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.
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
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.
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:
1506 gpg --import --homedir=/usr/local/news/etc/pgp <file>
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:
1513 env PGPPATH=/usr/local/news/etc/pgp pgp <file>
1515 You can safely answer "no" to questions about whether you want to sign,
1516 trust, or certify keys.
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.
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.
~ian / inn-innduct.git / blob