moderators

title: moderators(5)

text:
# moderators(5)

## NAME
moderators - Submission addresses for moderated groups

## DESCRIPTION
When an unapproved article is posted locally to a moderated newsgroup, it is not passed off to innd for normal handling; instead, it is sent via e-mail to the submission address for that newsgroup. The submission address is determined using this configuration file.

The file pathetc/moderators is a list of associations between uwildmat(3) patterns matching newsgroups and the submission address for those newsgroups. Blank lines and lines starting with a number sign ("#") are ignored. All other lines should consist of two fields separated by a colon:

```
    <pattern>:<address>
```

The first field is a uwildmat(3) pattern matching the group or groups to which this line applies. The first matching line is used, so more specific patterns should be listed before general patterns.

The second field, the submission address, should be a simple e-mail address with one exception: at most one %s may occur anywhere in the address. If present, it will be replaced by the name of the newsgroup, with all periods in the name changed to dashes ("-"). If there is a literal "%" in the submission address, it must be written as "%%", even if not followed by an "s".

With the %s syntax, periods are converted to dashes for historical reasons, from back in the days when periods in the local part of addresses were not always handled correctly. It's probably no longer necessary, but so much now depends on it that it can't be easily changed.

It's intended that the sample moderators file included in the INN distribution always be sufficient for all world-wide newsgroups. The hosts behind moderators.isc.org have graciously volunteered to handle forwarding tasks for all world-wide newsgroups so that individual sites don't have to keep track of the submission addresses for moderated groups. The forwarding database used by moderators.isc.org is coordinated by <moderators-request@isc.org>; if you know of a world-wide newsgroup hierarchy that is not correctly handled by moderators.isc.org, please send the details to that address.

Given that, the only thing you should have to add to the sample file under normal circumstances are the forwarding addresses for local or limited-distribution moderated groups.

If this file doesn't exist, or if a post is made to a moderated group that has no matching entry in this file, nnrpd falls back on the value of moderatormailer set in inn.conf and, failing that, rejects the post.

## EXAMPLES
Here is a sample file:

```
    example.important:announce@example.com
    example.*:%s@smtp.example.com
    *:%s@moderators.isc.org
```

Using the above file, postings to the moderated newsgroup in the left column below will be sent to the address shown in the right column below:

```
    example.important   announce@example.com
    example.x-announce  example-x-announce@smtp.example.com
    alt.dev.null        alt-dev-null@moderators.isc.org
```

Note that periods are changed to dashes and dashes are left alone with the %s syntax, so two moderated newsgroups whose names differ only by changing a period to a dash would go to the same address. Such newsgroup pairs should therefore not be created.

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten in POD by Russ Allbery <eagle@eyrie.org>.

$Id: moderators.pod 9767 2014-12-07 21:13:43Z iulius $

## SEE ALSO
inn.conf(5), nnrpd(8), uwildmat(3).


motd.news

package: inn

title: motd.news(5)

text:
# motd.news(5)

## NAME
motd.news - Message of the day information for feeders or readers

## DESCRIPTION
Two files, found in pathetc, contain local information for news feeders or news readers in a free-form format. The entire files are returned verbatim to any client that issues the LIST MOTD command. This might be used for new information, notification of upcoming downtime, or similar purposes.

These files are named motd.innd (for news feeders) and motd.nnrpd (for news readers); they are used by innd and nnrpd, respectively.

Make sure that these files are encoded in UTF-8. They should also be "dot-stuffed", that is to say that a line beginning with a dot should have that dot doubled.

Be aware that use of the LIST MOTD command is not widespread (though documented in RFC 6048) and most news clients will never ask for this file.

If one or both of these files are missing, it is not an error. The server will just send the client the appropriate response for an unmaintained motd.innd or motd.nnrpd file.

On a fresh INN install, samples for these files are installed in pathec; you will therefore find in motd.innd.sample and motd.nnrpd.sample a few examples of messages that can be communicated to news clients.

## HISTORY
Rewritten in POD by Russ Allbery <eagle@eyrie.org> for InterNetNews.

$Id: motd.news.pod 9767 2014-12-07 21:13:43Z iulius $

## SEE ALSO
inn.conf(5).


newsfeeds

title: newsfeeds(5)

text:
# newsfeeds(5)

## NAME
newsfeeds - Determine where Usenet articles are sent

## DESCRIPTION
The file pathetc/newsfeeds specifies how incoming articles should be distributed to other programs and files on the server. It is parsed by the InterNetNews server innd(8) when it starts up, or when directed to by ctlinnd(8). innd doesn't send articles to remote sites itself, so newsfeeds doesn't directly determine which remote news servers articles are sent to. Instead, it specifies what batch files should be created or which programs should be run (and what information should be sent to them), and then this information is used by programs like innxmit(8) and innfeed(8) to feed articles to remote sites.

The newsfeeds file isn't used solely to set up feeding accepted articles to remote sites but also to pass them (or bits of information about them) to any local programs or files that want that data. For example, controlchan(8), a daemon that processes incoming control messages, runs out of newsfeeds, as could a news to mail gateway.

The file is interpreted as a set of lines, parsed according to the following rules: If a line ends with a backslash, the backslash, the newline, and any whitespace at the start of the next line is deleted. This is repeated until the entire "logical" line is collected. If the logical line is blank or starts with a number sign ("#"), it is ignored.

All other lines are interpreted as feed entries. An entry should consist of four colon-separated fields; two of the fields may have optional sub-fields, marked off by a slash. Fields or sub-fields that take multiple parameters should be separated by a comma. Extra whitespace can cause problems and should be avoided. Except for the site names, case is significant. The format of an entry is:

```
    sitename[/exclude,exclude,...]\
        :pattern,pattern...[/distribution,distribution...]\
        :flag,flag...\
        :parameter
```

Each field is described below.

The sitename is the name of the site to which a news article can be sent. It is used for writing log entries and for determining if an article should be forwarded to a site. (A "site" is the generic term for some destination of newsfeed data; it often corresponds to a remote news peer, but doesn't have to. For example, a local archiving program run from newsfeeds is also a "site".) If sitename already appears in the article's Path: header, then the article will not be sent to the site. The name is usually whatever the remote site uses to identify itself in the Path: header, but can be almost any word.

Be careful, though, to avoid having the sitename accidentally match a Path: header entry unintentionally. For this reason, special local entries (such as archivers or gateways) should probably end with an exclamation point to make sure that they do not have the same name as any real site. For example, "gateway" is an obvious name for the local entry that forwards articles out to a mailing list. If a site with the name "gateway" posts an article, when the local site receives the article it will see the name in the Path and not send the article to its own "gateway" entry. Since "gateway!" can't appear as an individual Path: entry since "!" is a delimiter in the Path: header, that would be a better thing to use for sitename.

(Another way to avoid this problem is with the "Ap" flag; see the description below.)

If an entry has an exclusion sub-field, the article will not be sent to that site if any of exclude appear in the Path: header. (It's sometimes convenient to have the sitename be an abbreviated form of the name of the remote site, since all the sitenames to which an article is sent are written to the log and using shorter sitenames can therefore improve performance for large servers. In this case, the Path: header entries of those sites should be given as exclude entries and the "Ap" flag used so that the abbreviated sitename doesn't accidentally match some other Path: header entry.)

The same sitename can be used more than once and the appropriate action will be taken for each entry that should receive the article, but this is recommended only for program feeds to avoid confusion. Case is not significant in site names.

The comma-separated pattern specifies which groups to send to the site; it is interpreted to build a "subscription list" for the site. The default subscription is to get all groups carried by the server. It is a uwildmat(3) pattern supporting poison ("@") wildcards; see the uwildmat(3) man page for full details on the pattern matching language. pattern will be matched against every newsgroup carried by the server and all newsgroups that match will be added to the subscription list for the site.

Normally, a given article (or information about it) is sent to a site if any of the newsgroups to which the article was posted are in that site's subscription list. If a newsgroup matches a "@" pattern in pattern, then not only is it not added to the subscription list, but any articles crossposted to that newsgroup also will not be sent to that site even if other newsgroups to which it was crossposted are in that site's subscription list. This is called a poison pattern (because matching groups are "poisoned").

For example, to receive all comp.* groups, but only comp.sources.unix within the sources newsgroups, the following pattern can be used:

```
    comp.*,!comp.sources.*,comp.sources.unix
```

Note that the trailing ".*" is required; the pattern has to match the whole newsgroup name. "comp.sources.*" could be written "comp.sources*" and would exclude the newsgroup comp.sources (if it exists) as well as the groups in the comp.sources.* hierarchy, but note that this would also exclude a newsgroup named comp.sources-only (whereas the above pattern would add that group to the site subscription list since it matches "comp.*" and none of the other patterns).

For another example, to feed alt.* and misc.* to a given site but not any articles posted to alt.binaries.warez (even if they're also crossposted to other alt.* or misc.* groups), the following pattern can be used:

```
    alt.*,@alt.binaries.warez,misc.*
```

Note, however, that if you reversed the "alt.*" and "@alt.binaries.warez" entries, this pattern would be equivalent to "alt.*,misc.*", since the last matching pattern determines whether a given newsgroup matches and the poison logic only applies if the poison entry is the last matching entry.

Control messages follow slightly different propagation rules than normal articles; see innd(8) for the details. Note that most subscriptions should have "!junk,!control,!control.*" in their pattern list due to those propagation rules (and since "junk" is a special internal newsgroup; see wanttrash in inn.conf(5) for more details on what it's used for) and that the best way to keep control messages local to a site is with a distribution.

A subscription can be further modified by specifying distributions that the site should or should not receive. The default is to send all articles to all sites that subscribe to any of the groups where it has been posted, but if an article has a Distribution: header and any distributions are specified, then they are checked according to the following rules:

1.

If the Distribution: header matches any of the values in the sub-field, the article is sent.

2.

If a distribution starts with an exclamation point, and it matches the Distribution: header, the article is not sent.

3.

If the Distribution: header does not match any distribution in the site's entry and no negations were used, the article is not sent.

4.

If the Distribution: header does not match any distribution in the site's entry and any distribution started with an exclamation point, the article is sent.

If an article has more than one distribution specified, then each one is handled according according to the above rules. If any of the specified distributions indicate that the article should be sent, it is; if none do, it is not sent. In other words, the rules are used as a logical or.

It is almost definitely a mistake to have a single feed that specifies distributions that start with an exclamation point along with some that don't.

Distributions are text words, not patterns; entries like "*" or "all" have no special meaning.

The flag field is described in "FLAG VALUES". The interpretation of the parameter field depends on the type of feed and is explained in more detail in "FEED TYPES". It can be omitted for some types of feeds.

The site named "ME" is special. There must be exactly one such entry, and it should be the first entry in the file. If the "ME" entry has an exclusion sub-field, incoming articles are rejected completely if any of the names specified in that exclusion sub-field appear in their Path: headers. If the "ME" entry has a subscription list, that list is prepended to the subscription list of all other entries. For example, "*,!control,!control.*,!junk,!foo.*" could be used to set the default subscription list for all other feeds so that local postings are not propagated unless "foo.*" explicitly appears in the site's subscription list. This feature tends to be somewhat confusing since the default subscription is prepended and can be overridden by other patterns.

If the "ME" entry has a distribution sub-field, only articles that match that distribution list are accepted and all other articles with a distribution are rejected. A common use for this is to put something like "/!local" in the "ME" entry to reject local postings from other misconfigured sites. The distribution sub-field of "ME" has no effect on the acceptance or rejection of articles that do not have a Distribution header field.

An empty "ME" entry is possible, in which case no exclusion patterns will be defined.

Finally, it is also possible to set variables in newsfeeds and use them later in the file. A line starting with "$" sets a variable. For example:

```
    $LOCALGROUPS=local.*,example.*
    $CONTROLGROUPS=control,control.*
```

This sets the variable "LOCALGROUPS" to "local.*,example.*" and the variable "CONTROLGROUPS" to "control,control.*". They can later be used elsewhere in the file, such as in a site entry like:

```
    news.example.com:$LOCALGROUPS:Tf,Wnm:
```

which is then completely equivalent to:

```
    news.example.com:local.*,example.*:Tf,Wnm:
```

Variables aren't solely simple substitution. If either "!" or "@" immediately preceds the variable and the value of the variable contains commas, that character will be duplicated before each comma. This somewhat odd-sounding behavior is designed to make it easier to use variables to construct feed patterns. The utility becomes more obvious when you observe that the line:

```
    news.example.net:*,@$LOCALGROUPS,!$CONTROLGROUPS:Tf,Wnm:
```

is therefore equivalent to:

```
    news.example.net:*,@local.*,@example.*,!control,!control.*:Tf,Wnm:
```

which (as explained below) excludes all of the groups in $LOCALGROUPS and unwanted control articles from the feed to that site.

## FLAG VALUES
The flags parameter specifies miscellaneous parameters, including the type of feed, what information should be sent to it, and various limitations on what articles should be sent to a site. They may be specified in any order and should be separated by commas. Flags that take values should have the value immediately after the flag letter with no whitespace. The valid flags are:

< size

An article will only be sent to this site if it is less than size bytes long. The default is no limit.

> size

An article will only be sent to this site if it is greater than size bytes long. The default is no limit.

A checks

An article will only be sent to this site if it meets the requirements specified in checks, which should be chosen from the following set. checks can be multiple letters if appropriate. Note that this flag is not effective on funnel targets; it has to be used on every funnel entry (for instance, Af is not effective on the innfeed! funnel target and therefore has to be specified on every funnelled news site).

c

Exclude all kinds of control messages.

C

Only send control messages, not regular articles.

d

Only send articles with a Distribution: header. Combined with a particular distribution value in the distribution part of the site entry, this can be used to limit articles sent to a site to just those with a particuliar distribution.

e

Only send articles where every newsgroup listed in the Newsgroups: header exists in the active file.

f

Don't send articles rejected by filters. This is only useful when dontrejectfiltered is set to true in inn.conf. With that variable set, this lets one accept all articles but not propagate filtered ones to some sites.

j

Propagate articles according to their Newsgroups: header. This is only useful when wanttrash is set to true in inn.conf. With that variable set, articles accepted and filed in "junk" (due to wanttrash) are fed to peers based on their subscription pattern applied to the Newsgroups: header as though they were accepted and all those groups were locally carried. Otherwise, they are propagated to sites that receive the "junk" newsgroup. This variable is useful if you want to run INN with a minimal active file and propagate all posts.

o

Only send articles for which overview data was stored.

O

Send articles to this site that don't have an Injection-Info: or X-Trace: header, even if the "O" flag is also given.

p

Only check the exclusions against the Path: header of articles; don't check the site name. This is useful if your site names aren't the same as the Path: entries added by those remote sites, or for program feeds where the site name is arbitrary and unrelated to the Path: header.

If both "c" and "C" are given, the last specified one takes precedence.

B high/low

If a site is being fed by a file, channel, or exploder (see below), the server will normally start trying to write the information as soon as possible. Providing a buffer may give better system performance and help smooth out overall load if a large batch of news comes in. The value of the this flag should be two numbers separated by a slash. high specifies the point at which the server can start draining the feed's I/O buffer, and low specifies when to stop writing and begin buffering again; the units are bytes. The default is to do no buffering, sending output as soon as it is possible to do so.

C count

If this flag is specified, an article will only be sent to this site if the number of groups it is posted to, plus the square of the number of groups followups would appear in, is no more than count. 30 is a good value for this flag, allowing for instance:

- crossposts to only 5 groups when followups aren't set;

- crossposts to up to 26 groups when followups are set to two groups;

- crossposts to up to 29 groups when followups are set to a single group;

- crossposts to up to 30 groups when followups are set to poster.

Note that if an article does not contain a Followup-To: header field, the number of groups followups would appear in is the number of groups it is posted to.

F name

Specifies the name of the file that should be used if it's necessary to begin spooling for the site (see below). If name is not an absolute path, it is taken to be relative to pathoutgoing in inn.conf. If name is a directory, the file togo in that directory will be used as the file name.

G count

If this flag is specified, an article will only be sent to this site if it is posted to no more than count newsgroups. This has the problem of filtering out many FAQs, as well as newsgroup creation postings and similar administrative announcements. Either the C flag or the U flag is a better solution.

H count

If this flag is specified, an article will only be sent to this site if it has count or fewer sites in its Path: line. This flag should only be used as a rough guide because of the loose interpretation of the Path: header; some sites put the poster's name in the header, and some sites that might logically be considered to be one hop become two because they put the posting workstation's name in the header. The default value for count if not specified is one. (Also see the O flag, which is sometimes more appropriate for some uses of this flag.)

I size

The flag specifies the size of the internal buffer for a file feed. If there are more file feeds than allowed by the system, they will be buffered internally in least-recently-used order. If the internal buffer grows bigger then size bytes, however, the data will be written out to the appropriate file. The default value is 16 KB.

N status

Restricts the articles sent to this site to those in newsgroups with the moderation status given by status. If status is "m", only articles in moderated groups are sent; if status is "u", only articles in unmoderated groups are sent.

O originator

If this flag is specified, an article will only be sent to this site if it contains an Injection-Info: header (or an X-Trace: header if no Injection-Info: header is found) and the first field of this header matches originator. originator is a uwildmat(3) expression without commas or a list of such expressions, separated by "/". The article is never sent if the first character of the pattern begins with "@" and the rest of the pattern matches. One use of this flag is to restrict the feed to locally generated posts by using an originator pattern that matches the Injection-Info: header added by the local server.

P priority

The nice priority that this channel or program feed should receive. This should be a positive number between 0 and 20 and is the priority that the new process will run with. This flag can be used to raise the priority to normal if you're using the nicekids parameter in inn.conf.

Q hashfeed

Specifies the hashfeed match expression for this site. It must be in the form "value/mod" or "start-end/mod". The Message-ID of the article is hashed using MD5, which results in a 128-bit hash. The lowest 32 bits are then taken by default as the hashfeed value (which is an integer). If the hashfeed value modulus "mod" plus one equals "value" or is between "start" and "end", the article will be fed to this site. All these numbers must be integers. It is a deterministic way to control the flow of articles and to split a feed. For instance:

```
    Q1/2      Feeds about 50% of all articles to this site.
    Q2/2      Feeds the other 50% of all articles.

```

Another example with three sites:

```
    Q1-3/10   Feeds about 30% of all articles.
    Q4-5/10   Feeds about 20% of all articles.
    Q6-10/10  Feeds about 50% of all articles.

```

If this flag is specified multiple times, the contents will be logically "OR"ed together (just one match is needed).

You can use an extended syntax of the form "value/mod_offset" or "start-end/mod_offset". As MD5 generates a 128-bit return value, it is possible to specify from which byte-offset the 32-bit integer used by hashfeed starts. The default value for "offset" is "_0" and thirteen overlapping values from "_0" to "_12" can be used. Only up to four totally independent values exist: "_0", "_4", "_8" and "_12".

Therefore, it allows generating a second level of deterministic distribution. Indeed, if a news server is fed "Q1/2", it can go on splitting thanks to "Q1-3/9_4" for instance. Up to four levels of deterministic distribution can be used.

The algorithm is compatible with the one used by Diablo 5.1 and up. If you want to use the legacy quickhashing method used by Diablo before 5.1, you can put an "@" sign just after the Q flag (for instance "Q@1-3/10", but the distribution of the messages is not perfect with this legacy method whose use is discouraged and for which offsets cannot be used).

S size

If the amount of data queued for the site gets to be larger than size bytes, the server will switch to spooling, appending to a file specified by the F flag, or pathoutgoing/sitename if F is not specified. Spooling usually happens only for channel or exploder feeds, when the spawned program isn't keeping up with its input.

T type

This flag specifies the type of feed for this site. type should be a letter chosen from the following set:

```
    c        Channel
    f        File
    l        Log entry only
    m        Funnel (multiple entries feed into one)
    p        Program
    x        Exploder

```

Each feed is described below in "FEED TYPES". The default is Tf, for a file feed.

U count

If this flag is specified, an article will only be sent to this site if followups to this article would be posted to no more than count newsgroups. (Also see C for a more complex way of handling this.)

W items

For a file, channel, or exploder feed, this flag controls what information will be sent to this site. For a program feed, only the asterisk ("*") has any effect. items should be chosen from the following set:

b

Size of the article (in wire format, meaning with CRLF at the end of each line, periods doubled at the beginning of lines, and ending in a line with a single period) in bytes.

e

The time the article will expire as seconds since epoch if it has an Expires: header, 0 otherwise.

f

The storage API token of the article (the same as "n"). The article can be retrieved given the storage API token by using sm(8).

g

The newsgroup the article is in; if cross-posted, then the first of the groups to which the article was posted that this site gets. (The difference from "G" is that this sends the newsgroup to which the article was posted even if it is a control message.)

h

The history hash key of the article (derived from the message ID).

m

The message ID of the article.

n

The storage API token of the article. The article can be retrieved given the storage API token by using sm(8).

p

The time the article was posted a seconds since epoch.

s

The site that fed the article to the server. This is taken from either the Path: header or the IP address of the sending site depending on the value of logipaddr in inn.conf. If logipaddr is true and the IP address is 0.0.0.0 (meaning that the article was fed from localhost by a program like rnews(8)), the Path: header value will be sent instead.

t

The time the article was received as seconds since epoch.

*

The names of the appropriate funnel entries, or all sites that get the article (see below for more details).

D

The value of the Distribution: header of the article, or "?" if there is no such header in the article.

G

Where the article is stored. If the newsgroup is crossposted, this is generally the first of the groups to which it was posted that this site receives; however, control messages are filed in control or control.* (which is the difference between this item and "g").

H

All of the headers, followed by a blank line. The Xref header will already be present, and a Bytes header containing the article's size in bytes as in the "b" item will be added to the headers. If used, this should be the only item in the list.

N

The value of the Newsgroups: header.

P

The value of the Path: header.

O

Overview data for the article.

R

Information needed for replication (the Xref header without the site name).

More than one letter can be given. If multiple items are specified, they will be written in the order specified separated by spaces. ("H" should be the only item if given, but if it's not a newline will be sent before the beginning of the headers.) The default is Wn.

The "H" and "O" items are intended for use by programs that create news overview databases or require similar information. WnteO is the flag to generate input needed by the overchan(8) program.

The asterisk ("*") has special meaning. Normally it expands to a space-separated list of all sites that received the current article. If, however, this site is a target of a funnel feed (in other words, if it is named by other sites which have the Tm flag), then the asterisk expands to the names of the funnel feeds that received the article. Similarly, if the site is a program feed, an asterisk in the parameter field will be expanded into the list of funnel feeds that received the article. A program feed cannot get the site list unless it is the target of other Tm feeds.

## FEED TYPES
innd provides four basic types of feeds: log, file, program, and channel. An exploder is a special type of channel. In addition, several entries can feed into the same feed; these are funnel feeds, which refer to an entry that is one of the other types. Funnel feeds are partially described above with the description of the W* flag. A funnel feed gets every article that would be sent to any of the feeds that funnel into it and normally include the W* flag in their flags so that the program processing that feed knows which sites received which articles. The most common funnel feed is innfeed(8).

Note that the term "feed" is technically a misnomer, since the server doesn't transfer articles itself and only writes data to a file, program, or log telling another program to transfer the articles.

The simplest feed is a log feed (Tl). Other than a mention in the news log file, pathlog/news, no data is written out. This is equivalent to a Tf entry writing to /dev/null, except that no file is ever opened. Flushing a log feed does nothing.

A file feed (Tf) is the next simplest type of feed. When the site should receive an article, the specified data is written out to the file named by the parameter field. If parameter is not an absolute path, it is taken to be relative to pathoutgoing in inn.conf. If parameter is not given, it defaults to pathoutgoing/sitename. The file name should be unique (two file feeds should not ever point to the same file).

File feeds are designed for use by external programs that periodically process the written data. To cooperate with innd properly, such external programs should first rename the batch file and then send a flush command for that site to innd using ctlinnd(8). innd will then write out any buffered data, close the file, and reopen it (under the original name), and the program can process the data in the renamed file at its leisure. File feeds are most frequently used in combination with nntpsend(8).

A program feed (Tp) spawns a given program for every article that the site receives. The parameter field must be the command line to execute, and should contain one instance of %s, which will be replaced by the storage API token of the article (the actual article can be retrieved by the program using sm(8)). The program will not receive anything on standard input (unlike earlier versions of INN, where the article is sent to the program on stdin), and standard output and error from the program will be set to the error log (pathlog/errlog). innd will try to avoid spawning a shell if the command has no shell meta-characters; this feature can be defeated if necessary for some reason by appending a semi-colon to the end of the command. The full path name of the program to be run must be specified unless the command will be run by the shell (and it is strongly recommended that the full path name always be specified regardless).

If a program feed is the target of a funnel, and if W* appears in the flags of the site, a single asterisk may be present in the parameter and will be replaced by a space-separated list of names of the sites feeding into the funnel which received the relevant article. If the site is not the target of a funnel, or if the W* flag is not used, the asterisk has no special meaning.

Flushing a program feed does nothing.

For a channel (Tc) or exploder (Tx) feed, the parameter field again names the process to start. As with program feeds, the full path to the program must be specified. However, rather than spawning the program for every article, it is spawned once and then whenever the site receives an article, the data specified by the site flags is written to the standard input of the spawned program. Standard output and error are set as with program feeds. If the process exits, it will be restarted automatically. If the process cannot be started, the server will spool input to a file named pathoutgoing/sitename and will try to start the process again later.

When a channel or exploder feed is flushed, the server closes its end of the pipe to the program's standard input. Any pending data that has not been written will be spooled; see the description of the S flag above. The server will then spawn a new instance of the program. No signal is sent to the program; it is up to the program handling a channel or exploder feed to notice end of file on its standard input and exit appropriately.

Exploders are a special type of channel feed. In addition to the channel feed behavior described above, exploders can also be sent command lines. These lines start with an exclamation point and their interpretation is up to the exploder. The following commands are generated automatically by the server:

```
    !newgroup group
    !rmgroup group
    !flush
    !flush site
```

These commands are sent whenever the ctlinnd(8) command of the same name is received by the server. In addition, the ctlinnd(8) "send" command can be used to send an arbitrary command line to an exploder. The primary exploder is buffchan(8).

Finally, Tm feeds are the input to a funnel. The parameter field of the site should name the site handling articles for all of the funnel inputs.

## EXAMPLES
The syntax of the newsfeeds file is so complex because you can specify a staggering variety of feeds. INN is capable of interacting with a wide variety of programs that do various things with news articles. Far and away the most common two entries in newsfeeds, however, are file feeds for nntpsend(8) and funnel feeds for innfeed(8).

The former look like this:

```
    feed.example.com:*,!control,!control.*,!junk:Tf,Wnm:
```

which generates a file named pathoutgoing/feed.example.com containing one line per article consisting of the storage API token, a space, and the message ID.

The latter look like this:

```
    feed.example.com:*,!control,!control.*,!junk:Tm:innfeed!
```

Very similar, except that this is the input to a funnel feed named "innfeed!". One could also write this as:

```
    example/feed.example.com:*,!control,!control.*,!junk:Ap,Tm:innfeed!
```

(note the Ap so that articles that contain just "example" in the Path: header will still be sent), which is completely equivalent except that this will be logged in pathlog/news as going to the site "example" rather than "feed.example.com".

The typical feed entry for innfeed(8) is a good example of a channel feed that's the target of various funnel feeds (make sure the path to innfeed is properly set):

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

Note that the pattern for this feed is just "!*" so that it won't receive any articles directly. The feed should only receive those articles that would go to one of the funnel feeds that are feeding into it. innfeed(8) will receive one line per article on its standard input containing the storage API token, the message ID, and a space-separated list of sites that should receive that article.

Here's a more esoteric example of a channel feed:

```
    watcher!:*:Tc,Wbnm\
        :exec awk '$1 > 1000000 { print "BIG", $2, $3 }' > /dev/console
```

This receives the byte size of each article along with the storage API token and message ID, and prints to the console a line for every article that's over a million bytes. This is actually rather a strange way to write this since INN can do the size check itself; the following is equivalent:

```
    watcher!:*:Tc,>1000000,Wbnm\
        :exec awk '{ print "BIG", $2, $3}' > /dev/console
```

Here's a cute, really simple news to mail gateway that also serves as an example of a fairly fancy program feed:

```
    mailer!:!*:W*,Tp\
        :sm %s | innmail -s "News article" *
```

Remember that %s is replaced by the storage API token, so this retrieves the article and pipes it into innmail (which is safer than programs like Mail(1) because it doesn't parse the body for tilde commands) with a given subject line. Note the use of "*" in the command line and W* in the flags; this entry is designed to be used as the target of funnel feeds such as:

```
    peter@example.com:news.software.nntp:Tm:mailer!
    sue@example.com:news.admin.misc:Tm:mailer!
```

Suppose that the server receives an article crossposted between news.admin.misc and news.software.nntp. The server will notice that the article should be sent to the site "peter@example.com" and the site "bob@example.com", both of which funnel into "mailer!", so it will look at the "mailer!" site and end up executing the command line:

```
    sm @...@ | innmail -s "News article" peter@example.com sue@example.com
```

which will mail the article to both Peter and Sue.

Finally, another very useful example of a channel feed: the standard entry for controlchan(8). Make sure its path is properly set.

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

This program only wants information about articles posted to a control newsgroup other than control.cancel, which due to the sorting of control messages described in innd(8) will send it all control messages except for cancel messages. In this case, we also exclude any article with a distribution of "collabra-internal". controlchan gets the storage API token, the name of the sending site (for processing old-style ihave and sendme control messages, be sure to read about logipaddr in controlchan(8)), and the message ID for each article.

For many other examples, including examples of the special "ME" site entry, see the example newsfeeds file distributed with INN. Also see the install documentation that comes with INN for information about setting up the standard newsfeeds entries used by most sites.

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Reformatted and rewritten in POD by Russ Allbery <eagle@eyrie.org>.

$Id: newsfeeds.pod 10283 2018-05-14 12:43:05Z iulius $

## SEE ALSO
active(5), buffchan(8), controlchan(8), ctlinnd(8), inn.conf(5), innd(8), innfeed(8), innxmit(8), nntpsend(8), uwildmat(3).


newsgroups

title: newsgroups(5)

text:
# newsgroups(5)

## NAME
newsgroups - List of newsgroups and their short descriptions

## DESCRIPTION
The file pathdb/newsgroups contains a list of newsgroups for which a short description is available. This file is generally updated by controlchan(8) whenever a control message is received; it is used by nnrpd in response to LIST NEWSGROUPS and is only meant to provide information to users. News readers often show the list of carried newsgroups along with these descriptions.

It is not necessary that all the groups carried by the news server (that is to say all the groups listed in the active file) be listed in the newsgroups file. And it is also not necessary that all the groups listed in the newsgroups file be carried by the news server. Nonetheless, it is of course better if the active and newsgroups files have exactly the same newsgroups.

If you use "ctlinnd newgroup" to manually create a group, only the active file is updated. You should then edit the newsgroups file in order to add a short description for the created group. The same goes for manually removing or changing the status of a newsgroup.

Each line of the newsgroups file consists of two fields separated by at least one tabulation:

```
    <name>\t<description>
```

The first field is the name of the newsgroup. The second field is its description.

You can get the newsgroups file of another NNTP server with getlist(1).

## PREFERRED FORMAT FOR A ONE-LINE NEWSGROUP DESCRIPTION
As far as the format of the newsgroups file is concerned, there is a preferred format for each line. Since news administrators do not generally have the time to fix up the lines that are being automatically included from newgroup or checkgroups messages, this information is provided so that control message senders can craft better control messages. It will also be useful for news administrators to know how to format the description of their local newsgroups.

There should be at least one hard tab (8 column tab stops) between the group name and the description. If the group name is at least 16 characters, it should be followed with one tab. If the group name is at least 8 characters, it should be followed with two tabs. And in the unlikely event the group name is less than 8 characters, it should be followed with three tabs. For instance:

```
    misc.transport.rail.europe  Railroads & railways in all of Europe.
    news.admin.nocem    NoCeM protocol policy issues and information.
    news.groups         Discussions and lists of newsgroups.
```

The total line length should be at most 79 columns. The description should start with a capital and not be more than 55 characters (79 - 24) long. If the group name is longer than 24 characters, the description should be correspondingly shorter. If the group is moderated, it should have " (Moderated)" (note the space before the opening parenthesis) at the very end of the description, not counted as part of the length of the description. This text must be exactly that, with no variations, as it is used by news software to find moderated groups.

Here is an example of moderated newsgroup:

```
    news.lists.misc     News-related statistics and lists. (Moderated)
```

Traditionally, all newsgroup descriptions ended with a period, but this is not necessary and steals away one character that is occasionally useful for forming a better description.

Some over-long descriptions could be made to easily fit the length by dropping useless wordings like "Discussion of" which do not meaningfully contribute to the description. Others are usually pretty easy to get to no more than column eighty, except when the group names start getting really long. Hopefully then the group name itself contains quite a bit of description.

In some cases, a longer description really will be necessary; they can of course be used within the newsgroups file. However, they will probably be less readable and less useful for some Usenet users.

Descriptions must not contain any control characters (octets between 0x00 and 0x1F).

## ENCODING OF THE DESCRIPTIONS
There is, at present, no good mechanism for managing the character set of the newsgroup descriptions. Many non-English hierarchies include newsgroup descriptions in their native languages, since this is more useful for their users, and those are included verbatim in the newsgroups file. This unfortunately means that different lines of the file will require different character set settings to read properly, and those character sets are not documented in the file. Hopefully some future standard will provide a way to address this; in the meantime, using UTF-8 for non-ASCII characters is recommended.

## MINIMAL NEWSGROUPS FILE
The minimal newsgroups file shipped with INN is:

```
    control             Various control messages (no posting).
    control.cancel      Cancel messages (no posting).
    control.checkgroups Hierarchy check control messages (no posting).
    control.newgroup    Newsgroup creation control messages (no posting).
    control.rmgroup     Newsgroup removal control messages (no posting).
    junk                Unfiled articles (no posting).
```

These lines must be tab-delimited, so please be careful in case you copy and paste them from above.

## HISTORY
Written by Julien Elie for InterNetNews. The preferred format for a one-line newsgroup description is based on the policies by which the newsgroups file in <https://ftp.isc.org/pub/usenet/CONFIG/> is maintained; they were originally written by David Lawrence <tale@isc.org> and updated by Russ Allbery <eagle@eyrie.org>.

$Id: newsgroups.pod 10097 2016-11-04 22:19:07Z iulius $

## SEE ALSO
active(5), controlchan(8), ctlinnd(8), getlist(1), nnrpd(8).


newslog

title: newslog(5)

summary: Description of INN log files

text:
# newslog(5)

## NAME
newslog - Description of INN log files

## DESCRIPTION
Most log files created by Usenet programs reside in the pathlog directory set in inn.conf and have a ".log" extension. Several versions are usually kept with an additional extension such as .1, .2, etc. -- the higher the number, the older the log. These old versions are stored in pathlog/OLD; they may be compressed and thus may have a ".1.gz", ".2.gz", etc. extension, up to ".nn.gz" where "nn" is the number of old logs kept by scanlogs which is set by logcycles in inn.conf.

The scanlogs script and related utilities are responsible for rotating and compressing these files. Some log files always have data (like news.notice), others only have data if there is a problem (like news.err), and others are only created if a particular program is used (like send-uucp.log used by send-uucp) or if a configuration parameter is set (like innfeed.log used by innfeed when debug-level is set in innfeed.conf).

Besides, the innstat script monitors the size of all log files.

Here are the log files used by INN:

control.log

This file maintains a count of the number of newgroup and rmgroup control messages seen for each newsgroup. The count is of the number of control messages with the indicated arguments, regardless if they were actually processed. All control arguments, including invalid ones, are counted. An example of lines which can be found in that log file is:

```
    3 Control: newgroup foo.bar moderated
    3 Control: rmgroup misc.removed
    1 Control: newgroup misc.created

```

This file is updated by tally.control, which is invoked by scanlogs if either one of these two log files exists in pathlog:

```
    newgroup.log
    rmgroup.log

```

These two log files contain a summary line describing the control message and the action taken by controlchan, followed by the article indented by four spaces, and a blank line. Whereas these files are rotated, control.log is not rotated so as to keep the count of seen control messages.

Note that other control log files are also rotated by scanlogs, if they exist, but their contents are not summarized. Here are their names:

```
    checkgroups.log
    default.log
    ihave.log
    miscctl.log
    sendme.log
    sendsys.log
    senduuname.log
    version.log

```

In order to create these files, the <type> and <action> fields of relevant control.ctl entries should be correctly set. For instance:

```
    Type            Action              Meaning
    ----            ------              -------
    all             log=miscctl         Log all messages by default.
    newgroup        doit=newgroup       Create group and log message.
    newgroup        log=newgroup        Log message.
    rmgroup         verify-*=rmgroup    PGP verify, remove group and log message.
    checkgroups     doit=checkgroups    Process and log message.

```

controlbatch.log

The controlbatch program appends all status messages to this file. It is rotated by scanlogs.

errlog

This file contains the standard output and standard error of any program spawned by innd, such as channel feeds configured in newsfeeds. This file should normally be empty. scanlogs will print the 50 first lines of this log file if it is non-empty so that they appear in daily Usenet reports generated by news.daily. Then, scanlogs rotates this log file.

expire.log

By default, when news.daily is going to expire old news articles, it writes the name of the program it invokes, followed by "start" and the time it has started. Any output from that program is then written, indented by four spaces. Then, the name of the program is written, followed by "end" and the time it has ended. Programs called, if needed, are in order: expireover, ctlinnd (with the "lowmark" option), expirerm and expire. Removed articles are listed in expire.list and low marks for each newsgroup (that is to say the number of the oldest article available in the newsgroup) in expire.lastlowmark.

After the expiry process, scanlogs rotates expire.log.

innfeed.log

When debug-level is set in innfeed.conf, innfeed appends debugging messages to this file. Note that the name of this file can be changed with the log-file parameter in innfeed.conf. Be that as it may, the right log file is rotated by scanlogs. innfeed also logs its status in innfeed.status (or the name set in status-file) if gen-html is set to false but this log file is not processed by scanlogs.

news

This file logs articles received by innd. Typical lines are:

```
    Aug 25 13:37:41.839 + news.server.fr <cancel.4066@foo.com> 1658 a.peer other.server.org inpaths!
    Aug 25 13:37:41.839 c news.server.fr <cancel.4066@foo.com> Cancelling <m070725@foo.com>
    Aug 25 13:37:54.638 - a.peer <23k82@bar.net> 437 Poison newsgroup

```

The first one indicates that an article from "news.server.fr" has been accepted ("+"). Its Message-ID is "<cancel.4066@foo.com>" and we will send the article to two peers ("a.peer" and "other.server.org", as specified in newsfeeds) and "inpaths!" (see ninpaths for more details about it). The second line mentions that this previous article is a cancel message ("c") for "<m070725@foo.com>" and that it has been processed (inndeed, controlchan processes all control articles except for cancels which are handled by innd). The third line indicates that the article whose Message-ID is "<23k82@bar.net>" has been rejected ("-") because it is posted to a poison newsgroup (a Perl or a Python filter located in pathfilter must have brought that reject along).

See the "LOGGING" section of the innd(8) man page for more information about the format of this log file.

innreport summarizes the rejected articles reported in this file and scanlogs rotates it.

news.crit

All critical error messages issued by innd are appended to this file via syslog. This log file should normally be empty. scanlogs will print the first 50 lines of this log file if it is non-empty so that they appear in daily Usenet reports generated by news.daily. Then, scanlogs rotates this log file. You should have the following line in your system syslog.conf file, using a tab character for the delimiter:

```
    news.crit           <pathlog>/news.crit

```

(A typical entry is shown; it should agree with pathlog in inn.conf and be tab-delimited.)

news.err

All major error messages issued by innd are appended to this file via syslog. This log file should normally be empty. scanlogs will print the first 50 lines of this log file if it is non-empty so that they appear in daily Usenet reports generated by news.daily. Then, scanlogs rotates this log file. You should have the following line in your system syslog.conf file, using a tab character for the delimiter:

```
    news.err            <pathlog>/news.err

```

(A typical entry is shown; it should agree with pathlog in inn.conf and be tab-delimited.)

news.notice

All standard error messages and status messages issued by innd, innfeed, nnrpd and some other programs are appended to this file via syslog. scanlogs uses the Perl script innreport to summarize this file. innreport will also print the first max_unknown unknown lines of this log file if such unrecognized lines are found in news.notice so that they appear in daily Usenet reports generated by news.daily. This parameter can be set in innreport.conf. Then, scanlogs rotates this log file. You should have the following line in your system syslog.conf file, using a tab character for the delimiter:

```
    news.notice         <pathlog>/news.notice

```

(A typical entry is shown; it should agree with pathlog in inn.conf and be tab-delimited.)

nntpsend.log

The nntpsend program appends all status messages to this file. It is rotated by scanlogs.

perl-nocem.log

The perl-nocem program appends all status messages to this file if "Sys::Syslog" is not used (otherwise, such messages are appended to news.notice). It is rotated by scanlogs.

send-ihave.log

The send-ihave program appends all status messages to this file. It is rotated by scanlogs.

send-nntp.log

The send-nntp program appends all status messages to this file. It is rotated by scanlogs.

send-uucp.log

The send-uucp program appends all status messages to this file. It is rotated by scanlogs.

unwanted.log

This log maintains a count of the number of articles that were rejected because they were posted to newsgroups that do not exist at the local site. This file is updated by innreport while processing the news.notice log file and it is maintained in reverse numeric order (the most popular rejected group first). This file is not rotated so as to keep the count of the articles posted to newsgroups which are absent from the active file of the news server. Note that logtrash has to be set to true in inn.conf for this file to be generated.

Finally, these files are also rotated by scanlogs, if they exist, but their contents are not summarized. Here are their names:

```
    badcontrol.log
    badpgp.log
    failedpgp.log
```

They can be used by programs which PGP verify articles.

## HISTORY
Written by Landon Curt Noll <chongo@toad.com> and Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten and converted to POD by Julien Elie.

$Id: newslog.pod 9903 2015-06-20 17:20:46Z iulius $

## SEE ALSO
control.ctl(5), ctlinnd(8), expire(8), expireover(8), expirerm(8), inn.conf(5), innd(8), innfeed.conf(5), innreport(8), innreport.conf(5), news.daily(8), nnrpd(8), nntpsend(8), scanlogs(8), send-nntp(8), send-uucp(8), syslog.conf(5), tally.control(8).


nnrpd.track

title: nnrpd.track(5)

text:
# nnrpd.track(5)

## NAME
nnrpd.track - file to specify hosts to be tracked by nnrpd.

## DESCRIPTION
This file, which is located in <pathetc in inn.conf>, specifies which hosts are to have their activities recorded during an nnrpd session. The nnrpd server reads it when first spawned by innd, provided readertrack in inn.conf is true; otherwise this file is not used.

Entries consist of one host specification per line, each line having two fields, separated by a colon:

```
host:identity
```

The first field is either one of the FQDNs of a host, or a domain name (in the form *.domain.com).

The second field is simply a segment of text which may be used to more easily identify the client, typically an e-mail address or other identifying mark.

For example:

```
nasty.foo.com:nasty@foo.com
*.bar.com:VeryNastyClient
```

Written by Steve Carrie <stephenc@uk.uu.net> for InterNetNews. This is revision 10179, dated 2017-09-18.

## SEE ALSO
inn.conf(5), innd(8), newsfeeds(5), nnrpd(8),


nntpsend.ctl

title: nntpsend.ctl(5)

summary: List of sites to feed via nntpsend

text:
# nntpsend.ctl(5)

## NAME
nntpsend.ctl - List of sites to feed via nntpsend

## DESCRIPTION
The file pathetc/nntpsend.ctl specifies the default list of sites to be fed by nntpsend. Comments begin with a number sign ("#") and continue through the end of the line. Blank lines and comments are ignored. All other lines should consist of four fields separated by a colon.

The first field is the name of the site as specified in the newsfeeds file.

The second field should be the hostname or IP address of the remote site.

The third field, if non-empty, specifies the default head truncation size of the batch file. If this field is empty, no truncation is performed. This field may be of the form "maxsize-truncsize", in which case it is passed to shrinkfile as "-m maxsize -s truncsize"; otherwise it is of the form "truncsize", in which case it is passed as "-s truncsize".

The fourth field specifies some default flags passed to innxmit. Note that the flag -a is always given to innxmit and need not appear here. If no -t flag is given in this field or on the nntpsend command line, "-t 180" will be given to innxmit.

See nntpsend(8) for an example of nntpsend.ctl config file.

## HISTORY
Written by Landon Curt Noll <chongo@toad.com> for InterNetNews. Converted to POD by Julien Elie.

$Id: nntpsend.ctl.pod 9071 2010-05-31 17:41:32Z iulius $

## SEE ALSO
innxmit(1), newsfeeds(5), nntpsend(8), shrinkfile(1).


ovdb

title: ovdb(5)

summary: Overview storage method for INN

text:
# ovdb(5)

## NAME
ovdb - Overview storage method for INN

## DESCRIPTION
The ovdb overview is a storage method that uses the Berkeley DB library to store overview data. It requires version 4.4 or later of the Berkeley DB library (4.7+ is recommended because older versions suffer from various issues).

The ovdb overview method makes use of the full transaction/logging/locking functionality of the Berkeley DB environment. Berkeley DB may be downloaded from <http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/overview/index.html> and is needed to build the ovdb backend.

## UPGRADING
There are several versions of the ovdb storage method:

- Version 1, the initial version shipped with INN 2.3.0 up to INN 2.3.5.

- Version 2, with improved performance, since INN 2.4.0.

- Version 3, corresponding to version 2 with compression enabled, starting with INN 2.5.0.

If you have a database created with a previous version of ovdb, your database will need to be upgraded using ovdb_init. See the ovdb_init(8) man page for upgrade instructions, as well as the COMPRESSION section below.

Note that when the Berkeley DB library is updated to a newer version, the ovdb database also needs being upgraded.

## INSTALLATION
If the Berkeley DB library is found at configure time, INN will be built with Berkeley DB support unless the --without-bdb flag is explicitly passed to configure. By default, configure will search for Berkeley DB in standard locations; there will be a message in the configure output indicating the pathname that will be used.

You can override this pathname by adding a path to the option, for instance --with-bdb=/usr/BerkeleyDB.4.4. This directory is expected to have subdirectories include and lib (lib32 and lib64 are also checked), containing respectively db.h, and the library itself. In case non-standard paths to the Berkeley DB libraries are used, one or both of the options --with-bdb-include and --with-bdb-lib can be given to configure with a path.

The ovdb database may take up more disk space for a given spool than the other overview methods. Plan on needing at least 1.1 KB for every article in your spool (not counting crossposts). So, if you have 5 million articles, you'll need at least 5.5 GB of disk space for ovdb. With compression enabled, this estimate changes to 0.9 KB per article, so you'll need at least 4.5 GB of disk space for 5 million articles. See the COMPRESSION section below. Plus, you'll need additional space for transaction logs: at least 100 MB. By default, the transaction logs go in the same directory as the database. To improve performance, they can be placed on a different disk -- see the DB_CONFIG section.

## CONFIGURATION
To enable the ovdb overview method, set the ovmethod parameter in inn.conf to "ovdb". The ovdb database is stored in the directory specified by the pathoverview parameter in inn.conf. This is the "DB_HOME" directory. To start out, this directory should be empty (other than an optional DB_CONFIG file; see DB_CONFIG for details), and innd (or makehistory) will create the files as necessary in that directory. Also, make sure the directory is owned by the news user.

Other parameters for configuring ovdb are in the ovdb.conf configuration file. The following parameters can be set in that file:

compress

If INN was compiled with zlib, and this compress parameter is true, ovdb will compress overview records that are longer than 600 bytes. See the COMPRESSION section below.

cachesize

Size of the memory pool cache, in kilobytes. The cache will have a backing store file in the DB directory which will be at least as big. In general, the bigger the cache, the better. Use "ovdb_stat -m" to see cache hit percentages. To make a change of this parameter take effect, shut down and restart INN (be sure to kill all of the nnrpd processes when shutting down). Default is 8000 (KB), which is adequate for small to medium-sized servers. Large servers will probably need at least 20000 (KB).

ncache

Number of regions across which to split the cache. The region size is equal to cachesize divided by ncache. Default is 1 for ncache, that is to say the cache will be allocated contiguously in memory.

numdbfiles

Overview data is split between this many files. Currently, innd will keep all of the files open, so don't set this too high or innd may run out of file descriptors. nnrpd only opens one at a time, regardless. May be set to one, or just a few, but only do that if your OS supports large (> 2 GB) files. Changing this parameter has no effect on an already-established database. Default is 32.

txn_nosync

If txn_nosync is set to false, Berkeley DB flushes the log after every transaction. This minimizes the number of transactions that may be lost in the event of a crash, but results in significantly degraded performance. Default is true.

useshm

If useshm is set to true, Berkeley DB will use shared memory instead of mmap for its environment regions (cache, lock, etc). With some platforms, this may improve performance. Default is false.

shmkey

Sets the shared memory key used by Berkeley DB when useshm is true. Berkeley DB will create several (usually 5) shared memory segments, using sequentially numbered keys starting with "shmkey". Choose a key that does not conflict with any existing shared memory segments on your system. Default is 6400.

pagesize

Sets the page size for the DB files (in bytes). Must be a power of 2. Best choices are 4096 or 8192. The default is 8192. Changing this parameter has no effect on an already-established database.

minkey

Sets the minimum number of keys per page. See the Berkeley DB documentation for more information. Default is based on page size and whether compression is enabled:

```
   default_minkey = MAX(2, pagesize / 2600) if compress is false
   default_minkey = MAX(2, pagesize / 1500) if compress is true

```

The lowest allowed minkey is 2. Setting minkey higher than the default is not recommended, as it will cause the databases to have a lot of overflow pages. Changing this parameter has no effect on an already-established database.

maxlocks

Sets the Berkeley DB lk_max parameter, which is the maximum number of locks that can exist in the database at the same time. Default is 4000.

nocompact

The nocompact parameter affects the behaviour of expireover. The expireover function in ovdb can do its job in one of two ways: by simply deleting expired records from the database; or by re-writing the overview records into a different location leaving out the expired records. The first method is faster, but it leaves 'holes' that result in space that can not immediately be reused. The second method 'compacts' the records by rewriting them. If this parameter is set to 0, expireover will compact all newsgroups; if set to 1, expireover will not compact any newsgroups; and if set to a value greater than one, expireover will only compact groups that have less than that number of articles.

Experience has shown that compacting has minimal effect (other than making expireover take longer) so the default is 1. This parameter will probably be removed in the future.

readserver

When the readserver parameter is set to false, each nnrpd process directly accesses the Berkeley DB environment. The process of attaching to the database (and detaching when finished) is fairly expensive, and can result in high loads in situations when there are lots of reader connections of relatively short duration. When the readserver parameter is set to true, the nnrpd processes will access overview via a helper server (ovdb_server -- which is started by ovdb_init). All ovdb reads will then be funnelled through a single process with a cleaner interface to the underlying Berkeley DB database. This will result in cleaner shutdowns for the database, improving stability and avoiding deadlocks, timing issues and corrupted databases. That's why you should try to set this parameter to true if you are experiencing any instability in the ovdb overview method.

Default value is true.

numrsprocs

This parameter is only used when readserver is true. It sets the number of ovdb_server processes. As each ovdb_server can process only one transaction at a time, running more servers can improve reader response times. Default is 5.

maxrsconn

This parameter is only used when readserver is true. It sets a maximum number of readers that a given ovdb_server process will serve at one time. This means the maximum number of readers for all of the ovdb_server processes is (numrsprocs * maxrsconn). This does not limit the actual number of readers, since nnrpd will fall back to opening the database directly if it can't connect to an ovdb_server. Default is 0, which means an unlimited number of connections is allowed.

## COMPRESSION
The ovdb storage method has the ability to compress overview data before it is stored into the database. In addition to consuming less disk space, compression keeps the average size of the database keys smaller. This in turn increases the average number of keys per page, which can significantly improve performance and also helps keep the database more compact. This feature requires that INN be built with zlib. Only records larger than 600 bytes get compressed, because that is the point at which compression starts to become significant.

If compression is not enabled (either from the compress option in ovdb.conf or INN was not built with zlib support), the database will be backward compatible with older versions of ovdb. However, if compression is enabled, the database is marked with a newer version that will prevent older versions of ovdb from opening the database.

You can upgrade an existing database to use compression simply by setting compress to true in ovdb.conf. Note that existing records in the database will remain uncompressed; only new records added after enabling compression will be compressed.

If you disable compression on a database that previously had it enabled, new records will be stored uncompressed, but the database will still be incompatible with older versions of ovdb (and will also be incompatible with this version of ovdb if INN was not built with zlib support). So to downgrade to a completely uncompressed database, you will have to rebuild the database using makehistory.

## DB_CONFIG
A file called DB_CONFIG may be placed in the database directory (pathoverview in inn.conf) to customize where the various database files and transaction logs are written. By default, all of the files are written in the "DB_HOME" directory. One way to improve performance is to put the transaction logs on a different disk. To do this, put:

```
    DB_LOG_DIR /path/to/logs
```

in the DB_CONFIG file. If the pathname you give starts with a "/", it is treated as an absolute path; otherwise, it is relative to the "DB_HOME" directory. Make sure that any directories you specify exist and have proper ownership/mode before starting INN, because they won't be created automatically. Also, don't change the DB_CONFIG file while anything that uses ovdb is running.

Another thing that you can do with this file is to split the overview database across multiple disks. In the DB_CONFIG file, you can list directories that Berkeley DB will search when it goes to open a database.

For example, let's say that you have pathoverview set to /mnt/overview and you have four additional file systems created on /mnt/ovX. You would create a file /mnt/overview/DB_CONFIG containing the following lines:

```
    set_data_dir /mnt/overview
    set_data_dir /mnt/ov1
    set_data_dir /mnt/ov2
    set_data_dir /mnt/ov3
    set_data_dir /mnt/ov4
```

Distribute your ovNNNNN files into the four filesystems (say, 8 each). When called upon to open a database file, the db library will look for it in each of the specified directories (in order). If said file is not found, one will be created in the first of those directories.

Whenever you change DB_CONFIG or move database files around, make sure all news processes that use the database are shut down first (including nnrpd processes).

The DB_CONFIG functionality is part of Berkeley DB itself, rather than something provided by ovdb. See the Berkeley DB documentation for complete details for the version of Berkeley DB that you're running.

## RUNNING
When starting the news system, rc.news will invoke the ovdb_init program. See the ovdb_init(8) man page for information about the tasks it performs. ovdb_init must be run before using the database.

And when stopping INN, rc.news kills the ovdb_monitor processes after the other INN processes have been shut down.

## DIAGNOSTICS
Problems relating to ovdb are logged to news.err with "OVDB" in the error message.

INN programs that use overview will fail to start up if the ovdb_monitor processes aren't running. Be sure to run ovdb_init before running anything that accesses overview.

Also, INN programs that use overview will fail to start up if the user running them is not the news user.

If a program accessing the database crashes, or otherwise exits uncleanly, it might leave a stale lock in the database. This lock could cause other processes to deadlock on that stale lock. To fix this, shut down all news processes (using "kill -9" if necessary) and then restart. ovdb_init should perform a recovery operation which will remove the locks and repair damage caused by killing the deadlocked processes.

## FILES
pathetc/inn.conf

The ovmethod and pathoverview parameters are relevant to ovdb.

pathetc/ovdb.conf

Optional configuration file for tuning. See CONFIGURATION above.

pathoverview

Directory where the database goes. Berkeley DB calls it the "DB_HOME" directory.

pathoverview/DB_CONFIG

Optional file to configure the layout of the database files.

pathrun/ovdb.sem

A file that gets locked by every process that is accessing the database. This is used by ovdb_init to determine whether the database is active or quiescent.

pathrun/ovdb_monitor.pid

Contains the process ID of ovdb_monitor.

## TO DO
Implement a way to limit how many databases can be open at once (to reduce file descriptor usage); maybe using something similar to the cache code in legacy ov3.c file.

## HISTORY
Written by Heath Kehoe <hakehoe@avalon.net> for InterNetNews.

$Id: ovdb.pod 10525 2021-01-20 11:51:15Z iulius $

## SEE ALSO
inn.conf(5), innd(8), makehistory(8), nnrpd(8), ovdb_init(8), ovdb_monitor(8), ovdb_stat(8).

Berkeley DB documentation: in the docs directory of the Berkeley DB source distribution, or on the Oracle Berkeley DB web page (<http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/overview/index.html>).


passwd.nntp

title: passwd.nntp(5)

text:
# passwd.nntp(5)

## NAME
passwd.nntp - Passwords for connecting to remote NNTP servers

## DESCRIPTION
The file pathetc/passwd.nntp contains host / name / password triplets for use when authenticating client programs to NNTP servers. This file is normally interpreted by NNTPsendpassword() in libinn(3). Blank lines and lines beginning with a number sign ("#") are ignored. All other lines should consist of three or four fields separated by colons:

```
    host:name:password
    host:name:password:style
```

The first field is the name of a host, and is matched in a case-insensitive manner. (No detailed matching, such as comparing IP addresses, is done.)

The second field is a user name, and the third is a password. If either the username or password is empty, then that portion of the authentication will not occur. (For example, a server may require only a username, in which case the password is not necessary. Note that a username is mandatory with AUTHINFO USER/PASS.)

The optional fourth field specifies the type of authentication to use. At present, the only recognized "authentication style" is "authinfo"; this is also the default. It means that AUTHINFO USER/PASS commands are used to authenticate to the remote host. (These NNTP commands are described in RFC 4643.)

For example:

```
    ##  UUNET needs a password, MIT doesn't.
    mit.edu:bbn::authinfo
    uunet.uu.net:bbn:yoyoma:authinfo
```

This file should not be world-readable.

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.

$Id: passwd.nntp.pod 8821 2009-11-20 17:32:37Z iulius $

## SEE ALSO
inn.conf(5), innd(8), libinn(3).