Welcome to INN 2.3!

    Please read this document thoroughly before trying to install INN. 
    You'll be glad you did.

    If you are upgrading from a previous major release of INN, 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.3. 
    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 an earlier minor release of INN, 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 .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 --with-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 config.status.

    For more information about recent changes, see NEWS.

Supported 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 or glibc 2.0 and up)
      Mac OS X 10.2 and up
      OpenBSD 2.8 and up
      SCO 5.0.4 (tested with gcc 2.8.1 and cc)
      Solaris 2.5.x and up
      UnixWare 7.1
      UX/4800 R11 and up

    So far as possible, INN is written in portable C and should work on any
    Unix platform.  It does, however, make extensive use of mmap() and
    certain other constructs that may be poorly or incompletely implemented,
    particularly on old operating systems.

    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.

Before You Begin

    INN requires several other packages be installed in order to be fully
    functional (or in some cases, to work at all):

    * 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 (note that gcc has some known problems compiling
      calls to inet_ntoa() on IRIX platforms).

    * 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.

    * INN requires at least Perl 5.003 to build and to run several
      subsystems, and requires at least 5.004 for embedded Perl filters to
      work.  All versions of Perl previous to 5.004 are buggy (including
      security problems) and INN is tested primarily with newer versions of
      Perl, so it's highly 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/>.

    * The INN Makefiles use the syntax "include FILE", rather than the
      syntax expected by some BSDish systems of ".include <FILE>".  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.

    * If you want to enable support for authenticated control messages (this
      is not required but is highly recommended) 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 (including in the US), and (as of version
      1.0.4 at least) supports RSA signatures used by most current control
      message senders.  You can get GnuPG from <http://www.gnupg.org/>.

      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.

    Also, if you want to use either the Tcl or Python embedded hooks, you'll
    need to have suitable versions of Tcl and/or Python installed.  See
    README.tcl_hook and README.python_hook for more information.

Unpacking the Distribution

    Released versions of INN are available from ftp.isc.org in /isc/inn. 
    New major releases will be announed on inn-announce@isc.org (see 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 /isc/inn/snapshots.  These
    are snapshots of the current INN CVS tree taken daily; there are two
    snapshots made every 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 inn-CURRENT-20000406.tar.gz and
    inn-STABLE-20000406.tar.gz.  Choose the newest file.

    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 inn
    (followed by a version number, -CURRENT, or -STABLE) where the source
    resides.

Installing INN

    Before beginning installation, you should make sure that there is a user
    on your system named "news", and that this user's primary group is set
    to a group called "news".  The home directory of this user should be set
    to the directory under which you wish to install INN (/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.

    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 "news" be the user "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.

    INN 2.3 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:

    --prefix=PATH
        Sets the installation prefix for INN.  The default is
        /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 /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
        --with-tmp-path below).

    --with-db-dir=PATH
        Sets the prefix for INN database files.  The default is PREFIX/db,
        where PREFIX is /usr/local/news unless overridden with the option
        above.  This 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 2GB or more during nightly expire), so this is a
        common portion of INN to move to a different file system.

    --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
        PREFIX/spool.  This is another common portion of INN to move to a
        different file system (often /news).

        It's also possible to set the paths for most other sections of the
        INN installation independently; see "./configure --help" and look
        for the --with-*-dir=PATH options.

    --with-tmp-path=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.

    --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: --with-largefiles can not be used with --enable-tagged-hash.

    --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.  You will need Perl 5.004 or
        later installed on your system to use this option (otherwise, INN
        will not compile).  See README.perl_hook for all the details.

        Even if you do not use this option, INN still requires Perl to build
        (but an earlier version may suffice).

    --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
        README.python_hook and README.python_auth_hook 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.

    --with-tcl
        Enables support for Tcl, allowing you to install filter scripts
        written in Tcl.  Most available filterse seem to be written in Perl
        these days, so you can safely leave out Tcl support.  If you choose
        to enable this, you will need to have a suitable Tcl distribution
        installed.  See README.tcl_hook for all the details.

    --with-innd-port=PORT
        By default, inndstart refuses to bind to any port under 1024 other
        than 119 and 433 for security reasons (to prevent attacks on
        rsh-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 inn.conf or by giving it to inndstart on the
        command line.)

    --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).

    --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 "./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.

    --enable-uucp-rnews
        If this option is given to configure, rnews will be installed setuid
        root, owned by group uucp, and mode 4550.  This will allow the UUCP
        subsystem to run rnews to process UUCP batches of news articles
        (rnews changes UID to the news user right after it starts).  Prior
        to INN 2.3, installing rnews setuid root 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.

    --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.

    --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.  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).

    --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.  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.

    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 and install a couple of setuid wrapper scripts
    needed to raise resource limits and allow innd to bind to port 119. 
    This will install INN under the install directory (/usr/local/news,
    unless you specified something else to the configure script.)

    If you use SSL support for nnrp, 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!

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, all of
    which have their 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:

    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 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 volues 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.

    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).

    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.

    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 cause
        wanted articles to expire much faster than you intended with no
        warning.

    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 ovmethod in 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 every 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 in, 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.

    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 buffindexed.conf.  See buffindexed.conf(5) for more
    information.

Configuring INN

    All documentation from this point on assumes that you have set up the
    news user on your system as suggested in "Installing INN" so that the
    root of your INN installation is ~news/.  If you've moved things around
    by using options with configure, you'll need to adjust the instructions
    to account for that.

    All of INN's configuration files are located in ~news/etc.  Unless noted
    otherwise, any files referred to below are in this directory.  When you
    first install INN, samples of each file (containing lots of comments)
    are installed in ~news/etc; refer to them 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 ~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
    ~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 man page for inn.conf (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 ("*") 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
    "!" mean to exclude groups matching that pattern.  For example:

        *, !comp.*, comp.os.*

    In this case, we're saying we match everything ("*"), except that we
    don't match anything under comp ("!comp.*"), unless it is actually under
    the comp.os hierarchy ("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 "@").  These patterns behave just like "!" 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 "@", however, that
    article will not match the pattern even if other newsgroups to which it
    was posted match other expressions.

    See wildmat(5) for full details on wildmat patterns.

    In all INN configuration files, blank lines and lines beginning with a
    "#" symbol are considered comments and are ignored.

  inn.conf

    The first, and most important file is 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 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 "yes",
    "true", or "on", whichever you prefer.  Similarly, false values can be
    written as "no", "false", or "off".)

    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:

    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.

    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 "abuse@example.com" or "postmaster@example.com".  If not
        specified, the newsmaster email address will be used.

    domain
        Sets the domain name for your server.  Normally this is determined
        automatically by INN, but in some cases it is necessary to set it
        manually.  For example, if you are running NIS on a SunOS system
        *and* your hostnames are not fully-qualified (ie, your systems are
        named "host" instead of "host.example.com") then you will need to
        use this option to set your domain name manually.  If in doubt,
        leave this option commented out or remove it completely.

    hiscachesize
        The 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 256 is
        a good default choice.

    logipaddr
        If set to true (the default), INN will log the IP address 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.

    organization
        Set this to the name of your organization as you want it to appear
        in the Organization: header of all articles posted locally 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 without one.

    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 no pathhost is specified then 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.

    rlimitnofile
        If set to a non-negative value (the default is -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 "File Descriptor Limits" for complete
        details.

    usecontrolchan
        If set to true, all control messages except for cancels will be
        ignored by innd so that they can be processed by an external program
        (controlchan).  This is *highly* recommended, since controlchan will
        serialize control message processing and prevent your system load
        from exploding when you get a flood of control messages.  The only
        reason why it isn't enabled by default is that it requires you to
        set up a special feed in newsfeeds (see below) and requires you to
        run:

            # cd /usr/include
            # h2ph * sys/*

        if you're using a version of Perl prior to 5.6.0 so that the
        Sys::Syslog Perl module works correctly.  (Otherwise, controlchan
        will log messages to errlog, which probably isn't what you want.)

    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.

  newsfeeds

    newsfeeds determines how incoming articles are redistributed to your
    peers and to other INN processes.  newsfeeds is very versatile and
    contains dozens of options; we will touch on just the basics here. 
    newsfeeds(5) contains more detailed information.

    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 ("\") 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; 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 "@").

    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 "Tf,Wnm"
    (to write out a batch file of articles to be sent, suitable for
    processing by nntpsend and innxmit), "Tm" (to send the article to a
    funnel feed, used with innfeed), and "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 ("Tf") it's the name of the
    file to write, for funnel feeds ("Tm") it's the name of the feed entry
    to funnel into, and for channel feeds ("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
    *outgoing* feeds, and the distribution patterns set the acceptable
    Distribution: header entries for *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, 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 and innxmit.  Batching gives you more control
    and tends to be extremely stable and reliable, but it's much slower and
    can't handle lots of articles 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 "/news.example.com" part.

    This entry will cause innd to write out a file in ~news/spool/outgoing
    named 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 the program sm).  innxmit knows how to read
    this format of file and send those articles to the remote site.  For
    information on setting it up to run periodically, see "Setting Up the
    Cron Jobs" below.  You will also need to set up a config file for
    nntpsend; see the man page for nntpsend.ctl for more information.

    If instead you want to use 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, called a channel feed.

    First, the special channel feed entry for innfeed that will collect all
    the funnel feeds:

        innfeed!\
            :!*\
            :Tc,Wnm*:/usr/local/news/bin/startinnfeed -y

    (adjust the path to startinnfeed if you installed it elsewhere).  Note
    that we don't feed this entry any articles directly (its newsgroup
    pattern is "!*").  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 "!", no site name containing
    that character can 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 "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 they put in the Path: header
    (if different than the actual name of the server), and <newsgroups> is
    the wildmat pattern of newsgroups they want.

    Finally, if you set usecontrolchan to "true" in inn.conf, you need to
    set up an entry for the controlchan program.  This entry should look
    like:

        controlchan!\
            :!*,control,control.*,!control.cancel\
            :Tc,Wnsm:/usr/local/news/bin/controlchan

    (modified for the actual path to controlchan if you put it somewhere
    else).  You should be able to just uncomment the example entry in the
    sample newsfeeds file, making sure the path is correct.  See "Processing
    Control Messages" for more details.

    For those of you upgrading from earlier versions of INN, note that the
    functionality of overchan and crosspost is now incorporated into INN and
    neither of those programs are necessary.  Unfortunately, crosspost
    currently will not work even with the tradspool storage method.  You can
    still use overchan if you make sure to set useoverchan to true in
    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.

  incoming.conf

    This 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 readers.conf.

    Start with the sample 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 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 uses.  For example, if you
    want to prevent example.com hosts from sending you any articles in the
    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
    *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 hosts.nntp configuration file.

  cycbuff.conf

    This configuration file is only required if CNFS is used.  If you aren't
    using CNFS, skip this section.

    CNFS stores articles in logical objects called metacycbuffs.  Each of
    the metacycbuffs is in turn composed of one or more physical buffers
    called 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 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:

    1.  Use a raw disk partition (best).  This will give you the most speed,
        but it requires your OS support mmap() on a block device.  Solaris
        supports this, FreeBSD and Linux (without patches) do not.  Also on
        many PC-based Unixes it is difficult to create more than eight
        partitions, which may limit your options.

    2.  Use a real file on a filesystem.  This will be a bit slower than
        using a raw disk partition, but it should work on any Unix system.

    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
    (alt.binaries.* and maybe a few other things like *.jobs* and
    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 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 2GB which will
    force all of your cycbuffs to be < 2GB.  Linux is known to have this
    limitation, FreeBSD does not.  Some OSes that support large files don't
    support block access to large raw 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 2GB, you'll have to use regular files.  If in
    doubt, keep your cycbuffs smaller than 2GB.  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).

    For each cycbuff you will be creating, add a line to 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 2GB, keep your sizes below 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 ":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.

    Finally, you have to create the cycbuffs.  See "Creating the Article
    Spool" for more information on how to do that.

  storage.conf

    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 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 storage.conf sequentially.

    The third parameter can be used to accept only articles in a certain
    size range into this storage class.  A <maxsize> of zero (or a missing
    <maxsize>) means no upper limit (and of course a <minsize> of 0 would
    mean no lower limit, because an article is always great 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 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 the expire.ctl file a bit later.

  expire.ctl

    This file sets the expiration policy for articles stored on the server. 
    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
    artcutoff parameter in inn.conf, defaulting to 10); the number on the
    "/remember/" line should match that.

    CNFS makes no further use of expire.ctl, since articles stored in CNFS
    buffers expire automatically when the buffer runs out of free space. 
    For other storage methods, there are two different syntaxes of this
    file, depending on whether "groupbaseexpiry" is set in inn.conf.  If it
    is set to false, expire.ctl takes entries of the form:

        <storage_class>:<keep>:<default>:<purge>

    <storage_class> is the number assigned to a storage class in
    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: header, 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 "never". 
    If <default> is "never", only articles with explicit Expires: headers
    will ever be expired.  If <keep> is "never", articles with explicit
    Expires: headers will be kept forever.  Setting <purge> to "never" says
    to honor Expires: headers even if they specify dates far into the
    future.  (Note that if <keep> is set to "never", all articles with
    Expires: headers are kept forever and the value of <purge> is not used.)

    If the value of "groupbaseexpiry" is true, expire.ctl takes entries of
    the form:

        <wildmat>:<flag>:<keep>:<default>:<purge>

    <wildmat> is a wildmat expression ("!" and "@" 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 "M"
    for moderated groups, "U" for unmoderated groups, and "A" for groups
    with any moderation status; the line only matches groups with a matching
    expiration status.  All of the other fields have the same meaning as
    above.

  readers.conf

    Provided that noreader is set to false in inn.conf, any connection from
    a host that doesn't match an entry in incoming.conf (and any connection
    from a host that does match such an entry but that then issues a MODE
    READER command) will be handed off to nnrpd, the part of INN that
    supports newsreading clients.  nnrpd uses readers.conf to determine
    whether a given connection is allowed to read news, and if so what
    newsgroups they can read and post to.

    There are a variety of fairly complicated things that one can do with
    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: "*"
            access: "Read Post"
        }

    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 "example.com" in the above to your domain and you're
    all set.  Lots of examples of more complicated things are in the example
    file.

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 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 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 commands that you should
    run:

        awk -F: \
        '/^cy/ { printf "dd if=/dev/zero of=%s bs=1k count=%s\n", $3, $4 }' \
        cycbuff.conf

    If you are using raw devices, you don't technically have to do anything
    at all (since INN is capable of using the devices in /dev), but you
    probably want to create special device files for those devices somewhere
    for INN's private use.  Not only is it more convenient to keep all of
    INN's stuff together, 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 /dev.

    To create the device files for INN, use mknod with a type of b, getting
    the major and minor device numbers from the existing devices in /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 cycbuff.conf).

    Solaris users please note:  On Solaris, do not use raw devices that
    include the first cylinder of the disk.  Solaris doesn't protect the
    superblock from being overwritten by an application writing to raw
    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.

Creating the Database Files

    At this point, you need to set up the news database directory
    (~news/db).  This directory will hold the active file (the list of
    newsgroups you carry), the active.times file (the creator and creation
    time of newsgroups created since the server was initialized), the
    newsgroups file (descriptions for all the newsgroups you carry), and the
    history 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 ~news/bin is in the default path of the news
    user (and while you're at it, make sure ~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 active and newsgroups
    from that server into ~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 active
    and 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 active file installed by INN is a good place to start
    and you can create additional groups after the server is running by
    using "ctlinnd newgroup".

    "control" and "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. 
    "to" must also exist as a newsgroup if you have mergetogroups set in
    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 ".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.

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 "news" syslog facility, INN will use it;
    otherwise, it will log to "local1".  Nearly every modern system has a
    "news" syslog facility so you can safely assume that yours does, but if
    in doubt take a look at the output from running "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
    "local1" instead of "news".

    Edit /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 /usr/local/news.)  These lines *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); for every entry in
    /etc/syslog.conf that starts with "*", add ";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 "crit",
    though.  "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.

Setting Up the Cron Jobs

    INN requires a special cron job to be set up on your system to run the
    news.daily script, 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 "delayrm" to the above
    option list for news.daily.

    If you use the batching method to send news, also set up a cron job to
    run nntpsend 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 man page.

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 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
    rlimitnofile in inn.conf to a higher value.  This will cause
    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 you won't
    be able to increase the limits above the hard limits set by your
    operating system; on some systems, that hard limit is 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 Linux, patching and recompiling the kernel; on
    Solaris 2.6 or earlier, the limit cannot be increased beyond 1024
    without breaking select() and thereby breaking all of INN).

    256 file descriptors will probably be enough for all but the largest
    site.  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).  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 /etc/system and rebooting.  You can increase it all the way to 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.

Starting and Stopping the System

    INN is started via the shell script 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 "stop"
    option:

        su - news -c '/usr/local/news/bin/rc.news stop'

    In the contrib directory of this source tree is a sample init script for
    people using System V-style init.d directories.

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 newsfeeds if you want
    your news server to process any control messages; see "Configuring INN"
    for specific instructions.

    The actions of controlchan are determined by control.ctl, which lists
    who can perform what actions.  The primary control messages to be
    concerned with are "newgroup" (to create a newsgroup), "rmgroup" (to
    remove a newsgroup), and "checkgroups" (to compare the list of groups
    carried in a hierarchy to a canonical list).  INN comes with a
    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
    control.ctl.  <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 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
    control.ctl entry using "gpg --edit-key" and the "delkey" command.

