INN Implementation Guide

 $Id: implementation.pod,v 1.3 1999/12/15 13:48:33 esamsono Exp esamsono $
 By Elena Samsonova, <elena.inn@inter.nl.net>.

Position among the INN documentation

From most general to most detailed, the INN documents are structured in the following way:

Relation to other INN documentation

This is the INN Implementation Guide. It describes various configuration aspects of INN parts in detail. For greater detail yet please refer to the Install document and manual pages. For an overview and description of several INN architectures please refer to the INN Architecture Guide. If you are not sure which architecture to choose, read the INN Cookbook. For something more general still, please refer to Readme.

How to use it?

Before you begin with this guide, have your architecture outlined because you need to know the purpose and function of your different components before you can intelligently configure them. Decide what functionalities your system will support and use this guide to look up those functionalities for step-by-step instructions on their configuration.

Note however that although this guide contains a lot of useful information (or so I intended it to contain), it is by no means a substitute to the manual pages which provide the most complete and precise information on the workings of each program and on available options.

Key to the document layout

This document consists of two sections: Topics and Scenarios. The first section describes various issues on implementation and maintenance. If you are unfamiliar with INN and/or with news in general, this section may be helpful. It could also be handy for implementation of new functionalities or just as a reference.

The second section is meant to answer questions of the kind ``How do I implement this particular setup?'', so in a way this is the proper How-To for INN.

For those who upgrade their INN installation rather than start from scratch: Note that several configuration files have a different format now!


Topics


User Access Rights and Closed Groups

INN knows several user authentication methods which were also mentioned in the INN Cookbook and the INN Architecture Guide. Here we shall look at these methods in detail. All the methods are configured in readers.conf. Each nnrpd process reads it as it is spawned.

readers.conf is made up of authentication and access realms. Access rules for each individual user coming in are determined by matching his authentication method to one of the authentication realms in the file and going through the access realms that match this authentication realm. Read the readers.conf(5) manual page for more details. See also the following example:

              # An authentication realm.
              auth "foo.com" {
                   key: "foo"
                   hosts: "foo.com,*.foo.com"
                   res: "ident"
                   auth: "shadow"
                   default: "<FAIL>"
                   default-domain: "foo.com"
              }

              # Access realms for two different groups of users.
              access "default" {
                   key: "foo"
                   users: "*@foo.com"
                   newsgroups: "*,!internal.*"
                   access: "Read Post"
              }

              access "administrators" {
                   key: "foo"
                   users: "admin1@foo.com,admin2@foo.com"
                   newsgroups: "*"
                   access: "Read Post"
              }

              # Access realm for users who couldn't authenticate.
              access "disallowed" {
                   key: "foo"
                   users: "<FAIL>@foo.com"
                   newsgroups: "*,!internal.*"
                   access: "Read"
              }

What follows are example setups for the corresponding authentication types.

IP address based

The server determines each user's rights based on the user IP address. The user does not have to do anything to authenticate himself, it is done automatically. This is a very cheap authentication method.

        auth "local_ips" {
                hosts: "222.111.123.0/20,222.222.123.0/18,222.123.1.1"
                default: "<user>"
                default-domain: "foo.com"
        }
        access "local_ips" {
                users: "*@foo.com"
                newsgroups: "*,!control*,!junk"
                access: "Read Post"
        }

Note that users who come from other IP addresses than listed here, will not be let in directly but will try to match a different authentication method instead.

Resolved IP addresses

The same as above, only now the IP addresses are first reverse resolved to get host names out of them. This is handy when your IP address space is not continuous so that you may be better off specifying host names. This method is slightly more expensive than the IP address based one.

The implementation is similar to the direct IP addresses method, except that now we replace the IP addresses with their resolved counterparts:

        auth "local_ips" {
                hosts: "*.foo.com"
                default: "<user>"
                default-domain: "foo.com"
        }
        access "local_ips" {
                users: "*@foo.com"
                newsgroups: "*,!control*,!junk"
                access: "Read Post"
        }

User name and password variants

Here the user is supposed to provide a user name and password combination to authenticate. There are many ways of doing it, and your particular way may not be available. Look at programs in ~news/bin/auth for available options. Note that authentication programs try to establish a connection with the user's news client and exchange data with it, so you need to test them against your users' news clients to make sure that they work.

You can also easily write your own authentication and resolve program to suite your particular needs. There are a few simple guidelines for that, and the good news is that you don't need to go through the rest of the INN code to figure out how to write such a hook. What you want is located in the authprogs/ directory of the INN source tree.

In readers.conf you define this type of authentication as follows:

        auth "passwords" {
                hosts:  "*"
                key:    "pwd"
                auth:   "check_password nntp"
        }
        access "passwords" {
                key:    "pwd"
                newsgroups: "*,!local.newstest,!control*,!junk"
                access: "Read Post"
        }
        
        access "admin" {
                users:  "newstest"
                key:    "pwd"
                newsgroups: "local.newstest"
                access: "Read Post"
        }

This example defines two groups of users that can access the server from any IP address (because we have hosts:  "*"). An external program check_password is used to perform authentication with the client. If authentication is successful, and user name appears to be ``newstest'', then access realm ``admin'' is used (it defines users:  "newstest"). Here we see that this user is allowed to access only one news group: local.newstest, and that this user is allowed to read it and post in it.

If user name appears to be other than ``newstest'', then access realm ``passwords'' matches (it does not define the users: keyword and is therefore checked when no more access realms with keyword ``pwd'' are found). It defines that the user has access to all news groups except local.newstest, all groups starting with control and news group junk, which he is allowed to read and post to. See the manual page for newsfeeds for more information on the newsgroups: string.

Closed groups

Closed groups are those that may be accessed only by certain users after authentication rather than by any user without authentication.

Closed groups can be set up using a combination of access methods mentioned above. In those examples, local.newstest is a closed group accessible by anyone passing through the access realm ``admin''.


Moderated Groups

Moderated groups are those which do not allow direct postings from users but only accept postings from a few special users called moderators. Any regular user postings are sent to the moderator per e-mail, and it is up to the moderator to decide whether the article gets posted or not, and if so, then post it.

Moderated groups are often named group_name.mod in news group hierarchies, but this is not a requirement.

On the server side, moderated groups are marked as m in the active file. Use ctlinnd to actually change a group's status. Direct editing of the active file may only be done on an idle system (i.e. INN not running). Editing it on the fly asks for various nasty problems.

Moderator e-mail addresses are listed in the moderators file. nnrpd consults this file when an article is posted to a moderated group and e-mails it to the moderator instead.

In order to actually post an article to a moderated group, the moderator has to supply an additional Approved: header with the very same e-mail address as the one where the articles are sent to. This is of course not an evil hacker proof method which was clearly designed at the time when Usenet was a safer place. Several attempts have been made to design better methods, but none of them could be accepted as standard because of the backwards incompatibility problems.

For more information on moderation, check out URL: http://www.landfield.com/usenet/moderators/handbook/


Cancel and Control Articles

Cancel articles don't really carry any content but they cancel posted articles instead, that is make them disappear from the spool and from the news stream you are sending out.

Control articles don't carry any real content either but are meant for news group maintenance: creation and deletion of news groups as well as status updates (e.g. moderated versus umoderated). A special type of a control article is a checkgroup article which contains a list of valid news groups within the corresponding hierarchy. Processing such an article means removing the groups that exist on your server but are not listed in the article, and creating the groups that are listed but not found on your server. The good news is that processing can be done automatically, either by configuring the server to process the articles as soon as they arrive (edit the configuration file control.ctl), or by processing them semi-manually with ctlinnd. See section News Groups Maintenance for details.

An obvious question that arises here is how to know whether an article is real or forged. There are several policies you can adopt to deal with this issue:

Keeping a list of valid sender addresses

This is a widely used method, although the least safe one (after accepting anything from anybody). You simply list sender e-mail addresses in control.ctl of people whose control articles you accept and of people whose control articles you ignore under any circumstances (a black list). control.ctl comes with the current addresses of hierarchy maintainers. Obviously, evil forces can forge that very easily.

Using PGP verification

This method has gained wide acceptance although it is not 100% forge-proof. The sender of a control article has to include his PGP signature in it, and this signature is checked against a known one. The article is only processed if the signature matches. control.ctl gives a number of examples how to use that as well. RTFM.


Handling News Feeds

Setting up incoming feed

Incoming feeds are handled by innd and are configured in incoming.conf. Pay attention to the peer ME which is your own news server. If this peer is not configured properly, the articles will not appear in your spool.

There's another important factor for setting up incoming feeds: the ME entry in newsfeeds. This is a special entry in which the news group pattern is prepended to all the other feeds, and the distributions pattern determines what distributions (from the Distribution: header of incoming articles) are accepted from remote sites by your server. If you are having troubles receiving feed, try deleting the distributions part entirely to receive all distributions. Please read the manual page for newsfeeds.

Setting up outgoing feed

Outgoing feeds are configured in newsfeeds which determines the method to be used to transfer the articles to the peer.

Batch method

For low-volume feeds batched method may be used with the transfer handled by nntpsend (which calls innxmit for each peer). nntpsend is configured in nntpsend.ctl and passwd.nntp.

Stream method

For high-volume feeds channel method may be used with the transfer handled by innfeed, one instance of the program serving all the peers. It is configured in innfeed.conf.

Setting up anti-spam filters

Filters for user postings

User postings may be pulled through an anti-spam filter that checks every article and rejects ``bad'' ones. If it is a Perl script, it should be copied to the bin/filter/filter_nnrpd.pl, if it is a Tcl/Tk script, it goes to bin/filter/filter_nnrpd.tcl.

Refer to the filter documentation for specific configuration details or see below description of some most popular filters.

Filters for the incoming feed

Incoming feed may be pulled through an anti-spam filter that checks every article and drops ``bad'' ones. If it is a Perl script, it should be copied to the bin/filter/filter_innd.pl, if it is a Tcl/Tk script, it goes to bin/filter/filter_innd.tcl.

Refer to the filter documentation for specific configuration details or see below description of some most popular filters.


News Groups Maintenance

News groups maintenance consists of keeping an up-to-date collection of news groups on your server with reasonable expire periods. See section Article Spool and Expiration for details on expiration. In this section we'll concentrate on keeping your list of news groups in the best shape.

There are several methods of news group maintenance:

These methods are not mutually exclusive and can indeed be combined. We shall look at them in detail.


Automatic and Manual Processing of Control Articles

Automatic processing means that as soon as a control article arrives in the news feed, innd processes it according to the configuration defined in control.ctl (see also section Cancel and Control Articles). The most important control articles are checkgroup, newgroup and rmgroup. Other articles are usually not processed, you can still log or mail them if you want, or drop them right away. Control articles are processed automatically if the corresponding entry in control.ctl is marked as doit (see manual page for control.ctl).

Checkgroup

Checkgroup articles contain a list of news groups belonging to the corresponding hierarchy. Processing such articles means removing news groups found on your server but not on the list, and adding news groups found on the list but not on your server. The usual way of handling checkgroup articles is to mail them to the news administrator for manual processing. There are two reasons for this: 1) processing of a long checkgroup article may cause a very substantial load on the server, and 2) processing a forged checkgroup article will mess up the whole hierarchy.

To process a checkgroup article, feed it to docheckgroups that is located in the lib subdirectory of your INN installation. Its output can be fed to a shell for actual processing. It is usually smart to redirect it into a file first and check for sanity.

Newgroup

Newgroup articles announce creation of a new group. You are only supposed to process these articles if they come from competent parties, i.e. maintainers of the corresponding news hierarchy. See section Cancel and Control Articles on authentication methods for automatic processing.

To process a newgroup article manually, use ctlinnd.

Rmgroup

Rmgroup articles announce deletion of a news group. Here again, you are only supposed to process these articles if they come from competent parties. If processing forged newgroup articles will only clutter your news spool, processing forged rmgroup article will delete valid news groups and potentially provoke your users' complaints. See section Cancel and Control Articles on authentication methods for automatic processing.

To process a rmgroup article manually, use ctlinnd.


Active File Synchronization and Clean-Up

If you do not receive control articles, or you don't want to bother with processing them yourself, you can opt for a totally different method of news group maintenance: active file synchronization. As implied by the name, you need a peer whose active file you take as an example and synchronize with it. Synchronization need not be complete, but it still means that you trust your peer to maintain an up-to-date active file. This can be done with actsync.

Even if you don't use active file synchronization for your news group maintenance, it is still a good idea to clean up your active file every now and then from illegal and silly groups. Good news is that you don't need to edit a 60,000 line file by hand (although it is a possibility, but ONLY when INN is not running). Use actsync to check and possibly fix your active file. Refer to the manual page for further details, it even contains some examples!


Article Spool and Expiration

See INN Architecture Guide and Install documents for a discussion of pros and cons of different article storage formats. Here we shall assume that you have already designed your article spool and discuss the specifics of setting up and maintaining them.

Traditional spool (tradspool)

This is the simplest method to set up: no set up. This method is used by default if you don't configure any of the methods described below. If you do configure other methods, you also need to configure tradspool in storage.conf.

The path to your spool is configured in inn.conf with the patharticles parameter. So all you need to do is make sure the directory exists and that you have some disk space there.

This method allows for a high level of article retention control which is configured in expire.ctl, please see the appropriate manual page.

Time hashed spool (timehash)

This method is set up in storage.conf. If you want to use timehash for (a part of) your spool, uncomment example entries and adjust the values. See the manual page of storage.conf for details.

This method allows for a high level of article retention control which is configured in expire.ctl, please see the appropriate manual page.

Time hashed buffered spool (timecaf)

This method is set up in storage.conf. If you want to use timecaf for (a part of) your spool, uncomment example entries and adjust the values. See the manual page of storage.conf for details.

This method allows for a high level of article retention control which is configured in expire.ctl, please see the appropriate manual page.

Cyclic buffer spool (CNFS)

This method is set up in two files: storage.conf to define the buffers and the criteria for articles to be stored there, and in cycbuff.conf to configure the buffers themselves (their location, size, etc.). See the appropriate manual pages for details.

This method has an automatic expiration capability, that is on one hand you never need to worry about expire anymore, and on the other hand, you have no control over article retention times. Well, almost no control. Since CNFS is a cyclic buffer method, the newest articles overwrite the oldest ones, so if your buffer is large enough, you may be reasonably certain to maintain descent article retention times. In case of an article explosion within the buffer, expiration will go too fast though. That is why it is generally a good idea to set up different buffers for text and binary groups, for example.


Scenarios

This section is meant to help you set up the various configurations of INN described in the INN Architecture Guide. These scenarios are not meant to be exhaustive, they only help you to get started. Please read the Install document for detailed information on setup issues, especially if these scenarios don't quite work for you. If you are still at a loss then, send me an e-mail. :)


Stand Alone Server with No Incoming or Outgoing Feed

Unless I am much mistaken, this sort of a server will not be used too heavily in which case you can go with the centralized architecture described in the INN Architecture Guide. If your server is going to be loaded heavily, then you will need to use your fantasy to apply the configuration described in this section to a different architecture.

Now, choosing the right article spool format depends on the number of internal groups you are going to have and on the amount of articles that you want to keep in them. See INN Architecture Guide and Install documents for details. For a very lightly used server however the simplest method (traditional spool) may be the most appropriate. See section Article Spool and Expiration on details of setting it up.

Now, to configure your server you need to take the following steps:

Logging configuration

Before you begin anything at all, you need to make sure your syslog is working and you can read its files, or debugging will prove hell to you. Syslog configuration is usually stored in /etc/syslog.conf where you can find out how news information is logged and/or change location of the news log file if necessary. It may be useful to make it ~news/log/news.log (note that ~news/log/news is a whole different log file that lists all articles that your server receives).

We shall now assume that all syslog output for news is stored in ~news/log/news.log.

innd configuration

Now for your convenience it's best to log in as user news so that you would not need to worry about permissions and stuff.

innd is configured in inn.conf. Most of the parameters should be already preset for you correctly by the installation procedure (see the Install document). Make sure though that nnrpdposthost is not set to anything so that the server would know to post articles locally. Feel free to configure other parameters to your liking when you've read the manual page for inn.conf. :)

Make sure that all the directories that are listed in inn.conf are actually created in ~news or innd and other problems may have problems starting up.

Creating news groups

You can create news groups in three ways:

Manual editing of the active file is not recommended because the syntax is very strict and humans tend to err which may lead to funny behaviour of INN. But it is a possibility.

If you are not exchanging news with anyone in the world, then most probably it does not make much sense for you to use other people's active file, so we'll skip this option (or look into getlist otherwise).

You can only use ctlinnd for group creation when innd is running, and in order to have it running, you need to have some news groups in your active... What to do with this chicken and egg problem?

First, we need to manually edit the active file to insert two obligatory groups junk and control. Put the following lines into your db/active:

        control 0000000000 0000000001 y
        junk 0000000000 0000000001 y

Now we shall continue to configure INN, and we shall add some real groups in the end of this scenario.

As you are starting from scratch, you will also need to create active.times in your ~news/db directory:

        touch ~news/db/active.times

Now, initialize the history database with the following commands:

        cd ~news/db
        makedbz -i
        mv history.n.dir history.dir
        mv history.n.hash history.hash
        mv history.n.index history.index
        chmod 644 *

Refusing control articles

Assuming that you as the god of your news server want to have absolute power over the news groups you carry, it may be a good idea to disable processing of control messages that may create or delete news groups. To do this, edit control.ctl to drop newgroup and rmgroup articles. See the manual page of control.ctl for details.

Setting news feeds (or the absence thereof)

Incoming news feeds are set up in incoming.conf. Since you have no external feeds, this file only needs to contain the ME entry which designates your local host, like this:

        peer ME {
          hostname:         "localhost, 127.0.0.1"
        }

It is also the default configuration.

Outgoing news feeds are set up in newsfeeds. The fact that you won't be sending any articles out, does not mean you may ignore this file though. Besides the actual outgoing feeds to external peers, it also defines channels to other programs running on your server, for example for handling the overview, etc. In a simple case with a reasonable spool you don't need any of that, but if you run into performance problems, see section Scaling System for Higher Load.

There is one entry in this file that must be set though, it is the special entry ME that defines what goes into your own spool. The news group pattern of it is prepended to all the other feeds, and the distribution pattern of it defines which distributions you accept from the incoming feeds. Although for a server without any feeds, this does not sound very important, you still need this entry. It is most probably safe to set it to its simplest version like so:

        ME:*,!junk::

That is, send out everything (except for junk) and accept all distributions (distributions omitted). Note that we agree to send out everything here even though we don't really have any feeds, but keep in mind that it is also used for communication with other programs that you may want to use. If you are not using any, it won't hurt either.

Allowing users to connect

This part may be a bit tricky even for a ``simple'' server like yours since you may have complex access rules. I cannot even start making assumptions here, so please refer to the section User Access Rights and Closed Groups for details.

Setting up expiration

Assuming you are using traditional spool or another method that supports expiration policies (see section Article Spool and Expiration for details), you need to edit expire.ctl to set them up.

Starting up innd

The proper way to start up innd is to run rc.news. This script also starts up innwatch that watches over innd. This is certainly the right way to start up innd in a production environment. For testing purposes however it may be handier to just use inndstart instead until INN runs properly so that you would not get tens of b<innwatch> processes hanging around.

To stop innd, don't just kill it, bah! :P Allow it to close all streams gracefully. See the manual page for ctlinnd or use the following command:

        ctlinnd shutdown Gone for lunch.

Anyway, start up innd now. Check the log file (~news/log/news.log which we set up before) for status and error information.

Creating real news groups

Suppose, you want to carry the following news groups:

        local.music
        local.poetry.general
        local.poetry.burns
        local.poetry.biron
        local.announce

of which local.announce is moderated and the other ones are open to everyone (I won't touch on closed groups here, see section User Access Rights and Closed Groups for further details).

Now you can create your five news groups as follows:

        ctlinnd newgroup local.music          y your_email@your.domain.com
        ctlinnd newgroup local.poetry.general y your_email@your.domain.com
        ctlinnd newgroup local.poetry.burns   y your_email@your.domain.com
        ctlinnd newgroup local.poetry.biron   y your_email@your.domain.com
        ctlinnd newgroup local.announce       m your_email@your.domain.com

The ``y'' flag stands for a regular open group, ``m'' stands for a moderated groups. More flags are possible, see the manual page for active.

Since you have one moderated group, you need to specify the moderator's e-mail address for it. You can do it in the moderators configuration file, please refer to its manual page for details.

Watching over innd

innwatch watches over innd and can be configured to do a wide range of things in the configuration file innwatch.ctl.

Running expire and rotating logs

Both these actions are performed by news.daily which calls expire and fastrm for expiration, ctlinnd renumber for active file renumbering, and scanlogs that calls innreport for log file rotation and reporting.

news.daily is run from cron on a daily basis. To make sure that expire does not take for ever, the following parameters are given:

        news.daily delayrm 

See section Article Spool and Expiration for details on expiration policies.

Reporting is defined in innreport.conf that is used by innreport.


Small Single Server with Feeds

By definition of a ``small single server'' you are most probably using the centralized architecture described in the INN Architecture Guide. If you are not, you should probably read that guide first.

Now, choosing the right article spool format depends on the number of news groups you are going to have and on the amount of articles that you want to keep in them. See INN Architecture Guide and Install documents for details. For a lightly used server however the simplest method (traditional spool) may be the most appropriate. See section Article Spool and Expiration on details of setting it up.

Now, to configure your server you need to take the following steps:

Logging configuration

Before you begin anything at all, you need to make sure your syslog is working and you can read its files, or debugging will prove hell to you. Syslog configuration is usually stored in /etc/syslog.conf where you can find out how news information is logged and/or change location of the news log file if necessary. It may be useful to make it ~news/log/news.log (note that ~news/log/news is a whole different log file that lists all articles that your server receives).

We shall now assume that all syslog output for news is stored in ~news/log/news.log.

innd configuration

Now for your convenience it's best to log in as user news so that you would not need to worry about permissions and stuff.

innd is configured in inn.conf. Most of the parameters should be already preset for you correctly by the installation procedure (see the Install document). Make sure though that nnrpdposthost is not set to anything so that the server would know to post articles locally. Feel free to configure other parameters to your liking when you've read the manual page for inn.conf. :)

Make sure that all the directories that are listed in inn.conf are actually created in ~news or innd and other problems may have problems starting up.

Creating news groups

You can create news groups in three ways:

Manual editing of the active file is not recommended because the syntax is very strict and humans tend to err which may lead to funny behaviour of INN. But it is a possibility.

Using someone else's active file may be a good idea if you exchange news feed with the outside world. The path to take here is either to get it from your peer (or peers) and purge it, or get the standard active file from ftp://ftp.isc.org/pub/usenet/CONFIG . Get active and newsgroups (the latter file contains descriptions of the news group hierarchies).

In order to get an active file from your peer, you can use getlist (see the manual page), pipe it to ~news/db/active and edit it removing the groups you don't want to carry. Note however that full feed currently contains something like 60,000 news groups and by the time you read this document it is likely to be much more, so you've got your work cut out for you. If you don't particularly care for editing :) you can get a subset of your peer's active file rather than the whole thing. Suppose, you want to carry the news.* hierarchy in its entirety (so that you could at least read news.software.nntp) and you are interested in everything about cats from all the other hierarchies. Then you could extract these groups from your peer with the following commands:

        getlist -h my.peer.com active news.* >  ~news/db/active
        getlist -h my.peer.com active *.cat* >> ~news/db/active

(The latter command will also get you all the catering groups, so you'll still have to edit the active file or use fancier patterns.)

If you are going to carry a very large number of news groups, especially in the alt.* hierarchy, you may want to clean your new active file before use. actsync can do this for you removing the most common trash news group patterns.

Now you need to manually edit the active file to insert two obligatory groups junk and control. Put the following lines into your db/active:

        control 0000000000 0000000001 y
        junk 0000000000 0000000001 y

And what about your own local groups? You could enter them into your active file the same way as you entered control and junk or you could create them properly with ctlinnd except that you can only use ctlinnd for group creation when innd is running, and we did not get it that far yet. It's Ok though, we shall continue to configure INN, and we shall add your local news groups in the end of this scenario.

As you are starting from scratch, you will also need to create active.times in your ~news/db directory:

        touch ~news/db/active.times

Now, initialize the history database with the following commands:

        cd ~news/db
        makedbz -i
        mv history.n.dir history.dir
        mv history.n.hash history.hash
        mv history.n.index history.index
        chmod 644 *

Processing control articles

If you have incoming feeds, you need to worry about processing control articles (see section Cancel and Control Articles for details). Set up the rules in control.ctl, read the manual page for it for more information.

Setting news feeds (or the absence thereof)

Incoming news feeds are set up in incoming.conf. It first of all needs to contain the ME entry which designates your local host, like this:

        peer ME {
          hostname:         "localhost, 127.0.0.1"
        }

It is also the default configuration. If you have incoming feeds, you should configure them here. Specific configuration depends on the types of feed you want to receive and the ways your peer wants to send it. See section Handling News Feeds and the manual page for incoming.conf for more information.

Outgoing news feeds are set up in newsfeeds. Besides the actual outgoing feeds to external peers, this file also defines channels to other programs running on your server, for example for handling the overview, etc. In a simple case with a reasonable spool you don't need any of that, but if you run into performance problems, see section Scaling System for Higher Load.

There is one entry in this file that must be set at any event, it is the special entry ME that defines what goes into your own spool. The news group pattern of it is prepended to all the other feeds, and the distribution pattern of it defines which distributions you accept from the incoming feeds. Although for a server without any feeds, this does not sound very important, you still need this entry. It is most probably safe to set it to its simplest version like so:

        ME:*,!junk::

That is, send out everything (except for junk) and accept all distributions (distributions omitted). Note that we agree to send out everything here even though we don't really have any feeds, but keep in mind that it is also used for communication with other programs that you may want to use. If you are not using any, it won't hurt either.

If you have outgoing feeds (and your own postings are also a feed), then you need to configure other entries in this file as well. Here again, the actual configuration will depend on the amount of articles you are sending out and on the type of feed your peer wants to accept so it is often a good idea to contact the peer to discuss this. For more information see section Handling News Feeds.

Allowing users to connect

This part may be a bit tricky even for a ``simple'' server like yours since you may have complex access rules. I cannot even start making assumptions here, so please refer to the section User Access Rights and Closed Groups for details.

Setting up expiration

Assuming you are using traditional spool or another method that supports expiration policies (see section Article Spool and Expiration for details), you need to edit expire.ctl to set them up.

Starting up innd

The proper way to start up innd is to run rc.news. This script also starts up innwatch that watches over innd. This is certainly the right way to start up innd in a production environment. For testing purposes however it may be handier to just use inndstart instead until INN runs properly so that you would not get tens of b<innwatch> processes hanging around.

To stop innd, don't just kill it, bah! :P Allow it to close all streams gracefully. See the manual page for ctlinnd or use the following command:

        ctlinnd shutdown Gone for lunch.

Anyway, start up innd now. Check the log file (~news/log/news.log which we set up before) for status and error information.

Creating local news groups

Suppose, you want to carry the following news groups:

        local.music
        local.poetry.general
        local.poetry.burns
        local.poetry.biron
        local.announce

of which local.announce is moderated and the other ones are open to everyone (I won't touch on closed groups here, see section User Access Rights and Closed Groups for further details).

Now you can create your five news groups as follows:

        ctlinnd newgroup local.music          y your_email@your.domain.com
        ctlinnd newgroup local.poetry.general y your_email@your.domain.com
        ctlinnd newgroup local.poetry.burns   y your_email@your.domain.com
        ctlinnd newgroup local.poetry.biron   y your_email@your.domain.com
        ctlinnd newgroup local.announce       m your_email@your.domain.com

The ``y'' flag stands for a regular open group, ``m'' stands for a moderated groups. More flags are possible, see the manual page for active.

Since you have one moderated group, you need to specify the moderator's e-mail address for it. You can do it in the moderators configuration file, please refer to its manual page for details.

Watching over innd

innwatch watches over innd and can be configured to do a wide range of things in the configuration file innwatch.ctl.

Running expire and rotating logs

Both these actions are performed by news.daily which calls expire and fastrm for expiration, ctlinnd renumber for active file renumbering, and scanlogs that calls innreport for log file rotation and reporting.

news.daily is run from cron on a daily basis. To make sure that expire does not take for ever, the following parameters are given:

        news.daily delayrm 

See section Article Spool and Expiration for details on expiration policies.

Reporting is defined in innreport.conf that is used by innreport.


Feeder Using a Shared Spool

Choosing the right article spool format depends on the number of news groups you are going to have and on the amount of articles that you want to keep in them. See INN Architecture Guide and Install documents for details. For a lightly used server however the simplest method (traditional spool) may be the most appropriate. See section Article Spool and Expiration on details of setting it up.

Now, to configure your server you need to take the following steps:

Logging configuration

Before you begin anything at all, you need to make sure your syslog is working and you can read its files, or debugging will prove hell to you. Syslog configuration is usually stored in /etc/syslog.conf where you can find out how news information is logged and/or change location of the news log file if necessary. It may be useful to make it ~news/log/news.log (note that ~news/log/news is a whole different log file that lists all articles that your server receives).

We shall now assume that all syslog output for news is stored in ~news/log/news.log.

innd configuration

Now for your convenience it's best to log in as user news so that you would not need to worry about permissions and stuff.

innd is configured in inn.conf. Most of the parameters should be already preset for you correctly by the installation procedure (see the Install document). Make sure though that nnrpdposthost is not set to anything so that the server would know to post articles locally. Feel free to configure other parameters to your liking when you've read the manual page for inn.conf. :)

Make sure that all the directories that are listed in inn.conf are actually created in ~news or innd and other problems may have problems starting up.

Creating news groups

You can create news groups in three ways:

Manual editing of the active file is not recommended because the syntax is very strict and humans tend to err which may lead to funny behaviour of INN. But it is a possibility.

Using someone else's active file may be a good idea if you exchange news feed with the outside world. The path to take here is either to get it from your peer (or peers) and purge it, or get the standard active file from ftp://ftp.isc.org/pub/usenet/CONFIG. Get active and newsgroups (the latter file contains descriptions of the news group hierarchies).

In order to get an active file from your peer, you can use getlist (see the manual page), pipe it to ~news/db/active and edit it removing the groups you don't want to carry. Note however that full feed currently contains something like 60,000 news groups and by the time you read this document it is likely to be much more, so you've got your work cut out for you. If you don't particularly care for editing :) you can get a subset of your peer's active file rather than the whole thing. Suppose, you want to carry the news.* hierarchy in its entirety (so that you could at least read news.software.nntp) and you are interested in everything about cats from all the other hierarchies. Then you could extract these groups from your peer with the following commands:

        getlist -h my.peer.com active news.* >  ~news/db/active
        getlist -h my.peer.com active *.cat* >> ~news/db/active

(The latter command will also get you all the catering groups, so you'll still have to edit the active file or use fancier patterns.)

If you are going to carry a very large number of news groups, especially in the alt.* hierarchy, you may want to clean your new active file before use. actsync can do this for you removing the most common trash news group patterns.

Now you need to manually edit the active file to insert two obligatory groups junk and control. Put the following lines into your db/active:

        control 0000000000 0000000001 y
        junk 0000000000 0000000001 y

And what about your own local groups? You could enter them into your active file the same way as you entered control and junk or you could create them properly with ctlinnd except that you can only use ctlinnd for group creation when innd is running, and we did not get it that far yet. It's Ok though, we shall continue to configure INN, and we shall add your local news groups in the end of this scenario.

As you are starting from scratch, you will also need to create active.times in your ~news/db directory:

        touch ~news/db/active.times

Now, initialize the history database with the following commands:

        cd ~news/db
        makedbz -i
        mv history.n.dir history.dir
        mv history.n.hash history.hash
        mv history.n.index history.index
        chmod 644 *

Processing control articles

If you have incoming feeds, you need to worry about processing control articles (see section Cancel and Control Articles for details). Set up the rules in control.ctl, read the manual page for it for more information.

Setting news feeds (or the absence thereof)

Incoming news feeds are set up in incoming.conf. It first of all needs to contain the ME entry which designates your local host, like this:

        peer ME {
          hostname:         "localhost, 127.0.0.1"
        }

It is also the default configuration. If you have incoming feeds, you should configure them here. Specific configuration depends on the types of feed you want to receive and the ways your peer wants to send it. See section Handling News Feeds and the manual page for incoming.conf for more information.

Outgoing news feeds are set up in newsfeeds. Besides the actual outgoing feeds to external peers, this file also defines channels to other programs running on your server, for example for handling the overview, etc. In a simple case with a reasonable spool you don't need any of that, but if you run into performance problems, see section Scaling System for Higher Load.

There is one entry in this file that must be set at any event, it is the special entry ME that defines what goes into your own spool. The news group pattern of it is prepended to all the other feeds, and the distribution pattern of it defines which distributions you accept from the incoming feeds. Although for a server without any feeds, this does not sound very important, you still need this entry. It is most probably safe to set it to its simplest version like so:

        ME:*,!junk::

That is, send out everything (except for junk) and accept all distributions (distributions omitted). Note that we agree to send out everything here even though we don't really have any feeds, but keep in mind that it is also used for communication with other programs that you may want to use. If you are not using any, it won't hurt either.

If you have outgoing feeds (and your own postings are also a feed), then you need to configure other entries in this file as well. Here again, the actual configuration will depend on the amount of articles you are sending out and on the type of feed your peer wants to accept so it is often a good idea to contact the peer to discuss this. For more information see section Handling News Feeds.

Allowing users to connect

The question to ask here is whether you want your users to be able to connect to the feeder or not. Probably not since this is what the readers are for. Assuming that you only want to allow user access to the feeder for the news administrator, you can have a very simple readers.conf. See section User Access Rights and Closed Groups for details.

Allowing readers to post in batch mode

It is necessary to give the readers post access to the feeder in the feeder's readers.conf file. Otherwise rnews from the readers cannot connect.

Allowing readers to post directly

In this case it is necessary to add the readers to incoming.conf rather than to readers.conf file.

Timely updates of active and history

So that the readers would be able to access all the articles in the spool for all actions (including canceling when they need to retrieve the article by message ID), active and history* files need to be updated frequently enough. If MMAP is used, then MMAP_SYNC must also be used with a sufficiently short interval.

Setting up expiration

Assuming you are using traditional spool or another method that supports expiration policies (see section Article Spool and Expiration for details), you need to edit expire.ctl to set them up.

Starting up innd

The proper way to start up innd is to run rc.news. This script also starts up innwatch that watches over innd. This is certainly the right way to start up innd in a production environment. For testing purposes however it may be handier to just use inndstart instead until INN runs properly so that you would not get tens of b<innwatch> processes hanging around.

To stop innd, don't just kill it, bah! :P Allow it to close all streams gracefully. See the manual page for ctlinnd or use the following command:

        ctlinnd shutdown Gone for lunch.

Anyway, start up innd now. Check the log file (~news/log/news.log which we set up before) for status and error information.

Creating local news groups

Suppose, you want to carry the following news groups:

        local.music
        local.poetry.general
        local.poetry.burns
        local.poetry.biron
        local.announce

of which local.announce is moderated and the other ones are open to everyone (I won't touch on closed groups here, see section User Access Rights and Closed Groups for further details).

Now you can create your five news groups as follows:

        ctlinnd newgroup local.music          y your_email@your.domain.com
        ctlinnd newgroup local.poetry.general y your_email@your.domain.com
        ctlinnd newgroup local.poetry.burns   y your_email@your.domain.com
        ctlinnd newgroup local.poetry.biron   y your_email@your.domain.com
        ctlinnd newgroup local.announce       m your_email@your.domain.com

The ``y'' flag stands for a regular open group, ``m'' stands for a moderated groups. More flags are possible, see the manual page for active.

Since you have one moderated group, you need to specify the moderator's e-mail address for it. You can do it in the moderators configuration file, please refer to its manual page for details.

Watching over innd

innwatch watches over innd and can be configured to do a wide range of things in the configuration file innwatch.ctl.

Running expire and rotating logs

Both these actions are performed by news.daily which calls expire and fastrm for expiration, ctlinnd renumber for active file renumbering, and scanlogs that calls innreport for log file rotation and reporting.

news.daily is run from cron on a daily basis. To make sure that expire does not take for ever, the following parameters are given:

        news.daily delayrm 

See section Article Spool and Expiration for details on expiration policies.

Reporting is defined in innreport.conf that is used by innreport.


Readers Using a Shared Spool

Since the readers in such a system do not run innd (see INN Architecture Guide for more information), we only need to worry about configuring nnrpd which is done in inn.conf. This file contains configuration parameters for innd as well which are ignored on the readers. For detailed information on all the parameters, consult the inn.conf manual page.

All the configuration of the spool, the active file and the history is done on the feeder, so you need to copy that configuration so that your reader would know where to find things and perform all the necessary mounts. The logging however is the reader's local affair and needs to be configured properly (and preferrably to a local disk).

Make sure that all the directories that are listed in inn.conf are actually created in ~news or innd and other problems may have problems starting up.

Now, to configure your server you need to take the following steps:

Logging configuration

Before you begin anything at all, you need to make sure your syslog is working and you can read its files, or debugging will prove hell to you. Syslog configuration is usually stored in /etc/syslog.conf where you can find out how news information is logged and/or change location of the news log file if necessary. It may be useful to make it ~news/log/news.log (note that ~news/log/news is a whole different log file that lists all articles that your server receives).

We shall now assume that all syslog output for news is stored in ~news/log/news.log.

Setting news feeds (or the absence thereof)

Incoming news feeds are set up in incoming.conf. Since you have no external feeds, this file only needs to contain the ME entry which designates your local host, like this:

        peer ME {
          hostname:         "localhost, 127.0.0.1"
        }

It is also the default configuration.

Outgoing news feeds are set up in newsfeeds. The fact that you won't be sending any articles out, does not mean you may ignore this file though. Besides the actual outgoing feeds to external peers, it also defines channels to other programs running on your server, for example for handling the overview, etc. In a simple case with a reasonable spool you don't need any of that, but if you run into performance problems, see section Scaling System for Higher Load.

There is one entry in this file that must be set though, it is the special entry ME that defines what goes into your own spool. The news group pattern of it is prepended to all the other feeds, and the distribution pattern of it defines which distributions you accept from the incoming feeds. Although for a server without any feeds, this does not sound very important, you still need this entry. It is most probably safe to set it to its simplest version like so:

        ME:*,!junk::

That is, send out everything (except for junk) and accept all distributions (distributions omitted). Note that we agree to send out everything here even though we don't really have any feeds, but keep in mind that it is also used for communication with other programs that you may want to use. If you are not using any, it won't hurt either.

Accepting user postings

As described in the INN Architecture Guide, the readers can forward user postings to the feeder either directly or using a queue.

Direct method

Set the following parameters in inn.conf:

  • nnrpdposthost: the feeder

  • nnrpdpostport: the port on the feeder that accepts NNTP connections

  • spoolfirst: false

nnrpd will connect to the feeder for every user posting (make sure the feeder is up and running!).

Queued method

Set the following parameters in inn.conf:

  • nnrpdposthost: the feeder

  • nnrpdpostport: the port on the feeder that accepts NNTP connections

  • spoolfirst: true

In this case, nnrpd will store user postings in a queue in queue/incoming directory. You should also run rnews that spools the articles in the queue to the feeder. It reads the above parameters from inn.conf.

rnews should be run frequently enough to make sure your users don't complain. The postings will only appear on the news server (and will only be sent out to the Internet) when they are transmitted to the feeder. A sensible value is every 5 minutes.

The following parameters are usually used:

        rnews -v -U

Running nnrpd as a daemon

Now for your convenience it's best to log in as user news so that you would not need to worry about permissions and stuff.

Running nnrpd as a deamon is done using the following start-up command:

        nnrpd -D

Note that you must have root privileges to do it.

The nnrpd daemon listens on port specified in the port parameter in inn.conf. Port 119 is the standard news port. For each new connection to the port, the nnrpd daemon spawns an nnrpd process that handles the user connection.

Log rotation and reporting

Use news.daily to do rotate the logs and create reports. Note that you need to explicitly turn off expire and renumber of the active file. Use the following parameters:

        news.daily noexpire norenumber

news.daily calls scanlogs which in turn calls innreport. The latter is configured in innreport.conf.


Feeders Using Replication

Choosing the right article spool format depends on the number of news groups you are going to have and on the amount of articles that you want to keep in them. See INN Architecture Guide and Install documents for details. Since you don't have to have the same expiration policies on the feeder as on the readers, you may want to limit the feeder's spool to the minimum. In this situation the simplest method (traditional spool) may be the most appropriate. See section Article Spool and Expiration on details of setting it up.

Now, to configure your server you need to take the following steps:

Logging configuration

Before you begin anything at all, you need to make sure your syslog is working and you can read its files, or debugging will prove hell to you. Syslog configuration is usually stored in /etc/syslog.conf where you can find out how news information is logged and/or change location of the news log file if necessary. It may be useful to make it ~news/log/news.log (note that ~news/log/news is a whole different log file that lists all articles that your server receives).

We shall now assume that all syslog output for news is stored in ~news/log/news.log.

innd configuration

Now for your convenience it's best to log in as user news so that you would not need to worry about permissions and stuff.

innd is configured in inn.conf. Most of the parameters should be already preset for you correctly by the installation procedure (see the Install document). Make sure though that nnrpdposthost is not set to anything so that the server would know to post articles locally. Feel free to configure other parameters to your liking when you've read the manual page for inn.conf. :)

Make sure that all the directories that are listed in inn.conf are actually created in ~news or innd and other problems may have problems starting up.

Creating news groups

You can create news groups in three ways:

Manual editing of the active file is not recommended because the syntax is very strict and humans tend to err which may lead to funny behaviour of INN. But it is a possibility.

Using someone else's active file may be a good idea if you exchange news feed with the outside world. The path to take here is either to get it from your peer (or peers) and purge it, or get the standard active file from ftp://ftp.isc.org/pub/usenet/CONFIG. Get active and newsgroups (the latter file contains descriptions of the news group hierarchies).

In order to get an active file from your peer, you can use getlist (see the manual page), pipe it to ~news/db/active and edit it removing the groups you don't want to carry. Note however that full feed currently contains something like 60,000 news groups and by the time you read this document it is likely to be much more, so you've got your work cut out for you. If you don't particularly care for editing :) you can get a subset of your peer's active file rather than the whole thing. Suppose, you want to carry the news.* hierarchy in its entirety (so that you could at least read news.software.nntp) and you are interested in everything about cats from all the other hierarchies. Then you could extract these groups from your peer with the following commands:

        getlist -h my.peer.com active news.* >  ~news/db/active
        getlist -h my.peer.com active *.cat* >> ~news/db/active

(The latter command will also get you all the catering groups, so you'll still have to edit the active file or use fancier patterns.)

If you are going to carry a very large number of news groups, especially in the alt.* hierarchy, you may want to clean your new active file before use. actsync can do this for you removing the most common trash news group patterns.

Now you need to manually edit the active file to insert two obligatory groups junk and control. Put the following lines into your db/active:

        control 0000000000 0000000001 y
        junk 0000000000 0000000001 y

And what about your own local groups? You could enter them into your active file the same way as you entered control and junk or you could create them properly with ctlinnd except that you can only use ctlinnd for group creation when innd is running, and we did not get it that far yet. It's Ok though, we shall continue to configure INN, and we shall add your local news groups in the end of this scenario.

As you are starting from scratch, you will also need to create active.times in your ~news/db directory:

        touch ~news/db/active.times

Now, initialize the history database with the following commands:

        cd ~news/db
        makedbz -i
        mv history.n.dir history.dir
        mv history.n.hash history.hash
        mv history.n.index history.index
        chmod 644 *

Processing control articles

If you have incoming feeds, you need to worry about processing control articles (see section Cancel and Control Articles for details). Set up the rules in control.ctl, read the manual page for it for more information.

Setting news feeds (or the absence thereof)

Incoming news feeds are set up in incoming.conf. It first of all needs to contain the ME entry which designates your local host, like this:

        peer ME {
          hostname:         "localhost, 127.0.0.1"
        }

It is also the default configuration. If you have incoming feeds, you should configure them here. Specific configuration depends on the types of feed you want to receive and the ways your peer wants to send it. See section Handling News Feeds and the manual page for incoming.conf for more information.

Outgoing news feeds are set up in newsfeeds. Besides the actual outgoing feeds to external peers, this file also defines channels to other programs running on your server, for example for handling the overview, etc. In a simple case with a reasonable spool you don't need any of that, but if you run into performance problems, see section Scaling System for Higher Load.

There is one entry in this file that must be set at any event, it is the special entry ME that defines what goes into your own spool. The news group pattern of it is prepended to all the other feeds, and the distribution pattern of it defines which distributions you accept from the incoming feeds. Although for a server without any feeds, this does not sound very important, you still need this entry. It is most probably safe to set it to its simplest version like so:

        ME:*,!junk::

That is, send out everything (except for junk) and accept all distributions (distributions omitted). Note that we agree to send out everything here even though we don't really have any feeds, but keep in mind that it is also used for communication with other programs that you may want to use. If you are not using any, it won't hurt either.

If you have outgoing feeds (and your own postings are also a feed), then you need to configure other entries in this file as well. Here again, the actual configuration will depend on the amount of articles you are sending out and on the type of feed your peer wants to accept so it is often a good idea to contact the peer to discuss this. For more information see section Handling News Feeds.

Allowing users to connect

The question to ask here is whether you want your users to be able to connect to the feeder or not. Probably not since this is what the readers are for. Assuming that you only want to allow user access to the feeder for the news administrator, you can have a very simple readers.conf. See section User Access Rights and Closed Groups for details.

Allowing readers to post in batch mode

It is necessary to give the readers post access to the feeder in the feeder's readers.conf file. Otherwise rnews from the readers cannot connect.

Allowing readers to post directly

In this case it is necessary to add the readers to incoming.conf rather than to readers.conf file.

Setting up expiration

Assuming you are using traditional spool or another method that supports expiration policies (see section Article Spool and Expiration for details), you need to edit expire.ctl to set them up. For methods that don't support controlled expiration, it's even easier: no setup necessary. :)

Starting up innd

The proper way to start up innd is to run rc.news. This script also starts up innwatch that watches over innd. This is certainly the right way to start up innd in a production environment. For testing purposes however it may be handier to just use inndstart instead until INN runs properly so that you would not get tens of b<innwatch> processes hanging around.

To stop innd, don't just kill it, bah! :P Allow it to close all streams gracefully. See the manual page for ctlinnd or use the following command:

        ctlinnd shutdown Gone for lunch.

Anyway, start up innd now. Check the log file (~news/log/news.log which we set up before) for status and error information.

Creating local news groups

Suppose, you want to carry the following news groups:

        local.music
        local.poetry.general
        local.poetry.burns
        local.poetry.biron
        local.announce

of which local.announce is moderated and the other ones are open to everyone (I won't touch on closed groups here, see section User Access Rights and Closed Groups for further details).

Now you can create your five news groups as follows:

        ctlinnd newgroup local.music          y your_email@your.domain.com
        ctlinnd newgroup local.poetry.general y your_email@your.domain.com
        ctlinnd newgroup local.poetry.burns   y your_email@your.domain.com
        ctlinnd newgroup local.poetry.biron   y your_email@your.domain.com
        ctlinnd newgroup local.announce       m your_email@your.domain.com

The ``y'' flag stands for a regular open group, ``m'' stands for a moderated groups. More flags are possible, see the manual page for active.

Since you have one moderated group, you need to specify the moderator's e-mail address for it. You can do it in the moderators configuration file, please refer to its manual page for details.

Watching over innd

innwatch watches over innd and can be configured to do a wide range of things in the configuration file innwatch.ctl.

Running expire and rotating logs

Both these actions are performed by news.daily which calls expire and fastrm for expiration, ctlinnd renumber for active file renumbering, and scanlogs that calls innreport for log file rotation and reporting.

news.daily is run from cron on a daily basis. To make sure that expire does not take for ever, the following parameters are given:

        news.daily delayrm 

See section Article Spool and Expiration for details on expiration policies.

Reporting is defined in innreport.conf that is used by innreport.


Readers Using Replication

The readers in such systems run innd as well as nnrpd as daemons (see INN Architecture Guide for details). Both daemons are configured in inn.conf.

Now, choosing the right article spool format depends on the number of news groups you are going to have and on the amount of articles that you want to keep in them. See INN Architecture Guide and Install documents for details. Since you may not have the same expiration policies on the readers as on the feeder, you may have a different spool structure. See section Article Spool and Expiration on details of setting it up.

Now, to configure your server you need to take the following steps:

Logging configuration

Before you begin anything at all, you need to make sure your syslog is working and you can read its files, or debugging will prove hell to you. Syslog configuration is usually stored in /etc/syslog.conf where you can find out how news information is logged and/or change location of the news log file if necessary. It may be useful to make it ~news/log/news.log (note that ~news/log/news is a whole different log file that lists all articles that your server receives).

We shall now assume that all syslog output for news is stored in ~news/log/news.log.

innd configuration

Now for your convenience it's best to log in as user news so that you would not need to worry about permissions and stuff.

innd is configured in inn.conf. Most of the parameters should be already preset for you correctly by the installation procedure (see the Install document). Feel free to configure the parameters to your liking when you've read the manual page for inn.conf. :)

Make sure that all the directories that are listed in inn.conf are actually created in ~news or innd and other problems may have problems starting up.

Making the reader be a slave

This means that the reader will keep the same article numbering as the feeder tells it to. To enable it, set in inn.conf:

        xrefslave: true

Accepting user postings

As described in the INN Architecture Guide, the readers can forward user postings to the feeder either directly or using a queue.

Direct method

Set the following parameters in inn.conf:

  • nnrpdposthost: the feeder

  • nnrpdpostport: the port on the feeder that accepts NNTP connections

  • spoolfirst: false

nnrpd will connect to the feeder for every user posting (make sure the feeder is up and running!).

Queued method

Set the following parameters in inn.conf:

  • nnrpdposthost: the feeder

  • nnrpdpostport: the port on the feeder that accepts NNTP connections

  • spoolfirst: true

In this case, nnrpd will store user postings in a queue in queue/incoming directory. You should also run rnews that spools the articles in the queue to the feeder. It reads the above parameters from inn.conf.

rnews should be run frequently enough to make sure your users don't complain. The postings will only appear on the news server (and will only be sent out to the Internet) when they are transmitted to the feeder. A sensible value is every 5 minutes.

The following parameters are usually used:

        rnews -v -U

Creating news groups

You can create news groups in three ways:

Manual editing of the active file is not recommended because the syntax is very strict and humans tend to err which may lead to funny behaviour of INN. But it is a possibility.

Using someone else's active file is what you want in this case: use the feeder's active file. Set up the feeder first and simply copy its active file to the reader. Done.

Using ctlinnd to set up groups is not necessary in this case because you have already got your active file.

As you are starting from scratch, you will also need to create active.times in your ~news/db directory:

        touch ~news/db/active.times

Now, initialize the history database with the following commands:

        cd ~news/db
        makedbz -i
        mv history.n.dir history.dir
        mv history.n.hash history.hash
        mv history.n.index history.index
        chmod 644 *

Processing control articles

Since you do not have any external incoming feeds, you do not need to worry about processing control articles (see section Cancel and Control Articles for details). The feeder processes them and maintains the active file. The reader should synchronize its active file with the feeder regularly, e.g. on a daily basis. This can be done with actsync. If the reader does not have any groups of its own (as it should not), then you can use the following command for synchronization:

        actsync -o x master

Note that if the period of synchronizations is too long, you will miss too many articles posted to the groups already created on the feeder but not yet on the reader. That is why at least daily synchronization is recommended.

Setting news feeds (or the absence thereof)

Incoming news feeds are set up in incoming.conf. Since you have no external feeds, this file only needs to contain the ME entry which designates your local host, like this:

        peer ME {
          hostname:         "localhost, 127.0.0.1"
        }

It is also the default configuration. Since you have one incoming feed (from the feeder), you should configure it here. Specific configuration depends on the type of feed you will be receiving and the way your feeder will be sending it. See section Handling News Feeds and the manual page for incoming.conf for more information.

Outgoing news feeds are set up in newsfeeds. The fact that you won't be sending any articles out, does not mean you may ignore this file though. Besides the actual outgoing feeds to external peers, it also defines channels to other programs running on your server, for example for handling the overview, etc. In a simple case with a reasonable spool you don't need any of that, but if you run into performance problems, see section Scaling System for Higher Load.

There is one entry in this file that must be set though, it is the special entry ME that defines what goes into your own spool. The news group pattern of it is prepended to all the other feeds, and the distribution pattern of it defines which distributions you accept from the incoming feeds. Although for a server without any feeds, this does not sound very important, you still need this entry. It is most probably safe to set it to its simplest version like so:

        ME:*,!junk::

That is, send out everything (except for junk) and accept all distributions (distributions omitted). Note that we agree to send out everything here even though we don't really have any feeds, but keep in mind that it is also used for communication with other programs that you may want to use. If you are not using any, it won't hurt either.

Setting up expiration

Assuming you are using traditional spool or another method that supports expiration policies (see section Article Spool and Expiration for details), you need to edit expire.ctl to set them up.

Starting up innd

The proper way to start up innd is to run rc.news. This script also starts up innwatch that watches over innd. This is certainly the right way to start up innd in a production environment. For testing purposes however it may be handier to just use inndstart instead until INN runs properly so that you would not get tens of b<innwatch> processes hanging around.

To stop innd, don't just kill it, bah! :P Allow it to close all streams gracefully. See the manual page for ctlinnd or use the following command:

        ctlinnd shutdown Gone for lunch.

Avoiding port conflicts between innd and nnrpd

In order to avoid conflicts, innd and nnrpd should run on different ports. Since inn.conf contains only one parameter for port and each spawned nnrpd reads the configuration file, you need to invoke innd with the other port as a command line parameter.

For example, if you have your users connect to the standard news port 119, and you have your innd run on port 120, then you set port in inn.conf to 119 and start up innd with the command:

        inndstart -P 120

Start up innd now. Check the log file (~news/log/news.log which we set up before) for status and error information.

Running nnrpd as a daemon

Running nnrpd as a deamon is done using the following start-up command:

        nnrpd -D

Note that you must have root privileges to do it.

The nnrpd daemon listens on port specified in the port parameter in inn.conf. Port 119 is the standard news port. For each new connection to the port, the nnrpd daemon spawns an nnrpd process that handles the user connection.

Watching over innd

innwatch watches over innd and can be configured to do a wide range of things in the configuration file innwatch.ctl.

Running expire and rotating logs

Both these actions are performed by news.daily which calls expire and fastrm for expiration, ctlinnd renumber for active file renumbering, and scanlogs that calls innreport for log file rotation and reporting.

news.daily is run from cron on a daily basis. To make sure that expire does not take for ever, the following parameters are given:

        news.daily delayrm 

See section Article Spool and Expiration for details on expiration policies.

Reporting is defined in innreport.conf that is used by innreport.


Scaling System for Higher Load

FIXME: to do.