1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "NEWSFEEDS 5"
132 .TH NEWSFEEDS 5 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
134 newsfeeds \- Determine where Usenet articles are sent
136 .IX Header "DESCRIPTION"
137 The file \fIpathetc\fR/newsfeeds specifies how incoming articles should be
138 distributed to other programs and files on the server. It is parsed by
139 the InterNetNews server \fIinnd\fR\|(8) when it starts up, or when directed to by
140 \&\fIctlinnd\fR\|(8). \fBinnd\fR doesn't send articles to remote sites itself, so
141 \&\fInewsfeeds\fR doesn't directly determine which remote news servers articles
142 are sent to. Instead, it specifies what batch files should be created or
143 which programs should be run (and what information should be sent to
144 them), and then this information is used by programs like \fIinnxmit\fR\|(8) and
145 \&\fIinnfeed\fR\|(8) to feed articles to remote sites.
147 The \fInewsfeeds\fR file isn't used solely to set up feeding accepted
148 articles to remote sites but also to pass them (or bits of information
149 about them) to any local programs or files that want that data. For
150 example, \fIcontrolchan\fR\|(8), a daemon that processes incoming control
151 messages, runs out of \fInewsfeeds\fR, as could a news to mail gateway.
153 The file is interpreted as a set of lines, parsed according to the
154 following rules: If a line ends with a backslash, the backslash, the
155 newline, and any whitespace at the start of the next line is deleted.
156 This is repeated until the entire \*(L"logical\*(R" line is collected. If the
157 logical line is blank or starts with a number sign (\f(CW\*(C`#\*(C'\fR), it is ignored.
159 All other lines are interpreted as feed entries. An entry should consist
160 of four colon-separated fields; two of the fields may have optional
161 sub\-fields, marked off by a slash. Fields or sub-fields that take
162 multiple parameters should be separated by a comma. Extra whitespace can
163 cause problems and should be avoided. Except for the site names, case is
164 significant. The format of an entry is:
167 \& sitename[/exclude,exclude,...]\e
168 \& :pattern,pattern...[/distribution,distribution...]\e
173 Each field is described below.
175 The \fIsitename\fR is the name of the site to which a news article can be
176 sent. It is used for writing log entries and for determining if an
177 article should be forwarded to a site. (A \*(L"site\*(R" is the generic term for
178 some destination of newsfeed data; it often corresponds to a remote news
179 peer, but doesn't have to. For example, a local archiving program run
180 from \fInewsfeeds\fR is also a \*(L"site.\*(R") If \fIsitename\fR already appears in
181 the article's Path: header, then the article will not be sent to the site.
182 The name is usually whatever the remote site uses to identify itself in
183 the Path: header, but can be almost any word.
185 Be careful, though, to avoid having the \fIsitename\fR accidentally match a
186 Path: header entry unintentionally. For this reason, special local
187 entries (such as archivers or gateways) should probably end with an
188 exclamation point to make sure that they do not have the same name as any
189 real site. For example, \f(CW\*(C`gateway\*(C'\fR is an obvious name for the local entry
190 that forwards articles out to a mailing list. If a site with the name
191 \&\f(CW\*(C`gateway\*(C'\fR posts an article, when the local site receives the article it
192 will see the name in the Path and not send the article to its own
193 \&\f(CW\*(C`gateway\*(C'\fR entry. Since \f(CW\*(C`gateway!\*(C'\fR can't appear as an individual Path:
194 entry since \f(CW\*(C`!\*(C'\fR is a delimiter in the Path: header, that would be a
195 better thing to use for \fIsitename\fR.
197 (Another way to avoid this problem is with the \f(CW\*(C`Ap\*(C'\fR flag; see the
200 If an entry has an exclusion sub\-field, the article will not be sent to
201 that site if any of \fIexclude\fR appear in the Path: header. (It's
202 sometimes convenient to have the \fIsitename\fR be an abbreviated form of the
203 name of the remote site, since all the \fIsitename\fRs to which an article
204 is sent are written to the log and using shorter \fIsitename\fRs can
205 therefore improve performance for large servers. In this case, the Path:
206 header entries of those sites should be given as \fIexclude\fR entries and
207 the \f(CW\*(C`Ap\*(C'\fR flag used so that the abbreviated \fIsitename\fR doesn't
208 accidentally match some other Path: header entry.)
210 The same \fIsitename\fR can be used more than once and the appropriate action
211 will be taken for each entry that should receive the article, but this is
212 recommended only for program feeds to avoid confusion. Case is not
213 significant in site names.
215 The comma-separated \fIpattern\fR specifies which groups to send to the site;
216 it is interpreted to build a \*(L"subscription list\*(R" for the site. The
217 default subscription is to get all groups carried by the server. It is a
218 \&\fIuwildmat\fR\|(3) pattern supporting poison (\f(CW\*(C`@\*(C'\fR) wildcards; see the \fIuwildmat\fR\|(3)
219 man page for full details on the pattern matching language. \fIpattern\fR
220 will be matched against every newsgroup carried by the server and all
221 newsgroups that match will be added to the subscription list for the site.
223 Normally, a given article (or information about it) is sent to a site if
224 any of the newsgroups to which the article was posted are in that site's
225 subscription list. If a newsgroup matches a \f(CW\*(C`@\*(C'\fR pattern in \fIpattern\fR,
226 then not only is it not added to the subscription list, but any articles
227 crossposted to that newsgroup also will not be sent to that site even if
228 other newsgroups to which it was crossposted are in that site's
229 subscription list. This is called a poison pattern (because matching
230 groups are \*(L"poisoned\*(R").
232 For example, to receive all comp.* groups, but only comp.sources.unix
233 within the sources newsgroups, the following \fIpattern\fR can be used:
236 \& comp.*,!comp.sources.*,comp.sources.unix
239 Note that the trailing \f(CW\*(C`.*\*(C'\fR is required; the pattern has to match the
240 whole newsgroup name. \f(CW\*(C`comp.sources.*\*(C'\fR could be written \f(CW\*(C`comp.sources*\*(C'\fR
241 and would exclude the newsgroup comp.sources (if it exists) as well as the
242 groups in the comp.sources.* hierarchy, but note that this would also
243 exclude a newsgroup named comp.sources\-only (whereas the above pattern
244 would add that group to the site subscription list since it matches
245 \&\f(CW\*(C`comp.*\*(C'\fR and none of the other patterns.
247 For another example, to feed alt.* and misc.* to a given site but not any
248 articles posted to alt.binaries.warez (even if they're also crossposted to
249 other alt.* or misc.* groups), the following pattern can be used:
252 \& alt.*,@alt.binaries.warez,misc.*
255 Note, however, that if you reversed the \f(CW\*(C`alt.*\*(C'\fR and <@alt.binaries.warez>
256 entries, this pattern would be equivalent to \f(CW\*(C`alt.*,misc.*\*(C'\fR, since the
257 last matching pattern determines whether a given newsgroup matches and the
258 poison logic only applies if the poison entry is the last matching entry.
260 Control messages follow slightly different propagation rules than normal
261 articles; see \fIinnd\fR\|(8) for the details. Note that most subscriptions
262 should have \f(CW\*(C`!junk,!control,!control.*\*(C'\fR in their pattern list due to those
263 propagation rules (and since junk is a special internal newsgroup; see
264 \&\fIwanttrash\fR in \fIinn.conf\fR\|(5) for more details on what it's used for) and
265 that the best way to keep control messages local to a site is with a
268 A subscription can be further modified by specifying distributions that
269 the site should or should not receive. The default is to send all
270 articles to all sites that subscribe to any of the groups where it has
271 been posted, but if an article has a Distribution: header and any
272 \&\fIdistribution\fRs are specified, then they are checked according to the
275 If the Distribution: header matches any of the values in the sub\-field,
278 If a \fIdistribution\fR starts with an exclamation point, and it matches the
279 Distribution: header, the article is not sent.
281 If the Distribution: header does not match any \fIdistribution\fR in the
282 site's entry and no negations were used, the article is not sent.
284 If the Distribution: header does not match any \fIdistribution\fR in the
285 site's entry and any \fIdistribution\fR started with an exclamation point,
288 If an article has more than one distribution specified, then each one is
289 handled according according to the above rules. If any of the specified
290 distributions indicate that the article should be sent, it is; if none do,
291 it is not sent. In other words, the rules are used as a logical or.
293 It is almost definitely a mistake to have a single feed that specifies
294 distributions that start with an exclamation point along with some that
297 Distributions are text words, not patterns; entries like \f(CW\*(C`*\*(C'\fR or \f(CW\*(C`all\*(C'\fR
298 have no special meaning.
300 The \fIflag\fR field is described in \*(L"\s-1FLAG\s0 \s-1VALUES\s0\*(R". The interpretation of
301 the \fIparameter\fR field depends on the type of feed and is explained in
302 more detail in \*(L"\s-1FEED\s0 \s-1TYPES\s0\*(R". It can be omitted for some types of
305 The site named \f(CW\*(C`ME\*(C'\fR is special. There must be exactly one such entry,
306 and it should be the first entry in the file. If the \f(CW\*(C`ME\*(C'\fR entry has an
307 exclusion sub\-field, incoming articles are rejected completely if any of
308 the names specified in that exclusion sub-field appear in their Path:
309 headers. If the \f(CW\*(C`ME\*(C'\fR entry has a subscription list, that list is
310 prepended to the subscription list of all other entries. For example,
311 \&\f(CW\*(C`*,!control,!control.*,!junk,!foo.*\*(C'\fR could be used to set the default subscription
312 list for all other feeds so that local postings are not propagated unless
313 \&\f(CW\*(C`foo.*\*(C'\fR explicitly appears in the site's subscription list. This feature
314 tends to be somewhat confusing since the default subscription is prepended
315 and can be overridden by other patterns.
317 If the \f(CW\*(C`ME\*(C'\fR entry has a distribution sub\-field, only articles that match
318 that distribution list are accepted and all other articles are rejected.
319 A common use for this is to put something like \f(CW\*(C`/!local\*(C'\fR in the \f(CW\*(C`ME\*(C'\fR
320 entry to reject local postings from other misconfigured sites.
322 Finally, it is also possible to set variables in \fInewsfeeds\fR and use them
323 later in the file. A line starting with \f(CW\*(C`$\*(C'\fR sets a variable. For
327 \& $LOCALGROUPS=local.*,example.*
330 This sets the variable \f(CW\*(C`LOCALGROUPS\*(C'\fR to \f(CW\*(C`local.*,example.*\*(C'\fR. This
331 variable can later be used elsewhere in the file, such as in a site entry
335 \& news.example.com:$LOCALGROUPS:Tf,Wnm:
338 which is then completely equivalent to:
341 \& news.example.com:local.*,example.*:Tf,Wnm:
344 Variables aren't solely simple substitution. If either \f(CW\*(C`!\*(C'\fR or \f(CW\*(C`@\*(C'\fR
345 immediately preceeds the variable and the value of the variable contains
346 commas, that character will be duplicated before each comma. This
347 somewhat odd-sounding behavior is designed to make it easier to use
348 variables to construct feed patterns. The utility becomes more obvious
349 when you observe that the line:
352 \& news.example.net:*,@$LOCALGROUPS:Tf,Wnm:
355 is therefore equivalent to:
358 \& news.example.net:*,@local.*,@example.*:Tf,Wnm:
361 which (as explained below) excludes all of the groups in \f(CW$LOCALGROUPS\fR from
362 the feed to that site.
364 .IX Header "FLAG VALUES"
365 The \fIflags\fR parameter specifies miscellaneous parameters, including the
366 type of feed, what information should be sent to it, and various
367 limitations on what articles should be sent to a site. They may be
368 specified in any order and should be separated by commas. Flags that take
369 values should have the value immediately after the flag letter with no
370 whitespace. The valid flags are:
371 .IP "\fB<\fR \fIsize\fR" 4
373 An article will only be sent to this site if it is less than \fIsize\fR bytes
374 long. The default is no limit.
375 .IP "\fB>\fR \fIsize\fR" 4
377 An article will only be sent to this site if it is greater than \fIsize\fR
378 bytes long. The default is no limit.
379 .IP "\fBA\fR \fIchecks\fR" 4
381 An article will only be sent to this site if it meets the requirements
382 specified in \fIchecks\fR, which should be chosen from the following set.
383 \&\fIchecks\fR can be multiple letters if appropriate.
387 Exclude all kinds of control messages.
390 Only send control messages, not regular articles.
393 Only send articles with a Distribution header. Combined with a particular
394 distribution value in the \fIdistribution\fR part of the site entry, this can
395 be used to limit articles sent to a site to just those with a particuliar
399 Only send articles where every newsgroup listed in the Newsgroups: header
400 exists in the active file.
403 Don't send articles rejected by filters. This is only useful when
404 \&\fIdontrejectfiltered\fR is set in \fIinn.conf\fR. With that variable set, this
405 lets one accept all articles but not propagate filtered ones to some
408 Only send articles for which overview data was stored.
411 Send articles to this site that don't have an X\-Trace: header, even if the
412 \&\f(CW\*(C`O\*(C'\fR flag is also given.
415 Only check the exclusions against the Path: header of articles; don't
416 check the site name. This is useful if your site names aren't the same as
417 the Path: entries added by those remote sites, or for program feeds where
418 the site name is arbitrary and unrelated to the Path: header.
422 If both \f(CW\*(C`c\*(C'\fR and \f(CW\*(C`C\*(C'\fR are given, the last specified one takes precedence.
424 .IP "\fBB\fR \fIhigh\fR/\fIlow\fR" 4
425 .IX Item "B high/low"
426 If a site is being fed by a file, channel, or exploder (see below), the
427 server will normally start trying to write the information as soon as
428 possible. Providing a buffer may give better system performance and help
429 smooth out overall load if a large batch of news comes in. The value of
430 the this flag should be two numbers separated by a slash. \fIhigh\fR
431 specifies the point at which the server can start draining the feed's I/O
432 buffer, and \fIlow\fR specifies when to stop writing and begin buffering
433 again; the units are bytes. The default is to do no buffering, sending
434 output as soon as it is possible to do so.
435 .IP "\fBC\fR \fIcount\fR" 4
437 If this flag is specified, an article will only be sent to this site if
438 the number of groups it is posted to, plus the square of the number of
439 groups followups would appear in, is no more than \fIcount\fR. \f(CW30\fR is a
440 good value for this flag, allowing crossposts to up to 29 groups when
441 followups are set to a single group or poster and only allowing crossposts
442 to 5 groups when followups aren't set.
443 .IP "\fBF\fR \fIname\fR" 4
445 Specifies the name of the file that should be used if it's necessary to
446 begin spooling for the site (see below). If \fIname\fR is not an absolute
447 path, it is taken to be relative to \fIpathoutgoing\fR in \fIinn.conf\fR. If
448 \&\fIname\fR is a directory, the file \fItogo\fR in that directory will be used as
450 .IP "\fBG\fR \fIcount\fR" 4
452 If this flag is specified, an article will only be sent to this site if it
453 is posted to no more than \fIcount\fR newsgroups. This has the problem of
454 filtering out many FAQs, as well as newsgroup creation postings and
455 similar administrative announcements. Either the \fBC\fR flag or the \fBU\fR
456 flag is a better solution.
457 .IP "\fBH\fR \fIcount\fR" 4
459 If this flag is specified, an article will only be sent to this site if it
460 has \fIcount\fR or fewer sites in its Path: line. This flag should only be
461 used as a rough guide because of the loose interpretation of the Path:
462 header; some sites put the poster's name in the header, and some sites
463 that might logically be considered to be one hop become two because they
464 put the posting workstation's name in the header. The default value for
465 \&\fIcount\fR if not specified is one. (Also see the \fBO\fR flag, which is
466 sometimes more appropriate for some uses of this flag.)
467 .IP "\fBI\fR \fIsize\fR" 4
469 The flag specifies the size of the internal buffer for a file feed. If
470 there are more file feeds than allowed by the system, they will be
471 buffered internally in least-recently-used order. If the internal buffer
472 grows bigger then \fIsize\fR bytes, however, the data will be written out to
473 the appropriate file. The default value is 16 \s-1KB\s0.
474 .IP "\fBN\fR \fIstatus\fR" 4
476 Restricts the articles sent to this site to those in newsgroups with the
477 moderation status given by \fIstatus\fR. If \fIstatus\fR is \f(CW\*(C`m\*(C'\fR, only articles
478 in moderated groups are sent; if \fIstatus\fR is \f(CW\*(C`u\*(C'\fR, only articles in
479 unmoderated groups are sent.
480 .IP "\fBO\fR \fIoriginator\fR" 4
481 .IX Item "O originator"
482 If this flag is specified, an article will only be sent to this site if it
483 contains an X\-Trace: header and the first field of this header matches
484 \&\fIoriginator\fR. \fIoriginator\fR is a \fIuwildmat\fR\|(3) expression without commas or
485 a list of such expressions, separated by \f(CW\*(C`/\*(C'\fR. The article is never sent
486 if the first character of the pattern begins with \f(CW\*(C`@\*(C'\fR and the rest of the
487 pattern matches. One use of this flag is to restrict the feed to locally
488 generated posts by using an \fIoriginator\fR pattern that matches the
489 X\-Trace: header added by the local server.
490 .IP "\fBP\fR \fIpriority\fR" 4
491 .IX Item "P priority"
492 The nice priority that this channel or program feed should receive. This
493 should be a positive number between 0 and 20 and is the priority that the
494 new process will run with. This flag can be used to raise the priority to
495 normal if you're using the \fInicekids\fR parameter in \fIinn.conf\fR.
496 .IP "\fBQ\fR \fIhashfeed\fR" 4
497 .IX Item "Q hashfeed"
498 Specifies the \fIhashfeed\fR match expression for this site. It must be in
499 the form \f(CW\*(C`value/mod\*(C'\fR or \f(CW\*(C`start\-end/mod\*(C'\fR. The Message-ID of the article
500 is hashed using \s-1MD5\s0, which results in a 128\-bit hash. The lowest
501 32\ bits are then taken by default as the hashfeed value (which is an
502 integer). If the hashfeed value modulus \f(CW\*(C`mod\*(C'\fR plus one equals \f(CW\*(C`value\*(C'\fR or
503 is between \f(CW\*(C`start\*(C'\fR and \f(CW\*(C`end\*(C'\fR, the article will be fed to this site. All
504 these numbers must be integers.
506 It is a deterministic way to control the flow of articles and to split a feed.
510 \& Q1/2 Feeds about 50% of all articles to this site.
511 \& Q2/2 Feeds the other 50% of all articles.
514 Another example with three sites:
517 \& Q1\-3/10 Feeds about 30% of all articles.
518 \& Q4\-5/10 Feeds about 20% of all articles.
519 \& Q6\-10/10 Feeds about 50% of all articles.
522 If this flag is specified multiple times, the contents will be
523 logically \f(CW\*(C`OR\*(C'\fRed together (just one match is needed).
525 You can use an extended syntax of the form \f(CW\*(C`value/mod_offset\*(C'\fR or
526 \&\f(CW\*(C`start\-end/mod_offset\*(C'\fR. As \s-1MD5\s0 generates a 128\-bit return value,
527 it is possible to specify from which byte-offset the 32\-bit integer
528 used by hashfeed starts. The default value for \f(CW\*(C`offset\*(C'\fR is \f(CW\*(C`_0\*(C'\fR
529 and thirteen overlapping values from \f(CW\*(C`_0\*(C'\fR to \f(CW\*(C`_12\*(C'\fR can be used.
530 Only up to four totally independent values exist: \f(CW\*(C`_0\*(C'\fR, \f(CW\*(C`_4\*(C'\fR,
531 \&\f(CW\*(C`_8\*(C'\fR and \f(CW\*(C`_12\*(C'\fR.
533 Therefore, it allows to a generate a second level of deterministic
534 distribution. Indeed, if a news server is fed \f(CW\*(C`Q1/2\*(C'\fR, it can go on
535 splitting thanks to \f(CW\*(C`Q1\-3/9_4\*(C'\fR for instance.
537 The algorithm is compatible with the one used by Diablo\ 5.1 and up.
538 If you want to use the legacy quickhashing method used by Diablo
539 before 5.1, you can put an \f(CW\*(C`@\*(C'\fR sign just after the \fBQ\fR flag (for
540 instance \f(CW\*(C`Q@1\-3/10\*(C'\fR, but the distribution of the messages is not
541 perfect with this legacy method whose use is discouraged and for
542 which offsets cannot be used).
543 .IP "\fBS\fR \fIsize\fR" 4
545 If the amount of data queued for the site gets to be larger than \fIsize\fR
546 bytes, the server will switch to spooling, appending to a file specified
547 by the \fBF\fR flag, or \fIpathoutgoing\fR/\fIsitename\fR if \fBF\fR is not specified.
548 Spooling usually happens only for channel or exploder feeds, when the
549 spawned program isn't keeping up with its input.
550 .IP "\fBT\fR \fItype\fR" 4
552 This flag specifies the type of feed for this site. \fItype\fR should be a
553 letter chosen from the following set:
559 \& m Funnel (multiple entries feed into one)
564 Each feed is described below in \*(L"\s-1FEED\s0 \s-1TYPES\s0\*(R". The default is \fBTf\fR,
566 .IP "\fBU\fR \fIcount\fR" 4
568 If this flag is specified, an article will only be sent to this site if
569 followups to this article would be posted to no more than \fIcount\fR
570 newsgroups. (Also see \fBC\fR for a more complex way of handling this.)
571 .IP "\fBW\fR \fIitems\fR" 4
573 For a file, channel, or exploder feed, this flag controls what information
574 will be sent to this site. For a program feed, only the asterisk (\f(CW\*(C`*\*(C'\fR)
575 has any effect. \fIitems\fR should be chosen from the following set:
579 Size of the article (in wire format, meaning with \s-1CRLF\s0 at the end of each
580 line, periods doubled at the beginning of lines, and ending in a line with
581 a single period) in bytes.
584 The time the article will expire as seconds since epoch if it has an
585 Expires: header, \f(CW0\fR otherwise.
588 The storage \s-1API\s0 token of the article (the same as \f(CW\*(C`n\*(C'\fR). The article can
589 be retrieved given the storage \s-1API\s0 token by using \fIsm\fR\|(8).
592 The newsgroup the article is in; if cross\-posted, then the first of the
593 groups to which the article was posted that this site gets. (The
594 difference from \f(CW\*(C`G\*(C'\fR is that this sends the newsgroup to which the article
595 was posted even if it is a control message.)
598 The history hash key of the article (derived from the message \s-1ID\s0).
601 The message \s-1ID\s0 of the article.
604 The storage \s-1API\s0 token of the article. The article can be retrieved given
605 the storage \s-1API\s0 token by using \fIsm\fR\|(8).
608 The time the article was posted a seconds since epoch.
611 The site that fed the article to the server. This is taken from either
612 the Path: header or the \s-1IP\s0 address of the sending site depending on the
613 value of \fIlogipaddr\fR in \fIinn.conf\fR. If \fIlogipaddr\fR is true and the \s-1IP\s0
614 address is \f(CW0.0.0.0\fR (meaning that the article was fed from localhost by
615 a program like \fIrnews\fR\|(8)), the Path: header value will be sent instead.
618 The time the article was received as seconds since epoch.
620 The names of the appropriate funnel entries, or all sites that get the
621 article (see below for more details).
624 The value of the Distribution: header of the article, or \f(CW\*(C`?\*(C'\fR if there is
625 no such header in the article.
628 Where the article is stored. If the newsgroup is crossposted, this is
629 generally the first of the groups to which it was posted that this site
630 receives; however, control messages are filed in control or control.*
631 (which is the difference between this item and \f(CW\*(C`g\*(C'\fR).
634 All of the headers, followed by a blank line. The Xref header will
635 already be present, and a Bytes header containing the article's size in
636 bytes as in the \f(CW\*(C`b\*(C'\fR item will be added to the headers. If used, this
637 should be the only item in the list.
640 The value of the Newsgroups: header.
643 The value of the Path: header.
646 Overview data for the article.
649 Information needed for replication (the Xref header without the site
654 More than one letter can be given. If multiple items are specified, they
655 will be written in the order specified separated by spaces. (\f(CW\*(C`H\*(C'\fR should
656 be the only item if given, but if it's not a newline will be sent before
657 the beginning of the headers.) The default is \fBWn\fR.
659 The \f(CW\*(C`H\*(C'\fR and \f(CW\*(C`O\*(C'\fR items are intended for use by programs that create news
660 overview databases or require similar information. \fBWnteO\fR is the flag
661 to generate input needed by the \fIoverchan\fR\|(8) program.
663 The asterisk (\f(CW\*(C`*\*(C'\fR) has special meaning. Normally it expands to a
664 space-separated list of all sites that received the current article. If,
665 however, this site is a target of a funnel feed (in other words, if it is
666 named by other sites which have the \fBTm\fR flag), then the asterisk expands
667 to the names of the funnel feeds that received the article. Similarly, if
668 the site is a program feed, an asterisk in the \fIparameter\fR field will be
669 expanded into the list of funnel feeds that received the article. A
670 program feed cannot get the site list unless it is the target of other
674 .IX Header "FEED TYPES"
675 \&\fBinnd\fR provides four basic types of feeds: log, file, program, and
676 channel. An exploder is a special type of channel. In addition, several
677 entries can feed into the same feed; these are funnel feeds, which refer
678 to an entry that is one of the other types. Funnel feeds are partially
679 described above with the description of the \fBW*\fR flag. A funnel feed
680 gets every article that would be sent to any of the feeds that funnel into
681 it and normally include the \fBW*\fR flag in their flags so that the program
682 processing that feed knows which sites received which articles. The most
683 common funnel feed is \fIinnfeed\fR\|(8).
685 Note that the term \*(L"feed\*(R" is technically a misnomer, since the server
686 doesn't transfer articles itself and only writes data to a file, program,
687 or log telling another program to transfer the articles.
689 The simplest feed is a log feed (\fBTl\fR). Other than a mention in the news
690 log file, \fIpathlog\fR/news, no data is written out. This is equivalent to
691 a \fBTf\fR entry writing to \fI/dev/null\fR, except that no file is ever opened.
692 Flushing a log feed does nothing.
694 A file feed (\fBTf\fR) is the next simplest type of feed. When the site
695 should receive an article, the specified data is written out to the file
696 named by the \fIparameter\fR field. If \fIparameter\fR is not an absolute path,
697 it is taken to be relative to \fIpathoutgoing\fR in \fIinn.conf\fR. If
698 \&\fIparameter\fR is not given, it defaults to \fIpathoutgoing\fR/\fIsitename\fR.
699 The file name should be unique (two file feeds should not ever point to
702 File feeds are designed for use by external programs that periodically
703 process the written data. To cooperate with \fBinnd\fR properly, such
704 external programs should first rename the batch file and then send a flush
705 command for that site to \fBinnd\fR using \fIctlinnd\fR\|(8). \fBinnd\fR will then
706 write out any buffered data, close the file, and reopen it (under the
707 original name), and the program can process the data in the renamed file
708 at its leisure. File feeds are most frequently used in combination with
709 \&\fInntpsend\fR\|(8).
711 A program feed (\fBTp\fR) spawns a given program for every article that the
712 site receives. The \fIparamter\fR field must be the command line to execute,
713 and should contain one instance of \f(CW%s\fR, which will be replaced by the
714 storage \s-1API\s0 token of the article (the actual article can be retrieved by
715 the program using \fIsm\fR\|(8)). The program will not receive anything on
716 standard input (unlike earlier versions of \s-1INN\s0, where the article is sent
717 to the program on stdin), and standard output and error from the program
718 will be set to the error log (\fIpathlog\fR/errlog). \fBinnd\fR will try to
719 avoid spawning a shell if the command has no shell meta\-characters; this
720 feature can be defeated if necessary for some reason by appending a
721 semi-colon to the end of the command. The full path name of the program
722 to be run must be specified unless the command will be run by the shell
723 (and it is strongly recommended that the full path name always be
724 specified regardless).
726 If a program feed is the target of a funnel, and if \fBW*\fR appears in the
727 flags of the site, a single asterisk may be present in the \fIparameter\fR
728 and will be replaced by a space-separated list of names of the sites
729 feeding into the funnel which received the relevant article. If the site
730 is not the target of a funnel, or if the \fBW*\fR flag is not used, the
731 asterisk has no special meaning.
733 Flushing a program feed does nothing.
735 For a channel (\fBTc\fR) or exploder (\fBTx\fR) feed, the \fIparameter\fR field
736 again names the process to start. As with program feeds, the full path to
737 the program must be specified. However, rather than spawning the program
738 for every article, it is spawned once and then whenever the site receives
739 an article, the data specified by the site flags is written to the
740 standard input of the spawned program. Standard output and error are set
741 as with program feeds. If the process exits, it will be restarted
742 automatically. If the process cannot be started, the server will spool
743 input to a file named \fIpathoutgoing\fR/\fIsitename\fR and will try to start
744 the process again later.
746 When a channel or exploder feed is flushed, the server closes its end of
747 the pipe to the program's standard input. Any pending data that has not
748 been written will be spooled; see the description of the \fBS\fR flag above.
749 The server will then spawn a new instance of the program. No signal is
750 sent to the program; it is up to the program handling a channel or
751 exploder feed to notice end of file on its standard input and exit
754 Exploders are a special type of channel feed. In addition to the channel
755 feed behavior described above, exploders can also be sent command lines.
756 These lines start with an exclamation point and their interpretation is up
757 to the exploder. The following commands are generated automatically by
767 These commands are sent whenever the \fIctlinnd\fR\|(8) command of the same name
768 is received by the server. In addition, the \fIctlinnd\fR\|(8) \f(CW\*(C`send\*(C'\fR command
769 can be used to send an arbitrary command line to an exploder. The primary
770 exploder is \fIbuffchan\fR\|(8).
772 Finally, \fBTm\fR feeds are the input to a funnel. The \fIparameter\fR field of
773 the site should name the site handling articles for all of the funnel
776 .IX Header "EXAMPLES"
777 All of the following examples assume that \s-1INN\s0 was installed with a prefix
778 of \fI/usr/local/news\fR; if you installed it somewhere else, modify the
779 paths as appropriate.
781 The syntax of the \fInewsfeeds\fR file is so complex because you can specify
782 a staggering variety of feeds. \s-1INN\s0 is capable of interacting with a wide
783 variety of programs that do various things with news articles. Far and
784 away the most common two entries in \fInewsfeeds\fR, however, are file feeds
785 for \fInntpsend\fR\|(8) and funnel feeds for \fIinnfeed\fR\|(8).
787 The former look like this:
790 \& feed.example.com:*,!control,!control.*,!junk:Tf,Wnm:
793 which generates a file named \fIpathoutgoing\fR/feed.example.com containing
794 one line per article consisting of the storage \s-1API\s0 token, a space, and the
797 The latter look like this:
800 \& feed.example.com:*,!control,!control.*,!junk:Tm:innfeed!
803 Very similar, except that this is the input to a funnel feed named
804 \&\f(CW\*(C`innfeed!\*(C'\fR. One could also write this as:
807 \& example/feed.example.com:*,!control,!control.*,!junk:Ap,Tm:innfeed!
810 (note the \fBAp\fR so that articles that contain just \f(CW\*(C`example\*(C'\fR in the Path:
811 header will still be sent), which is completely equivalent except that
812 this will be logged in \fIpathlog\fR/news as going to the site \f(CW\*(C`example\*(C'\fR
813 rather than \f(CW\*(C`feed.example.com\*(C'\fR.
815 The typical feed entry for \fIinnfeed\fR\|(8) is a good example of a channel feed
816 that's the target of various funnel feeds:
819 \& innfeed!:!*:Tc,Wnm*:/usr/local/news/bin/startinnfeed \-y
822 Note that the \fIpattern\fR for this feed is just \f(CW\*(C`!*\*(C'\fR so that it won't
823 receive any articles directly. The feed should only receive those
824 articles that would go to one of the funnel feeds that are feeding into
825 it. \fIinnfeed\fR\|(8) (spawned by \fBstartinnfeed\fR) will receive one line per
826 article on its standard input containing the storage \s-1API\s0 token, the
827 message \s-1ID\s0, and a space-separated list of sites that should receive that
830 Here's a more esoteric example of a channel feed:
833 \& watcher!:*:Tc,Wbnm\e
834 \& :exec awk '$1 > 1000000 { print "BIG", $2, $3 }' > /dev/console
837 This receives the byte size of each article along with the storage \s-1API\s0
838 token and message \s-1ID\s0, and prints to the console a line for every article
839 that's over a million bytes. This is actually rather a strange way to
840 write this since \s-1INN\s0 can do the size check itself; the following is
844 \& watcher!:*:Tc,>1000000,Wbnm\e
845 \& :exec awk '{ print "BIG", $2, $3}' > /dev/console
848 Here's a cute, really simple news to mail gateway that also serves as an
849 example of a fairly fancy program feed:
852 \& mailer!:!*:W*,Tp\e
853 \& :sm %s | innmail \-s "News article" *
856 Remember that \f(CW%s\fR is replaced by the storage \s-1API\s0 token, so this
857 retrieves the article and pipes it into \fBinnmail\fR (which is safer than
858 programs like \fIMail\fR\|(1) because it doesn't parse the body for tilde
859 commands) with a given subject line. Note the use of \f(CW\*(C`*\*(C'\fR in the command
860 line and \fBW*\fR in the flags; this entry is designed to be used as the
861 target of funnel feeds such as:
864 \& peter@example.com:news.software.nntp:Tm:mailer!
865 \& sue@example.com:news.admin.misc:Tm:mailer!
868 Suppose that the server receives an article crossposted between
869 news.admin.misc and news.software.nntp. The server will notice that the
870 article should be sent to the site \f(CW\*(C`peter@example.com\*(C'\fR and the site
871 \&\f(CW\*(C`bob@example.com\*(C'\fR, both of which funnel into \f(CW\*(C`mailer!\*(C'\fR, so it will look
872 at the \f(CW\*(C`mailer!\*(C'\fR site and end up executing the command line:
875 \& sm @...@ | innmail \-s "News article" peter@example.com sue@example.com
878 which will mail the article to both Peter and Sue.
880 Finally, another very useful example of a channel feed: the standard
881 entry for \fIcontrolchan\fR\|(8).
885 \& :!*,control,control.*,!control.cancel/!collabra\-internal\e
886 \& :Tc,Wnsm:/usr/local/news/bin/controlchan
889 This program only wants information about articles posted to a control
890 newsgroup other than control.cancel, which due to the sorting of control
891 messages described in \fIinnd\fR\|(8) will send it all control messages except for
892 cancel messages. In this case, we also exclude any article with a
893 distribution of \f(CW\*(C`collabra\-internal\*(C'\fR. \fBcontrolchan\fR gets the storage
894 \&\s-1API\s0 token, the name of the sending site (for processing old-style ihave
895 and sendme control messages, be sure to read about \fIlogipaddr\fR in
896 \&\fIcontrolchan\fR\|(8)), and the message \s-1ID\s0 for each article.
898 For many other examples, including examples of the special \f(CW\*(C`ME\*(C'\fR site
899 entry, see the example \fInewsfeeds\fR file distributed with \s-1INN\s0. Also see the
900 install documentation that comes with \s-1INN\s0 for information about setting up
901 the standard newsfeeds entries used by most sites.
904 Written by Rich \f(CW$alz\fR <rsalz@uunet.uu.net> for InterNetNews. Reformatted
905 and rewritten in \s-1POD\s0 by Russ Allbery <rra@stanford.edu>.
907 $Id: newsfeeds.5 7880 2008-06-16 20:37:13Z iulius $
909 .IX Header "SEE ALSO"
910 \&\fIactive\fR\|(5), \fIbuffchan\fR\|(8), \fIcontrolchan\fR\|(8), \fIctlinnd\fR\|(8), \fIinn.conf\fR\|(5), \fIinnd\fR\|(8),
911 \&\fIinnfeed\fR\|(8), \fIinnxmit\fR\|(8), \fInntpsend\fR\|(8), \fIuwildmat\fR\|(3).
~ian / inn-innduct.git / blob