=head1 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 F<config.status>.

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

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

=item *

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

=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) 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 need to
install both GnuPG and pgpgpg from <http://www.gnupg.org/>; a link for
pgpgpg is under "Front ends."

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.

=back

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
F<README.tcl_hook> and F<README.python_hook> for more information.

=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 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 F<inn-CURRENT-20000406.tar.gz> and
F<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 F<inn>
(followed by a version number, -CURRENT, or -STABLE) 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>.  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.

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.

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:

=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 /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-path> 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.  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.

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

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

=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
    tablesize:  3rd field on the 1st line of history.dir

If you don't have at least that much RAM, try rebuilding INN with tagged
hash enabled.

NOTE: B<--with-largefiles> can not 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.  You will need Perl 5.004 or later installed
on your system to use this option (otherwise, INN will not compile).  See
F<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).

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

=item B<--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
F<README.tcl_hook> for all the details.

=item B<--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
F<inn.conf> or by giving 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 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.

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

=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 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 (F</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!

=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, 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:

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

=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 cause wanted articles to
expire 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 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 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.

=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 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, samples of each file (containing lots of comments)
are installed in F<~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 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 man page for F<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 (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 wildmat(5) 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.

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

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

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

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

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

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

=item 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 L<File
Descriptor Limits> for complete details.

=item 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 I<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 F<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
F<errlog>, which probably isn't what you want.)

=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.
newsfeeds(5) 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; 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, 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 C</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.  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 L<Setting Up the Cron Jobs> below.
You will also need to set up a config file for nntpsend; see the man page
for F<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 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 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 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 F<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.

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

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

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:

=over 4

=item 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.  See L<Creating the Article Spool> for more discussion
of how to set this up.

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

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

=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 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 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 the F<expire.ctl> file a bit later.

=head2 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 F<inn.conf>, defaulting to 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.  For
other storage methods, there are two different syntaxes of this file,
depending on whether C<groupbaseexpiry> is set 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: 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 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 a matching
expiration status.  All of the other fields have the same meaning as
above.

=head2 readers.conf

Provided that noreader is set to false in F<inn.conf>, any connection from
a host that doesn't match an entry in F<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 F<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
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: "*"
        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 C<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.

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

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

=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 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 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
and you can create additional groups after the server is running by using
C<ctlinnd newgroup>.

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

=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 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 F<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 F</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.

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