X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=INSTALL;fp=INSTALL;h=0000000000000000000000000000000000000000;hb=b7a32e2d73e3ab1add8208d3e157f7269a31ef4d;hp=eceb489f340d9ab89c547ebddc78cd947c559ddf;hpb=ac902a8299ff4469b356836f431ead31c3377377;p=innduct.git diff --git a/INSTALL b/INSTALL deleted file mode 100644 index eceb489..0000000 --- a/INSTALL +++ /dev/null @@ -1,1527 +0,0 @@ -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 . - -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 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 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 - . 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 ". If your - system expects the latter syntax, the recommended solution is to - install GNU make from . 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 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: - - - - 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 (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 | tar -xf - - - Extracting the source distribution will create a directory named - inn- or inn-- 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 - ). - - 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\ - :\ - :Tf,Wnm: - - where 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\ - :\ - :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 - 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\ - :\ - :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 { - newsgroups: - class: - size: [,] - expires: [,] - options: - } - - 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 of 0 (or a missing - ) means no upper limit (and of course a 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: - - ::: - - is the number assigned to a storage class in - storage.conf. 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 and . All - articles in this storage class will be kept for at least days, - regardless of their Expires: headers, and all articles in this storage - class will be expired after days, even if their Expires: headers - specify a longer life. - - All three of these fields can also contain the special keyword "never". - If is "never", only articles with explicit Expires: headers - will ever be expired. If is "never", articles with explicit - Expires: headers will be kept forever. Setting to "never" says - to honor Expires: headers even if they specify dates far into the - future. (Note that if is set to "never", all articles with - Expires: headers are kept forever and the value of is not used.) - - If the value of "groupbaseexpiry" is true, expire.ctl takes entries of - the form: - - :::: - - 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. 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: "" - 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 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 - - where 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 - - 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. 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. -