+++ /dev/null
-=head1 Welcome to INN 2.4!
-
-Please read this document thoroughly before trying to install INN. You'll
-be glad you did.
-
-If you are upgrading from a major release of INN prior to 2.3, it is
-recommended that you make copies of your old configuration files and use
-them as guides for doing a clean installation and configuration of 2.4.
-Many config files have changed, some have been added, and some have been
-removed. You'll find it much easier to start with a fresh install than to
-try to update your old installation. This is particularly true if you're
-upgrading from a version of INN prior to 2.0.
-
-If you are upgrading from INN 2.3 or later, you may be able to just update
-the binaries, scripts, and man pages by running:
-
- make update
-
-after building INN and then comparing the new sample configuration files
-with your current ones to see if anything has changed. If you take this
-route, the old binaries, scripts, and man pages will be saved with an
-extension of C<.OLD> so that you can easily back out. Be sure to
-configure INN with the same options that you used previously if you take
-this approach (in particular, INN compiled with B<--enable-largefiles>
-can't read the data structures written by INN compiled without that flag,
-and vice versa). If you don't remember what options you used but you have
-your old build tree, look at the comments at the beginning of
-F<config.status>.
-
-If you made ckpasswd setuid root so that you could use system passwords,
-you'll have to do that again after make update. (It's much better to use
-PAM instead if you can.)
-
-If you use C<make update> to upgrade from INN 2.3, also look at the new
-sample configuration files in F<samples> to see if there are new options
-of interest to you. In particular, F<control.ctl> has been updated and
-F<inn.conf> has various new options.
-
-For more information about recent changes, see F<NEWS>.
-
-=head1 Supported Systems
-
-As much as possible, INN is written in portable C and should work on any
-Unix platform. It does, however, make extensive use of mmap(2) and
-certain other constructs that may be poorly or incompletely implemented,
-particularly on very old operating systems.
-
-INN has been confirmed to work on the following operating systems:
-
- AIX 4.3
- FreeBSD 2.2.x and up
- HP-UX 10.20 and up
- Linux 2.x (tested with libc 5.4, glibc 2.0 and up)
- Mac OS X 10.2 and up
- NetBSD 1.6 and up
- OpenBSD 2.8 and up
- SCO 5.0.4 (tested with gcc 2.8.1, cc)
- Solaris 2.5.x and up
- UnixWare 7.1
- UX/4800 R11 and up
-
-If you have gotten INN working on an operating system other than the ones
-listed above, please let us know at <inn-bugs@isc.org>.
-
-=head1 Before You Begin
-
-INN requires several other packages be installed in order to be fully
-functional (or in some cases, to work at all):
-
-=over 2
-
-=item *
-
-In order to build INN, you will need a C compiler that understands ANSI C.
-If you are trying to install INN on an operating system that doesn't have
-an ANSI C compiler (such as SunOS), installing gcc is recommended. You
-can get it from <ftp://ftp.gnu.org/gnu/gcc/> or its mirrors. INN is
-tested with gcc more thoroughly than with any other compiler, so even if
-you have another compiler available, you may wish to use gcc instead.
-
-=item *
-
-Currently, in order to build INN, you will need an implementation of yacc.
-GNU bison (from <ftp://ftp.gnu.org/gnu/bison/> or its mirrors) will work
-fine. We hope to remove this requirement in the future.
-
-=item *
-
-INN requires at least Perl 5.004_03 to build and to run several
-subsystems. INN is tested primarily with newer versions of Perl, so it's
-generally recommended that you install the latest stable distribution of
-Perl before compiling INN. For instructions on obtaining and installing
-Perl, see <http://www.perl.com/pub/language/info/software.html>. Note
-that you may need to use the same compiler and options (particularly
-largefile support) for Perl and INN.
-
-If you're using a version of Perl prior to 5.6.0, you may need to make
-sure that the Perl versions of your system header files have been
-generated in order for Sys::Syslog to work properly (used by various
-utility programs, including controlchan). To do this, run the following
-two commands:
-
- # cd /usr/include
- # h2ph * sys/*
-
-An even better approach is to install Perl 5.6.1 or later, which have a
-fixed version of Sys::Syslog that doesn't require this (as well as many
-other improvements over earlier versions of Perl).
-
-=item *
-
-The INN Makefiles use the syntax C<include FILE>, rather than the syntax
-expected by some BSDish systems of C<.include E<lt>FILEE<gt>>. If your
-system expects the latter syntax, the recommended solution is to install
-GNU make from <ftp://ftp.gnu.org/make/>. You may have GNU make already
-installed as gmake, in which case using gmake rather than make to build
-INN should be sufficient.
-
-=item *
-
-If you want to enable support for authenticated control messages (this is
-not required, but is highly recommended for systems carrying public Usenet
-hierarchies) then you will need to install some version of PGP. The
-recommended version is GnuPG, since it's actively developed, supports
-OpenPGP, is freely available and free to use for any purpose (in the US
-and elsewhere), and (as of version 1.0.4 at least) supports the RSA
-signatures used by most current control message senders.
-
-Alternately, you can install PGP from <http://www.pgp.com/> or one of the
-international versions of it. Be warned, however, that the licensing
-restrictions on PGP inside the United States are extremely unclear; it's
-possible that if you are installing INN for a company in the U.S., even if
-the news server is not part of the business of that company, you would
-need to purchase a commercial license for PGP. For an educational or
-non-profit organization, this shouldn't be a problem.
-
-=item *
-
-If you want to use either the Python embedded hooks, you'll need to have a
-suitable versions of Python installed. See F<doc/hook-python> for more
-information.
-
-=item *
-
-Many of INN's optional features require other packages (primarily
-libraries) be installed. If you wish to use any of these optional
-features, you will need to install those packages first. Here is a table
-of configure options enabling optional features and the software and
-versions you'll need:
-
- --with-perl Perl 5.004_03 or higher, 5.6.1+ recommended
- --with-python Python 1.5.2 or higher
- --with-berkeleydb BerkeleyDB 2.0 or higher, 4.2+ recommended
- --with-openssl OpenSSL 0.9.6 or higher
- --with-sasl SASL 2.x or higher
- --with-kerberos MIT Kerberos v5 1.2.x or higher
-
-If any of these libraries (other than Perl or Python) are built shared and
-installed in locations where your system doesn't search for shared
-libraries by default, you may need to encode the paths to those shared
-libraries in the INN binaries. For more information on shared library
-paths, see:
-
- <http://www.eyrie.org/~eagle/notes/rpath.html>
-
-For most systems, setting the environment variable LD_RUN_PATH to a
-colon-separated list of additional directories in which to look for shared
-libraries before building INN will be sufficient.
-
-=back
-
-=head1 Unpacking the Distribution
-
-Released versions of INN are available from ftp.isc.org in F</isc/inn>.
-New major releases will be announed on <inn-announce@isc.org> (see
-F<README>) when they're made.
-
-If you want more a more cutting-edge version, you can obtain current
-snapshots from from ftp.isc.org in directory F</isc/inn/snapshots>. These
-are snapshots of the INN CVS tree taken daily; there are two snapshots
-made each night (one of the current development branch, and one of the
-stable branch consisting of bug fixes to the previous major release).
-They are stored in date format; in other words the snapshots from April
-6th, 2000, would be named F<inn-CURRENT-20000406.tar.gz> and
-F<inn-STABLE-20000406.tar.gz>. Choose the newest file of whichever branch
-you prefer. (Note that the downloading, configuring, and compiling steps
-can be done while logged in as any user.)
-
-The distribution is in gzip compressed tar archive format. To extract it,
-execute:
-
- gunzip -c <inn-src-file> | tar -xf -
-
-Extracting the source distribution will create a directory named
-F<< inn-<version> >> or F<< inn-<BRANCH>-<date> >> where the source
-resides.
-
-=head1 Installing INN
-
-Before beginning installation, you should make sure that there is a user
-on your system named C<news>, and that this user's primary group is set to
-a group called C<news>. You can change these with the B<--with-news-user>
-and B<--with-news-group> options to configure (see below). The home
-directory of this user should be set to the directory under which you wish
-to install INN (F</usr/local/news> is the default and is a good choice).
-INN will install itself as this user and group. You can change these if
-you want, but these are the defaults and it's easier to stick with them on
-a new installation.
-
-By default, INN sends reports to the user C<usenet>. This account isn't
-used for any other purposes. You can change it with the
-B<--with-news-master> option to configure (see below).
-
-WARNING: By default, INN installs various configuration files as
-group-writeable, and in general INN is not hardened from a security
-standpoint against an attack by someone who is already in the news group.
-In general, you should consider membership in the news group as equivalent
-to access to the news account. You should not rely on being able to keep
-anyone with access to the news GID from converting that into access to the
-news UID. The recommended configuration is to have the only member of the
-group C<news> be the user C<news>.
-
-Installing INN so that all of its files are under a single directory tree,
-rather than scattering binaries, libraries, and man pages throughout the
-file system, is strongly recommended. It helps keep everything involved
-in the operation of INN together as a unit and will make the installation
-instructions easier to follow.
-
-As a side note, whenever doing anything with a running news server, first
-log in as this user. That way, you can ensure that all files created by
-any commands you run are created with the right ownership to be readable
-by the server. Particularly avoid doing anything in the news spool itself
-as root, and make sure you fix the ownership of any created files if you
-have to. INN doesn't like files in the news spool owned by a user other
-than the news user. However, since certain binaries need to be setuid
-root, indiscriminate use of C<chown news> is not the solution. (If you
-don't like to log in to system accounts, careful use of C<chmod g+s> on
-directories and a umask of C<002> or C<007> may suffice.)
-
-INN uses GNU autoconf and a generated configure script to make
-configuration rather painless. Unless you have a rather abnormal setup,
-configure should be able to completely configure INN for your system. If
-you want to change the defaults, you can invoke the configure script with
-one or more command line options. Type:
-
- ./configure --help
-
-for a full list of supported options. Some of the most commonly used
-options are:
-
-=over 4
-
-=item B<--prefix>=PATH
-
-Sets the installation prefix for INN. The default is F</usr/local/news>.
-All of INN's programs and support files will be installed under this
-directory. This should match the home directory of your news user (it
-will make installation and maintenance easier). It is not recommended to
-set this to F</usr>; if you decide to do that anyway, make sure to point
-INN's temporary directory at a directory that isn't world-writeable (see
-B<--with-tmp-dir> below).
-
-=item B<--with-db-dir>=PATH
-
-Sets the prefix for INN database files. The default is F<PREFIX/db>,
-where PREFIX is F</usr/local/news> unless overridden with the option
-above. The history and active files will be stored in this directory, and
-writes to those files are an appreciable percentage of INN's disk
-activity. The history file can also be quite large (requiring up to 2 GB
-or more during nightly expire), so this is a common portion of INN to move
-to a different file system.
-
-=item B<--with-spool-dir>=PATH
-
-Sets the prefix for the news spool (when using any storage method other
-than CNFS) and the overview spool. The default is F<PREFIX/spool>. This
-is another common portion of INN to move to a different file system (often
-F</news>).
-
-=item B<--with-tmp-dir>=PATH
-
-Sets the directory in which INN will create temporary files. This should
-under no circumstances be the same as the system temporary directory or
-otherwise be set to a world-writeable directory, since INN doesn't take
-care to avoid symlink attacks and other security problems possible with a
-world-writeable directory. This directory should be reserved for the
-exclusive use of INN and only writeable by the news user. Usage is
-generally light, so this is unlikely to need a separate partition.
-
-It's also possible to set the paths for most other sections of the INN
-installation independently; see C<./configure --help> and look for the
-B<--with-*-dir>=PATH options.
-
-=item B<--enable-largefiles>
-
-Enables large file support. This is not enabled by default, even on
-platforms that support it, because it changes the format of INN's on-disk
-databases (making it difficult to upgrade an earlier INN installation) and
-can significantly increase the size of some of the history database files.
-Large file support is not necessary unless your history database is so
-large that it exceeds 2 GB or you want to use CNFS buffers larger than 2
-GB.
-
-The history, tradindexed and buffindexed overview, CNFS, and timecaf
-databases written by an INN built with this option are incompatible with
-those written by an INN without this option.
-
-=item B<--enable-tagged-hash>
-
-Use tagged hash table for the history database. The tagged hash format
-uses much less memory but is somewhat slower. This option is recommended
-if you have less than 256 MB of RAM on your news server. If you install
-INN without tagged hash (the default) and expire takes an excessive amount
-of time, you should make sure the RAM in your system satisfies the
-following formula:
-
- ram > 10 * tablesize
-
- ram: Amount of system RAM (in bytes)
- tablesize: 3rd field on the 1st line of history.dir (bytes)
-
-If you don't have at least that much RAM, try rebuilding INN with tagged
-hash enabled.
-
-NOTE: B<--enable-largefiles> cannot be used with B<--enable-tagged-hash>.
-
-=item B<--with-perl>
-
-Enables support for embedded Perl, allowing you to install filter scripts
-written in Perl. Highly recommended, because many really good spam
-filters are written in Perl. See F<doc/hook-perl> for all the details.
-
-Even if you do not use this option, INN still requires Perl as mentioned
-above.
-
-=item B<--with-python>
-
-Enables support for Python, allowing you to install filter and
-authentication scripts written in Python. You will need Python 1.5.2 or
-later installed on your system to enable this option. See
-F<doc/hook-python> for all the details. Note that there is an
-incompatibility between INN and Python 2.0 when Python is compiled with
-cycle garbage collection; this problem was reported fixed in Python 2.1a1.
-
-=item B<--with-innd-port>=PORT
-
-By default, inndstart(8) refuses to bind to any port under 1024 other than
-119 and 433 for security reasons (to prevent attacks on rsh(1)-based
-commands and replacing standard system daemons). If you want to run innd
-on a different port under 1024, you'll need to tell configure what port
-you intend to use. (You'll also still need to set the port number in
-F<inn.conf> or give it to inndstart on the command line.)
-
-=item B<--with-syslog-facility>=FACILITY
-
-Specifies the syslog facility that INN programs should log to. The
-default is LOG_NEWS unless configure detects that your system doesn't
-understand that facility, in which case it uses LOG_LOCAL1. This flag
-overrides the automatic detection. Be sure to specify a facility not used
-by anything else on your system (one of LOG_LOCAL0 through LOG_LOCAL7, for
-example).
-
-=item B<--enable-libtool>
-
-INN has optional support for libtool to generate shared versions of INN's
-libraries. This can significantly decrease the size of the various
-binaries that come with a complete INN installation. You can also choose
-to use libtool even when only building static libraries; a libtool build
-may be somewhat more portable on weird systems. libtool builds aren't the
-default because they take somewhat longer. See C<./configure --help> for
-the various available options related to libtool builds.
-
-Please note that INN's shared library interface is not stable and may
-change drastically in future releases. For this reason, it's also not
-properly versioned and won't be until some degree of stability is
-guaranteed, and the relevant header files are not installed. Only INN
-should use INN's shared libraries, and you should only use the shared
-libraries corresponding to the version of INN that you're installing.
-
-Also, when updating an existing version of INN, INN tries to save backup
-copies of all files so that you can revert to the previous installed
-version. Unfortunately, when using shared libraries, this confuses
-ldconfig on some systems (such as Linux) and the symbolic links for the
-libraries may point to the .OLD versions. If this happens, you can either
-fix the links by hand or remove the .OLD versions and re-run ldconfig.
-
-=item B<--enable-uucp-rnews>
-
-If this option is given to configure, rnews will be installed setuid news,
-owned by group uucp, and mode 4550. This will allow the UUCP subsystem
-to run rnews to process UUCP batches of news articles. Prior to INN 2.3,
-installing rnews setuid news was standard; since most sites no longer use
-UUCP, it is no longer the default as of INN 2.3 and must be requested at
-configure time. You probably don't want to use this option unless your
-server accepts UUCP news batches.
-
-=item B<--enable-setgid-inews>
-
-If this option is given to configure, inews will be installed setgid news
-and world-executable so that non-privileged users on the news server
-machine can use inews to post articles locally (somewhat faster than
-opening a new network connection). For standalone news servers, by far
-the most common configuration now, there's no need to use this option;
-even if you have regular login accounts on your news server, INN's inews
-can post fine via a network connection to your running news server and
-doesn't need to use the local socket (which is what setgid enables it to
-do). Installing inews setgid was the default prior to INN 2.3.
-
-=item B<--with-berkeleydb=PATH>
-
-Enables support for Berkeley DB (2.x or 3.x), which means that it will
-then be possible to use the ovdb overview method if you wish. Enabling
-this configure option doesn't mean you'll be required to use ovdb, but it
-does require that Berkeley DB be installed on your system (including the
-header files, not just the runtime libraries). If a path is given, it
-sets the installed directory of Berkeley DB (configure will search for it
-in some standard locations, but if you have it installed elsewhere, you
-may need this option).
-
-=item B<--with-openssl=PATH>
-
-Enables support for SSL for news reading, which means it will be possible
-to have SSL or TLS encrypted NNTP connections between your server and
-newsreaders. This option requires OpenSSL be installed on your system
-(including the header files, not just the runtime libraries). If a path
-is given, it sets the installed directory of OpenSSL. After compiling and
-installing INN with this option, you'll still need to make a certificate
-and private key to use SSL. See below for details on how to do that.
-
-=item B<--enable-ipv6>
-
-Enables support for IPv6 in innd, innfeed, nnrpd, and several of the
-supporting programs. This option should be considered developmental at
-present. For more information see F<doc/IPv6-info> (and if you have any
-particularly good or bad news to report, please let us know at
-<inn-bugs@isc.org>).
-
-=back
-
-For the most common installation, a standalone news server, a suggested
-set of options is:
-
- ./configure --with-perl
-
-provided that you have the necessary version of Perl installed.
-(Compiling with an embedded Perl interpretor will allow you to use one of
-the available excellent spam filters if you so choose.)
-
-If the configure program runs successfully, then you are ready to build
-the distribution. From the root of the INN source tree, type:
-
- make
-
-At this point you can step away from the computer for a little while and
-have a quick snack while INN compiles. On a decently fast system it
-should only take five or ten minutes at the most to build.
-
-Once the build has completed successfully, you are ready to install INN
-into its final home. Type:
-
- make install
-
-You will need to run this command as root so that INN can create the
-directories it needs, change ownerships (if you did not compile as the
-news user) and install a couple of setuid wrapper programs needed to raise
-resource limits and allow innd to bind to ports under 1024. This step
-will install INN under the install directory (F</usr/local/news>, unless
-you specified something else to the configure script).
-
-If you are configuring SSL support for newsreaders, you must make a
-certificate and private key at least once. Type:
-
- make cert
-
-as root in order to do this.
-
-You are now ready for the really fun part: configuring your copy of INN!
-
-=head1 Choosing an Article Storage Format
-
-The first thing to decide is how INN should store articles on your system.
-There are four different methods for you to choose from, each of which has
-its own advantages and disadvantages. INN can support all four at the
-same time, so you can store certain newsgroups in one method and other
-newsgroups in another method.
-
-The supported storage formats are:
-
-=over 4
-
-=item tradspool
-
-This is the storage method used by all versions of INN previous to 2.0.
-Articles are stored as individual text files whose names are the same as
-the article number. The articles are divided up into directories based on
-the newsgroup name. For example, article 12345 in news.software.nntp
-would be stored as F<news/software/nntp/12345> relative to the root of the
-article spool.
-
-Advantages: Widely used and well-understood storage mechanism, can read
-article spools written by older versions of INN, compatible with all
-third-party INN add-ons, provides easy and direct access to the articles
-stored on your server and makes writing programs that fiddle with the news
-spool very easy, and gives you fine control over article retention times.
-
-Disadvantages: Takes a very fast file system and I/O system to keep up
-with current Usenet traffic volumes due to file system overhead. Groups
-with heavy traffic tend to create a bottleneck because of inefficiencies
-in storing large numbers of article files in a single directory. Requires
-a nightly expire program to delete old articles out of the news spool, a
-process that can slow down the server for several hours or more.
-
-=item timehash
-
-Articles are stored as individual files as in tradspool, but are divided
-into directories based on the arrival time to ensure that no single
-directory contains so many files as to cause a bottleneck.
-
-Advantages: Heavy traffic groups do not cause bottlenecks, and fine
-control of article retention time is still possible.
-
-Disadvantages: The ability to easily find all articles in a given
-newsgroup and manually fiddle with the article spool is lost, and INN
-still suffers from speed degredation due to file system overhead (creating
-and deleting individual files is a slow operation).
-
-=item timecaf
-
-Similar to timehash, articles are stored by arrival time, but instead of
-writing a separate file for each article, multiple articles are put in the
-same file.
-
-Advantages: Roughly four times faster than timehash for article writes,
-since much of the file system overhead is bypassed, while still retaining
-the same fine control over article retention time.
-
-Disadvantages: Even worse than timehash, and similar to cnfs (below),
-using this method means giving up all but the most careful manually
-fiddling with your article spool. As one of the newer and least widely
-used storage types, timecaf has not been as thoroughly tested as the other
-methods.
-
-=item cnfs
-
-CNFS stores articles sequentially in pre-configured buffer files. When
-the end of the buffer is reached, new articles are stored from the
-beginning of the buffer, overwriting older articles.
-
-Advantages: Blazingly fast because no file creations or deletions are
-necessary to store an article. Unlike all other storage methods, does not
-require manual article expiration; old articles are deleted to make room
-for new ones when the buffers get too full. Also, with CNFS your server
-will never throttle itself due to a full spool disk, and groups are
-restricted to just the buffer files you give them so that they can never
-use more than the amount of disk space you allocate to them.
-
-Disadvantages: Article retention times are more difficult to control
-because old articles are overwritten automatically. Attacks on Usenet,
-such as flooding or massive amounts of spam, can result in wanted articles
-expiring much faster than you intended (with no warning).
-
-=back
-
-Some general recommendations: If you are installing a transit news server
-(one that just accepts news and sends it out again to other servers and
-doesn't support any readers), use CNFS exclusively and don't worry about
-any of the other storage methods. Otherwise, put high-volume groups and
-groups whose articles you don't need to keep around very long (binaries
-groups, *.jobs*, news.lists.filters, etc.) in CNFS buffers, and use
-timehash, timecaf, or tradspool (if you have a fast I/O subsystem or need
-to be able to go through the spool manually) for everything else. You'll
-probably find it most convenient to keep special hierarchies like local
-hierarchies and hierarchies that should never expire in tradspool.
-
-If your news server will be supporting readers, you'll also need to choose
-an overview storage mechanism (by setting I<ovmethod> in F<inn.conf>).
-There are three overview mechanisms to choose from: tradindexed,
-buffindexed, and ovdb. tradindexed is very fast for readers, but it has
-to update two files for each incoming article and can be quite slow to
-write. buffindexed can keep up with a large feed more easily, since it
-uses large buffers to store all overview information, but it's somewhat
-slower for readers (although not as slow as the unified overview in INN
-2.2). ovdb stores overview data in a Berkeley DB database; it's fast and
-very robust, but requires more disk space. See the ovdb(5) man page for
-more information on it.
-
-Note that ovdb has not been as widely tested as the other overview
-mechanisms and should be considered experimental. tradindexed is the best
-tested and most widely used of the overview implementations.
-
-If buffindexed is chosen, you will need to create the buffers for it to
-use (very similar to creating CNFS buffers) and list the available buffers
-in F<buffindexed.conf>. See buffindexed.conf(5) for more information.
-
-=head1 Configuring INN
-
-All documentation from this point on assumes that you have set up the news
-user on your system as suggested in L<Installing INN> so that the root of
-your INN installation is F<~news/>. If you've moved things around by
-using options with C<configure>, you'll need to adjust the instructions to
-account for that.
-
-All of INN's configuration files are located in F<~news/etc>. Unless
-noted otherwise, any files referred to below are in this directory. When
-you first install INN, a sample of each file (containing lots of comments)
-is installed in F<~news/etc>; refer to these for concrete examples of
-everything discussed in this section.
-
-All of INN's configuration files, all of the programs that come with it,
-and some of its library routines have documentation in the form of man
-pages. These man pages were installed in F<~news/man> as part of the INN
-installation process and are the most complete reference to how INN works.
-You're strongly encouraged to refer to the man pages frequently while
-configuring INN, and for quick reference afterwards. Any detailed
-questions about individual configuration files or the behavior of specific
-programs should be answered in them. You may want to add F<~news/man> to
-your MANPATH environment variable; otherwise, you may have to use a
-command like:
-
- man -M ~news/man inn.conf
-
-to see the inn.conf(5) man page (for example).
-
-Before we begin, it is worth mentioning the wildmat pattern matching
-syntax used in many configuration files. These are simple wildcard
-matches using the asterisk (C<*>) as the wildcard character, much like the
-simple wildcard expansion used by Unix shells.
-
-In many cases, wildmat patterns can be specified in a comma-separated list
-to indicate a list of newsgroups. When used in this fashion, each pattern
-is checked in turn to see if it matches, and the last pattern in the line
-that matches the group name is used. Patterns beginning with C<!> mean to
-exclude groups matching that pattern. For example:
-
- *, !comp.*, comp.os.*
-
-In this case, we're saying we match everything (C<*>), except that we
-don't match anything under comp (C<!comp.*>), unless it is actually under
-the comp.os hierarchy (C<comp.os.*>). This is because non-comp groups
-will match only the first pattern (so we want them), comp.os groups will
-match all three patterns (so we want them too, because the third pattern
-counts in this case), and all other comp groups will match the first and
-second patterns and will be excluded by the second pattern.
-
-Some uses of wildmat patterns also support "poison" patterns (patterns
-starting with C<@>). These patterns behave just like C<!> patterns when
-checked against a single newsgroup name. Where they become special is for
-articles crossposted to multiple newsgroups; normally, such an article
-will be considered to match a pattern if any of the newsgroups it is
-posted to matches the pattern. If any newsgroup the article is posted to
-matches an expression beginning with C<@>, however, that article will not
-match the pattern even if other newsgroups to which it was posted match
-other expressions.
-
-See uwildmat(3) for full details on wildmat patterns.
-
-In all INN configuration files, blank lines and lines beginning with a
-C<#> symbol are considered comments and are ignored. Be careful, not all
-files permit comments to begin in the middle of the line.
-
-=head2 inn.conf
-
-The first, and most important file is F<inn.conf>. This file is organized
-as a series of parameter-value pairs, one per line. The parameter is
-first, followed by a colon and one or more whitespace characters, and then
-the value itself. For some parameters the value is a string or a number;
-for others it is true or false. (True values can be written as C<yes>,
-C<true>, or C<on>, whichever you prefer. Similarly, false values can be
-written as C<no>, C<false>, or C<off>.)
-
-F<inn.conf> contains dozens of changeable parameters (see inn.conf(5) for
-full details), but only a few really need to be edited during normal
-operation:
-
-=over 4
-
-=item allownewnews
-
-If set to true then INN will support the NEWNEWS command for news readers.
-While this can be an expensive operation, its speed has been improved
-considerably as of INN 2.3 and it's probably safe to turn on without
-risking excessive server load. The default is true. (Note that the
-I<access:> setting in F<readers.conf> overrides this value; see
-readers.conf(5) for more details.)
-
-=item complaints
-
-Used to set the value of the X-Complaints-To: header, which is added to
-all articles posted locally. The usual value would be something like
-C<abuse@example.com> or C<postmaster@example.com>. If not specified, the
-newsmaster email address will be used.
-
-=item hiscachesize
-
-The amount of memory (in kilobytes) to allocate for a cache of recently
-used history file entries. Setting this to 0 disables history caching.
-History caching can greatly increase the number of articles per second
-that your server is capable of processing. A value of C<256> is a good
-default choice.
-
-=item logipaddr
-
-If set to true (the default), INN will log the IP address (or hostname, if
-the host is listed in F<incoming.conf> with a hostname) of the remote host
-from which it received an article. If set to false, the trailing Path:
-header entry is logged instead. If you are using controlchan (see below)
-and need to process ihave/sendme control messages (this is very, very
-unlikely, so if you don't know what this means, don't worry about it),
-make sure you set this to false, since controlchan needs a site name, not
-an IP address.
-
-=item organization
-
-Set this to the name of your organization as you want it to appear in the
-Organization: header of all articles posted locally and not already
-containing that header. This will be overridden by the value of the
-ORGANIZATION environment variable (if it exists). If neither this
-parameter nor the environment variable or set, no Organization: header
-will be added to posts which lack one.
-
-=item pathhost
-
-This is the name of your news server as you wish it to appear in the Path:
-header of all postings which travel through your server (this includes
-local posts and incoming posts that you forward out to other sites). If
-this parameter is unspecified, the fully-qualified domain name (FQDN) of
-the machine will be used instead. Please use the FQDN of your server or
-an alias for your server unless you have a very good reason not to; a
-future version of the news RFCs may require this.
-
-=item rlimitnofile
-
-If set to a non-negative value (the default is C<-1>), INN (both innd and
-innfeed) will try to raise the maximum number of open file descriptors to
-this value when it starts. This may be needed if you have lots of
-incoming and outgoing feeds. Note that the maximum value for this setting
-is very operating-system-dependent, and you may have to reconfigure your
-system (possibly even recompile your kernel) to increase it. See L<File
-Descriptor Limits> for complete details.
-
-=back
-
-There are tons of other possible settings; you may want to read through
-inn.conf(5) to get a feel for your options. Don't worry if you don't
-understand the purpose of most of them right now. Some of the settings
-are only needed for very obscure things, and with more experience running
-your news server the rest will make more sense.
-
-=head2 newsfeeds
-
-F<newsfeeds> determines how incoming articles are redistributed to your
-peers and to other INN processes. F<newsfeeds> is very versatile and
-contains dozens of options; we will touch on just the basics here.
-The manpage contains more detailed information.
-
-F<newsfeeds> is organized as a series of feed entries. Each feed entry is
-composed of four fields separated by colons. Entries may span multiple
-lines by using a backslash (C<\>) to indicate that the next line is a
-continuation of the current line. (Note that comments don't interact with
-backslashes in the way you might expect. A commented-out line ending in a
-backslash will still be considered continued on the next line, possibly
-resulting in more commented out than you intended or bizarre syntax
-errors. In general, it's best to avoid commenting out lines in the middle
-of continuation lines.)
-
-The first field in an entry is the name of the feed. It must be unique,
-and for feeds to other news servers it is usually set to the actual
-hostname of the remote server (this makes things easier). The name can
-optionally be followed by a slash and a comma-separated exclude list. If
-the feed name or any of the names in the exclude list appear in the Path
-line of an article, then that article will not be forwarded to the feed as
-it is assumed that it has passed through that site once already. The
-exclude list is useful when a news server's hostname is not the same as
-what it puts in the Path header of its articles, or when you don't want a
-feed to receive articles from a certain source.
-
-The second field specifies a set of desired newsgroups and distribution
-lists, given as newsgroup-pattern/distribution-list. The distribution
-list is not described here; see newsfeeds(5) for information (it's not
-used that frequently in practice). The newsgroup pattern is a
-wildmat-style pattern list as described above (supporting C<@>).
-
-The third field is a comma-separated list of flags that determine both the
-type of feed entry and sets certain parameters for the entry. See
-newsfeeds(5) for information on the flag settings; you can do a surprising
-amount with them. The three most common patterns, and the ones mainly
-used for outgoing news feeds to other sites, are C<Tf,Wnm> (to write out a
-batch file of articles to be sent, suitable for processing by nntpsend and
-innxmit), C<Tm> (to send the article to a funnel feed, used with innfeed),
-and C<Tc,Wnm*> (to collect a funnel feed and send it via a channel feed to
-an external program, used to send articles to innfeed).
-
-The fourth field is a multi-purpose parameter whose meaning depends on the
-settings of the flags in the third field. To get a feel for it using the
-examples above, for file feeds (C<Tf>) it's the name of the file to write,
-for funnel feeds (C<Tm>) it's the name of the feed entry to funnel into,
-and for channel feeds (C<Tc>) it's the name of the program to run and feed
-references to articles.
-
-Now that you have a rough idea of the file layout, we'll begin to add the
-actual feed entries. First, we'll set up the special ME entry. This entry
-is required and serves two purposes: the newsgroup pattern specified here
-is prepended to the newsgroup list of all other feeds, and the
-distribution pattern for this entry determines what distributions (from
-the Distribution: header of incoming articles) are accepted from remote
-sites by your server. The example in the sample newsfeeds file is a good
-starting point. If you are going to create a local hierarchy that should
-not be distributed off of your system, it may be useful to exclude it from
-the default subscription pattern, but default subscription patterns are
-somewhat difficult to use right so you may want to just exclude it
-specifically from every feed instead.
-
-The ME entry tends to confuse a lot of people, so this point is worth
-repeating: the newsgroup patterns set the default subscription for
-I<outgoing> feeds, and the distribution patterns set the acceptable
-Distribution: header entries for I<incoming> articles. This is confusing
-enough that it may change in later versions of INN.
-
-There are two basic ways to feed articles to remote sites. The most
-common for large sites and particularly for transit news servers is
-innfeed(8), which sends articles to remote sites in real time (the article
-goes out to all peers that are supposed to receive it immediately after
-your server accepts it). For smaller sites, particularly sites where the
-only outgoing messages will be locally posted articles, it's more common
-to batch outgoing articles and send them every ten minutes or so from cron
-using nntpsend(8) and innxmit(8). Batching gives you more control and
-tends to be extremely stable and reliable, but it's much slower and can't
-handle high volume very well.
-
-Batching outgoing posts is easy to set up; for each peer, add an entry to
-newsfeeds that looks like:
-
- remote.example.com/news.example.com\
- :<newsgroups>\
- :Tf,Wnm:
-
-where <newsgroups> is the wildmat pattern for the newsgroups that site
-wants. In this example, the actual name of the remote site is
-"remote.example.com", but it puts "news.example.com" in the Path: header.
-If the remote site puts its actual hostname in the Path: header, you won't
-need the C</news.example.com> part.
-
-This entry will cause innd to write out a file in F<~news/spool/outgoing>
-named F<remote.example.com> and containing the Message-ID and storage
-token of each message to send to that site. (The storage token is INN's
-internal pointer to where an article is stored; to retrieve an article
-given its storage token, use sm(8)). F<innxmit> knows how to read files
-of this format and send those articles to the remote site. For
-information on setting it up to run periodically, see L<Setting Up the
-Cron Jobs> below. You will also need to set up a config file for
-F<nntpsend>; see the man page for nntpsend.ctl(5) for more information.
-
-If instead you want to use F<innfeed> to send outgoing messages
-(recommended for sites with more than a couple of peers), you need some
-slightly more complex magic. You still set up a separate entry for each
-of your peers, but rather than writing out batch files, they all "funnel"
-into a special innfeed entry. That special entry collects all of the
-separate funnel feeds and sends the data through a special sort of feed to
-an external program (F<innfeed> in this case); this is a "channel" feed.
-
-First, the special channel feed entry for F<innfeed> that will collect all
-the funnel feeds:
-
- innfeed!\
- :!*\
- :Tc,Wnm*:/usr/local/news/bin/startinnfeed -y
-
-(adjust the path to startinnfeed(1) if you installed it elsewhere). Note
-that we don't feed this entry any articles directly (its newsgroup pattern
-is C<!*>). Note also that the name of this entry ends in an exclamation
-point. This is a standard convention for all special feeds; since the
-delimiter for the Path: header is C<!>, no site name containing that
-character can ever match the name of a real site.
-
-Next, set up entries for each remote site to which you will be feeding
-articles. All of these entries should be of the form:
-
- remote.example.com/news.example.com\
- :<newsgroups>\
- :Tm:innfeed!
-
-specifying that they funnel into the C<innfeed!> feed. As in the previous
-example for batching, "remote.example.com" is the actual name of the
-remote peer, "news.example.com" is what it puts in the Path: header (if
-different than the actual name of the server), and <newsgroups> is the
-wildmat pattern of newsgroups to be sent.
-
-As an alternative to NNTP, INN may also feed news out to an IMAP server,
-by using imapfeed(8), which is almost identical to F<innfeed>. The
-F<startinnfeed> process can be told to start F<imapfeed> instead of
-F<innfeed>. The feed entry for this is as follows:
-
- imapfeed!\
- :!*\
- :Tc,Wnm*,S16384:/usr/local/news/bin/startinnfeed imapfeed
-
-And set up entries for each remote site like:
-
- remote.example.com/news.example.com\
- :<newsgroups>\
- :Tm:imapfeed!
-
-For more information on F<imapfeed>, look at the
-F<innfeed/imap_connection.c>. For more information on IMAP in general,
-see RFC 2060.
-
-Finally, there is a special entry for controlchan(8), which processes
-newsgroup control messages, that should always be in F<newsfeeds> unless
-you never want to honor any control messages. This entry should look
-like:
-
- controlchan!\
- :!*,control,control.*,!control.cancel\
- :Tc,Wnsm:/usr/local/news/bin/controlchan
-
-(modified for the actual path to F<controlchan> if you put it somewhere
-else). See L<Processing Control Messages> for more details.
-
-For those of you upgrading from earlier versions of INN, note that the
-functionality of overchan(8) and F<crosspost> is now incorporated into INN
-and neither of those programs is necessary. Unfortunately, F<crosspost>
-currently will not work even with the tradspool storage method. You can
-still use F<overchan> if you make sure to set I<useoverchan> to true in
-F<inn.conf> so that innd doesn't write overview data itself, but be
-careful: innd may accept articles faster than overchan can process the
-data.
-
-=head2 incoming.conf
-
-F<incoming.conf> file specifies which machines are permitted to connect to
-your host and feed it articles. Remote servers you peer with should be
-listed here. Connections from hosts not listed in this file will (if you
-don't allow readers) be rejected or (if you allow readers) be handed off
-to nnrpd and checked against the access restrictions in F<readers.conf>.
-
-Start with the sample F<incoming.conf> and, for each remote peer, add an
-entry like:
-
- peer remote.example.com { }
-
-This uses the default parameters for that feed and allows incoming
-connections from a machine named "remote.example.com". If that peer could
-be connecting from several different machines, instead use an entry like:
-
- peer remote.example.com {
- hostname: "remote.example.com, news.example.com"
- }
-
-This will allow either "remote.example.com" or "news.example.com" to feed
-articles to you. (In general, you should add new peer lines for each
-separate remote site you peer with, and list multiple host names using the
-I<hostname> key if one particular remote site uses multiple servers.)
-
-You can restrict the newsgroups a remote site is allowed to send you,
-using the same sort of pattern that newsfeeds(5) uses. For example, if
-you want to prevent "example.com" hosts from sending you any articles in
-the C<local.*> hierarchy (even if they're crossposted to other groups),
-change the above to:
-
- peer remote.example.com {
- patterns: "*, @local.*"
- hostname: "remote.example.com, news.example.com"
- }
-
-Note, however, that restricting what a remote side can send you will
-I<not> reduce your incoming bandwidth usage. The remote site will still
-send you the entire article; INN will just reject it rather than saving it
-to disk. To reduce bandwidth, you have to contact your peers and ask them
-not to send you the traffic you don't want.
-
-There are various other things you can set, including the maximum number
-of connections the remote host will be allowed. See incoming.conf(5) for
-all the details.
-
-Note for those familiar with older versions of INN: this file replaces
-the old F<hosts.nntp> configuration file.
-
-=head2 cycbuff.conf
-
-F<cycbuff.conf> is only required if CNFS is used. If you aren't using
-CNFS, skip this section.
-
-CNFS stores articles in logical objects called I<metacycbuffs>. Each
-metacycbuff is in turn composed of one or more physical buffers called
-I<cycbuffs>. As articles are written to the metacycbuff, each article is
-written to the next cycbuff in the list in a round-robin fashion (unless
-C<sequential> mode is specified, in which case each cycbuff is filled
-before moving on to the next). This is so that you can distribute the
-individual cycbuffs across multiple physical disks and balance the load
-between them.
-
-There are two ways to create your cycbuffs:
-
-=over 4
-
-=item 1.
-
-Use a block device directly. This will probably give you the most speed
-since it avoids the file system overhead of large files, but it requires
-your OS support mmap(2) on a block device. Solaris supports this, as do
-late Linux 2.4 kernels. FreeBSD does not at last report. Also on many
-PC-based Unixes it is difficult to create more than eight partitions,
-which may limit your options.
-
-=item 2.
-
-Use a real file on a filesystem. This will probably be a bit slower than
-using a block device directly, but it should work on any Unix system.
-
-=back
-
-If you're having doubts, use option #2; it's easier to set up and should
-work regardless of your operating system.
-
-Now you need to decide on the sizes of your cycbuffs and metacycbuffs.
-You'll probably want to separate the heavy-traffic groups
-(C<alt.binaries.*> and maybe a few other things like C<*.jobs*> and
-C<news.lists.filters>) into their own metacycbuff so that they don't
-overrun the server and push out articles on the more useful groups. If
-you have any local groups that you want to stay around for a while then
-you should put them in their own metacycbuff as well, so that they don't
-get pushed out by other traffic. (Or you might store them in one of the
-other storage methods, such as tradspool.)
-
-For each metacycbuff, you now need to determine how many cycbuffs will
-make up the metacycbuff, the size of those cycbuffs, and where they will
-be stored. Some OSes do not support files larger than 2 GB, which will
-limit the size you can make a single cycbuff, but you can still combine
-many cycbuffs into each metacycbuff. Older versions of Linux are known to
-have this limitation; FreeBSD does not. Some OSes that support large
-files don't support direct access to block devices for large partitions
-(Solaris prior to Solaris 7, or not running in 64-bit mode, is in this
-category); on those OSes, if you want cycbuffs over 2 GB, you'll have to
-use regular files. If in doubt, keep your cycbuffs smaller than 2 GB.
-Also, when laying out your cycbuffs, you will want to try to arrange them
-across as many physical disks as possible (or use a striped disk array and
-put them all on that).
-
-In order to use any cycbuff larger than 2 GB, you need to build INN with
-the B<--enable-largefiles> option. See L<Installing INN> for more
-information and some caveats.
-
-For each cycbuff you will be creating, add a line to F<cycbuff.conf> like
-the following:
-
- cycbuff:NAME:/path/to/buffer:SIZE
-
-NAME must be unique and must be at most seven characters long. Something
-simple like "BUFF00", "BUFF01", etc. is a decent choice, or you may want
-to use something that includes the SCSI target and slice number of the
-partition. SIZE is the buffer size in kilobytes (if you're trying to stay
-under 2 GB, keep your sizes below C<2097152>).
-
-Now, you need to tell INN how to group your cycbuffs into metacycbuffs.
-This is similar to creating cycbuff entries:
-
- metacycbuff:BUFFNAME:CYCBUFF,CYCBUFF,CYCBUFF
-
-BUFFNAME is the name of the metacycbuff and must be unique and at most
-eight characters long. These should be a bit more meaningful than the
-cycbuff names since they will be used in other config files as well. Try
-to name them after what will be stored in them; for example, if this
-metacycbuff will hold alt.binaries postings, "BINARIES" would be a good
-choice. The last part of the entry is a comma-separated list of all of
-the cycbuffs that should be used to build this metacycbuff. Each cycbuff
-should only appear in one metacycbuff line, and all metacycbuff lines must
-occur after all cycbuff lines in the file.
-
-If you want INN to fill each cycbuff before moving on to the next one
-rather than writing to them round-robin, add C<:SEQUENTIAL> to the end of
-the metacycbuff line. This may give noticeably better performance when
-using multiple cycbuffs on the same spindle (such as partitions or slices
-of a larger disk), but will probably give worse performance if your
-cycbuffs are spread out across a lot of spindles.
-
-By default, CNFS data is flushed to disk every 25 articles. If you're
-running a small server with a light article load, this could mean losing
-quite a few articles in a crash. You can change this interval by adding a
-cycbuffupdate line to your F<cycbuff.conf> file; see cycbuff.conf(5) for
-more details.
-
-Finally, you have to create the cycbuffs. See L<Creating the Article
-Spool> for more information on how to do that.
-
-=head2 storage.conf
-
-F<storage.conf> determines where incoming articles will be stored (what
-storage method, and in the case of CNFS, what metacycbuff). Each entry in
-the file defines a storage class for articles. The first matching storage
-class is used to store the article; if no storage class matches, INN will
-reject that article. (This is almost never what you want, so make sure
-this file ends in a catch-all entry that will match everything.)
-
-A storage class definition looks like this:
-
- method <methodname> {
- newsgroups: <wildmat>
- class: <storage_class>
- size: <minsize>[,<maxsize>]
- expires: <mintime>[,<maxtime>]
- options: <options>
- }
-
-<methodname> is the name of the storage method to use to store articles in
-this class ("cnfs", "timehash", "timecaf", "tradspool", or the special
-method "trash" that accepts the article and throws it away).
-
-The first parameter is a wildmat pattern in the same format used by the
-newsfeeds(5) file, and determines what newsgroups are accepted by this
-storage class.
-
-The second parameter is a unique number identifying this storage class and
-should be between 0 and 255. It can be used to control article
-expiration, and for timehash and timecaf will set the top-level directory
-in which articles accepted by this storage class are stored. The easiest
-way to deal with this parameter is to just number all storage classes in
-F<storage.conf> sequentially. The assignment of a particular number to a
-storage class is arbitrary but I<permanent> (since it is used in storage
-tokens).
-
-The third parameter can be used to accept only articles in a certain size
-range into this storage class. A <maxsize> of C<0> (or a missing
-<maxsize>) means no upper limit (and of course a <minsize> of C<0> would
-mean no lower limit, because all articles are more than zero bytes long).
-If you don't want to limit the size of articles accepted by this storage
-class, leave this parameter out entirely.
-
-The fourth parameter you probably don't want to use; it lets you assign
-storage classes based on the Expires: header of incoming articles. The
-exact details are in storage.conf(5). It's very easy to use this
-parameter incorrectly; leave it out entirely unless you've read the man
-page and know what you're doing.
-
-The fifth parameter is the options parameter. Currently only CNFS uses
-this field; it should contain the name of the metacycbuff used to store
-articles in this storage class.
-
-If you're using CNFS exclusively, just create one storage class for each
-metacycbuff that you have defined in F<cycbuff.conf> and set the
-newsgroups pattern according to what newsgroups should be stored in that
-buffer.
-
-If you're using timehash or timecaf, the storage class IDs are used to
-store articles in separate directory trees, which you can take advantage
-of to put particular storage classes on different disks. Also, currently
-storage class is the only way to specify expiration time, so you will need
-to divide up your newsgroups based on how long you want to retain articles
-in those groups and create a storage class for each such collection of
-newsgroups. Make note of the storage class IDs you assign as they will be
-needed when you edit F<expire.ctl> a bit later.
-
-=head2 expire.ctl
-
-F<expire.ctl> sets the expiration policy for articles stored on the
-server. Be careful, since the default configuration will expire most
-articles after 10 days; in most circumstances this deletion is
-I<permanent>, so read this whole section carefully if you want to keep
-local hierarchies forever. (See archive(8) for a way to automate backups
-of important articles.)
-
-Only one entry is required for all storage classes; it looks like:
-
- /remember/:10
-
-This entry says how long to keep the Message-IDs for articles that have
-already expired in the history file so that the server doesn't accept them
-again. Occasionally, fairly old articles will get regurgitated somewhere
-and offered to you again, so even after you've expired articles from your
-spool, you want to keep them around in your history file for a little
-while to ensure you don't get duplicates.
-
-INN will reject any articles more than a certain number of days old (the
-I<artcutoff> parameter in F<inn.conf>, defaulting to C<10>); the number on
-the C</remember/> line should match that.
-
-CNFS makes no further use of F<expire.ctl>, since articles stored in CNFS
-buffers expire automatically when the buffer runs out of free space (but
-see the C<-N> option in expireover(8) if you really want to expire them
-earlier). For other storage methods, there are two different syntaxes of
-this file, depending on I<groupbaseexpiry> in F<inn.conf>. If it is set
-to false, F<expire.ctl> takes entries of the form:
-
- <storage_class>:<keep>:<default>:<purge>
-
-<storage_class> is the number assigned to a storage class in
-F<storage.conf>. <default> is the number of days to keep normal articles
-in that storage class (decimal values are allowed). For articles that
-don't have an Expires: header, those are the only two values that matter.
-For articles with an Expires: header, the other two values come into play;
-the date given in the Expires: header of an article will be honored,
-subject to the contraints set by <keep> and <purge>. All articles in this
-storage class will be kept for at least <keep> days, regardless of their
-Expires: headers, and all articles in this storage class will be expired
-after <purge> days, even if their Expires: headers specify a longer life.
-
-All three of these fields can also contain the special keyword C<never>.
-If <default> is C<never>, only articles with explicit Expires: headers
-will ever be expired. If <keep> is C<never>, articles with explicit
-Expires: headers will be kept forever. Setting <purge> to C<never> says
-to honor Expires: headers even if they specify dates far into the future.
-(Note that if <keep> is set to C<never>, all articles with Expires:
-headers are kept forever and the value of <purge> is not used.)
-
-If the value of C<groupbaseexpiry> is true, F<expire.ctl> takes entries of
-the form:
-
- <wildmat>:<flag>:<keep>:<default>:<purge>
-
-<wildmat> is a wildmat expression (C<!> and C<@> not permitted, and only a
-single expression, not a comma-separated set of them). Each expiration
-line applies to groups matching the wildmat expression. <flag> is C<M>
-for moderated groups, C<U> for unmoderated groups, and C<A> for groups
-with any moderation status; the line only matches groups with the
-indicated expiration status. All of the other fields have the same
-meaning as above.
-
-=head2 readers.conf
-
-Provided that I<noreader> is set to false in F<inn.conf>, any connection
-from a host that doesn't match an entry in F<incoming.conf> (as well as
-any connection from a host that does match such an entry, but has issued a
-MODE READER command) will be handed off to nnrpd(8), the part of INN that
-supports newsreading clients. nnrpd uses F<readers.conf> to determine
-whether a given connection is allowed to read news, and if so what
-newsgroups the client can read and post to.
-
-There are a variety of fairly complicated things that one can do with
-F<readers.conf>, things like run external authentication programs that can
-query RADIUS servers. See readers.conf(5) and the example file for all
-the gory details. Here's an example of probably the simplest reasonable
-configuration, one that only allows clients in the example.com domain to
-read from the server and allows any host in that domain to read and post
-to all groups:
-
- auth "example.com" {
- hosts: "example.com, *.example.com"
- default: "<user>"
- default-domain: "example.com"
- }
-
- access "all" {
- users: "*@example.com"
- newsgroups: "*"
- }
-
-If you're running a server for one particular domain, want to allow all
-hosts within that domain to read and post to any group on the server, and
-want to deny access to anyone outside that domain, just use the above and
-change C<example.com> in the above to your domain and you're all set.
-Lots of examples of more complicated things are in the sample file.
-
-=head1 Creating the Article Spool (CNFS only)
-
-If you are using actual files as your CNFS buffers, you will need to
-pre-create those files, ensuring they're the right size. The easiest way
-to do this is with dd. For each cycbuff in F<cycbuff.conf>, create the
-buffer with the following commands (as the news user):
-
- dd if=/dev/zero of=/path/to/buffer bs=1k count=BUFFERSIZE
- chmod 664 /path/to/buffer
-
-Substitute the correct path to the buffer and the size of the buffer as
-specified in F<cycbuff.conf>. This will create a zero-filled file of the
-correct size; it may take a while, so be prepared to wait.
-
-Here's a command that will print out the dd(1) commands that you should
-run:
-
- awk -F: \
- '/^cy/ { printf "dd if=/dev/zero of=%s bs=1k count=%s\n", $3, $4 }' \
- ~news/etc/cycbuff.conf
-
-If you are using block devices, you don't technically have to do anything
-at all (since INN is capable of using the devices in F</dev>), but you
-probably want to create special device files for those devices somewhere
-for INN's private use. It s more convenient to keep all of INN's stuff
-together, but more importantly, the device files used by INN really should
-be owned by the news user and group, and you may not want to do that with
-the files in F</dev>.
-
-To create the device files for INN, use mknod(8) with a type of C<b>,
-getting the major and minor device numbers from the existing devices in
-F</dev>. There's a small shell script in cycbuff.conf(5) that may help
-with this. Make sure to create the device files in the location INN
-expects them (specified in F<cycbuff.conf>).
-
-Solaris users please note: on Solaris, do not use block devices that
-include the first cylinder of the disk. Solaris doesn't protect the
-superblock from being overwritten by an application writing to block
-devices and includes it in the first cylinder of the disk, so unless you
-use a slice that starts with cylinder 1 instead of 0, INN will invalidate
-the partition table when it tries to initialize the cycbuff and all
-further accesses will fail until you repartition.
-
-=head1 Creating the Database Files
-
-At this point, you need to set up the news database directory
-(F<~news/db>). This directory will hold the active(5) file (the list of
-newsgroups you carry), the active.times(5) file (the creator and creation
-time of newsgroups created since the server was initialized), the
-newsgroups(5) file (descriptions for all the newsgroups you carry), and
-the history(5) file (a record of every article the server currently has or
-has seen in the past few days, used to decide whether to accept or refuse
-new incoming messages).
-
-Before starting to work on this, make sure you're logged on as the news
-user, since all of these files need to be owned by that user. This is a
-good policy to always follow; if you are doing any maintenance work on
-your news server, log on as the news user. Don't do maintenance work as
-root. Also make sure that F<~news/bin> is in the default path of the news
-user (and while you're at it, make sure F<~news/man> is in the default
-MANPATH) so that you can run INN maintenance commands without having to
-type the full path.
-
-If you already have a server set up (if you're upgrading, or setting up a
-new server based on an existing server), copy F<active> and F<newsgroups>
-from that server into F<~news/db>. Otherwise, you'll need to figure out
-what newsgroups you want to carry and create new active and newsgroups
-files for them. If you plan to carry a full feed, or something close to
-that, go to <ftp://ftp.isc.org/pub/usenet/CONFIG/> and download F<active>
-and F<newsgroups> from there; that will start you off with reasonably
-complete files. If you plan to only carry a small set of groups, the
-default minimal F<active> file installed by INN is a good place to start;
-you can create additional groups after the server is running by using
-C<ctlinnd newgroup>. (Another option is to use actsync(8) to synchronize
-your newsgroup list to that of another server.)
-
-C<control> and C<junk> must exist as newsgroups in your active file for
-INN to start, and creating pseudogroups for the major types of control
-messages is strongly encouraged for all servers that aren't standalone.
-If you don't want these groups to be visible to clients, do I<not> delete
-them; simply hide them in F<readers.conf>. C<to> must also exist as a
-newsgroup if you have mergetogroups set in F<inn.conf>.
-
-Next, you need to create an empty history database. To do this, type:
-
- cd ~news/db
- touch history
- makedbz -i
-
-When it finishes, rename the files it created to remove the C<.n> in the
-file names and then make sure the file permissions are correct on all the
-files you've just created:
-
- chmod 644 *
-
-Your news database files are now ready to go.
-
-=head1 Configuring syslog
-
-While some logs are handled internally, INN also logs a wide variety of
-information via syslog. INN's nightly report programs know how to roll
-and summarize those syslog log files, but when you first install INN you
-need to set them up.
-
-If your system understands the C<news> syslog facility, INN will use it;
-otherwise, it will log to C<local1>. Nearly every modern system has a
-C<news> syslog facility so you can safely assume that yours does, but if
-in doubt take a look at the output from running C<configure>. You should
-see a line that looks like:
-
- checking log level for news... LOG_NEWS
-
-If that says LOG_LOCAL1 instead, change the below instructions to use
-C<local1> instead of C<news>.
-
-Edit F</etc/syslog.conf> on your system and add lines that look like the
-following:
-
- news.crit /usr/local/news/log/news.crit
- news.err /usr/local/news/log/news.err
- news.notice /usr/local/news/log/news.notice
-
-(Change the path names as necessary if you installed INN in a different
-location than F</usr/local/news>.) These lines I<must> be tab-delimited,
-so don't copy and paste from these instructions. Type it in by hand and
-make sure you use a tab, or you'll get mysterious failures. You'll also
-want to make sure that news log messages don't fill your other log files
-(INN generates a lot of log traffic); so for every entry in
-F</etc/syslog.conf> that starts with C<*>, add C<;news.none> to the end of
-the first column. For example, if you have a line like:
-
- *.err /dev/console
-
-change it to:
-
- *.err;news.none /dev/console
-
-(You can choose not to do this for the higher priority log messages, if
-you want to make sure they go to your normal high-priority log files as
-well as INN's. Don't bother with anything lower priority than C<crit>,
-though. C<news.err> isn't interesting enough to want to see all the
-time.) Now, make sure that the news log files exist; syslog generally
-won't create files automatically. Enter the following commands:
-
- touch /usr/local/news/log/news.crit
- touch /usr/local/news/log/news.err
- touch /usr/local/news/log/news.notice
- chown news /usr/local/news/log/news.*
- chgrp news /usr/local/news/log/news.*
-
-(again adjusting the paths if necessary for your installation). Finally,
-send a HUP signal to syslogd to make it re-read its configuration file.
-
-=head1 Setting Up the Cron Jobs
-
-INN requires a special cron job to be set up on your system to run
-news.daily(8) which performs daily server maintenance tasks such as
-article expiration and the processing and rotation of the server logs.
-Since it will slow the server down while it is running, it should be run
-during periods of low server usage, such as in the middle of the night.
-To run it at 3am, for example, add the following entry to the news user's
-crontab file:
-
- 0 3 * * * /usr/local/news/bin/news.daily expireover lowmark
-
-or, if your system does not have per-user crontabs, put the following line
-into your system crontab instead:
-
- 0 3 * * * su -c "/usr/local/news/bin/news.daily expireover lowmark" news
-
-If you're using any non-CNFS storage methods, add C<delayrm> to the above
-option list for news.daily.
-
-The news user obviously must be able to run cron jobs. On Solaris, this
-means that it must have a valid F</etc/shadow> entry and must not be
-locked (although it may be a non-login account). There may be similar
-restrictions with other operating systems.
-
-If you use the batching method to send news, also set up a cron job to run
-nntpsend(8) every ten minutes. nntpsend will run innxmit for all
-non-empty pending batch files to send pending news to your peers. That
-cron entry should look something like:
-
- 0,10,20,30,40,50 * * * * /usr/local/news/bin/nntpsend
-
-The pathnames and user ID used above are the installation defaults; change
-them to match your installation if you used something other than the
-defaults.
-
-The parameters passed to news.daily in the above example are the most
-common (and usually the most efficient) ones to use. More information on
-what these parameters do can be found in the news.daily(8) man page.
-
-=head1 File Descriptor Limits
-
-INN likes to use a lot of file descriptors, particularly if you have a lot
-of peers. Depending on what your system defaults are, you may need to
-make sure the default limit is increased for INN (particularly for innd
-and innfeed). This is vital on Solaris, which defaults (at least as of
-2.6) to an absurdly low limit of 64 file descriptors per process.
-
-One way to increase the number of file descriptors is to set
-I<rlimitnofile> in F<inn.conf> to a higher value. This will cause both
-startinnfeed and inndstart (the setuid root wrapper scripts that start
-innfeed and innd, respectively) to increase the file descriptor limits
-before they run the regular INN programs. Note, however, that INN won't
-be able to increase the limits above the hard limits set by your operating
-system; on some systems, that hard limit is normally 256 file descriptors
-(Linux, for example). On others, like Solaris, it's 1024. Increasing the
-limit beyond that value may require serious system configuration work.
-(On some operating systems, it requires patching and recompiling the
-kernel. On Solaris it can be changed in F</etc/system>, but for 2.6 or
-earlier the limit cannot be increased beyond 1024 without breaking
-select(2) and thereby breaking all of INN. For current versions of Linux,
-you may be able to change the maximum by writing to
-F</proc/sys/fs/file-max>.)
-
-256 file descriptors will probably be enough for all but the largest
-sites. There is no harm in setting the limits higher than you actually
-need (provided they're set to something lower than or equal to your system
-hard limit). C<256> is therefore a reasonable value to try.
-
-If you're installing INN on a Solaris system, particularly if you're
-installing it on a dedicated news server machine, it may be easier to just
-increase the default file descriptor limit across the board for all
-processes. You can do that by putting the line:
-
- set rlim_fd_cur = 256
-
-in F</etc/system> and rebooting. You can increase it all the way to
-C<1024> (and may need to if you have a particularly large site), but that
-can cause RPC and some stdio applications to break. It therefore probably
-isn't a good idea on a machine that isn't dedicated to INN.
-
-=head1 Starting and Stopping the System
-
-INN is started via the shell script F<rc.news>. This must be run as the
-news user and not as root. To start INN on system boot, you therefore
-want to put something like:
-
- su - news -c /usr/local/news/bin/rc.news
-
-in the system boot scripts. If innd is stopped or killed, you can restart
-it by running rc.news by hand as the news user.
-
-The rc.news script may also be used to shut down INN, with the C<stop>
-option:
-
- su - news -c '/usr/local/news/bin/rc.news stop'
-
-In the F<contrib> directory of this source tree is a sample init script
-for people using System V-style init.d directories.
-
-=head1 Processing Newsgroup Control Messages
-
-Control messages are specially-formatted messages that tell news servers
-to take various actions. Cancels (commands to delete messages) are
-handled internally by INN, and all other control messages are processed by
-controlchan. controlchan should be run out of F<newsfeeds> if you want
-your news server to process any control messages; see L<Configuring INN>
-for specific instructions.
-
-The actions of controlchan are determined by F<control.ctl>, which lists
-who can perform what actions. The primary control messages to be
-concerned with are C<newgroup> (to create a newsgroup), C<rmgroup> (to
-remove a newsgroup), and C<checkgroups> (to compare the list of groups
-carried in a hierarchy to a canonical list). INN comes with a
-F<control.ctl> file that processes control messages in most major public
-hierarchies; if you don't want to act on all those control messages, you
-should remove from that file all entries for hierarchies you don't want to
-carry.
-
-You can tell INN to just authenticate control messages based on the From
-header of the message, but this is obviously perilous and control messages
-are widely forged. Many hierarchies sign all of their control messages
-with PGP, allowing news servers to verify their authenticity, and checking
-those signatures for hierarchies that use them is highly recommended.
-controlchan knows how to do this (using pgpverify) without additional
-configuration, but you do have to provide it with a public key ring
-containing the public keys of all of the hierarchy administrators whose
-control messages you want to check.
-
-INN expects the public key ring to either be in the default location for a
-PGP public key ring for the news user (generally ~news/.gnupg for GnuPG
-and ~news/.pgp for old PGP implementations), or in pathetc/pgp
-(/usr/local/news/etc/pgp by default). The latter is the recommended path.
-To add a key to that key ring, use:
-
- gpg --import --homedir=/usr/local/news/etc/pgp <file>
-
-where <file> is a file containing the hierarchy key. Change the homedir
-setting to point to pathetc/pgp if you have INN installed in a non-default
-location. If you're using the old-style PGP program, an equivalent
-command is:
-
- env PGPPATH=/usr/local/news/etc/pgp pgp <file>
-
-You can safely answer "no" to questions about whether you want to sign,
-trust, or certify keys.
-
-The URLs from which you can get hierarchy keys are noted in comments in
-F<control.ctl>. L<ftp://ftp.isc.org/pub/pgpcontrol/PGPKEYS> tries to
-collect the major hierarchy keys.
-
-If you are using GnuPG, please note that the first user ID on the key will
-be the one that's used by INN for verification and must match the key
-listed in F<control.ctl>. If a hierarchy key has multiple user IDs, you
-may have to remove all the user IDs except the one that matches the
-F<control.ctl> entry using C<gpg --edit-key> and the C<delkey> command.
~ian / inn-innduct.git / blobdiff