+++ /dev/null
-Welcome to INN 2.4!
-
- Please read this document thoroughly before trying to install INN.
- You'll be glad you did.
-
- If you are upgrading from a major release of INN prior to 2.3, it is
- recommended that you make copies of your old configuration files and use
- them as guides for doing a clean installation and configuration of 2.4.
- Many config files have changed, some have been added, and some have been
- removed. You'll find it much easier to start with a fresh install than
- to try to update your old installation. This is particularly true if
- you're upgrading from a version of INN prior to 2.0.
-
- If you are upgrading from INN 2.3 or later, you may be able to just
- update the binaries, scripts, and man pages by running:
-
- make update
-
- after building INN and then comparing the new sample configuration files
- with your current ones to see if anything has changed. If you take this
- route, the old binaries, scripts, and man pages will be saved with an
- extension of ".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 --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 INN 2.3, also look at the new
- sample configuration files in samples to see if there are new options of
- interest to you. In particular, control.ctl has been updated and
- inn.conf has various new options.
-
- 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-bugs@isc.org>.
-
-Before You Begin
-
- INN requires several other packages be installed in order to be fully
- functional (or in some cases, to work at all):
-
- * In order to build INN, you will need a C compiler that understands
- ANSI C. If you are trying to install INN on an operating system that
- doesn't have an ANSI C compiler (such as SunOS), installing gcc is
- recommended. You can get it from <ftp://ftp.gnu.org/gnu/gcc/> or its
- mirrors. INN is tested with gcc more thoroughly than with any other
- compiler, so even if you have another compiler available, you may wish
- to use gcc instead.
-
- * Currently, in order to build INN, you will need an implementation of
- yacc. GNU bison (from <ftp://ftp.gnu.org/gnu/bison/> or its mirrors)
- will work fine. We hope to remove this requirement in the future.
-
- * INN requires at least Perl 5.004_03 to build and to run several
- subsystems. INN is tested primarily with newer versions of Perl, so
- it's generally recommended that you install the latest stable
- distribution of Perl before compiling INN. For instructions on
- obtaining and installing Perl, see
- <http://www.perl.com/pub/language/info/software.html>. Note that you
- may need to use the same compiler and options (particularly largefile
- support) for Perl and INN.
-
- If you're using a version of Perl prior to 5.6.0, you may need to make
- sure that the Perl versions of your system header files have been
- generated in order for Sys::Syslog to work properly (used by various
- utility programs, including controlchan). To do this, run the
- following two commands:
-
- # cd /usr/include
- # h2ph * sys/*
-
- An even better approach is to install Perl 5.6.1 or later, which have
- a fixed version of Sys::Syslog that doesn't require this (as well as
- many other improvements over earlier versions of Perl).
-
- * The INN Makefiles use the syntax "include FILE", rather than the
- syntax expected by some BSDish systems of ".include <FILE>". If your
- system expects the latter syntax, the recommended solution is to
- install GNU make from <ftp://ftp.gnu.org/make/>. You may have GNU
- make already installed as gmake, in which case using gmake rather than
- make to build INN should be sufficient.
-
- * If you want to enable support for authenticated control messages (this
- is not required, but is highly recommended for systems carrying public
- Usenet hierarchies) then you will need to install some version of PGP.
- The recommended version is GnuPG, since it's actively developed,
- supports OpenPGP, is freely available and free to use for any purpose
- (in the US and elsewhere), and (as of version 1.0.4 at least) supports
- the RSA signatures used by most current control message senders.
-
- Alternately, you can install PGP from <http://www.pgp.com/> or one of
- the international versions of it. Be warned, however, that the
- licensing restrictions on PGP inside the United States are extremely
- unclear; it's possible that if you are installing INN for a company in
- the U.S., even if the news server is not part of the business of that
- company, you would need to purchase a commercial license for PGP. For
- an educational or non-profit organization, this shouldn't be a
- problem.
-
- * If you want to use either the Python embedded hooks, you'll need to
- have a suitable versions of Python installed. See doc/hook-python for
- more information.
-
- * Many of INN's optional features require other packages (primarily
- libraries) be installed. If you wish to use any of these optional
- features, you will need to install those packages first. Here is a
- table of configure options enabling optional features and the software
- and versions you'll need:
-
- --with-perl Perl 5.004_03 or higher, 5.6.1+ recommended
- --with-python Python 1.5.2 or higher
- --with-berkeleydb BerkeleyDB 2.0 or higher, 4.2+ recommended
- --with-openssl OpenSSL 0.9.6 or higher
- --with-sasl SASL 2.x or higher
- --with-kerberos MIT Kerberos v5 1.2.x or higher
-
- If any of these libraries (other than Perl or Python) are built shared
- and installed in locations where your system doesn't search for shared
- libraries by default, you may need to encode the paths to those shared
- libraries in the INN binaries. For more information on shared library
- paths, see:
-
- <http://www.eyrie.org/~eagle/notes/rpath.html>
-
- For most systems, setting the environment variable LD_RUN_PATH to a
- colon-separated list of additional directories in which to look for
- shared libraries before building INN will be sufficient.
-
-Unpacking the Distribution
-
- Released versions of INN are available from ftp.isc.org in /isc/inn.
- New major releases will be announed on <inn-announce@isc.org> (see
- README) when they're made.
-
- If you want more a more cutting-edge version, you can obtain current
- snapshots from from ftp.isc.org in directory /isc/inn/snapshots. These
- are snapshots of the INN CVS tree taken daily; there are two snapshots
- made each night (one of the current development branch, and one of the
- stable branch consisting of bug fixes to the previous major release).
- They are stored in date format; in other words the snapshots from April
- 6th, 2000, would be named 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). 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 isn't
- used for any other purposes. You can change it with the
- --with-news-master option to configure (see below).
-
- WARNING: By default, INN installs various configuration files as
- group-writeable, and in general INN is not hardened from a security
- standpoint against an attack by someone who is already in the news
- group. In general, you should consider membership in the news group as
- equivalent to access to the news account. You should not rely on being
- able to keep anyone with access to the news GID from converting that
- into access to the news UID. The recommended configuration is to have
- the only member of the group "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, CNFS, and timecaf
- databases written by an INN built with this option are incompatible
- with those written by an INN without this option.
-
- --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, inndstart(8) refuses to bind to any port under 1024
- other than 119 and 433 for security reasons (to prevent attacks on
- rsh(1)-based commands and replacing standard system daemons). If
- you want to run innd on a different port under 1024, you'll need to
- tell configure what port you intend to use. (You'll also still need
- to set the port number in inn.conf or give it to inndstart on the
- command line.)
-
- --with-syslog-facility=FACILITY
- Specifies the syslog facility that INN programs should log to. The
- default is LOG_NEWS unless configure detects that your system
- doesn't understand that facility, in which case it uses LOG_LOCAL1.
- This flag overrides the automatic detection. Be sure to specify a
- facility not used by anything else on your system (one of LOG_LOCAL0
- through LOG_LOCAL7, for example).
-
- --enable-libtool
- INN has optional support for libtool to generate shared versions of
- INN's libraries. This can significantly decrease the size of the
- various binaries that come with a complete INN installation. You
- can also choose to use libtool even when only building static
- libraries; a libtool build may be somewhat more portable on weird
- systems. libtool builds aren't the default because they take
- somewhat longer. See "./configure --help" for the various available
- options related to libtool builds.
-
- Please note that INN's shared library interface is not stable and
- may change drastically in future releases. For this reason, it's
- also not properly versioned and won't be until some degree of
- stability is guaranteed, and the relevant header files are not
- installed. Only INN should use INN's shared libraries, and you
- should only use the shared libraries corresponding to the version of
- INN that you're installing.
-
- Also, when updating an existing version of INN, INN tries to save
- backup copies of all files so that you can revert to the previous
- installed version. Unfortunately, when using shared libraries, this
- confuses ldconfig on some systems (such as Linux) and the symbolic
- links for the libraries may point to the .OLD versions. If this
- happens, you can either fix the links by hand or remove the .OLD
- versions and re-run ldconfig.
-
- --enable-uucp-rnews
- If this option is given to configure, rnews will be installed setuid
- 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 (2.x or 3.x), which means that it
- will then be possible to use the ovdb overview method if you wish.
- Enabling this configure option doesn't mean you'll be required to
- use ovdb, but it does require that Berkeley DB be installed on your
- system (including the header files, not just the runtime libraries).
- If a path is given, it sets the installed directory of Berkeley DB
- (configure will search for it in some standard locations, but if you
- have it installed elsewhere, you may need this option).
-
- --with-openssl=PATH
- Enables support for SSL for news reading, which means it will be
- possible to have SSL or TLS encrypted NNTP connections between your
- server and newsreaders. This option requires OpenSSL be installed
- on your system (including the header files, not just the runtime
- libraries). If a path is given, it sets the installed directory of
- OpenSSL. After compiling and installing INN with this option,
- you'll still need to make a certificate and private key to use SSL.
- See below for details on how to do that.
-
- --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-bugs@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 interpretor will allow you to use one
- of the available excellent spam filters if you so choose.)
-
- If the configure program runs successfully, then you are ready to build
- the distribution. From the root of the INN source tree, type:
-
- make
-
- At this point you can step away from the computer for a little while and
- have a quick snack while INN compiles. On a decently fast system it
- should only take five or ten minutes at the most to build.
-
- Once the build has completed successfully, you are ready to install INN
- into its final home. Type:
-
- make install
-
- You will need to run this command as root so that INN can create the
- directories it needs, change ownerships (if you did not compile as the
- news user) and install a couple of setuid wrapper programs needed to
- raise resource limits and allow innd to bind to ports under 1024. This
- step will install INN under the install directory (/usr/local/news,
- unless you specified something else to the configure script).
-
- If you are configuring SSL support for newsreaders, you must make a
- certificate and private key at least once. Type:
-
- make cert
-
- as root in order to do this.
-
- You are now ready for the really fun part: configuring your copy of
- INN!
-
-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 degredation due to file system overhead
- (creating and deleting individual files is a slow operation).
-
- timecaf
- Similar to timehash, articles are stored by arrival time, but
- instead of writing a separate file for each article, multiple
- articles are put in the same file.
-
- Advantages: Roughly four times faster than timehash for article
- writes, since much of the file system overhead is bypassed, while
- still retaining the same fine control over article retention time.
-
- Disadvantages: Even worse than timehash, and similar to cnfs
- (below), using this method means giving up all but the most careful
- manually fiddling with your article spool. As one of the newer and
- least widely used storage types, timecaf has not been as thoroughly
- tested as the other methods.
-
- cnfs
- CNFS stores articles sequentially in pre-configured buffer files.
- When the end of the buffer is reached, new articles are stored from
- the beginning of the buffer, overwriting older articles.
-
- Advantages: Blazingly fast because no file creations or deletions
- are necessary to store an article. Unlike all other storage
- methods, does not require manual article expiration; old articles
- are deleted to make room for new ones when the buffers get too full.
- Also, with CNFS your server will never throttle itself due to a full
- spool disk, and groups are restricted to just the buffer files you
- give them so that they can never use more than the amount of disk
- space you allocate to them.
-
- Disadvantages: Article retention times are more difficult to
- control because old articles are overwritten automatically. Attacks
- on Usenet, such as flooding or massive amounts of spam, can 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.
-
- If your news server will be supporting readers, you'll also need to
- choose an overview storage mechanism (by setting *ovmethod* in
- inn.conf). There are three overview mechanisms to choose from:
- tradindexed, buffindexed, and ovdb. tradindexed is very fast for
- readers, but it has to update two files for each incoming article and
- can be quite slow to write. buffindexed can keep up with a large feed
- more easily, since it uses large buffers to store all overview
- information, but it's somewhat slower for readers (although not as slow
- as the unified overview in INN 2.2). ovdb stores overview data in a
- Berkeley DB database; it's fast and very robust, but requires more disk
- space. See the ovdb(5) man page for more information on it.
-
- Note that ovdb has not been as widely tested as the other overview
- mechanisms and should be considered experimental. tradindexed is the
- best tested and most widely used of the overview implementations.
-
- If buffindexed is chosen, you will need to create the buffers for it to
- use (very similar to creating CNFS buffers) and list the available
- buffers in buffindexed.conf. See buffindexed.conf(5) for more
- information.
-
-Configuring INN
-
- All documentation from this point on assumes that you have set up the
- news user on your system as suggested in "Installing INN" so that the
- root of your INN installation is ~news/. If you've moved things around
- by using options with "configure", you'll need to adjust the
- instructions to account for that.
-
- All of INN's configuration files are located in ~news/etc. Unless noted
- otherwise, any files referred to below are in this directory. When you
- first install INN, a sample of each file (containing lots of comments)
- is installed in ~news/etc; refer to these for concrete examples of
- everything discussed in this section.
-
- All of INN's configuration files, all of the programs that come with it,
- and some of its library routines have documentation in the form of man
- pages. These man pages were installed in ~news/man as part of the INN
- installation process and are the most complete reference to how INN
- works. You're strongly encouraged to refer to the man pages frequently
- while configuring INN, and for quick reference afterwards. Any detailed
- questions about individual configuration files or the behavior of
- specific programs should be answered in them. You may want to add
- ~news/man to your MANPATH environment variable; otherwise, you may have
- to use a command like:
-
- man -M ~news/man inn.conf
-
- to see the 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.
-
- 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 email 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 or 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
- manpage contains more detailed information.
-
- newsfeeds is organized as a series of feed entries. Each feed entry is
- composed of four fields separated by colons. Entries may span multiple
- lines by using a backslash ("\") to indicate that the next line is a
- continuation of the current line. (Note that comments don't interact
- with backslashes in the way you might expect. A commented-out line
- ending in a backslash will still be considered continued on the next
- line, possibly resulting in more commented out than you intended or
- bizarre syntax errors. In general, it's best to avoid commenting out
- lines in the middle of continuation lines.)
-
- The first field in an entry is the name of the feed. It must be unique,
- and for feeds to other news servers it is usually set to the actual
- hostname of the remote server (this makes things easier). The name can
- optionally be followed by a slash and a comma-separated exclude list.
- If the feed name or any of the names in the exclude list appear in the
- Path line of an article, then that article will not be forwarded to the
- feed as it is assumed that it has passed through that site once already.
- The exclude list is useful when a news server's hostname is not the same
- as what it puts in the Path header of its articles, or when you don't
- want a feed to receive articles from a certain source.
-
- The second field specifies a set of desired newsgroups and distribution
- lists, given as newsgroup-pattern/distribution-list. The distribution
- list is not described here; 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 ~news/spool/outgoing
- named remote.example.com and containing the Message-ID and storage token
- of each message to send to that site. (The storage token is INN's
- internal pointer to where an article is stored; to retrieve an article
- given its storage token, use 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*:/usr/local/news/bin/startinnfeed -y
-
- (adjust the path to startinnfeed(1) if you installed it elsewhere).
- Note that we don't feed this entry any articles directly (its newsgroup
- pattern is "!*"). 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
- startinnfeed process can be told to start imapfeed instead of innfeed.
- The feed entry for this is as follows:
-
- imapfeed!\
- :!*\
- :Tc,Wnm*,S16384:/usr/local/news/bin/startinnfeed imapfeed
-
- And set up entries for each remote site like:
-
- remote.example.com/news.example.com\
- :<newsgroups>\
- :Tm:imapfeed!
-
- For more information on imapfeed, look at the innfeed/imap_connection.c.
- For more information on IMAP in general, see RFC 2060.
-
- Finally, there is a special entry for controlchan(8), which processes
- newsgroup control messages, that should always be in newsfeeds unless
- you never want to honor any control messages. This entry should look
- like:
-
- controlchan!\
- :!*,control,control.*,!control.cancel\
- :Tc,Wnsm:/usr/local/news/bin/controlchan
-
- (modified for the actual path to controlchan if you put it somewhere
- else). See "Processing 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. Unfortunately, crosspost
- currently will not work even with the tradspool storage method. You can
- still use overchan if you make sure to set *useoverchan* to true in
- inn.conf so that innd doesn't write overview data itself, but be
- careful: innd may accept articles faster than overchan can process the
- data.
-
- incoming.conf
-
- 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.
-
- 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. Some OSes do not support files larger than 2 GB, which will
- limit the size you can make a single cycbuff, but you can still combine
- many cycbuffs into each metacycbuff. Older versions of Linux are known
- to have this limitation; FreeBSD does not. Some OSes that support large
- files don't support direct access to block devices for large partitions
- (Solaris prior to Solaris 7, or not running in 64-bit mode, is in this
- category); on those OSes, if you want cycbuffs over 2 GB, you'll have to
- use regular files. If in doubt, keep your cycbuffs smaller than 2 GB.
- Also, when laying out your cycbuffs, you will want to try to arrange
- them across as many physical disks as possible (or use a striped disk
- array and put them all on that).
-
- In order to use any cycbuff larger than 2 GB, you need to build INN with
- the --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:CYCBUFF,CYCBUFF,CYCBUFF
-
- BUFFNAME is the name of the metacycbuff and must be unique and at most
- eight characters long. These should be a bit more meaningful than the
- cycbuff names since they will be used in other config files as well.
- Try to name them after what will be stored in them; for example, if this
- metacycbuff will hold alt.binaries postings, "BINARIES" would be a good
- choice. The last part of the entry is a comma-separated list of all of
- the cycbuffs that should be used to build this metacycbuff. Each
- cycbuff should only appear in one metacycbuff line, and all metacycbuff
- lines must occur after all cycbuff lines in the file.
-
- If you want INN to fill each cycbuff before moving on to the next one
- rather than writing to them round-robin, add ":SEQUENTIAL" to the end of
- the metacycbuff line. This may give noticeably better performance when
- using multiple cycbuffs on the same spindle (such as partitions or
- slices of a larger disk), but will probably give worse performance if
- your cycbuffs are spread out across a lot of spindles.
-
- 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" for more information on how to do that.
-
- storage.conf
-
- storage.conf determines where incoming articles will be stored (what
- storage method, and in the case of CNFS, what metacycbuff). Each entry
- in the file defines a storage class for articles. The first matching
- storage class is used to store the article; if no storage class matches,
- INN will reject that article. (This is almost never what you want, so
- make sure this file ends in a catch-all entry that will match
- everything.)
-
- A storage class definition looks like this:
-
- method <methodname> {
- newsgroups: <wildmat>
- class: <storage_class>
- size: <minsize>[,<maxsize>]
- expires: <mintime>[,<maxtime>]
- options: <options>
- }
-
- <methodname> is the name of the storage method to use to store articles
- in this class ("cnfs", "timehash", "timecaf", "tradspool", or the
- special method "trash" that accepts the article and throws it away).
-
- The first parameter is a wildmat pattern in the same format used by the
- newsfeeds(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; it lets you assign
- storage classes based on the Expires: header of incoming articles. The
- exact details are in storage.conf(5). It's very easy to use this
- parameter incorrectly; leave it out entirely unless you've read the man
- page and know what you're doing.
-
- The fifth parameter is the options parameter. Currently only CNFS uses
- this field; it should contain the name of the metacycbuff used to store
- articles in this storage class.
-
- If you're using CNFS exclusively, just create one storage class for each
- metacycbuff that you have defined in cycbuff.conf and set the newsgroups
- pattern according to what newsgroups should be stored in that buffer.
-
- If you're using timehash or timecaf, the storage class IDs are used to
- store articles in separate directory trees, which you can take advantage
- of to put particular storage classes on different disks. Also,
- currently storage class is the only way to specify expiration time, so
- you will need to divide up your newsgroups based on how long you want to
- retain articles in those groups and create a storage class for each such
- collection of newsgroups. Make note of the storage class IDs you assign
- as they will be needed when you edit 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 10 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/:10
-
- This entry says how long to keep the Message-IDs for articles that have
- already expired in the history file so that the server doesn't accept
- them again. Occasionally, fairly old articles will get regurgitated
- somewhere and offered to you again, so even after you've expired
- articles from your spool, you want to keep them around in your history
- file for a little while to ensure you don't get duplicates.
-
- INN will reject any articles more than a certain number of days old (the
- *artcutoff* parameter in inn.conf, defaulting to 10); the number on the
- "/remember/" line should match that.
-
- CNFS makes no further use of expire.ctl, since articles stored in CNFS
- buffers expire automatically when the buffer runs out of free space (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 contraints set by <keep> and <purge>. All
- articles in this storage class will be kept for at least <keep> days,
- regardless of their Expires: headers, and all articles in this storage
- class will be expired after <purge> days, even if their Expires: headers
- specify a longer life.
-
- All three of these fields can also contain the special keyword "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 }' \
- ~news/etc/cycbuff.conf
-
- If you are using block devices, you don't technically have to do
- anything at all (since INN is capable of using the devices in /dev), but
- you probably want to create special device files for those devices
- somewhere for INN's private use. It s more convenient to keep all of
- INN's stuff together, but more importantly, the device files used by INN
- really should be owned by the news user and group, and you may not want
- to do that with the files in /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
- (~news/db). This directory will hold the active(5) file (the list of
- newsgroups you carry), the active.times(5) file (the creator and
- creation time of newsgroups created since the server was initialized),
- the newsgroups(5) file (descriptions for all the newsgroups you carry),
- and the history(5) file (a record of every article the server currently
- has or has seen in the past few days, used to decide whether to accept
- or refuse new incoming messages).
-
- Before starting to work on this, make sure you're logged on as the news
- user, since all of these files need to be owned by that user. This is a
- good policy to always follow; if you are doing any maintenance work on
- your news server, log on as the news user. Don't do maintenance work as
- root. Also make sure that ~news/bin is in the default path of the news
- user (and while you're at it, make sure ~news/man is in the default
- MANPATH) so that you can run INN maintenance commands without having to
- type the full path.
-
- If you already have a server set up (if you're upgrading, or setting up
- a new server based on an existing server), copy active and newsgroups
- from that server into ~news/db. Otherwise, you'll need to figure out
- what newsgroups you want to carry and create new active and newsgroups
- files for them. If you plan to carry a full feed, or something close to
- that, go to <ftp://ftp.isc.org/pub/usenet/CONFIG/> and download active
- and newsgroups from there; that will start you off with reasonably
- complete files. If you plan to only carry a small set of groups, the
- default minimal active file installed by INN is a good place to start;
- 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" 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 ~news/db
- touch history
- makedbz -i
-
- When it finishes, rename the files it created to remove the ".n" in the
- file names and then make sure the file permissions are correct on all
- the files you've just created:
-
- chmod 644 *
-
- Your news database files are now ready to go.
-
-Configuring syslog
-
- While some logs are handled internally, INN also logs a wide variety of
- information via syslog. INN's nightly report programs know how to roll
- and summarize those syslog log files, but when you first install INN you
- need to set them up.
-
- If your system understands the "news" syslog facility, INN will use it;
- otherwise, it will log to "local1". Nearly every modern system has a
- "news" syslog facility so you can safely assume that yours does, but if
- in doubt take a look at the output from running "configure". You should
- see a line that looks like:
-
- checking log level for news... LOG_NEWS
-
- If that says LOG_LOCAL1 instead, change the below instructions to use
- "local1" instead of "news".
-
- Edit /etc/syslog.conf on your system and add lines that look like the
- following:
-
- news.crit /usr/local/news/log/news.crit
- news.err /usr/local/news/log/news.err
- news.notice /usr/local/news/log/news.notice
-
- (Change the path names as necessary if you installed INN in a different
- location than /usr/local/news.) These lines *must* be tab-delimited, so
- don't copy and paste from these instructions. Type it in by hand and
- make sure you use a tab, or you'll get mysterious failures. You'll also
- want to make sure that news log messages don't fill your other log files
- (INN generates a lot of log traffic); 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 /usr/local/news/log/news.crit
- touch /usr/local/news/log/news.err
- touch /usr/local/news/log/news.notice
- chown news /usr/local/news/log/news.*
- chgrp news /usr/local/news/log/news.*
-
- (again adjusting the paths if necessary for your installation).
- Finally, send a HUP signal to syslogd to make it re-read its
- configuration file.
-
-Setting Up the Cron Jobs
-
- INN requires a special cron job to be set up on your system to run
- news.daily(8) which performs daily server maintenance tasks such as
- article expiration and the processing and rotation of the server logs.
- Since it will slow the server down while it is running, it should be run
- during periods of low server usage, such as in the middle of the night.
- To run it at 3am, for example, add the following entry to the news
- user's crontab file:
-
- 0 3 * * * /usr/local/news/bin/news.daily expireover lowmark
-
- or, if your system does not have per-user crontabs, put the following
- line into your system crontab instead:
-
- 0 3 * * * su -c "/usr/local/news/bin/news.daily expireover lowmark" news
-
- If you're using any non-CNFS storage methods, add "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 * * * * /usr/local/news/bin/nntpsend
-
- The pathnames and user ID used above are the installation defaults;
- change them to match your installation if you used something other than
- the defaults.
-
- The parameters passed to news.daily in the above example are the most
- common (and usually the most efficient) ones to use. More information
- on what these parameters do can be found in the news.daily(8) man page.
-
-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 both
- startinnfeed and inndstart (the setuid root wrapper scripts that start
- innfeed and innd, respectively) to increase the file descriptor limits
- before they run the regular INN programs. Note, however, that INN won't
- be able to increase the limits above the hard limits set by your
- operating system; on some systems, that hard limit is normally 256 file
- descriptors (Linux, for example). On others, like Solaris, it's 1024.
- Increasing the limit beyond that value may require serious system
- configuration work. (On some operating systems, it requires patching
- and recompiling the kernel. On Solaris it can be changed in
- /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 -c /usr/local/news/bin/rc.news
-
- in the system boot scripts. If innd is stopped or killed, you can
- restart it by running rc.news by hand as the news user.
-
- The rc.news script may also be used to shut down INN, with the "stop"
- option:
-
- su - news -c '/usr/local/news/bin/rc.news stop'
-
- In the contrib directory of this source tree is a sample init script for
- people using System V-style init.d directories.
-
-Processing Newsgroup Control Messages
-
- Control messages are specially-formatted messages that tell news servers
- to take various actions. Cancels (commands to delete messages) are
- handled internally by INN, and all other control messages are processed
- by controlchan. controlchan should be run out of newsfeeds if you want
- your news server to process any control messages; see "Configuring INN"
- for specific instructions.
-
- The actions of controlchan are determined by control.ctl, which lists
- who can perform what actions. The primary control messages to be
- concerned with are "newgroup" (to create a newsgroup), "rmgroup" (to
- remove a newsgroup), and "checkgroups" (to compare the list of groups
- carried in a hierarchy to a canonical list). INN comes with a
- control.ctl file that processes control messages in most major public
- hierarchies; if you don't want to act on all those control messages, you
- should remove from that file all entries for hierarchies you don't want
- to carry.
-
- You can tell INN to just authenticate control messages based on the From
- header of the message, but this is obviously perilous and control
- messages are widely forged. Many hierarchies sign all of their control
- messages with PGP, allowing news servers to verify their authenticity,
- and checking those signatures for hierarchies that use them is highly
- recommended. controlchan knows how to do this (using pgpverify) without
- additional configuration, but you do have to provide it with a public
- key ring containing the public keys of all of the hierarchy
- administrators whose control messages you want to check.
-
- INN expects the public key ring to either be in the default location for
- a PGP public key ring for the news user (generally ~news/.gnupg for
- GnuPG and ~news/.pgp for old PGP implementations), or in pathetc/pgp
- (/usr/local/news/etc/pgp by default). The latter is the recommended
- path. To add a key to that key ring, use:
-
- gpg --import --homedir=/usr/local/news/etc/pgp <file>
-
- where <file> is a file containing the hierarchy key. Change the homedir
- setting to point to pathetc/pgp if you have INN installed in a
- non-default location. If you're using the old-style PGP program, an
- equivalent command is:
-
- env PGPPATH=/usr/local/news/etc/pgp pgp <file>
-
- You can safely answer "no" to questions about whether you want to sign,
- trust, or certify keys.
-
- The URLs from which you can get hierarchy keys are noted in comments in
- control.ctl. <ftp://ftp.isc.org/pub/pgpcontrol/PGPKEYS> tries to
- collect the major hierarchy keys.
-
- If you are using GnuPG, please note that the first user ID on the key
- will be the one that's used by INN for verification and must match the
- key listed in control.ctl. If a hierarchy key has multiple user IDs,
- you may have to remove all the user IDs except the one that matches the
- control.ctl entry using "gpg --edit-key" and the "delkey" command.
-
~ian / innduct.git / blobdiff