.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "NEWSFEEDS 5"
.TH NEWSFEEDS 5 2025-04-04 "INN 2.7.3" "InterNetNews Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
newsfeeds \- Determine where Usenet articles are sent
.SH "IN A NUTSHELL"
.IX Header "IN A NUTSHELL"
The \fInewsfeeds\fR file configures what \fBinnd\fR does with incoming accepted
articles.
.PP
A minimalist \fInewsfeeds\fR file which parameters an outgoing NNTP feed to
\&\f(CW\*(C`news.server.com\*(C'\fR, using path identity \f(CW\*(C`server\*(C'\fR (as it appears in Path
header fields), of all the articles you receive is:
.PP
.Vb 2
\& # Mandatory line, with no exclusion patterns defined.
\& ME:::
\&
\& # A real\-time feed through innfeed of all your articles.
\& news.server.com/server\e
\& :*\e
\& :Tm:innfeed!
\&
\& # The channel feed entry for innfeed.
\& # Change "/usr/lib/news/bin" to the directory path
\& # of the innfeed program.
\& innfeed!:!*:Tc,Wnm*:/usr/lib/news/bin/innfeed
.Ve
.PP
In order to find an external feed, you can ask in the news.admin.peering
newsgroup. Several news administrators will certainly respond and gracefully
provide you with a news feed.
.PP
Other entries may be added in \fInewsfeeds\fR depending on your needs. See the
examples below and also in the archive(8), controlchan(8), news2mail(8),
ninpaths(8) and perl\-nocem(8) man pages for the most widely used.
.PP
If you exclude local hierarchies or newsgroups from the feed, make sure to add
\&\f(CW\*(C`!control,!control.*\*(C'\fR so that cancel articles or any kind of control articles
related to excluded hierarchies or newsgroups are not propagated to the remote
peer. Its \fInewsfeeds\fR entry then looks like:
.PP
.Vb 3
\& news.server.com/server\e
\& :*,!local.*,@*bina*,!control,!control.*\e
\& :Tm:innfeed!
.Ve
.PP
After any changes, run \f(CW\*(C`inncheck\*(C'\fR to perform basic syntax checks, and reload
this configuration file with the following command:
.PP
.Vb 1
\& ctlinnd reload newsfeeds \*(Aqnew peer\*(Aq
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The file \fIpathetc\fR/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). \fBinnd\fR doesn't send articles to remote sites itself, so
\&\fInewsfeeds\fR 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.
.PP
Used in conjunction with delayer(1) in the configuration of the related funnel
feed, \fBinnfeed\fR can even send a delayed feed to remote peers or to another
local instance of \fBinnd\fR, notably to permit the rejection of spam before it
actually arrives.
.PP
The \fInewsfeeds\fR 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 \fInewsfeeds\fR, as could a news to mail gateway.
.PP
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 (\f(CW\*(C`#\*(C'\fR), it is ignored.
.PP
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:
.PP
.Vb 4
\& sitename[/exclude,exclude,...]\e
\& :pattern,pattern...[/distribution,distribution...]\e
\& :flag,flag...\e
\& :parameter
.Ve
.PP
Each field is described below.
.PP
The \fIsitename\fR 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 \fInewsfeeds\fR is also a "site".) If \fIsitename\fR already appears
in the article's Path header field body, 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 field body, but can be almost
any word.
.PP
Be careful, though, to avoid having the \fIsitename\fR accidentally match a path
identity in the Path header field 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, \f(CW\*(C`gateway\*(C'\fR is an obvious name for the local entry that
forwards articles out to a mailing list. If a site with the name \f(CW\*(C`gateway\*(C'\fR
posts an article, when the local site receives the article it will see the
name in the Path header field and not send the article to its own \f(CW\*(C`gateway\*(C'\fR
entry. Since \f(CW\*(C`gateway!\*(C'\fR can't appear as an individual path identity in the
Path header field (as \f(CW\*(C`!\*(C'\fR is the delimiter), that would be a better thing to
use for \fIsitename\fR.
.PP
(Another way to avoid this problem is with the \f(CW\*(C`Ap\*(C'\fR flag; see the
description below.)
.PP
If an entry has an exclusion sub-field, the article will not be sent
to that site if any of \fIexclude\fR appear in the Path header field body.
(It's sometimes convenient to have the \fIsitename\fR be an abbreviated form of
the name of the remote site, since all the \fIsitename\fRs to which an article
is sent are written to the log and using shorter \fIsitename\fRs can therefore
improve performance for large servers. In this case, the path identities of
those sites should be given as \fIexclude\fR entries and the \f(CW\*(C`Ap\*(C'\fR flag used so
that the abbreviated \fIsitename\fR doesn't accidentally match some other path
identities in Path header fields.)
.PP
The same \fIsitename\fR 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.
.PP
The comma-separated \fIpattern\fR 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
\&\fIuwildmat\fR pattern supporting poison (\f(CW\*(C`@\*(C'\fR) wildcards; see the libinn_uwildmat
man page for full details on the pattern matching language. \fIpattern\fR
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.
.PP
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 an \f(CW\*(C`@\*(C'\fR pattern in \fIpattern\fR,
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").
.PP
For example, to receive all comp.* groups, but only comp.sources.unix
within the sources newsgroups, the following \fIpattern\fR can be used:
.PP
.Vb 1
\& comp.*,!comp.sources.*,comp.sources.unix
.Ve
.PP
Note that the trailing \f(CW\*(C`.*\*(C'\fR is required; the pattern has to match the
whole newsgroup name. \f(CW\*(C`comp.sources.*\*(C'\fR could be written \f(CW\*(C`comp.sources*\*(C'\fR
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
\&\f(CW\*(C`comp.*\*(C'\fR and none of the other patterns).
.PP
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:
.PP
.Vb 1
\& alt.*,@alt.binaries.warez,misc.*
.Ve
.PP
Note, however, that if you reversed the \f(CW\*(C`alt.*\*(C'\fR and \f(CW\*(C`@alt.binaries.warez\*(C'\fR
entries, this pattern would be equivalent to \f(CW\*(C`alt.*,misc.*\*(C'\fR, 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.
.PP
Control messages follow slightly different propagation rules than normal
articles; see innd(8) for the details. Note that most subscriptions
should have \f(CW\*(C`!junk,!control,!control.*\*(C'\fR in their pattern list due to those
propagation rules (and since \f(CW\*(C`junk\*(C'\fR is a special internal newsgroup; see
\&\fIwanttrash\fR 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.
.PP
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 field and any
\&\fIdistribution\fRs are specified, then they are checked according to the
following rules:
.IP 1. 4
If the Distribution header field matches any of the values in the sub-field,
the article is sent.
.IP 2. 4
If a \fIdistribution\fR starts with an exclamation point, and it matches the
Distribution header field, the article is not sent.
.IP 3. 4
If the Distribution header field does not match any \fIdistribution\fR in the
site's entry and no negations were used, the article is not sent.
.IP 4. 4
If the Distribution header field does not match any \fIdistribution\fR in the
site's entry and any \fIdistribution\fR started with an exclamation point,
the article is sent.
.PP
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.
.PP
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.
.PP
Distributions are text words, not patterns; entries like \f(CW\*(C`*\*(C'\fR or \f(CW\*(C`all\*(C'\fR
have no special meaning.
.PP
The \fIflag\fR field is described in "FLAG VALUES". The interpretation of
the \fIparameter\fR 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.
.PP
The site named \f(CW\*(C`ME\*(C'\fR is special. There must be exactly one such entry,
and it should be the first entry in the file. If the \f(CW\*(C`ME\*(C'\fR 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 header field bodies. If the \f(CW\*(C`ME\*(C'\fR entry has a subscription list,
that list is prepended to the subscription list of all other entries.
For example, \f(CW\*(C`*,!control,!control.*,!junk,!foo.*\*(C'\fR could be used to
set the default subscription list for all other feeds so that local
postings are not propagated unless \f(CW\*(C`foo.*\*(C'\fR 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.
.PP
If the \f(CW\*(C`ME\*(C'\fR 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 \f(CW\*(C`/!local\*(C'\fR in the \f(CW\*(C`ME\*(C'\fR entry to reject local postings from other
misconfigured sites. The distribution sub-field of \f(CW\*(C`ME\*(C'\fR has no effect on
the acceptance or rejection of articles that do not have a Distribution
header field.
.PP
An empty \f(CW\*(C`ME\*(C'\fR entry is possible, in which case no exclusion patterns will
be defined.
.PP
Finally, it is also possible to set variables in \fInewsfeeds\fR and use them
later in the file. A line starting with \f(CW\*(C`$\*(C'\fR sets a variable. For
example:
.PP
.Vb 2
\& $LOCALGROUPS=local.*,example.*
\& $CONTROLGROUPS=control,control.*
.Ve
.PP
This sets the variable \f(CW\*(C`LOCALGROUPS\*(C'\fR to \f(CW\*(C`local.*,example.*\*(C'\fR and the
variable \f(CW\*(C`CONTROLGROUPS\*(C'\fR to \f(CW\*(C`control,control.*\*(C'\fR. They can later be
used elsewhere in the file, such as in a site entry like:
.PP
.Vb 1
\& news.example.com:$LOCALGROUPS:Tf,Wnm:
.Ve
.PP
which is then completely equivalent to:
.PP
.Vb 1
\& news.example.com:local.*,example.*:Tf,Wnm:
.Ve
.PP
Variables aren't solely simple substitution. If either \f(CW\*(C`!\*(C'\fR or \f(CW\*(C`@\*(C'\fR
immediately precedes 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:
.PP
.Vb 1
\& news.example.net:*,@$LOCALGROUPS,!$CONTROLGROUPS:Tf,Wnm:
.Ve
.PP
is therefore equivalent to:
.PP
.Vb 1
\& news.example.net:*,@local.*,@example.*,!control,!control.*:Tf,Wnm:
.Ve
.PP
which (as explained below) excludes all of the groups in $LOCALGROUPS
and unwanted control articles from the feed to that site.
.SH "FLAG VALUES"
.IX Header "FLAG VALUES"
The \fIflags\fR 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:
.IP "\fB<\fR \fIsize\fR" 4
.IX Item "< size"
An article will only be sent to this site if it is less than \fIsize\fR bytes
long. The default is no limit.
.IP "\fB>\fR \fIsize\fR" 4
.IX Item "> size"
An article will only be sent to this site if it is greater than \fIsize\fR
bytes long. The default is no limit.
.IP "\fBA\fR \fIchecks\fR" 4
.IX Item "A checks"
An article will only be sent to this site if it meets the requirements
specified in \fIchecks\fR, which should be chosen from the following set.
\&\fIchecks\fR 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, \fBAf\fR is not effective on the \fIinnfeed!\fR funnel
target and therefore has to be specified on every funnelled news site).
.RS 4
.IP c 3
.IX Item "c"
Exclude all kinds of control messages.
.IP C 3
.IX Item "C"
Only send control messages, not regular articles.
.IP d 3
.IX Item "d"
Only send articles with a Distribution header field. Combined with a
particular distribution value in the \fIdistribution\fR part of the site
entry, this can be used to limit articles sent to a site to just those
with a particular distribution.
.IP e 3
.IX Item "e"
Only send articles where every newsgroup listed in the Newsgroups header
field body exists in the \fIactive\fR file.
.IP f 3
.IX Item "f"
Don't send articles rejected by filters. This is only useful when
\&\fIdontrejectfiltered\fR is set to true in \fIinn.conf\fR. With that variable
set, this lets one accept all articles but not propagate filtered ones to
some sites.
.IP j 3
.IX Item "j"
Propagate articles according to their Newsgroups header field. This is only
useful when \fIwanttrash\fR is set to true in \fIinn.conf\fR. With that variable
set, articles accepted and filed in \f(CW\*(C`junk\*(C'\fR (due to \fIwanttrash\fR) are fed to
peers based on their subscription pattern applied to the Newsgroups header
field as though they were accepted and all those groups were locally carried.
Otherwise, they are propagated to sites that receive the \f(CW\*(C`junk\*(C'\fR newsgroup.
.Sp
This variable is useful if you want to run INN with a minimal \fIactive\fR
file and propagate all posts.
.IP o 3
.IX Item "o"
Only send articles for which overview data was stored.
.IP O 3
.IX Item "O"
Send articles to this site that don't have an Injection-Info or X\-Trace
header field, even if the \f(CW\*(C`O\*(C'\fR flag is also given.
.IP p 3
.IX Item "p"
Only check the exclusions against the Path header field of articles; don't
check the site name. This is useful if your site names aren't the same as
the path identities in Path header fields added by those remote sites, or
for program feeds where the site name is arbitrary and unrelated to the Path
header field body.
.RE
.RS 4
.Sp
If both \f(CW\*(C`c\*(C'\fR and \f(CW\*(C`C\*(C'\fR are given, the last specified one takes precedence.
.RE
.IP "\fBB\fR \fIhigh\fR/\fIlow\fR" 4
.IX Item "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
this flag should be two numbers separated by a slash. \fIhigh\fR
specifies the point at which the server can start draining the feed's I/O
buffer, and \fIlow\fR 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.
.IP "\fBC\fR \fIcount\fR" 4
.IX Item "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 \fIcount\fR. \f(CW\*(C`30\*(C'\fR is a
good value for this flag, allowing for instance:
.RS 4
.IP \(bu 3
crossposts to only 5 groups when followups aren't set;
.IP \(bu 3
crossposts to up to 26 groups when followups are set to two groups;
.IP \(bu 3
crossposts to up to 29 groups when followups are set to a single group;
.IP \(bu 3
crossposts to up to 30 groups when followups are set to poster.
.RE
.RS 4
.Sp
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.
.RE
.IP "\fBF\fR \fIname\fR" 4
.IX Item "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 \fIname\fR is not an absolute
path, it is taken to be relative to \fIpathoutgoing\fR in \fIinn.conf\fR. If
\&\fIname\fR is a directory, the file \fItogo\fR in that directory will be used as
the file name.
.IP "\fBG\fR \fIcount\fR" 4
.IX Item "G count"
If this flag is specified, an article will only be sent to this site if it
is posted to no more than \fIcount\fR newsgroups. This has the problem of
filtering out many FAQs, as well as newsgroup creation postings and
similar administrative announcements. Either the \fBC\fR flag or the \fBU\fR
flag is a better solution.
.IP "\fBH\fR \fIcount\fR" 4
.IX Item "H count"
If this flag is specified, an article will only be sent to this site
if it has \fIcount\fR or fewer sites in its Path header field body.
This flag should only be used as a rough guide because of the loose
interpretation of the Path header field; some sites put the poster's
name in the header field body, 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 field body. The default value for
\&\fIcount\fR if not specified is one. (Also see the \fBO\fR flag, which is
sometimes more appropriate for some uses of this flag.)
.IP "\fBI\fR \fIsize\fR" 4
.IX Item "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 than \fIsize\fR bytes, however, the data will be written out to
the appropriate file. The default value is \f(CW\*(C`16\*(C'\fR\ KB.
.IP "\fBN\fR \fIstatus\fR" 4
.IX Item "N status"
Restricts the articles sent to this site to those in newsgroups with the
moderation status given by \fIstatus\fR. If \fIstatus\fR is \f(CW\*(C`m\*(C'\fR, only articles
in moderated groups are sent; if \fIstatus\fR is \f(CW\*(C`u\*(C'\fR, only articles in
unmoderated groups are sent.
.IP "\fBO\fR \fIoriginator\fR" 4
.IX Item "O originator"
If this flag is specified, an article will only be sent to this site
if it contains an Injection-Info header field (or an X\-Trace header
field if no Injection-Info header field is found) and the first
field of this header field matches \fIoriginator\fR. \fIoriginator\fR is a
\&\fIuwildmat\fR expression without commas or a list of such expressions,
separated by \f(CW\*(C`/\*(C'\fR. The article is never sent if the first character
of the pattern begins with \f(CW\*(C`@\*(C'\fR and the rest of the pattern matches.
One use of this flag is to restrict the feed to locally generated posts
by using an \fIoriginator\fR pattern that matches the Injection-Info
header field added by the local server.
.IP "\fBP\fR \fIpriority\fR" 4
.IX Item "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 \fInicekids\fR parameter in \fIinn.conf\fR.
.IP "\fBQ\fR \fIhashfeed\fR" 4
.IX Item "Q hashfeed"
Specifies the \fIhashfeed\fR match expression for this site. It must be in
the form \f(CW\*(C`value/mod\*(C'\fR or \f(CW\*(C`start\-end/mod\*(C'\fR. 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 \f(CW\*(C`mod\*(C'\fR plus one equals \f(CW\*(C`value\*(C'\fR or
is between \f(CW\*(C`start\*(C'\fR and \f(CW\*(C`end\*(C'\fR, the article will be fed to this site. All
these numbers must be integers.
.Sp
It is a deterministic way to control the flow of articles and to split a feed.
For instance:
.Sp
.Vb 2
\& Q1/2 Feeds about 50% of all articles to this site.
\& Q2/2 Feeds the other 50% of all articles.
.Ve
.Sp
Another example with three sites:
.Sp
.Vb 3
\& 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.
.Ve
.Sp
If this flag is specified multiple times, the contents will be
logically \f(CW\*(C`OR\*(C'\fRed together (just one match is needed).
.Sp
You can use an extended syntax of the form \f(CW\*(C`value/mod_offset\*(C'\fR or
\&\f(CW\*(C`start\-end/mod_offset\*(C'\fR. 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 \f(CW\*(C`offset\*(C'\fR is \f(CW\*(C`_0\*(C'\fR
and thirteen overlapping values from \f(CW\*(C`_0\*(C'\fR to \f(CW\*(C`_12\*(C'\fR can be used.
Only up to four totally independent values exist: \f(CW\*(C`_0\*(C'\fR, \f(CW\*(C`_4\*(C'\fR,
\&\f(CW\*(C`_8\*(C'\fR and \f(CW\*(C`_12\*(C'\fR.
.Sp
Therefore, it allows generating a second level of deterministic
distribution. Indeed, if a news server is fed \f(CW\*(C`Q1/2\*(C'\fR, it can go on
splitting thanks to \f(CW\*(C`Q1\-3/9_4\*(C'\fR for instance. Up to four levels of
deterministic distribution can be used.
.Sp
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 \f(CW\*(C`@\*(C'\fR sign just after the \fBQ\fR flag (for
instance \f(CW\*(C`Q@1\-3/10\*(C'\fR, but the distribution of the messages is not
perfect with this legacy method whose use is discouraged and for
which offsets cannot be used).
.IP "\fBS\fR \fIsize\fR" 4
.IX Item "S size"
If the amount of data queued for the site gets to be larger than \fIsize\fR
bytes, the server will switch to spooling, appending to a file specified
by the \fBF\fR flag, or \fIpathoutgoing\fR/\fIsitename\fR if \fBF\fR is not specified.
Spooling usually happens only for channel or exploder feeds, when the
spawned program isn't keeping up with its input.
.IP "\fBT\fR \fItype\fR" 4
.IX Item "T type"
This flag specifies the type of feed for this site. \fItype\fR should be a
letter chosen from the following set:
.Sp
.Vb 6
\& c Channel
\& f File
\& l Log entry only
\& m Funnel (multiple entries feed into one)
\& p Program
\& x Exploder
.Ve
.Sp
Each feed is described below in "FEED TYPES". The default is \fBTf\fR,
for a file feed.
.IP "\fBU\fR \fIcount\fR" 4
.IX Item "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 \fIcount\fR
newsgroups. (Also see \fBC\fR for a more complex way of handling this.)
.IP "\fBW\fR \fIitems\fR" 4
.IX Item "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 (\f(CW\*(C`*\*(C'\fR)
has any effect. \fIitems\fR should be chosen from the following set:
.RS 4
.IP b 3
.IX Item "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.
.IP e 3
.IX Item "e"
The time the article will expire as seconds since epoch if it has an
Expires header field, \f(CW\*(C`0\*(C'\fR otherwise.
.IP f 3
.IX Item "f"
The storage API token of the article (the same as \f(CW\*(C`n\*(C'\fR). The article can
be retrieved given the storage API token by using sm(1).
.IP g 3
.IX Item "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 \f(CW\*(C`G\*(C'\fR is that this sends the newsgroup to which the article
was posted even if it is a control message.)
.IP h 3
.IX Item "h"
The history hash key of the article (derived from the message ID).
.IP m 3
.IX Item "m"
The message ID of the article.
.IP n 3
.IX Item "n"
The storage API token of the article. The article can be retrieved given
the storage API token by using sm(1).
.IP p 3
.IX Item "p"
The time the article was posted a seconds since epoch.
.IP s 3
.IX Item "s"
The site that fed the article to the server. This is taken from
either the Path header field body or the IP address of the sending site
depending on the value of \fIlogipaddr\fR in \fIinn.conf\fR. If \fIlogipaddr\fR
is true and the IP address is \f(CW\*(C`0.0.0.0\*(C'\fR (meaning that the article was
fed from localhost by a program like rnews(1)), the Path header field body
will be sent instead.
.IP t 3
.IX Item "t"
The time the article was received as seconds since epoch.
.IP * 3
The names of the appropriate funnel entries, or all sites that get the
article (see below for more details).
.IP D 3
.IX Item "D"
The body of the Distribution header field of the article, or \f(CW\*(C`?\*(C'\fR
if there is no such header field in the article.
.IP G 3
.IX Item "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 \f(CW\*(C`g\*(C'\fR).
.IP H 3
.IX Item "H"
All of the headers, followed by a blank line. The Xref header field will
already be present, and a Bytes header field containing the article's size in
bytes as in the \f(CW\*(C`b\*(C'\fR item will be added to the headers. If used, this
should be the only item in the list.
.IP N 3
.IX Item "N"
The body of the Newsgroups header field.
.IP P 3
.IX Item "P"
The body of the Path header field.
.IP O 3
.IX Item "O"
Overview data for the article.
.IP R 3
.IX Item "R"
Information needed for replication (the Xref header field without the site
name).
.RE
.RS 4
.Sp
More than one letter can be given. If multiple items are specified, they
will be written in the order specified separated by spaces. (\f(CW\*(C`H\*(C'\fR 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 \fBWn\fR.
.Sp
The \f(CW\*(C`H\*(C'\fR and \f(CW\*(C`O\*(C'\fR items are intended for use by programs that create news
overview databases or require similar information. \fBWnteO\fR is the flag
to generate input needed by the overchan(8) program.
.Sp
The asterisk (\f(CW\*(C`*\*(C'\fR) 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 \fBTm\fR 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 \fIparameter\fR 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
\&\fBTm\fR feeds.
.RE
.SH "FEED TYPES"
.IX Header "FEED TYPES"
\&\fBinnd\fR 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 \fBW*\fR flag. A funnel feed
gets every article that would be sent to any of the feeds that funnel into
it and normally include the \fBW*\fR 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).
.PP
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.
.PP
The simplest feed is a log feed (\fBTl\fR). Other than a mention in the news
log file, \fIpathlog\fR/news, no data is written out. This is equivalent to
a \fBTf\fR entry writing to \fI/dev/null\fR, except that no file is ever opened.
Flushing a log feed does nothing.
.PP
A file feed (\fBTf\fR) 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 \fIparameter\fR field. If \fIparameter\fR is not an absolute path,
it is taken to be relative to \fIpathoutgoing\fR in \fIinn.conf\fR. If
\&\fIparameter\fR is not given, it defaults to \fIpathoutgoing\fR/\fIsitename\fR.
The file name should be unique (two file feeds should not ever point to
the same file).
.PP
File feeds are designed for use by external programs that periodically
process the written data. To cooperate with \fBinnd\fR properly, such
external programs should first rename the batch file and then send a flush
command for that site to \fBinnd\fR using ctlinnd(8). \fBinnd\fR 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).
.PP
A program feed (\fBTp\fR) spawns a given program for every article that the
site receives. The \fIparameter\fR field must be the command line to execute,
and should contain one instance of \f(CW\*(C`%s\*(C'\fR, which will be replaced by the
storage API token of the article (the actual article can be retrieved by
the program using sm(1)). 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 (\fIpathlog\fR/errlog). \fBinnd\fR 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).
.PP
If a program feed is the target of a funnel, and if \fBW*\fR appears in the
flags of the site, a single asterisk may be present in the \fIparameter\fR
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 \fBW*\fR flag is not used, the
asterisk has no special meaning.
.PP
Flushing a program feed does nothing.
.PP
For a channel (\fBTc\fR) or exploder (\fBTx\fR) feed, the \fIparameter\fR 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 \fIpathoutgoing\fR/\fIsitename\fR and will try to start
the process again later.
.PP
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 \fBS\fR 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.
.PP
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:
.PP
.Vb 4
\& !newgroup group
\& !rmgroup group
\& !flush
\& !flush site
.Ve
.PP
These commands are sent whenever the ctlinnd(8) command of the same name
is received by the server. In addition, the ctlinnd(8) \f(CW\*(C`send\*(C'\fR command
can be used to send an arbitrary command line to an exploder. The primary
exploder is buffchan(8).
.PP
Finally, \fBTm\fR feeds are the input to a funnel. The \fIparameter\fR field of
the site should name the site handling articles for all of the funnel
inputs.
.SH EXAMPLES
.IX Header "EXAMPLES"
The syntax of the \fInewsfeeds\fR 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 \fInewsfeeds\fR, however, are file feeds
for nntpsend(8) and funnel feeds for innfeed(8).
.PP
The former look like this:
.PP
.Vb 1
\& feed.example.com:*,!control,!control.*,!junk:Tf,Wnm:
.Ve
.PP
which generates a file named \fIpathoutgoing\fR/feed.example.com containing
one line per article consisting of the storage API token, a space, and the
message ID.
.PP
The latter look like this:
.PP
.Vb 1
\& feed.example.com:*,!control,!control.*,!junk:Tm:innfeed!
.Ve
.PP
Very similar, except that this is the input to a funnel feed named
\&\f(CW\*(C`innfeed!\*(C'\fR. One could also write this as:
.PP
.Vb 1
\& example/feed.example.com:*,!control,!control.*,!junk:Ap,Tm:innfeed!
.Ve
.PP
(note the \fBAp\fR so that articles that contain just \f(CW\*(C`example\*(C'\fR in the Path
header field body will still be sent), which is completely equivalent
except that this will be logged in \fIpathlog\fR/news as going to the site
\&\f(CW\*(C`example\*(C'\fR rather than \f(CW\*(C`feed.example.com\*(C'\fR.
.PP
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 \fBinnfeed\fR
is properly set):
.PP
.Vb 1
\& innfeed!:!*:Tc,Wnm*:<pathbin in inn.conf>/innfeed \-y
.Ve
.PP
Note that the \fIpattern\fR for this feed is just \f(CW\*(C`!*\*(C'\fR 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.
.PP
Here's a more esoteric example of a channel feed:
.PP
.Vb 3
\& watcher!:*:Tc,Wbnm\e
\& :exec awk \*(Aq$1 > 1000000 { print "BIG", $2, $3 }\*(Aq \e
\& >> <pathlog>/bigart
.Ve
.PP
This receives the byte size of each article along with the storage API token
and Message-ID, and appends to a \fIbigart\fR log file 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:
.PP
.Vb 2
\& watcher!:*:Tc,>1000000,Wbnm\e
\& :exec awk \*(Aq{ print "BIG", $2, $3}\*(Aq >> <pathlog>/bigart
.Ve
.PP
Here's a cute, really simple news to mail gateway that also serves as an
example of a fairly fancy program feed:
.PP
.Vb 2
\& mailer!:!*:W*,Tp\e
\& :sm %s | innmail \-s "News article" *
.Ve
.PP
Remember that \f(CW\*(C`%s\*(C'\fR is replaced by the storage API token, so this
retrieves the article and pipes it into \fBinnmail\fR (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 \f(CW\*(C`*\*(C'\fR in the command
line and \fBW*\fR in the flags; this entry is designed to be used as the
target of funnel feeds such as:
.PP
.Vb 2
\& peter@example.com:news.software.nntp:Tm:mailer!
\& sue@example.com:news.admin.misc:Tm:mailer!
.Ve
.PP
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 \f(CW\*(C`peter@example.com\*(C'\fR and the site
\&\f(CW\*(C`bob@example.com\*(C'\fR, both of which funnel into \f(CW\*(C`mailer!\*(C'\fR, so it will look
at the \f(CW\*(C`mailer!\*(C'\fR site and end up executing the command line:
.PP
.Vb 2
\& sm @...@ | innmail \-s "News article" \e
\& peter@example.com sue@example.com
.Ve
.PP
which will mail the article to both Peter and Sue.
.PP
Finally, another very useful example of a channel feed: the standard
entry for controlchan(8). Make sure its path is properly set.
.PP
.Vb 3
\& controlchan!\e
\& :!*,control,control.*,!control.cancel\e
\& :AC,Tc,Wnsm:<pathbin in inn.conf>/controlchan
.Ve
.PP
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. \fBcontrolchan\fR 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 \fIlogipaddr\fR in controlchan(8)), and the message ID for
each article.
.PP
For many other examples, including examples of the special \f(CW\*(C`ME\*(C'\fR site
entry, see the example \fInewsfeeds\fR 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.
.SH HISTORY
.IX Header "HISTORY"
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Reformatted
and rewritten in POD by Russ Allbery <eagle@eyrie.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
active(5), buffchan(8), controlchan(8), ctlinnd(8), delayer(1), inn.conf(5),
innd(8), innfeed(8), innxmit(8), libinn_uwildmat(3), nntpsend(8).