Installing INN

Table of Contents

  1. Welcome to INN 2.5!
  2. Supported Systems
  3. Before You Begin
  4. Unpacking the Distribution
  5. Installing INN
  6. Choosing an Article Storage Format
  7. Choosing an Overview Storage Mechanism
  8. Configuring INN
  9. Creating the Article Spool (CNFS only)
  10. Creating the Database Files
  11. Configuring syslog
  12. Setting Up the Cron Jobs
  13. File Descriptor Limits
  14. Starting and Stopping the System
  15. Processing Newsgroup Control Messages

Welcome to INN 2.5!

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

If you are upgrading from a major release of INN prior to 2.3, it is recommended that you make copies of your old configuration files and use them as guides for doing a clean installation and configuration of 2.5. Many config files have changed, some have been added, and some have been removed. You'll find it much easier to start with a fresh install than to try to update your old installation. This is particularly true if you're upgrading from a version of INN prior to 2.0.

If you are upgrading from INN 2.3 or later, you may be able to just update the binaries, scripts, and man pages by running:

    make update

after building INN and then comparing the new sample configuration files with your current ones to see if anything has changed. If you take this route, the old binaries and scripts will be saved with an extension of .OLD so that you can easily back out. Note that if you do not want to have such backup copies, you can deactivate this behaviour with make BACKUP_OPTION='' update instead of a mere make update. Be sure to configure INN with the same options that you used previously if you take this approach (in particular, INN compiled with --enable-largefiles can't read the data structures written by INN compiled without that flag, and vice versa). If you don't remember what options you used but you have your old build tree, look at the comments at the beginning of config.status.

If you made ckpasswd setuid root so that you could use system passwords, you'll have to do that again after make update. (It's much better to use PAM instead if you can.)

If you use make update to upgrade from a previous major release of INN, also look at the new sample configuration files in samples to see if there are new options of interest to you.

For more information about recent changes, see NEWS.

Supported Systems

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

INN has been confirmed to work on the following operating systems:

    AIX 4.3
    FreeBSD 2.2.x and up
    HP-UX 10.20 and up
    Linux 2.x (tested with libc 5.4, glibc 2.0 and up)
    Mac OS X 10.2 and up
    NetBSD 1.6 and up
    OpenBSD 2.8 and up
    SCO 5.0.4 (tested with gcc 2.8.1, cc)
    Solaris 2.5.x and up
    UnixWare 7.1
    UX/4800 R11 and up

If you have gotten INN working on an operating system other than the ones listed above, please let us know at <inn-workers@lists.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):

Unpacking the Distribution

Released versions of INN are available from <ftp://ftp.isc.org/isc/inn/>. New major releases will be announced on <inn-announce@lists.isc.org> (see README) when they're made.

If you want a more cutting-edge version, you can obtain current snapshots from <ftp://ftp.isc.org/isc/inn/snapshots/>. These are snapshots of the INN Subversion tree taken daily; there are two snapshots made each night (one of the current development branch, and one of the stable branch consisting of bug fixes to the previous major release). They are stored in date format; in other words the snapshots from April 6th, 2000, would be named inn-CURRENT-20000406.tar.gz and inn-STABLE-20000406.tar.gz. Choose the newest file of whichever branch you prefer. (Note that the downloading, configuring, and compiling steps can be done while logged in as any user.)

The distribution is in gzip compressed tar archive format. To extract it, execute:

    gunzip -c <inn-src-file> | tar -xf -

Extracting the source distribution will create a directory named inn-<version> or inn-<BRANCH>-<date> 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. You can change these with the --with-news-user and --with-news-group options to configure (see below). The home directory of this user should be set to the directory under which you wish to install INN (/usr/local/news is the default and is a good choice). This location will be set as pathnews in inn.conf. INN will install itself as this user and group. You can change these if you want, but these are the defaults and it's easier to stick with them on a new installation.

By default, INN sends reports to the user usenet. This account is used for instance by controlchan (notifying any changes as for newsgroups) or news.daily (sending Usenet daily reports). You can change it with the --with-news-master option to configure (see below). There is also the mailto keyword which can be given to news.daily in order to modify the mail address to which these reports are sent.

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. However, since certain binaries need to be setuid root, indiscriminate use of chown news is not the solution. (If you don't like to log in to system accounts, careful use of chmod g+s on directories and a umask of 002 or 007 may suffice.)

INN uses GNU autoconf and a generated configure script to make configuration rather painless. Unless you have a rather abnormal setup, configure should be able to completely configure INN for your system. If you want to change the defaults, you can invoke the configure script with one or more command line options. Type:

    ./configure --help

for a full list of supported options. Some of the most commonly used options are:

--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-dir 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. The history and active files will be stored in this directory, and writes to those files are an appreciable percentage of INN's disk activity. The history file can also be quite large (requiring up to 2 GB or more during nightly expire), so this is a common portion of INN to move to a different file system.

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

--with-tmp-dir=PATH

Sets the directory in which INN will create temporary files. This should under no circumstances be the same as the system temporary directory or otherwise be set to a world-writeable directory, since INN doesn't take care to avoid symlink attacks and other security problems possible with a world-writeable directory. This directory should be reserved for the exclusive use of INN and only writeable by the news user. Usage is generally light, so this is unlikely to need a separate partition.

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

--enable-largefiles

Enables large file support. This is not enabled by default, even on platforms that support it, because it changes the format of INN's on-disk databases (making it difficult to upgrade an earlier INN installation) and can significantly increase the size of some of the history database files. Large file support is not necessary unless your history database is so large that it exceeds 2 GB or you want to use CNFS buffers larger than 2 GB.

The history, tradindexed and buffindexed overview, and timecaf databases written by an INN built with this option are incompatible with those written by an INN without this option. (CNFS buffers are compatible.)

--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: --enable-largefiles cannot 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. See doc/hook-perl for all the details.

Even if you do not use this option, INN still requires Perl as mentioned above.

--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 doc/hook-python for all the details. Note that there is an incompatibility between INN and Python 2.0 when Python is compiled with cycle garbage collection; this problem was reported fixed in Python 2.1a1.

--with-innd-port=PORT

By default, innbind(8) refuses to bind to any port under 1024 other than 119, 433 and 563 for security reasons (to prevent attacks on rsh(1)-based commands and replacing standard system daemons). If you want to run innd on a different port under 1024, you'll need to tell configure what port you intend to use. (You'll also still need to set the port number in inn.conf or give it to innd 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 but man pages 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 news, owned by group uucp, and mode 4550. This will allow the UUCP subsystem to run rnews to process UUCP batches of news articles. Prior to INN 2.3, installing rnews setuid news was standard; since most sites no longer use UUCP, it is no longer the default as of INN 2.3 and must be requested at configure time. You probably don't want to use this option unless your server accepts UUCP news batches.

--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 (4.4 or higher), which means that it will then be possible to use the ovdb overview method if you wish. Enabling this configure option doesn't mean you'll be required to use ovdb, but it does require that Berkeley DB be installed on your system (including the header files, not just the runtime libraries). If a path is given, it sets the installed directory of Berkeley DB (configure will search for it in some standard locations, but if you have it installed elsewhere, you may need this option).

--with-zlib=PATH

The ovdb storage method can optionally use compression. If --with-berkeleydb is set, and configure finds a suitable Berkeley DB version, this option defaults to yes, otherwise the default is no. If you have zlib but it is not installed under /usr or /usr/local, you must specify the directory where it is installed.

--with-openssl=PATH

Enables support for TLS/SSL for news reading, which means it will be possible to have TLS encrypted NNTP connections between your server and newsreaders. This option requires OpenSSL be installed on your system (including the header files, not just the runtime libraries). If a path is given, it sets the installed directory of OpenSSL. After compiling and installing INN with this option, you'll still need to make a certificate and private key to use TLS. See below for details on how to do that.

--enable-ipv6

Enables support for IPv6 in innd, innfeed, nnrpd, and several of the supporting programs. This option should be considered developmental at present. For more information see doc/IPv6-info (and if you have any particularly good or bad news to report, please let us know at <inn-workers@lists.isc.org>).

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

Normally, you will need to run this command as root so that INN can create the directories it needs, change ownerships (if you did not compile as the news user) and install a setuid program needed to raise resource limits and allow innd to bind to ports under 1024. This step will install INN under the install directory (/usr/local/news, known as pathnews in inn.conf, unless you specified something else to the configure script).

Exceptionally, if you are installing INN into a directory writable by the news user, you can run make install as the configured news user. The resulting INN installation won't be able to use ports below 1024 (including the default NNTP port of 119) unless you then run make install-root as root, which will install only the setuid helper program.

If you are configuring TLS/SSL support for newsreaders, you must make a certificate and private key at least once. Type:

    make cert

as root in order to do this.

You are now ready for the really fun part: configuring your copy of INN!

Choosing an Article Storage Format

The first thing to decide is how INN should store articles on your system. There are four different methods for you to choose from, each of which has its own advantages and disadvantages. INN can support all four at the same time, so you can store certain newsgroups in one method and other newsgroups in another method.

The supported storage formats are:

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 volumes due to file system overhead. Groups with heavy traffic tend to create a bottleneck because of inefficiencies in storing large numbers of article files in a single directory. Requires a nightly expire program to delete old articles out of the news spool, a process that can slow down the server for several hours or more.

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 degradation 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 result in wanted articles expiring 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.

Choosing an Overview Storage Mechanism

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

It is very fast for readers, but it has to update two files for each incoming article and can be quite slow to write.

buffindexed

It can keep up with a large feed more easily, since it uses large buffers to store all overview information, but it's somewhat slower for readers (although not as slow as the unified overview in INN 2.2). 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.

ovdb

It stores overview data in a Berkeley DB database; it's fast and very robust, but may require more disk space. See the ovdb(5) man page for more information on it.

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 (pathnews in inn.conf). 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 pathetc in inn.conf. Unless noted otherwise, any files referred to below are in this directory. When you first install INN, a sample of each file (containing lots of comments) is installed in pathetc; refer to these for concrete examples of everything discussed in this section.

All of INN's configuration files, all of the programs that come with it, and some of its library routines have documentation in the form of man pages. These man pages were installed in pathnews/share/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 pathnews/share/man to your MANPATH environment variable; otherwise, you may have to use a command like:

    man -M <pathnews in inn.conf>/share/man inn.conf

to see the inn.conf(5) man page (for example).

Before we begin, it is worth mentioning the wildmat pattern matching syntax used in many configuration files. These are simple wildcard matches using the asterisk (*) 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. For instance, if an article is crossposted between misc.foo and misc.bar, the pattern:

    misc.*,!misc.bar

will match that article whereas the pattern:

    misc.*,@misc.bar

will not match that article. An article posted only to misc.bar will fail to match either pattern.

See uwildmat(3) 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. Be careful, not all files permit comments to begin in the middle of the line.

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 then the value itself. For some parameters the value is a string or a number; for others it is true or false. (True values can be written as 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. (Note that the access setting in readers.conf overrides this value; see readers.conf(5) for more details.)

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 e-mail address will be used.

hiscachesize

The amount of memory (in kilobytes) to allocate for a cache of recently used history file entries. Setting this to 0 disables history caching. History caching can greatly increase the number of articles per second that your server is capable of processing. A value of 256 is a good default choice.

logipaddr

If set to true (the default), INN will log the IP address (or hostname, if the host is listed in incoming.conf with a hostname) of the remote host from which it received an article. If set to false, the trailing Path: header entry is logged instead. If you are using controlchan (see below) and need to process ihave/sendme control messages (this is very, very unlikely, so if you don't know what this means, don't worry about it), make sure you set this to false, since controlchan needs a site name, not an IP address.

organization

Set this to the name of your organization as you want it to appear in the Organization: header of all articles posted locally and not already containing that header. This will be overridden by the value of the ORGANIZATION environment variable (if it exists). If neither this parameter nor the environment variable is set, no Organization: header will be added to posts which lack 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 this parameter is unspecified, the fully-qualified domain name (FQDN) of the machine will be used instead. Please use the FQDN of your server or an alias for your server unless you have a very good reason not to; a future version of the news RFCs may require this.

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.

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. The man page 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: header of an article, then that article will not be forwarded to the feed as it is assumed that it has passed through that site once already. The exclude list is useful when a news server's hostname is not the same as what it puts in the Path: header of its articles, or when you don't want a feed to receive articles from a certain source.

The second field specifies a set of desired newsgroups and distribution lists, given as newsgroup-pattern/distribution-list. The distribution list is not described here; see newsfeeds(5) for information (it's not used that frequently in practice). The newsgroup pattern is a wildmat-style pattern list as described above (supporting @).

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(8), which sends articles to remote sites in real time (the article goes out to all peers that are supposed to receive it immediately after your server accepts it). For smaller sites, particularly sites where the only outgoing messages will be locally posted articles, it's more common to batch outgoing articles and send them every ten minutes or so from cron using nntpsend(8) and innxmit(8). Batching gives you more control and tends to be extremely stable and reliable, but it's much slower and can't handle high volume very well.

Batching outgoing posts is easy to set up; for each peer, add an entry to newsfeeds that looks like:

    remote.example.com/news.example.com\
        :<newsgroups>\
        :Tf,Wnm:

where <newsgroups> is the wildmat pattern for the newsgroups that site wants. In this example, the actual name of the remote site is remote.example.com, but it puts news.example.com in the Path: header. If the remote site puts its actual hostname in the Path: header, you won't need the /news.example.com part.

This entry will cause innd to write out a file in pathspool/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 sm(8)). innxmit knows how to read files of this format and send those articles to the remote site. For information on setting it up to run periodically, see "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(5) 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 (innfeed in this case); this is a "channel" feed.

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

    innfeed!\
        :!*\
        :Tc,Wnm*:<pathbin in inn.conf>/innfeed -y

(adjust the path to innfeed(8) 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 ever match the name of a real site.

Next, set up entries for each remote site to which you will be feeding articles. All of these entries should be of the form:

    remote.example.com/news.example.com\
        :<newsgroups>\
        :Tm:innfeed!

specifying that they funnel into the innfeed! feed. As in the previous example for batching, remote.example.com is the actual name of the remote peer, news.example.com is what it puts in the Path: header (if different than the actual name of the server), and <newsgroups> is the wildmat pattern of newsgroups to be sent.

As an alternative to NNTP, INN may also feed news out to an IMAP server, by using imapfeed(8), which is almost identical to innfeed. The feed entry for this is as follows:

    imapfeed!\
        :!*\
        :Tc,Wnm*,S16384:<pathbin in inn.conf>/imapfeed

And set up entries for each remote site like:

    remote.example.com/news.example.com\
        :<newsgroups>\
        :Tm:imapfeed!

For more information on imapfeed, look at the innfeed/imap_connection.c file. For more information on IMAP in general, see RFC 3501.

Finally, there is a special entry for controlchan(8), which processes newsgroup control messages, that should always be in newsfeeds unless you never want to honor any control messages. This entry should look like:

    controlchan!\
        :!*,control,control.*,!control.cancel\
        :AC,Tc,Wnsm:<pathbin in inn.conf>/controlchan

(modified for the actual path to controlchan if you put it somewhere else). See Processing Newsgroup Control Messages for more details.

For those of you upgrading from earlier versions of INN, note that the functionality of overchan(8) and crosspost is now incorporated into INN and neither of those programs is necessary. Although crosspost is no longer shipped with INN (and will not be working if used), 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

incoming.conf file specifies which machines are permitted to connect to your host and feed it articles. Remote servers you peer with should be listed here. Connections from hosts not listed in this file will (if you don't allow readers) be rejected or (if you allow readers) be handed off to nnrpd and checked against the access restrictions in 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(5) 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

cycbuff.conf is only required if CNFS is used. If you aren't using CNFS, skip this section.

CNFS stores articles in logical objects called metacycbuffs. Each metacycbuff 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 block device directly. This will probably give you the most speed since it avoids the file system overhead of large files, but it requires your OS support mmap(2) on a block device. Solaris supports this, as do late Linux 2.4 kernels. FreeBSD does not at last report. Also on many PC-based Unixes it is difficult to create more than eight partitions, which may limit your options.

  2. Use a real file on a filesystem. This will probably be a bit slower than using a block device directly, but it should work on any Unix system.

If you're having doubts, use option #2; it's easier to set up and should work regardless of your operating system. More information about the creation of these cycbuffs can be found in cycbuff.conf(5) man page.

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 you might store them in one of the other storage methods, such as tradspool.)

For each metacycbuff, you now need to determine how many cycbuffs will make up the metacycbuff, the size of those cycbuffs, and where they will be stored. Also, when laying out your cycbuffs, you will want to try to arrange them across as many physical disks as possible (or use a striped disk array and put them all on that).

In order to use any cycbuff larger than 2 GB, you need to build INN with the --enable-largefiles option. See Installing INN for more information and some caveats.

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 2 GB, 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:CYCBUF1,CYCBUF2,CYCBUF3

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.

By default, CNFS data is flushed to disk every 25 articles. If you're running a small server with a light article load, this could mean losing quite a few articles in a crash. You can change this interval by adding a cycbuffupdate: line to your cycbuff.conf file; see cycbuff.conf(5) for more details.

Finally, you have to create the cycbuffs. See "Creating the Article Spool (CNFS only)" 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>
        exactmatch: <bool>
    }

<methodname> is the name of the storage method to use to store articles in this class (cnfs, timehash, timecaf, tradspool, or the special method trash that accepts the article and throws it away).

The first parameter is a wildmat pattern in the same format used by the newsfeeds(5) file, and determines what newsgroups are accepted by this storage class.

The second parameter is a unique number identifying this storage class and should be between 0 and 255. It can be used to control article expiration, and for timehash and timecaf will set the top-level directory in which articles accepted by this storage class are stored. The easiest way to deal with this parameter is to just number all storage classes in storage.conf sequentially. The assignment of a particular number to a storage class is arbitrary but permanent (since it is used in storage tokens).

The third parameter can be used to accept only articles in a certain size range into this storage class. A <maxsize> of 0 (or a missing <maxsize>) means no upper limit (and of course a <minsize> of 0 would mean no lower limit, because all articles are more than zero bytes long). If you don't want to limit the size of articles accepted by this storage class, leave this parameter out entirely.

The fourth parameter you probably don't want to use 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.

The sixth parameter is a boolean which is false by default: any non-zero number of matching newsgroups is sufficient, provided no newsgroup matches a poison wildmat. If it is set to true, all the newsgroups in the Newsgroups: header of incoming articles will be examined to see if they match the newsgroups wildmat pattern.

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 expire.ctl a bit later.

expire.ctl

expire.ctl sets the expiration policy for articles stored on the server. Be careful, since the default configuration will expire most articles after 15 days; in most circumstances this deletion is permanent, so read this whole section carefully if you want to keep local hierarchies forever. (See archive(8) for a way to automate backups of important articles.)

Only one entry is required for all storage classes; it looks like:

    /remember/:11

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 be one more than that number in order to take into account articles whose posting date is one day into the future.

CNFS makes no further use of expire.ctl, since articles stored in CNFS buffers expire automatically when the buffer runs out of free space (but see the -N option in expireover(8) if you really want to expire them earlier). For other storage methods, there are two different syntaxes of this file, depending on groupbaseexpiry 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 constraints set by <keep> and <purge>. All articles in this storage class will be kept for at least <keep> days, regardless of their Expires: headers, and all articles in this storage class will be expired after <purge> days, even if their Expires: headers specify a longer life.

All three of these fields can also contain the special keyword 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 the indicated 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 (as well as any connection from a host that does match such an entry, but has issued a MODE READER command) will be handed off to nnrpd(8), the part of INN that supports newsreading clients. nnrpd uses readers.conf to determine whether a given connection is allowed to read news, and if so what newsgroups the client can read and post to.

There are a variety of fairly complicated things that one can do with readers.conf, things like run external authentication programs that can query RADIUS servers. See readers.conf(5) and the example file for all the gory details. Here's an example of probably the simplest reasonable configuration, one that only allows clients in the example.com domain to read from the server and allows any host in that domain to read and post to all groups:

    auth "example.com" {
        hosts: "example.com, *.example.com"
        default: "<user>"
        default-domain: "example.com"
    }

    access "all" {
        users: "*@example.com"
        newsgroups: "*"
    }

If you're running a server for one particular domain, want to allow all hosts within that domain to read and post to any group on the server, and want to deny access to anyone outside that domain, just use the above and change example.com in the above to your domain and you're all set. Lots of examples of more complicated things are in the sample file.

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

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

If you are using block devices, you don't technically have to do anything at all (since INN is capable of using the devices in /dev), but you probably want to create special device files for those devices somewhere for INN's private use. It is more convenient to keep all of INN's stuff together, but more importantly, the device files used by INN really should be owned by the news user and group, and you may not want to do that with the files in /dev.

To create the device files for INN, use mknod(8) 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 block devices that include the first cylinder of the disk. Solaris doesn't protect the superblock from being overwritten by an application writing to block devices and includes it in the first cylinder of the disk, so unless you use a slice that starts with cylinder 1 instead of 0, INN will invalidate the partition table when it tries to initialize the cycbuff and all further accesses will fail until you repartition.

Creating the Database Files

At this point, you need to set up the news database directory (in pathdb). This directory will hold the active(5) file (the list of newsgroups you carry), the active.times(5) file (the creator and creation time of newsgroups created since the server was initialized), the newsgroups(5) file (descriptions for all the newsgroups you carry), and the history(5) file (a record of every article the server currently has or has seen in the past few days, used to decide whether to accept or refuse new incoming messages).

Before starting to work on this, make sure you're logged on as the news user, since all of these files need to be owned by that user. This is a good policy to always follow; if you are doing any maintenance work on your news server, log on as the news user. Don't do maintenance work as root. Also make sure that pathbin is in the default path of the news user (and while you're at it, make sure pathnews/share/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 pathdb. 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; you can create additional groups after the server is running by using ctlinnd newgroup. (Another option is to use actsync(8) to synchronize your newsgroup list to that of another server.)

control, control.cancel 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. If you don't want these groups to be visible to clients, do not delete them; simply hide them in readers.conf. 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 <pathdb in inn.conf>
    touch history
    makedbz -i

(Note that if you install INN with make install, you do not need to run these commands: the installation takes care of creating the history database.)

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           <pathlog in inn.conf>/news.crit
    news.err            <pathlog in inn.conf>/news.err
    news.notice         <pathlog in inn.conf>/news.notice

(Change the path names as necessary in order to match pathlog, which defaults to /usr/local/news/log.) 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); so 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 <pathlog in inn.conf>/news.crit
    touch <pathlog in inn.conf>/news.err
    touch <pathlog in inn.conf>/news.notice
    chown news <pathlog in inn.conf>/news.*
    chgrp news <pathlog in inn.conf>/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 news.daily(8) which performs daily server maintenance tasks such as article expiration and the processing and rotation of the server logs. Since it will slow the server down while it is running, it should be run during periods of low server usage, such as in the middle of the night. To run it at 3am, for example, add the following entry to the news user's crontab file:

    0 3 * * * <pathbin in inn.conf>/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 news -s /bin/sh -c '<pathbin in inn.conf>/news.daily expireover lowmark'

If you're using any non-CNFS storage methods, add delayrm to the above option list for news.daily.

The news user obviously must be able to run cron jobs. On Solaris, this means that it must have a valid /etc/shadow entry and must not be locked (although it may be a non-login account). There may be similar restrictions with other operating systems.

If you use the batching method to send news, also set up a cron job to run nntpsend(8) every ten minutes. nntpsend will run innxmit for all non-empty pending batch files to send pending news to your peers. That cron entry should look something like:

    0,10,20,30,40,50 * * * * <pathbin in inn.conf>/nntpsend

The pathnames and user ID used above are the installation defaults; change them to match your installation if you used something other than the defaults.

The parameters passed to news.daily in the above example are the most common (and usually the most efficient) ones to use. More information on what these parameters do can be found in the news.daily(8) man page.

You may also want to run rnews each hour to process spooled messages created while innd is not available:

    12 * * * * <pathbin in inn.conf>/rnews -U

And it is also a good practice to refresh each day INN's cached IP addresses:

    30 2 * * * <pathbin in inn.conf>/ctlinnd -t 120 -s reload incoming.conf 'flush cache'

File Descriptor Limits

INN likes to use a lot of file descriptors, particularly if you have a lot of peers. Depending on what your system defaults are, you may need to make sure the default limit is increased for INN (particularly for innd and innfeed). This is vital on Solaris, which defaults (at least as of 2.6) to an absurdly low limit of 64 file descriptors per process.

One way to increase the number of file descriptors is to set rlimitnofile in inn.conf to a higher value. This will cause innd and innfeed to try to increase the file descriptor limits when they start. Note, however, that INN won't be able to increase the limits above the hard limits set by your operating system; on some systems, that hard limit is normally 256 file descriptors (Linux, for example). On others, like Solaris, it's 1024. Increasing the limit beyond that value may require serious system configuration work. (On some operating systems, it requires patching and recompiling the kernel. On Solaris it can be changed in /etc/system, but for 2.6 or earlier the limit cannot be increased beyond 1024 without breaking select(2) and thereby breaking all of INN. For current versions of Linux, you may be able to change the maximum by writing to /proc/sys/fs/file-max.)

256 file descriptors will probably be enough for all but the largest sites. There is no harm in setting the limits higher than you actually need (provided they're set to something lower than or equal to your system hard limit). 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 -s /bin/sh -c <pathbin in inn.conf>/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 -s /bin/sh -c '<pathbin in inn.conf>/rc.news stop'

In the contrib directory of this source tree, two sample init scripts are provided: one for people using System V-style init.d directories, and another for people using systemd-style init scripts.

If you wish to use TLS/SSL for your readers, you need to start a second nnrpd to listen to these connections to NNTPS port 563 and put something like that in your init scripts:

    su news -s /bin/sh -c '<pathbin in inn.conf>/nnrpd -D -c <pathetc in inn.conf>/readers-ssl.conf -p 563 -S'

where readers-ssl.conf is the file which indicates whether a given connection is allowed to read and post news (you can also use the previously created readers.conf file to handle TLS/SSL connections). Note that a news client which supports the STARTTLS command can also use the conventional NNTP port 119 to initiate a TLS connection. However, such clients are not widespread yet.

In the shutdown section of the init script, you can put:

    start-stop-daemon --stop --name nnrpd --quiet --oknodo

or if you do not have a start-stop-daemon utility:

    su news -s /bin/sh -c 'killall nnrpd'

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, a channel feed program which should be run out of newsfeeds if you want your news server to process any control messages; see Configuring INN for specific instructions. Note that pgpverify must also be set to true in inn.conf.

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. The last version of that file is available from <ftp://ftp.isc.org/pub/usenet/CONFIG/control.ctl>.

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 pathnews/.gnupg for GnuPG and pathnews/.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=<pathetc in inn.conf>/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=<pathetc in inn.conf>/pgp pgp <file>

You can safely answer no to questions about whether you want to sign, trust, or certify keys. And you may afterwards do:

    cp <pathetc in inn.conf>/pgp/pubring.gpg <pathetc in inn.conf>/pgp/trustedkeys.gpg

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 and you can just import the whole file.

If you want to make sure that the keys have been correcly imported, use:

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

$Id: install.pod 9599 2014-02-08 13:56:54Z iulius $

Last spun 2014-07-26 from POD modified 2014-02-08